diff --git a/.claude/settings.local.json b/.claude/settings.local.json deleted file mode 100644 index ae27c085..00000000 --- a/.claude/settings.local.json +++ /dev/null @@ -1,14 +0,0 @@ -{ - "permissions": { - "allow": [ - "Bash(find \"C:\\\\Work\\\\Projects\\\\Published\\\\SourceFlow\\\\SourceFlow.Net/src/SourceFlow.Cloud.AWS/Attributes\" -type f -name \"*.cs\" 2>/dev/null | head -10)", - "Bash(find /c/Work/Projects/Published/SourceFlow/SourceFlow.Net/src -name \"*Cloud*\" -o -name \"*cloud*\" 2>/dev/null | head -50)", - "Bash(find /c/Work/Projects/Published/SourceFlow/SourceFlow.Net/tests/SourceFlow.Cloud.AWS.Tests/Unit -type f -name \"*.cs\" 2>/dev/null | grep -v obj | sort)", - "Bash(find /c/Work/Projects/Published/SourceFlow/SourceFlow.Net/tests -type f -name \"*.cs\" | xargs grep -l \"Idempotency\\\\|DeadLetter\\\\|Masker\\\\|CloudTelemetry\\\\|PolymorphicJson\\\\|Encryption\" | grep -v obj | head -20)", - "Bash(find \"C:/Work/Projects/Published/SourceFlow/SourceFlow.Net/tests/SourceFlow.Cloud.AWS.Tests\" -name \"*.csproj\" | xargs cat)", - "Bash(find \"C:/Work/Projects/Published/SourceFlow/SourceFlow.Net/tests/SourceFlow.Core.Tests\" -name \"*.csproj\" | xargs cat)", - "Bash(ls \"C:\\\\Work\\\\Projects\\\\Published\\\\SourceFlow\\\\SourceFlow.Net\\\\src\\\\SourceFlow.Cloud.AWS\\\\Attributes\\\\\" 2>/dev/null && echo \"EXISTS\" || echo \"EMPTY_OR_MISSING\"\nls \"C:\\\\Work\\\\Projects\\\\Published\\\\SourceFlow\\\\SourceFlow.Net\\\\src\\\\SourceFlow.Cloud.AWS\\\\Management\\\\\" 2>/dev/null && echo \"EXISTS\" || echo \"EMPTY_OR_MISSING\")", - "Bash(ls \"C:\\\\Work\\\\Projects\\\\Published\\\\SourceFlow\\\\SourceFlow.Net\\\\src\\\\SourceFlow\\\\\" 2>/dev/null || echo \"NOT_FOUND\"\nls \"C:\\\\Work\\\\Projects\\\\Published\\\\SourceFlow\\\\SourceFlow.Net\\\\src\\\\\" 2>/dev/null)" - ] - } -} diff --git a/.dockerignore b/.dockerignore index fe1152bd..af8096fd 100644 --- a/.dockerignore +++ b/.dockerignore @@ -1,30 +1,20 @@ -**/.classpath -**/.dockerignore -**/.env -**/.git -**/.gitignore -**/.project -**/.settings -**/.toolstarget +# Build context for the demo images (samples/**/Dockerfile). Keep it small: sources and build props only. +**/bin +# ...except the Studio site builder (npx @sourceflow/studio build), which lives in a bin folder. +!web/app/bin +**/obj **/.vs **/.vscode -**/*.*proj.user -**/*.dbmdl -**/*.jfm -**/azds.yaml -**/bin -**/charts -**/docker-compose* -**/Dockerfile* +**/*.user **/node_modules -**/npm-debug.log -**/obj -**/secrets.dev.yaml -**/values.dev.yaml -LICENSE -README.md -!**/.gitignore -!.git/HEAD -!.git/config -!.git/packed-refs -!.git/refs/heads/** \ No newline at end of file +.git +.github +BenchmarkDotNet.Artifacts +TestResults +Images +docs +tests +quality +eng +**/Dockerfile* +**/docker-compose* diff --git a/.editorconfig b/.editorconfig index 8a46cdd1..ad5e9322 100644 --- a/.editorconfig +++ b/.editorconfig @@ -114,3 +114,21 @@ csharp_style_conditional_delegate_call = true:suggestion # Code quality dotnet_code_quality_unused_parameters = all:suggestion + +# --------------------------------------------------------------------------- +# SourceFlow v3 additions (implementation plan 02 §6, plan 04 §8) +# --------------------------------------------------------------------------- +[*.cs] +# v3 code uses file-scoped namespaces. +csharp_style_namespace_declarations = file_scoped:suggestion +# Library code awaits with ConfigureAwait(false) (design doc 09 HP-2). +dotnet_diagnostic.CA2007.severity = suggestion + +# Generated code +[*.g.cs] +generated_code = true + +# Test projects: underscores in test names and no ConfigureAwait. +[tests/**.cs] +dotnet_diagnostic.CA2007.severity = none +dotnet_diagnostic.CA1707.severity = none diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 00000000..97002d40 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,7 @@ +# Text files are stored and checked out with LF on every platform, so tests that read source files, embedded scripts and +# golden files see the same bytes on Windows as in CI (core.autocrlf would otherwise check them out with CRLF). +* text=auto eol=lf + +# Windows scripts keep CRLF. +*.cmd text eol=crlf +*.bat text eol=crlf diff --git a/.github/workflows/studio-pr.yml b/.github/workflows/studio-pr.yml new file mode 100644 index 00000000..800ad555 --- /dev/null +++ b/.github/workflows/studio-pr.yml @@ -0,0 +1,64 @@ +# SourceFlow Studio checks (implementation plan 10 §4). WP-S.7: the core client (WASM-01..08); WP-S.8: the app shell +# (STU-UT, STU-CT) and the Playwright scenarios against `dotnet sourceflow studio` (STU-E2E). Accessibility and +# performance budgets join with the views (WP-S.9 onwards). WP-S.12: the static site build and the workflow-diff action. +name: studio-pr + +on: + pull_request: + branches: [ "v3.0.0" ] + paths: [ "web/**", "src/Workflows/**", "src/Tooling/SourceFlow.Tool/**", "schemas/**", "tests/Golden/**", "samples/OrderFulfilment/**", "samples/TravelBooking/**", "docs/v3.0.0/reference/guides/workflow-dsl-reference.md", ".github/workflows/studio-pr.yml", ".github/workflows/workflow-diff.yml" ] + push: + branches: [ "v3.0.0" ] + paths: [ "web/**", "src/Workflows/**", "src/Tooling/SourceFlow.Tool/**", "schemas/**", "tests/Golden/**", "samples/OrderFulfilment/**", "samples/TravelBooking/**", "docs/v3.0.0/reference/guides/workflow-dsl-reference.md", ".github/workflows/studio-pr.yml", ".github/workflows/workflow-diff.yml" ] + +permissions: + contents: read + +concurrency: + group: studio-pr-${{ github.ref }} + cancel-in-progress: true + +env: + DOTNET_NOLOGO: "true" + DOTNET_CLI_TELEMETRY_OPTOUT: "true" + +jobs: + core-client: + runs-on: ubuntu-latest + defaults: + run: + working-directory: web + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-dotnet@v4 + with: + global-json-file: global.json + - uses: actions/setup-node@v4 + with: + node-version: "22.18" + cache: npm + cache-dependency-path: web/package-lock.json + - run: npm ci + - name: Type check + run: npm run typecheck + # The core builds without the wasm-tools workload (no AOT or native relinking); it is trimmed on publish. + - name: Build the WebAssembly core + run: npm run build:wasm + - name: WASM-01..08, STU-UT, STU-CT, the site build and the workflow-diff action (Vitest) + run: npm test + - name: Build the workflow-diff action + run: npm run build:action + - name: Build the app + run: npm run build + - name: Build the tool (the Studio local host) + working-directory: . + run: dotnet build src/Tooling/SourceFlow.Tool -c Debug + - name: Install Chromium for Playwright + run: npx playwright install --with-deps chromium + - name: STU-E2E (Playwright) + run: npm run e2e + - uses: actions/upload-artifact@v4 + if: failure() + with: + name: playwright-traces + path: web/app/test-results diff --git a/.github/workflows/v3-codeql.yml b/.github/workflows/v3-codeql.yml new file mode 100644 index 00000000..39383bec --- /dev/null +++ b/.github/workflows/v3-codeql.yml @@ -0,0 +1,32 @@ +# CodeQL for v3 (implementation plan 08 §1). +name: v3-codeql + +on: + push: + branches: [ "v3.0.0" ] + pull_request: + branches: [ "v3.0.0" ] + schedule: + - cron: "17 5 * * 1" + +permissions: + actions: read + contents: read + security-events: write + +jobs: + codeql: + name: codeql + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-dotnet@v4 + with: + global-json-file: global.json + - uses: github/codeql-action/init@v3 + with: + languages: csharp + queries: security-extended + build-mode: manual + - run: dotnet build SourceFlow.slnx -c Release + - uses: github/codeql-action/analyze@v3 diff --git a/.github/workflows/v3-images.yml b/.github/workflows/v3-images.yml new file mode 100644 index 00000000..95abecb8 --- /dev/null +++ b/.github/workflows/v3-images.yml @@ -0,0 +1,89 @@ +# Demo images of the samples on GitHub Container Registry: TravelBooking (the Bookings and Hotels services) and +# OrderFulfilment (one image for its four services), each with SourceFlow Studio for its workspace. +# Tags: the branch name, the short commit SHA and v3-latest (the tag docker-compose.yml pulls by default). +name: v3-images + +on: + push: + branches: [ "v3.0.0", "v3/**" ] + paths: + - "src/**" + - "samples/**" + - "web/**" + - "schemas/**" + - "Directory.Build.props" + - "Directory.Build.targets" + - "Directory.Packages.props" + - "global.json" + - ".dockerignore" + - ".github/workflows/v3-images.yml" + workflow_dispatch: + +permissions: + contents: read + packages: write + +concurrency: + group: v3-images-${{ github.ref }} + cancel-in-progress: true + +jobs: + image: + name: ${{ matrix.image }} + runs-on: ubuntu-latest + strategy: + fail-fast: false + matrix: + include: + - image: sourceflow-travel-bookings + dockerfile: samples/TravelBooking/Dockerfile + service: Bookings + - image: sourceflow-travel-hotels + dockerfile: samples/TravelBooking/Dockerfile + service: Hotels + - image: sourceflow-travel-studio + dockerfile: samples/TravelBooking/Studio.Dockerfile + service: "" + - image: sourceflow-order-fulfilment + dockerfile: samples/OrderFulfilment/Dockerfile + service: "" + - image: sourceflow-order-studio + dockerfile: samples/OrderFulfilment/Studio.Dockerfile + service: "" + steps: + - uses: actions/checkout@v4 + + - name: Image name + id: name + run: echo "image=ghcr.io/${GITHUB_REPOSITORY_OWNER,,}/${{ matrix.image }}" >> "$GITHUB_OUTPUT" + + - uses: docker/setup-qemu-action@v3 + - uses: docker/setup-buildx-action@v3 + + - uses: docker/login-action@v3 + with: + registry: ghcr.io + username: ${{ github.actor }} + password: ${{ secrets.GITHUB_TOKEN }} + + - id: meta + uses: docker/metadata-action@v5 + with: + images: ${{ steps.name.outputs.image }} + tags: | + type=ref,event=branch + type=sha,format=short + type=raw,value=v3-latest + + - uses: docker/build-push-action@v6 + with: + context: . + file: ${{ matrix.dockerfile }} + build-args: | + SERVICE=${{ matrix.service }} + platforms: linux/amd64,linux/arm64 + push: true + tags: ${{ steps.meta.outputs.tags }} + labels: ${{ steps.meta.outputs.labels }} + cache-from: type=gha,scope=${{ matrix.image }} + cache-to: type=gha,mode=max,scope=${{ matrix.image }} diff --git a/.github/workflows/v3-nightly.yml b/.github/workflows/v3-nightly.yml new file mode 100644 index 00000000..4f58552d --- /dev/null +++ b/.github/workflows/v3-nightly.yml @@ -0,0 +1,219 @@ +# v3 nightly (implementation plan 08 §3): full matrices, real cloud, chaos, long property runs. +name: v3-nightly + +on: + schedule: + - cron: "0 2 * * *" + workflow_dispatch: + +permissions: + contents: read + id-token: write # OIDC federation to the cloud sandboxes (no long-lived secrets) + +env: + DOTNET_NOLOGO: "true" + TEST_ARGS: "-c Release --no-build --ignore-exit-code 8 --report-trx" + +jobs: + database-matrix: + name: storage (${{ matrix.db }}) + strategy: + fail-fast: false + matrix: + include: + - { db: "postgres:15", provider: PostgreSQL, image: "postgres:15-alpine" } + - { db: "postgres:16", provider: PostgreSQL, image: "postgres:16-alpine" } + - { db: "postgres:17", provider: PostgreSQL, image: "postgres:17-alpine" } + - { db: "postgres:17-partitioned", provider: PostgreSQL, image: "postgres:17-alpine" } + - { db: "mssql:2022", provider: SqlServer, image: "", mssql: "mcr.microsoft.com/mssql/server:2022-latest" } + - { db: "mssql:2025", provider: SqlServer, image: "", mssql: "mcr.microsoft.com/mssql/server:2025-latest" } + runs-on: ubuntu-latest + env: + SOURCEFLOW_TEST_DATABASE: ${{ matrix.db }} + SOURCEFLOW_TEST_POSTGRES_IMAGE: ${{ matrix.image }} + SOURCEFLOW_TEST_SQLSERVER_IMAGE: ${{ matrix.mssql }} + steps: + - uses: actions/checkout@v4 + with: + ref: v3.0.0 + - uses: actions/setup-dotnet@v4 + with: + global-json-file: global.json + - run: dotnet build SourceFlow.slnx -c Release + - run: dotnet test --project tests/Storage/SourceFlow.Storage.Tests/SourceFlow.Storage.Tests.csproj ${{ env.TEST_ARGS }} --filter-trait "Provider=${{ matrix.provider }}" + + benchmarks: + # WP-2.10: component benchmarks and measurements (PERF-01..06, 08, 10). Results are uploaded for the trend store; + # the regression gate against quality/benchmarks/baselines (plan 08 §4) is a follow-up. + name: component benchmarks + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + ref: v3.0.0 + - uses: actions/setup-dotnet@v4 + with: + global-json-file: global.json + - run: dotnet run -c Release --project quality/benchmarks/SourceFlow.Benchmarks -- baseline + - uses: actions/upload-artifact@v4 + if: always() + with: + name: benchmarks + path: | + quality/benchmarks/baselines/*.json + BenchmarkDotNet.Artifacts/results/** + + real-cloud: + name: real cloud (${{ matrix.cloud }}) + if: vars.SOURCEFLOW_REAL_CLOUD == 'true' + strategy: + fail-fast: false + matrix: + include: + - { cloud: aws, trait: Aws } + - { cloud: azure, trait: Azure } + - { cloud: gcp, trait: Gcp } + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + ref: v3.0.0 + - uses: actions/setup-dotnet@v4 + with: + global-json-file: global.json + - if: matrix.cloud == 'aws' + uses: aws-actions/configure-aws-credentials@v4 + with: + role-to-assume: ${{ vars.AWS_TEST_ROLE_ARN }} + aws-region: ${{ vars.AWS_TEST_REGION }} + - if: matrix.cloud == 'azure' + uses: azure/login@v2 + with: + client-id: ${{ vars.AZURE_CLIENT_ID }} + tenant-id: ${{ vars.AZURE_TENANT_ID }} + subscription-id: ${{ vars.AZURE_SUBSCRIPTION_ID }} + - if: matrix.cloud == 'gcp' + uses: google-github-actions/auth@v2 + with: + workload_identity_provider: ${{ vars.GCP_WIF_PROVIDER }} + service_account: ${{ vars.GCP_TEST_SERVICE_ACCOUNT }} + - run: dotnet build SourceFlow.slnx -c Release + - name: Transport TCK, KMS and E2E on the real cloud + env: + SOURCEFLOW_REAL_CLOUD: ${{ matrix.cloud }} + AZURE_SERVICEBUS_NAMESPACE: ${{ vars.AZURE_SERVICEBUS_NAMESPACE }} + SOURCEFLOW_KMS_AWS_KEY: ${{ vars.SOURCEFLOW_KMS_AWS_KEY }} + SOURCEFLOW_KMS_AZURE_KEY: ${{ vars.SOURCEFLOW_KMS_AZURE_KEY }} + SOURCEFLOW_KMS_GCP_KEY: ${{ vars.SOURCEFLOW_KMS_GCP_KEY }} + run: | + dotnet test --project tests/Cloud/SourceFlow.Cloud.Tests/SourceFlow.Cloud.Tests.csproj ${{ env.TEST_ARGS }} --filter-trait "Cloud=${{ matrix.trait }}" + dotnet test --project tests/EndToEnd/SourceFlow.EndToEnd.Tests/SourceFlow.EndToEnd.Tests.csproj ${{ env.TEST_ARGS }} --filter-trait "Cloud=${{ matrix.trait }}" + + chaos: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + ref: v3.0.0 + - uses: actions/setup-dotnet@v4 + with: + global-json-file: global.json + - run: dotnet build SourceFlow.slnx -c Release + - run: >- + dotnet test --project tests/EndToEnd/SourceFlow.EndToEnd.Tests/SourceFlow.EndToEnd.Tests.csproj + ${{ env.TEST_ARGS }} --filter-trait "Category=Chaos" + + load-tier-m: + # WP-4.7: the tier-M load test (doc 09 §5, PERF-09) against the TravelBooking services built from this checkout (the + # Bookings service, its workflow to Hotels over LocalStack), with k6 on the same Docker network. The hosted runner shares 4 vCPUs between the service, PostgreSQL and k6, so it reports rather + # than gates; the milestone acceptance run is on a dedicated 4-vCPU service instance (quality/loadtest/README.md). + name: load test (tier M) + runs-on: ubuntu-latest + continue-on-error: true + steps: + - uses: actions/checkout@v4 + with: + ref: v3.0.0 + - run: docker compose up -d --build --wait postgres localstack hotels bookings + - name: k6 at 1,000 commands/s + run: >- + docker run --rm -i --network sourceflow-demo_default + -e BOOKINGS_URL=http://bookings:8080 -e HOTELS_URL=http://hotels:8080 -e RATE=1000 -e DURATION=5m + grafana/k6:2.3.0 run - < quality/loadtest/k6/travel-tier-m.js | tee loadtest-summary.txt + - uses: actions/upload-artifact@v4 + if: always() + with: + name: load-tier-m + path: loadtest-summary.txt + + relay-latency: + # PERF-07 (WP-4.7): outbox commit to broker acknowledgement, p95 <= 250 ms, on PostgreSQL with each emulator. + name: relay latency (emulators) + runs-on: ubuntu-latest + env: + MSSQL_SA_PASSWORD: ${{ secrets.EMULATOR_SA_PASSWORD || 'SourceFlow_Emulator_1' }} + AWS_ENDPOINT_URL: http://localhost:4566 + AWS_ACCESS_KEY_ID: test + AWS_SECRET_ACCESS_KEY: test + AWS_REGION: eu-west-1 + PUBSUB_EMULATOR_HOST: localhost:8085 + SERVICEBUS_EMULATOR_CONNECTION: "Endpoint=sb://localhost;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=SAS_KEY_VALUE;UseDevelopmentEmulator=true;" + SERVICEBUS_EMULATOR_ADMIN_CONNECTION: "Endpoint=sb://localhost:5300;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=SAS_KEY_VALUE;UseDevelopmentEmulator=true;" + steps: + - uses: actions/checkout@v4 + with: + ref: v3.0.0 + - uses: actions/setup-dotnet@v4 + with: + global-json-file: global.json + - run: | + docker compose -f eng/emulators/localstack/docker-compose.yml up -d + docker compose -f eng/emulators/pubsub/docker-compose.yml up -d + docker compose -f eng/emulators/servicebus/docker-compose.yml up -d + for i in $(seq 1 90); do + curl -sf http://localhost:5300/health >/dev/null && exit 0 + sleep 2 + done + echo "Service Bus emulator not healthy"; exit 1 + - run: dotnet build SourceFlow.slnx -c Release + - run: >- + dotnet test --project tests/EndToEnd/SourceFlow.EndToEnd.Tests/SourceFlow.EndToEnd.Tests.csproj + ${{ env.TEST_ARGS }} --filter-trait "Category=Performance" --output Detailed + + dast: + # WP-4.7 (plan 08): OWASP ZAP API scan of the TravelBooking Bookings service's query API, driven by deploy/dast/query-api.openapi.json + # (a unit test keeps it equal to the mapped routes). Any medium or high finding fails the night. The injection corpus + # over HTTP (QRY-57..59) runs with the end-to-end tests. + name: dast (OWASP ZAP) + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + ref: v3.0.0 + - run: docker compose up -d --build --wait postgres localstack hotels bookings + - name: ZAP API scan + run: | + mkdir -p zap && cp deploy/dast/* zap/ && chmod 777 zap + docker run --rm --network sourceflow-demo_default -v "$PWD/zap:/zap/wrk:rw" ghcr.io/zaproxy/zaproxy:stable zap-api-scan.py -t /zap/wrk/query-api.openapi.json -f openapi -O http://bookings:8080 -c zap-rules.tsv -J zap-report.json -r zap-report.html || true + high=$(jq '[.site[].alerts[] | select((.riskcode | tonumber) >= 2)] | length' zap/zap-report.json) + echo "medium or high findings: $high" + test "$high" -eq 0 + - uses: actions/upload-artifact@v4 + if: always() + with: + name: dast-report + path: zap/zap-report.* + + long-properties: + runs-on: ubuntu-latest + env: + CsCheck_Iter: "50000" + steps: + - uses: actions/checkout@v4 + with: + ref: v3.0.0 + - uses: actions/setup-dotnet@v4 + with: + global-json-file: global.json + - run: dotnet build SourceFlow.slnx -c Release + - run: dotnet test --solution SourceFlow.slnx ${{ env.TEST_ARGS }} --filter-trait "Category=Property" diff --git a/.github/workflows/v3-pr.yml b/.github/workflows/v3-pr.yml new file mode 100644 index 00000000..c28eefc2 --- /dev/null +++ b/.github/workflows/v3-pr.yml @@ -0,0 +1,323 @@ +# v3 required checks (implementation plan 08 §2). v2 workflows keep their master/release filters. +name: v3-pr + +on: + pull_request: + branches: [ "v3.0.0" ] + push: + branches: [ "v3.0.0" ] + +permissions: + contents: read + +concurrency: + group: v3-pr-${{ github.ref }} + cancel-in-progress: true + +env: + DOTNET_NOLOGO: "true" + DOTNET_CLI_TELEMETRY_OPTOUT: "true" + # Microsoft.Testing.Platform returns 8 when a filtered run selects no tests in a project + # (categories that have no tests yet). Real failures still fail the job. + # tests/CodeCoverage.settings.xml leaves out sample modules (child processes) and generated sources. + TEST_ARGS: "-c Release --no-build --ignore-exit-code 8 --coverage --coverage-output-format cobertura --coverage-settings ${{ github.workspace }}/tests/CodeCoverage.settings.xml --report-trx" + +jobs: + dependency-review: + # Doc 10 §7: new or updated dependencies with known vulnerabilities fail the PR. + if: github.event_name == 'pull_request' + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/dependency-review-action@v4 + with: + fail-on-severity: moderate + + build: + name: build (${{ matrix.os == 'ubuntu-latest' && 'ubuntu' || 'windows' }}) + strategy: + fail-fast: false + matrix: + os: [ ubuntu-latest, windows-latest ] + runs-on: ${{ matrix.os }} + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + - uses: actions/setup-dotnet@v4 + with: + global-json-file: global.json + - run: dotnet restore SourceFlow.slnx + - run: dotnet build SourceFlow.slnx -c Release --no-restore -warnaserror + - name: AOT publish check (ARCH-06) + if: matrix.os == 'ubuntu-latest' + # PublishAot is set inside the project: as a global property it would reach the netstandard2.0 generator (NETSDK1207). + run: | + dotnet publish tests/Fixtures/Bank/Bank.AotCheck/Bank.AotCheck.csproj -c Release -p:SourceFlowAotCheck=true -warnaserror + dotnet publish tests/Fixtures/Cloud.AotCheck/Cloud.AotCheck.csproj -c Release -p:SourceFlowAotCheck=true -warnaserror + + unit: + needs: build + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-dotnet@v4 + with: + global-json-file: global.json + - run: dotnet build SourceFlow.slnx -c Release + - name: Unit, architecture and in-memory conformance + run: >- + dotnet test --solution SourceFlow.slnx ${{ env.TEST_ARGS }} + --filter-not-trait "Requires=Docker" --filter-not-trait "Requires=LocalStack" + --filter-not-trait "Requires=PubSubEmulator" --filter-not-trait "Requires=ServiceBusEmulator" + --filter-not-trait "Requires=RealCloud" --filter-not-trait "Requires=Terraform" + --filter-not-trait "Category=Chaos" --filter-not-trait "Category=Performance" + - uses: actions/upload-artifact@v4 + if: always() + with: + name: unit-results + path: "**/TestResults/**" + + storage: + needs: build + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-dotnet@v4 + with: + global-json-file: global.json + - run: dotnet build SourceFlow.slnx -c Release + - name: Storage conformance kit and query compilers (Testcontainers) + run: >- + dotnet test --project tests/Storage/SourceFlow.Storage.Tests/SourceFlow.Storage.Tests.csproj + ${{ env.TEST_ARGS }} --filter-not-trait "Category=Chaos" + - uses: actions/upload-artifact@v4 + if: always() + with: + name: storage-results + path: "**/TestResults/**" + + transports: + name: transports (${{ matrix.cloud }}) + needs: build + strategy: + fail-fast: false + matrix: + include: + - cloud: aws + trait: Aws + compose: eng/emulators/localstack/docker-compose.yml + - cloud: gcp + trait: Gcp + compose: eng/emulators/pubsub/docker-compose.yml + - cloud: azure + trait: Azure + compose: eng/emulators/servicebus/docker-compose.yml + runs-on: ubuntu-latest + env: + MSSQL_SA_PASSWORD: ${{ secrets.EMULATOR_SA_PASSWORD || 'SourceFlow_Emulator_1' }} + AWS_ENDPOINT_URL: http://localhost:4566 + AWS_ACCESS_KEY_ID: test + AWS_SECRET_ACCESS_KEY: test + AWS_REGION: eu-west-1 + PUBSUB_EMULATOR_HOST: localhost:8085 + SERVICEBUS_EMULATOR_CONNECTION: "Endpoint=sb://localhost;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=SAS_KEY_VALUE;UseDevelopmentEmulator=true;" + SERVICEBUS_EMULATOR_ADMIN_CONNECTION: "Endpoint=sb://localhost:5300;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=SAS_KEY_VALUE;UseDevelopmentEmulator=true;" + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-dotnet@v4 + with: + global-json-file: global.json + - name: Start emulator + run: docker compose -f ${{ matrix.compose }} up -d + - name: Emulator health gate + shell: bash + run: | + for i in $(seq 1 90); do + case "${{ matrix.cloud }}" in + aws) curl -sf http://localhost:4566/_localstack/health | grep -q '"sqs": "available"' && exit 0 ;; + gcp) curl -sf -X PUT http://localhost:8085/v1/projects/sourceflow-emulator/topics/health >/dev/null && exit 0 ;; + azure) curl -sf http://localhost:5300/health >/dev/null && exit 0 ;; + esac + sleep 2 + done + echo "emulator not healthy"; exit 1 + - run: dotnet build SourceFlow.slnx -c Release + - name: Transport unit tests + emulator TCK + run: >- + dotnet test --project tests/Cloud/SourceFlow.Cloud.Tests/SourceFlow.Cloud.Tests.csproj + ${{ env.TEST_ARGS }} --filter-trait "Cloud=${{ matrix.trait }}" --filter-not-trait "Requires=RealCloud" --filter-not-trait "Requires=Terraform" + - uses: actions/upload-artifact@v4 + if: always() + with: + name: transports-${{ matrix.cloud }}-results + path: "**/TestResults/**" + + iac: + # deploy/topology (WP-3.5): the Terraform modules applied to LocalStack and the Pub/Sub emulator and checked with + # ProvisioningMode.Validate, every module's `terraform test` suite, and the Bicep module built for every fixture. + # deploy/observability (WP-4.3): promtool checks the generated alert rules (the unit job checks they are up to date). + needs: build + runs-on: ubuntu-latest + env: + AWS_ENDPOINT_URL: http://localhost:4566 + AWS_ACCESS_KEY_ID: test + AWS_SECRET_ACCESS_KEY: test + AWS_REGION: eu-west-1 + PUBSUB_EMULATOR_HOST: localhost:8085 + TF_PLUGIN_CACHE_DIR: ${{ github.workspace }}/.terraform-plugins + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-dotnet@v4 + with: + global-json-file: global.json + - uses: hashicorp/setup-terraform@v3 + with: + terraform_version: 1.9.8 + terraform_wrapper: false + - name: Bicep + run: az bicep install && az bicep version + - uses: actions/cache@v4 + with: + path: .terraform-plugins + key: terraform-plugins-${{ hashFiles('deploy/topology/terraform/**/*.tf') }} + - name: Start emulators + run: | + mkdir -p .terraform-plugins + docker compose -f eng/emulators/localstack/docker-compose.yml up -d + docker compose -f eng/emulators/pubsub/docker-compose.yml up -d + for i in $(seq 1 90); do + curl -sf http://localhost:4566/_localstack/health | grep -q '"sqs": "available"' && curl -sf -X PUT http://localhost:8085/v1/projects/sourceflow-emulator/topics/health >/dev/null && exit 0 + sleep 2 + done + echo "emulators not healthy"; exit 1 + - run: terraform fmt -check -recursive deploy/topology/terraform + - name: Prometheus alert rules (deploy/observability) + run: docker run --rm --entrypoint promtool -v "$PWD/deploy/observability:/rules:ro" prom/prometheus:v3.13.4 check rules /rules/sourceflow-alerts.yaml + - run: dotnet build SourceFlow.slnx -c Release + - name: IaC modules against the topology fixtures + run: >- + dotnet test --project tests/Cloud/SourceFlow.Cloud.Tests/SourceFlow.Cloud.Tests.csproj + ${{ env.TEST_ARGS }} --filter-trait "Requires=Terraform" + - uses: actions/upload-artifact@v4 + if: always() + with: + name: iac-results + path: "**/TestResults/**" + + e2e: + # E2E-17..24 run the Bank services on PostgreSQL (Testcontainers) over each emulator. + needs: [ unit, storage, transports ] + runs-on: ubuntu-latest + env: + MSSQL_SA_PASSWORD: ${{ secrets.EMULATOR_SA_PASSWORD || 'SourceFlow_Emulator_1' }} + AWS_ENDPOINT_URL: http://localhost:4566 + AWS_ACCESS_KEY_ID: test + AWS_SECRET_ACCESS_KEY: test + AWS_REGION: eu-west-1 + PUBSUB_EMULATOR_HOST: localhost:8085 + SERVICEBUS_EMULATOR_CONNECTION: "Endpoint=sb://localhost;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=SAS_KEY_VALUE;UseDevelopmentEmulator=true;" + SERVICEBUS_EMULATOR_ADMIN_CONNECTION: "Endpoint=sb://localhost:5300;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=SAS_KEY_VALUE;UseDevelopmentEmulator=true;" + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-dotnet@v4 + with: + global-json-file: global.json + - run: | + docker compose -f eng/emulators/localstack/docker-compose.yml up -d + docker compose -f eng/emulators/pubsub/docker-compose.yml up -d + docker compose -f eng/emulators/servicebus/docker-compose.yml up -d + for i in $(seq 1 90); do + curl -sf http://localhost:5300/health >/dev/null && exit 0 + sleep 2 + done + echo "Service Bus emulator not healthy"; exit 1 + - run: dotnet build SourceFlow.slnx -c Release + - name: End-to-end scenarios + run: >- + dotnet test --project tests/EndToEnd/SourceFlow.EndToEnd.Tests/SourceFlow.EndToEnd.Tests.csproj + ${{ env.TEST_ARGS }} --filter-not-trait "Category=Chaos" --filter-not-trait "Category=Performance" --filter-not-trait "Requires=RealCloud" + - uses: actions/upload-artifact@v4 + if: always() + with: + name: e2e-results + path: "**/TestResults/**" + + coverage: + needs: [ unit, storage, transports, e2e ] + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-dotnet@v4 + with: + global-json-file: global.json + - uses: actions/download-artifact@v4 + with: + path: results + - run: dotnet tool install -g dotnet-reportgenerator-globaltool + - name: Merge coverage + run: reportgenerator -reports:"results/**/*.cobertura.xml" -targetdir:coverage -reporttypes:"Cobertura;MarkdownSummaryGithub" + - name: Coverage gate (plan 04 §5) + run: dotnet run --project eng/CoverageGate/CoverageGate.csproj -c Release -- coverage/Cobertura.xml eng/CoverageGate/thresholds.json + - run: cat coverage/SummaryGithub.md >> "$GITHUB_STEP_SUMMARY" + + api-traceability: + needs: build + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-dotnet@v4 + with: + global-json-file: global.json + - run: dotnet build SourceFlow.slnx -c Release + - name: Public API approval and traceability (ARCH-08) + run: >- + dotnet test --solution SourceFlow.slnx -c Release --no-build --ignore-exit-code 8 + --filter-trait "Category=PublicApi" --filter-trait "Category=Architecture" + - name: TravelBooking manifest drift check (doc 15 §3.2, WP-S.2) + # Design-time export: each host is built but never started, so the unreachable connection string is never used. + shell: bash + run: | + set -e + for service in Bookings Hotels; do + dotnet src/Tooling/SourceFlow.Tool/bin/Release/net10.0/SourceFlow.Tool.dll manifest export \ + --project "samples/TravelBooking/$service.Api" -c Release --no-build --check \ + --output "samples/TravelBooking/$service/sourceflow.manifest.json" \ + -- "--ConnectionStrings:SourceFlow=Host=localhost;Port=1" + done + - name: OrderFulfilment sample manifest drift check (WP-S.13) + # The sample's host runs one service per Service setting; each service's manifest is exported and compared. + shell: bash + run: | + set -e + for service in orders inventory payments shipping; do + dotnet src/Tooling/SourceFlow.Tool/bin/Release/net10.0/SourceFlow.Tool.dll manifest export \ + --project samples/OrderFulfilment/OrderFulfilment.Host -c Release --no-build --check \ + --output "samples/OrderFulfilment/${service^}/sourceflow.manifest.json" \ + -- "--Service=$service" "--ConnectionStrings:SourceFlow=Host=localhost;Port=1" + done + + pack: + needs: coverage + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + - uses: actions/setup-dotnet@v4 + with: + global-json-file: global.json + - run: dotnet pack SourceFlow.slnx -c Release -o artifacts + - name: Verify package layout + shell: bash + run: | + set -e + pkg=$(ls artifacts/SourceFlow.Net.*.nupkg | head -1) + unzip -l "$pkg" | grep -q "analyzers/dotnet/cs/SourceFlow.Generators.dll" + for p in artifacts/*.nupkg; do + if unzip -l "$p" | grep " lib/" | grep -v " lib/net10.0/"; then echo "non-net10.0 lib in $p"; exit 1; fi + done + - uses: actions/upload-artifact@v4 + with: + name: packages + path: artifacts diff --git a/.github/workflows/v3-release.yml b/.github/workflows/v3-release.yml new file mode 100644 index 00000000..64f3691c --- /dev/null +++ b/.github/workflows/v3-release.yml @@ -0,0 +1,157 @@ +# v3 release (implementation plan 08 §6, doc 10 §7, WP-5.5): pack, SBOM, sign, attest, publish. +# push to v3.0.0 3.0.0-alpha. packages on GitHub Packages (signed when the certificate is configured) +# tag v3.0.0-rc.N, v3.* GitHub Packages and nuget.org, and a GitHub release with the SBOMs; author signing is required +# Secrets: NUGET_SIGNING_CERTIFICATE (base64 PFX) and NUGET_SIGNING_PASSWORD (repository); NUGET_API_KEY in the +# protected 'nuget-release' environment, so publishing to nuget.org needs a release approver. +name: v3-release + +on: + push: + branches: [ "v3.0.0" ] + tags: [ "v3.*" ] + workflow_dispatch: + +permissions: + contents: write # the GitHub release on tags + packages: write # alpha packages on GitHub Packages + id-token: write # Sigstore (keyless) attestations + attestations: write + +concurrency: + group: v3-release-${{ github.ref }} + cancel-in-progress: false + +env: + DOTNET_NOLOGO: "true" + CYCLONEDX_VERSION: 6.3.1 + TIMESTAMPER: http://timestamp.digicert.com + +jobs: + release: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + - uses: actions/setup-dotnet@v4 + with: + global-json-file: global.json + + - name: Version + id: version + shell: bash + run: | + if [[ "$GITHUB_REF_TYPE" == "tag" ]]; then + version="${GITHUB_REF_NAME#v}" + echo "release=true" >> "$GITHUB_OUTPUT" + else + version="3.0.0-alpha.${GITHUB_RUN_NUMBER}" + echo "release=false" >> "$GITHUB_OUTPUT" + fi + echo "version=$version" >> "$GITHUB_OUTPUT" + echo "prerelease=$([[ "$version" == *-* ]] && echo true || echo false)" >> "$GITHUB_OUTPUT" + + # The SourceFlow.Tool package embeds the Studio SPA and the WebAssembly core (`sourceflow studio`); build them first. + - uses: actions/setup-node@v4 + with: + node-version: "22.18" + cache: npm + cache-dependency-path: web/package-lock.json + - name: Build SourceFlow Studio (embedded in the tool) + working-directory: web + run: | + npm ci + npm run build:wasm + npm run build + + # Deterministic, CI (ContinuousIntegrationBuild, embedded untracked sources) and SourceLink builds: Directory.Build.props. + - name: Build + run: dotnet build SourceFlow.slnx -c Release -warnaserror -p:Version=${{ steps.version.outputs.version }} + + - name: Unit tests + run: >- + dotnet test --solution SourceFlow.slnx -c Release --no-build --ignore-exit-code 8 + --filter-trait "Category=Unit" --filter-not-trait "Requires=Docker" + + - name: Pack + run: dotnet pack SourceFlow.slnx -c Release --no-build -p:Version=${{ steps.version.outputs.version }} -o artifacts + + - name: SBOM (CycloneDX, one per package) + shell: bash + run: | + set -euo pipefail + dotnet tool install --global CycloneDX --version "$CYCLONEDX_VERSION" + mkdir -p artifacts/sbom + for project in $(find src -name '*.csproj' | sort); do + name=$(basename "$project" .csproj) + [[ -f "artifacts/$name.${{ steps.version.outputs.version }}.nupkg" ]] || continue # only shipped packages + dotnet-CycloneDX "$project" -o artifacts/sbom -fn "$name.cdx.json" -F Json -st Library \ + -sn "$name" -sv "${{ steps.version.outputs.version }}" -dpr + done + ls -l artifacts/sbom + + - name: Author signing + shell: bash + env: + CERTIFICATE: ${{ secrets.NUGET_SIGNING_CERTIFICATE }} + PASSWORD: ${{ secrets.NUGET_SIGNING_PASSWORD }} + run: | + set -euo pipefail + if [[ -z "$CERTIFICATE" ]]; then + if [[ "${{ steps.version.outputs.release }}" == "true" ]]; then + echo "::error::Release tags need NUGET_SIGNING_CERTIFICATE (doc 10 §7: packages are author-signed)." + exit 1 + fi + echo "::warning::NUGET_SIGNING_CERTIFICATE is not configured: alpha packages are unsigned (they still carry provenance attestations)." + exit 0 + fi + echo "$CERTIFICATE" | base64 --decode > "$RUNNER_TEMP/signing.pfx" + dotnet nuget sign artifacts/*.nupkg --certificate-path "$RUNNER_TEMP/signing.pfx" --certificate-password "$PASSWORD" --timestamper "$TIMESTAMPER" --overwrite + dotnet nuget verify --all artifacts/*.nupkg + rm -f "$RUNNER_TEMP/signing.pfx" + + - name: Provenance attestation + uses: actions/attest-build-provenance@v2 + with: + subject-path: "artifacts/*.nupkg" + + - uses: actions/upload-artifact@v4 + with: + name: packages-${{ steps.version.outputs.version }} + path: artifacts + + - name: Publish to GitHub Packages + run: >- + dotnet nuget push "artifacts/*.nupkg" --skip-duplicate + --source "https://nuget.pkg.github.com/${{ github.repository_owner }}/index.json" + --api-key "${{ secrets.GITHUB_TOKEN }}" + + outputs: + version: ${{ steps.version.outputs.version }} + release: ${{ steps.version.outputs.release }} + prerelease: ${{ steps.version.outputs.prerelease }} + + publish: + # Release tags only: nuget.org and the GitHub release, behind the environment's required reviewers. + needs: release + if: needs.release.outputs.release == 'true' + runs-on: ubuntu-latest + environment: nuget-release + steps: + - uses: actions/download-artifact@v4 + with: + name: packages-${{ needs.release.outputs.version }} + path: artifacts + - uses: actions/setup-dotnet@v4 + with: + dotnet-version: "10.0.x" + - name: Publish to nuget.org + run: dotnet nuget push "artifacts/*.nupkg" --skip-duplicate --source https://api.nuget.org/v3/index.json --api-key "${{ secrets.NUGET_API_KEY }}" + - name: GitHub release with the SBOMs + shell: bash + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + flags=(--repo "$GITHUB_REPOSITORY" --generate-notes --title "SourceFlow.Net ${{ needs.release.outputs.version }}") + [[ "${{ needs.release.outputs.prerelease }}" == "true" ]] && flags+=(--prerelease) + gh release create "$GITHUB_REF_NAME" artifacts/*.nupkg artifacts/*.snupkg artifacts/sbom/*.cdx.json "${flags[@]}" diff --git a/.github/workflows/v3-scorecard.yml b/.github/workflows/v3-scorecard.yml new file mode 100644 index 00000000..eaeff4d0 --- /dev/null +++ b/.github/workflows/v3-scorecard.yml @@ -0,0 +1,41 @@ +# OpenSSF Scorecard (doc 10 §7: target score ≥ 7). Results go to code scanning. +# +# scorecard-action accepts only pull requests and the default branch: any other push fails its option +# validation whatever publish_results says. So it scores pull requests into master (v3.0.0 among them) +# and master itself, and publishes only from master. +name: v3-scorecard + +on: + schedule: + - cron: "30 4 * * 1" + push: + branches: [ "master" ] + pull_request: + branches: [ "master" ] + workflow_dispatch: + +permissions: read-all + +jobs: + analysis: + # A manual run from another branch would be refused by the action; skip it instead. + if: >- + github.event_name == 'schedule' || github.event_name == 'pull_request' || + github.ref_name == github.event.repository.default_branch + runs-on: ubuntu-latest + permissions: + security-events: write # upload the SARIF + id-token: write # publish the results + steps: + - uses: actions/checkout@v4 + with: + persist-credentials: false + # v2.4.1+ pull the action image from ghcr.io; the gcr.io image of v2.4.0 can no longer be pulled. + - uses: ossf/scorecard-action@v2.5.0 + with: + results_file: scorecard.sarif + results_format: sarif + publish_results: ${{ github.event_name != 'pull_request' }} + - uses: github/codeql-action/upload-sarif@v3 + with: + sarif_file: scorecard.sarif diff --git a/.github/workflows/v3-weekly.yml b/.github/workflows/v3-weekly.yml new file mode 100644 index 00000000..58f1d332 --- /dev/null +++ b/.github/workflows/v3-weekly.yml @@ -0,0 +1,81 @@ +# v3 weekly (implementation plan 08 §1): coverage-guided fuzzing of every parser that reads untrusted bytes, 2 hours per +# target (doc 10 §7, WP-5.5). Mutation testing and the licence report join this workflow with their work packages. +name: v3-weekly + +on: + schedule: + - cron: "0 3 * * 0" + workflow_dispatch: + inputs: + seconds: + description: "Fuzzing time per target, in seconds" + default: "7200" + +permissions: + contents: read + +env: + DOTNET_NOLOGO: "true" + # libFuzzer driver for SharpFuzz, built from source at a pinned release (no prebuilt binary is downloaded). + LIBFUZZER_DOTNET_REF: v2025.05.02.0904 + SHARPFUZZ_VERSION: 2.3.0 + +jobs: + fuzz: + name: fuzz (${{ matrix.target }}) + runs-on: ubuntu-latest + timeout-minutes: 180 + strategy: + fail-fast: false + matrix: + target: + - cloudevents-binary + - cloudevents-structured + - aws-wire + - gcp-wire + - azure-wire + - registry + - protected-payload + - personal-data + - sfql + - sql + steps: + - uses: actions/checkout@v4 + with: + ref: v3.0.0 + - uses: actions/setup-dotnet@v4 + with: + global-json-file: global.json + + - name: Build libfuzzer-dotnet + run: | + git clone --depth 1 --branch "$LIBFUZZER_DOTNET_REF" https://github.com/Metalnem/libfuzzer-dotnet.git "$RUNNER_TEMP/libfuzzer-dotnet" + clang -fsanitize=fuzzer "$RUNNER_TEMP/libfuzzer-dotnet/libfuzzer-dotnet.cc" -o "$RUNNER_TEMP/libfuzzer-dotnet/libfuzzer-dotnet" + + - name: Publish and instrument the harness + run: | + dotnet tool install --global SharpFuzz.CommandLine --version "$SHARPFUZZ_VERSION" + dotnet publish quality/fuzz/SourceFlow.Fuzz -c Release -o fuzz-bin + # Instrument SourceFlow and the sample domain only: the harness and SDK assemblies don't need coverage. + for dll in fuzz-bin/SourceFlow.*.dll fuzz-bin/Bank.*.dll; do + case "$dll" in *SourceFlow.Fuzz.dll|*SourceFlow.Generators.dll) continue ;; esac + sharpfuzz "$dll" + done + dotnet fuzz-bin/SourceFlow.Fuzz.dll corpus corpus + + - name: Fuzz ${{ matrix.target }} + env: + SOURCEFLOW_FUZZ_TARGET: ${{ matrix.target }} + run: | + mkdir -p findings + "$RUNNER_TEMP/libfuzzer-dotnet/libfuzzer-dotnet" \ + --target_path=dotnet --target_arg=fuzz-bin/SourceFlow.Fuzz.dll \ + -max_total_time="${{ github.event.inputs.seconds || '7200' }}" -timeout=10 -rss_limit_mb=4096 \ + -artifact_prefix=findings/ -dict="corpus/${{ matrix.target }}.dict" \ + "corpus/${{ matrix.target }}" + + - uses: actions/upload-artifact@v4 + if: failure() + with: + name: fuzz-findings-${{ matrix.target }} + path: findings/ diff --git a/.github/workflows/workflow-diff.yml b/.github/workflows/workflow-diff.yml new file mode 100644 index 00000000..95d21604 --- /dev/null +++ b/.github/workflows/workflow-diff.yml @@ -0,0 +1,54 @@ +# Workflow diff (doc 15 §6.3, WFD-36; WP-S.12): on a pull request that changes *.sfflow.yaml, the before and after +# statecharts as SVGs (the run's workflow-diff artifact) and a comment with the changes and Mermaid diagrams. It runs +# the action from this repository (web/actions/workflow-diff), built with the WebAssembly core of the same commit. +name: workflow-diff + +on: + pull_request: + branches: [ "v3.0.0" ] + paths: [ "**/*.sfflow.yaml" ] + +permissions: + contents: read + pull-requests: write + +concurrency: + group: workflow-diff-${{ github.event.pull_request.number }} + cancel-in-progress: true + +env: + DOTNET_NOLOGO: "true" + DOTNET_CLI_TELEMETRY_OPTOUT: "true" + +jobs: + diff: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 # the base commit's files too + - uses: actions/setup-dotnet@v4 + with: + global-json-file: global.json + - uses: actions/setup-node@v4 + with: + node-version: "22.18" + cache: npm + cache-dependency-path: web/package-lock.json + - name: Build the action and its WebAssembly core + working-directory: web + run: | + npm ci + npm run build:wasm + npm run build:action + - name: Diff the workflows + uses: ./web/actions/workflow-diff + with: + out: workflow-diff + # A pull request from a fork gets a read-only token: the SVGs are still uploaded. + comment: ${{ github.event.pull_request.head.repo.full_name == github.repository }} + - uses: actions/upload-artifact@v4 + with: + name: workflow-diff + path: workflow-diff + if-no-files-found: ignore diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..87b6fd18 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,37 @@ +# Contributing to SourceFlow.Net v3 + +v3 is being built on the **`v3.0.0`** integration branch according to the plans in [`docs/v3.0.0/engineering/implementation`](docs/v3.0.0/engineering/implementation/README.md). `master` carries v2 until the GA cutover. + +## Branches + +| Branch | Use | +|--------|-----| +| `v3.0.0` | Integration branch. Protected: changes arrive by pull request only (squash merge) | +| `v3/-` | One branch per work package, e.g. `v3/wp-1.6-command-processor`, or per milestone slice, e.g. `v3/m1-core`. Branch from `v3.0.0`, open the PR back into `v3.0.0` | +| `master` | v2 hotfixes only. Record each one in the [forward-port log](docs/v3.0.0/engineering/implementation/forward-port-log.md) | + +Never create a tag named `v3.0.0` while the `v3.0.0` branch exists (implementation plan 02 §2). Pre-release tags such as `v3.0.0-rc.1` are fine. + +## Pull requests + +A PR into `v3.0.0` merges only when it meets the work package's **Definition of Done** ([plan 09 §1](docs/v3.0.0/engineering/implementation/09-Definition-of-Done-Risks-and-Tracking.md#1-definition-of-done-per-work-package)): + +- every deliverable and test ID assigned to the work package exists and passes; +- tests carry `[Trait("Id", "…")]` and `[Trait("Covers", "…")]`; +- coverage meets [plan 04 §5](docs/v3.0.0/engineering/implementation/04-Test-Strategy-and-Coverage.md#5-coverage-targets-and-enforcement); +- the public API approval files are updated and reviewed; +- the build has zero warnings and no AOT or trimming warnings; +- any divergence from the design is written into the design docs in the same PR. + +## Building and testing + +```bash +dotnet build SourceFlow.slnx -c Release +dotnet test --solution SourceFlow.slnx -c Release --filter-not-trait "Category=Integration" +``` + +`dotnet test` runs on Microsoft.Testing.Platform (opted in by `global.json`), so filters use the xUnit v3 options (`--filter-trait`, `--filter-not-trait`, `--filter-query`), not the VSTest `--filter` syntax. + +Integration tests need Docker. See [plan 06](docs/v3.0.0/engineering/implementation/06-Integration-and-E2E-Test-Plan.md). + +Update [`STATUS.md`](docs/v3.0.0/engineering/implementation/STATUS.md) in the PR that completes a work package. diff --git a/Directory.Build.props b/Directory.Build.props new file mode 100644 index 00000000..12a96317 --- /dev/null +++ b/Directory.Build.props @@ -0,0 +1,38 @@ + + + + + net10.0 + latest + enable + enable + true + SourceFlow.Net contributors + CodeShayk + Copyright © SourceFlow.Net contributors + MIT + https://github.com/CodeShayk/SourceFlow.Net + https://github.com/CodeShayk/SourceFlow.Net + git + + 3.0.0-alpha.0 + + true + latest + + + + true + true + + diff --git a/Directory.Build.targets b/Directory.Build.targets new file mode 100644 index 00000000..d0f7079d --- /dev/null +++ b/Directory.Build.targets @@ -0,0 +1,14 @@ + + + + + + + + + + diff --git a/Directory.Packages.props b/Directory.Packages.props new file mode 100644 index 00000000..88db79b8 --- /dev/null +++ b/Directory.Packages.props @@ -0,0 +1,79 @@ + + + + 16.3.0 + + + + true + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/GitVersion.yml b/GitVersion.yml index 1ec30612..00f5584e 100644 --- a/GitVersion.yml +++ b/GitVersion.yml @@ -1,4 +1,4 @@ -next-version: 2.0.0 +next-version: 3.0.0 tag-prefix: '[vV]' mode: ContinuousDeployment branches: @@ -29,6 +29,19 @@ branches: increment: Inherit regex: ^(pull|pull\-requests|pr)[/-] source-branches: ['master', 'develop', 'release', 'pre-release'] + v3: + # v3.0.0 integration branch (implementation plan 02 §2). Switch tag to 'rc' at M6 (WP-6.3). + regex: ^v3\.0\.0$ + tag: alpha + increment: None + prevent-increment-of-merged-branch-version: true + source-branches: ['master'] + v3-work: + # Work-package branches: v3/- (implementation plan 02 §1) + regex: ^v3/ + tag: '{BranchName}' + increment: Inherit + source-branches: ['v3'] feature: tag: '{BranchName}' increment: Inherit diff --git a/README.md b/README.md index 22bb3e06..7d68efa4 100644 --- a/README.md +++ b/README.md @@ -1,176 +1,212 @@ -# event SourceFlow.Net v2.0.0 -[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/CodeShayk/SourceFlow.Net/blob/master/LICENSE.md) +# event SourceFlow.Net v3.0.0 +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/CodeShayk/SourceFlow.Net/blob/master/LICENSE) [![GitHub Release](https://img.shields.io/github/v/release/CodeShayk/SourceFlow.Net?logo=github&sort=semver)](https://github.com/CodeShayk/SourceFlow.Net/releases/latest) -[![master-build](https://github.com/CodeShayk/SourceFlow.Net/actions/workflows/Master-Build.yml/badge.svg)](https://github.com/CodeShayk/SourceFlow.Net/actions/workflows/Master-Build.yml) -[![master-codeql](https://github.com/CodeShayk/SourceFlow.Net/actions/workflows/Master-CodeQL.yml/badge.svg)](https://github.com/CodeShayk/SourceFlow.Net/actions/workflows/Master-CodeQL.yml) +[![v3-pr](https://github.com/CodeShayk/SourceFlow.Net/actions/workflows/v3-pr.yml/badge.svg?branch=v3.0.0)](https://github.com/CodeShayk/SourceFlow.Net/actions/workflows/v3-pr.yml) +[![.Net 10](https://img.shields.io/badge/.Net-10-blue)](https://dotnet.microsoft.com/en-us/download/dotnet/10.0)

- A modern, lightweight, and extensible .NET framework for building event-sourced applications using Domain-Driven Design (DDD) principles and Command Query Responsibility Segregation (CQRS) patterns. + An event-sourcing and CQRS framework for .NET 10: pure aggregates, effectively-once messaging across services, projections, a query language, workflows you can draw, and the tools to run them in production.

--- ## Overview -SourceFlow.Net empowers developers to build scalable, maintainable applications by providing a complete toolkit for event sourcing, domain modeling, and command/query separation. Built from the ground up for .NET 9.0 with **performance** and **developer experience** as core priorities. - -### Key Features -* 🏗️ **Domain-Driven Design Support** - First-class support for aggregates, entities, value objects -* ⚡ **CQRS Implementation** - Complete command/query separation with optimized read models -* 📊 **Event Sourcing Foundation** - Event-first design with full audit trail -* 🧱 **Clean Architecture** - Clear separation of concerns and dependency management -* 💾 **Flexible Persistence** - Multiple storage options including Entity Framework Core -* 🔄 **Event Replay** - Built-in command replay for debugging and state reconstruction -* 🎯 **Type Safety** - Strongly-typed commands, events, and projections -* 📦 **Dependency Injection** - Seamless integration with .NET DI container -* 📈 **OpenTelemetry Integration** - Built-in distributed tracing and metrics for operations at scale -* ⚡ **Memory Optimization** - ArrayPool-based optimization for extreme throughput scenarios -* 🛡️ **Resilience Patterns** - Polly integration for fault tolerance with retry policies and circuit breakers - -### Core Concepts - -#### v1.0.0 Architecture - -**Aggregates** -- An `Aggregate` encapsulates a root domain entity within a bounded context (microservice) -- Changes to aggregates are initiated by publishing commands -- Aggregates subscribe to events to react to external changes from other sagas or workflows that may affect their state - -**Sagas** -- A `Saga` represents a long-running transaction that orchestrates complex business processes -- Sagas subscribe to commands and execute the actual updates to aggregate entities -- They manage both success and failure flows to ensure data consistency and preserve aggregate state -- Sagas can publish commands to themselves or other sagas to coordinate multi-step workflows -- Events can be raised by sagas during command handling to notify other components of state changes - -**Events** -- Events are published to interested subscribers when state changes occur -- Two primary event subscribers exist in the framework: - - **Aggregates**: React to events from external workflows that impact their domain state - - **Views**: Project event data into optimized read models for query operations - -**Views** -- Views subscribe to events and transform domain data into denormalized view models -- View models provide optimized read access for consumers such as UIs or reporting systems -- Data in view models follows eventual consistency patterns - -#### v2.0.0 Roadmap (Cloud Integration) - -**Command Dispatcher** -- Dispatches commands to cloud-based message queues for distributed processing -- Targets specific command queues based on bounded context routing -- Configured using the Bus Configuration System fluent API - -**Command Queue** -- A dedicated queue for each bounded context (microservice) -- Routes incoming commands to the appropriate subscribing sagas within the domain - -**Event Dispatcher** -- Publishes domain events to cloud-based topics for cross-service communication -- Enables event-driven architecture across distributed systems -- Configured using the Bus Configuration System fluent API - -**Event Listeners** -- Bootstrap components that listen to subscribed event topics -- Dispatch received events to the appropriate aggregates and views within each domain context -- Enable seamless integration across bounded contexts - -**Bus Configuration System** -- Code-first fluent API for configuring command and event routing -- Automatic resource creation (queues, topics, subscriptions) -- Type-safe configuration with compile-time validation -- Simplified setup using short names instead of full URLs/ARNs -- See [Cloud Configuration Guide](docs/SourceFlow.Net-README.md#-cloud-configuration-with-bus-configuration-system) for details - -#### Architecture -architecture - -Click on **[Architecture](https://github.com/CodeShayk/SourceFlow.Net/blob/master/docs/Architecture/README.md)** for more details on how to extend SourceFlow.Net for bespoke requirements. - - -### RoadMap - -| Package | Version | Release Date |Details |.Net Frameworks| -|------|---------|--------------|--------|-----------| -|SourceFlow|v2.0.0 [![NuGet version](https://badge.fury.io/nu/SourceFlow.Net.svg)](https://badge.fury.io/nu/SourceFlow.Net)|15th Mar 2026|v1.0.0 Core functionality with integrated cloud abstractions. Cloud.Core consolidated into main package. Breaking changes: namespace updates from SourceFlow.Cloud.Core.* to SourceFlow.Cloud.*|[![.Net 10](https://img.shields.io/badge/.Net-10-blue)](https://dotnet.microsoft.com/en-us/download/dotnet/10.0) [![.Net 9.0](https://img.shields.io/badge/.Net-9.0-blue)](https://dotnet.microsoft.com/en-us/download/dotnet/9.0) [![.Net Standard 2.1](https://img.shields.io/badge/.NetStandard-2.1-blue)](https://github.com/dotnet/standard/blob/v2.1.0/docs/versions/netstandard2.1.md) [![.Net Standard 2.0](https://img.shields.io/badge/.NetStandard-2.0-blue)](https://github.com/dotnet/standard/blob/v2.0.0/docs/versions/netstandard2.0.md)| -|SourceFlow|v1.0.0|29th Nov 2025|Initial stable release with event sourcing and CQRS|[![.Net 10](https://img.shields.io/badge/.Net-10-blue)](https://dotnet.microsoft.com/en-us/download/dotnet/10.0) [![.Net 9.0](https://img.shields.io/badge/.Net-9.0-blue)](https://dotnet.microsoft.com/en-us/download/dotnet/9.0) [![.Net Standard 2.1](https://img.shields.io/badge/.NetStandard-2.1-blue)](https://github.com/dotnet/standard/blob/v2.1.0/docs/versions/netstandard2.1.md) [![.Net Standard 2.0](https://img.shields.io/badge/.NetStandard-2.0-blue)](https://github.com/dotnet/standard/blob/v2.0.0/docs/versions/netstandard2.0.md) [![.Net Framework 4.6.2](https://img.shields.io/badge/.Net-4.6.2-blue)](https://dotnet.microsoft.com/en-us/download/dotnet-framework/net46)| -|SourceFlow.Stores.EntityFramework|v2.0.0 [![NuGet version](https://badge.fury.io/nu/SourceFlow.Stores.EntityFramework.svg)](https://badge.fury.io/nu/SourceFlow.Stores.EntityFramework)|29th Nov 2025|v1.0.0 Core EF store implementations with new cloud idempotency provider implementation. |[![.Net 10](https://img.shields.io/badge/.Net-10-blue)](https://dotnet.microsoft.com/en-us/download/dotnet/10.0) [![.Net 9.0](https://img.shields.io/badge/.Net-9.0-blue)](https://dotnet.microsoft.com/en-us/download/dotnet/9.0) [![.Net 8.0](https://img.shields.io/badge/.Net-8.0-blue)](https://dotnet.microsoft.com/en-us/download/dotnet/8.0) [![.Net Standard 2.1](https://img.shields.io/badge/.NetStandard-2.1-blue)](https://github.com/dotnet/standard/blob/v2.1.0/docs/versions/netstandard2.1.md) [![.Net Standard 2.0](https://img.shields.io/badge/.NetStandard-2.0-blue)](https://github.com/dotnet/standard/blob/v2.0.0/docs/versions/netstandard2.0.md)| -|SourceFlow.Stores.EntityFramework|v1.0.0 |29th Nov 2025|Provides store implementation using EF. Can configure different (types of ) databases for each store.|[![.Net 10](https://img.shields.io/badge/.Net-10-blue)](https://dotnet.microsoft.com/en-us/download/dotnet/10.0) [![.Net 9.0](https://img.shields.io/badge/.Net-9.0-blue)](https://dotnet.microsoft.com/en-us/download/dotnet/9.0) [![.Net 8.0](https://img.shields.io/badge/.Net-8.0-blue)](https://dotnet.microsoft.com/en-us/download/dotnet/8.0) [![.Net Standard 2.1](https://img.shields.io/badge/.NetStandard-2.1-blue)](https://github.com/dotnet/standard/blob/v2.1.0/docs/versions/netstandard2.1.md) [![.Net Standard 2.0](https://img.shields.io/badge/.NetStandard-2.0-blue)](https://github.com/dotnet/standard/blob/v2.0.0/docs/versions/netstandard2.0.md)| -|SourceFlow.Cloud.AWS|v2.0.0 |15th Mar 2026 |Provides support for AWS cloud with cross domain boundary command and Event publishing & subscription. Includes comprehensive testing framework with LocalStack integration, performance benchmarks, security validation, and resilience testing.|[![.Net 10](https://img.shields.io/badge/.Net-10-blue)](https://dotnet.microsoft.com/en-us/download/dotnet/10.0) [![.Net 9.0](https://img.shields.io/badge/.Net-9.0-blue)](https://dotnet.microsoft.com/en-us/download/dotnet/9.0) [![.Net 8.0](https://img.shields.io/badge/.Net-8.0-blue)](https://dotnet.microsoft.com/en-us/download/dotnet/8.0)| -|SourceFlow.Cloud.Azure|v2.0.0 |(TBC) |Provides support for Azure cloud with cross domain boundary command and Event publishing & subscription. Includes comprehensive testing framework with Azurite integration, performance benchmarks, security validation, and resilience testing.|[![.Net 10](https://img.shields.io/badge/.Net-10-blue)](https://dotnet.microsoft.com/en-us/download/dotnet/10.0) [![.Net 9.0](https://img.shields.io/badge/.Net-9.0-blue)](https://dotnet.microsoft.com/en-us/download/dotnet/9.0) [![.Net 8.0](https://img.shields.io/badge/.Net-8.0-blue)](https://dotnet.microsoft.com/en-us/download/dotnet/8.0)| -## Companion Book - - - From Problems to Patterns: Domain-Driven Design and Event Sourcing in .NET - - -**From Problems to Patterns — Domain-Driven Design and Event Sourcing in .NET** -*By Najaf A. Shaikh · First Edition, 2026* +SourceFlow.Net lets you build a domain as event-sourced services. You write aggregates as pure functions that decide +events from commands, and the framework stores the events, keeps your read models up to date, moves commands and events +between services over the cloud broker of your choice, and runs long-lived workflows between them. Messages are handled +effectively once, everything is traced and measured with OpenTelemetry, and a source generator replaces reflection, so +services start fast and work with Native AOT and trimming. + +v3.0.0 is a redesign of v2 for .NET 10. If you are upgrading, read [what changed](docs/v3.0.0/reference/Versions/v3.0.0/CHANGELOG.md) +and the [migration guide](docs/v3.0.0/reference/guides/migrating-from-v2.md); v2 is documented in [docs/legacy-version](docs/legacy-version). + +### Key features + +- **Fluent configuration.** One `AddSourceFlow(sf => sf…)` chain enables a service and its features: storage, broker, + health checks, the query API, security, provisioning and node roles, each off until enabled, and `When(…)` to follow + configuration. +- **Event-sourced aggregates as pure deciders.** `Decide(command, context)` returns a `Decision` (accept with events, + reject with an error, or no-op); `When(event)` evolves the state. No base classes, no I/O in the domain, trivial to test. +- **Business rejections are values.** A rejection is an `Error` with a stable code, returned to the caller (HTTP 422) or + sent back to the service that asked, never an exception. +- **Source generation instead of reflection.** A module per assembly registers its aggregates, handlers, projections, + process managers and message types; analyzers catch mistakes at build time (SF0001 and on). +- **Effectively-once messaging.** A transactional outbox and per-consumer inbox in the same store as the events, idempotent + command ids, optimistic concurrency with automatic re-decide. +- **One command owner, many subscribers.** Commands are routed to the one service that owns them, locally or over the broker; + events are published to topics and subscribed to by others. +- **Persistence.** PostgreSQL and SQL Server event stores with a commit-ordered, gap-free global position; an in-memory store + for tests and development. +- **Projections and read models.** Inline (same transaction) or async (partitioned, fenced subscriptions with checkpoints), + document projections, EF Core projections, rebuilds with blue/green generations. +- **Cloud transports with parity.** AWS (SNS/SQS), Azure (Service Bus) and Google Cloud (Pub/Sub), all passing one + conformance kit, plus an in-memory reference broker; provisioning modes and topology as data. +- **Query side.** Named, versioned domain queries bound at startup, and SFQL, a query language with CESQL predicates compiled + to injection-proof SQL, served by a per-service query API. +- **Workflows and SourceFlow Studio.** Write a workflow between services in YAML; the build compiles it into a process manager + with retries, timeouts, compensation and operator hand-off. Studio draws, validates, simulates and tests it in the browser. +- **Security and compliance.** Encryption of personal data with per-subject keys and crypto-shredding (AWS KMS, Azure Key + Vault, Google Cloud KMS), redaction, multi-tenancy with row-level security. +- **Operations.** OpenTelemetry traces and metrics with standard semantic conventions, health checks, dashboards and alerts, + and the `dotnet sourceflow` CLI for schema, streams, projections, parked messages, manifests and workflows. + +### A taste -The complete, runnable companion code for all 32 chapters of the book is available in the [dd-event-sourcing-dotnet-samples](https://github.com/CodeShayk/dd-event-sourcing-dotnet-samples) repository. Every code example builds and all tests pass. The code evolves chapter by chapter through a single Bank Account domain — starting from a naive CRUD implementation and ending with a containerised, observable, event-sourced system built on **SourceFlow.Net**. +```csharp +[StronglyTypedId] +public readonly partial record struct AccountId(Guid Value); + +[MessageType("bank.account.deposit", 1)] +public sealed record Deposit(AccountId AccountId, decimal Amount) : ICommand; + +[MessageType("bank.account.deposited", 1)] +public sealed record MoneyDeposited(AccountId AccountId, decimal Amount, decimal BalanceAfter) : IEvent; + +[Aggregate("bank-account")] +public sealed partial record BankAccount : IAggregate +{ + public static BankAccount Initial { get; } = new(); + public AccountStatus Status { get; init; } + public decimal Balance { get; init; } + + public Decision Decide(Deposit c, DecisionContext ctx) => this switch + { + { Status: not AccountStatus.Open } => Decision.Reject(AccountErrors.NotOpen), + _ when c.Amount <= 0 => Decision.Reject(AccountErrors.AmountMustBePositive), + _ => Decision.Accept(new MoneyDeposited(c.AccountId, c.Amount, Balance + c.Amount)), + }; + + private BankAccount When(MoneyDeposited e) => this with { Balance = e.BalanceAfter }; +} + +[SourceFlowModule(typeof(AccountsJsonContext))] +public sealed partial class AccountsModule; +``` -## Getting Started -### Installation -add nuget packages for SourceFlow.Net -> - dotnet add package SourceFlow.Net -> - dotnet add package SourceFlow.Stores.EntityFramework -> - dotnet add package SourceFlow.Cloud.AWS -> - add custom implementation for stores, and extend for your cloud. +```csharp +// One fluent chain enables the service and the features it uses +builder.Services.AddSourceFlow(sf => sf + .WithServiceName("bank") + .AddModule() + .UsePostgreSql(connectionString) + .UseAwsTransport(o => o.Region = "eu-west-1") // or UseAzureTransport, UseGcpTransport, UseInMemoryTransport + .WithHealthChecks() + .When(configuration.GetValue("Features:QueryApi"), s => s.WithQueryApi())); + +app.MapSourceFlowHealthChecks(); // /health, /health/ready, /health/sourceflow +// 200 with an ETag, 202 when sent on to its owner, 422 for a rejection, 409 for a conflict +app.MapCommand("/accounts/{accountId}/deposits"); +``` -### Cloud Integration with Idempotency +```csharp +CommandResult result = await sender.SendAsync(new Deposit(accountId, 50m)); // ICommandSender +// result.Status: Accepted, NoOp, Rejected, Conflict, Duplicate or Dispatched (sent to its owner) +``` -When deploying SourceFlow.Net applications to the cloud with AWS or Azure, idempotency is crucial for handling duplicate messages in distributed systems. +The [TravelBooking sample](samples/TravelBooking) is two services, Bookings and Hotels, and the workflow between them. + +### Architecture + +```mermaid +flowchart LR + client([HTTP / ICommandSender]) --> router{Routing} + router -- owned here --> agg[Aggregate
Decide / When] + router -- owned elsewhere --> outbox + agg --> store[(Event store
events + outbox + inbox)] + store --> inline[Inline projections] + store --> subs[Async subscriptions] --> rm[(Read models)] + store --> pm[Process managers
and workflows] --> router + store --> outbox[Outbox relay] --> broker[[AWS / Azure / GCP
or in-memory]] + broker --> inbox[Receivers + inbox] + inbox -- commands --> router + inbox -- remote events --> pm + rm --> query[Domain queries / SFQL query API] +``` -#### Single-Instance Deployments (Default) +One core package holds the programming model, the runtime and the extensibility interfaces (SPIs); adapters implement them +for each database and cloud. See the [architecture documentation](docs/v3.0.0/reference/Architecture/README.md). + +## Packages + +Every package targets **.NET 10** (`net10.0`). + +| Package | What it does | Docs | +|---------|--------------|------| +| `SourceFlow.Net` | Core: programming model, runtime, outbox/inbox, subscriptions, middleware, telemetry, in-memory adapters, SPIs. Includes the source generator and analyzers. | [README](docs/v3.0.0/reference/SourceFlow.Net-README.md) | +| `SourceFlow.Storage.PostgreSQL` | Event store, outbox, inbox, checkpoints, leases and documents on PostgreSQL; SFQL compiler. | [README](docs/v3.0.0/reference/SourceFlow.Storage.PostgreSQL-README.md) | +| `SourceFlow.Storage.SqlServer` | The same on SQL Server. | [README](docs/v3.0.0/reference/SourceFlow.Storage.SqlServer-README.md) | +| `SourceFlow.Storage.EntityFrameworkCore` | EF Core read-model projections in the SourceFlow transaction. | [README](docs/v3.0.0/reference/SourceFlow.Storage.EntityFrameworkCore-README.md) | +| `SourceFlow.Cloud.Aws` | SNS/SQS transport, provisioner, AWS KMS keys. | [README](docs/v3.0.0/reference/SourceFlow.Cloud.Aws-README.md) | +| `SourceFlow.Cloud.Azure` | Service Bus transport, provisioner, Azure Key Vault keys. | [README](docs/v3.0.0/reference/SourceFlow.Cloud.Azure-README.md) | +| `SourceFlow.Cloud.Gcp` | Pub/Sub transport, provisioner, Google Cloud KMS keys. | [README](docs/v3.0.0/reference/SourceFlow.Cloud.Gcp-README.md) | +| `SourceFlow.AspNetCore` | Command endpoints, domain query endpoints, the query API, health checks. | [README](docs/v3.0.0/reference/SourceFlow.AspNetCore-README.md) | +| `SourceFlow.Testing` | Given/When/Then specs, workflow specs, in-memory test host, storage and transport conformance kits. | [README](docs/v3.0.0/reference/SourceFlow.Testing-README.md) | +| `SourceFlow.Tool` | The `sourceflow` command-line .NET tool (`dotnet sourceflow`), which also runs inside a service; it embeds SourceFlow Studio. | [README](docs/v3.0.0/reference/SourceFlow.Tool-README.md) | +| `SourceFlow.Studio` | Service manifests, domain workspace, workflow DSL, validator, simulator, exporters; the Studio web app (`web/app`) and the `workflow-diff` GitHub Action (`web/actions/workflow-diff`), which are to be published as `@sourceflow/studio` and `sourceflow/workflow-diff`. | [README](docs/v3.0.0/reference/SourceFlow.Studio-README.md) | + +### Roadmap + +| Package | Version | Release date | Details | .NET | +|---------|---------|--------------|---------|------| +| SourceFlow.Net and the packages above | v3.0.0 | Unreleased | Redesign: event sourcing with pure deciders, source generation, outbox/inbox, PostgreSQL and SQL Server stores, AWS/Azure/GCP transports with parity, SFQL query side, workflows and Studio. See the [changelog](docs/v3.0.0/reference/Versions/v3.0.0/CHANGELOG.md). | [![.Net 10](https://img.shields.io/badge/.Net-10-blue)](https://dotnet.microsoft.com/en-us/download/dotnet/10.0) | +| SourceFlow | v2.0.0 [![NuGet version](https://badge.fury.io/nu/SourceFlow.Net.svg)](https://badge.fury.io/nu/SourceFlow.Net) | 15th Mar 2026 | Core functionality with integrated cloud abstractions ([docs](docs/legacy-version/SourceFlow.Net-README.md)). | .NET 10, 9, Standard 2.1, 2.0 | +| SourceFlow | v1.0.0 | 29th Nov 2025 | Initial stable release with event sourcing and CQRS. | .NET 10, 9, Standard 2.1, 2.0, Framework 4.6.2 | + +## Getting started + +```bash +dotnet add package SourceFlow.Net +dotnet add package SourceFlow.Storage.PostgreSQL # or SourceFlow.Storage.SqlServer +dotnet add package SourceFlow.AspNetCore # HTTP command endpoints and health checks +dotnet add package SourceFlow.Cloud.Aws # or .Azure / .Gcp, when services talk over a broker +``` -For single-instance deployments, SourceFlow automatically uses an in-memory idempotency service: +The `sourceflow` CLI is a .NET tool (`dotnet tool install --global SourceFlow.Tool`, once 3.0 packages are published), +runs inside your service (`dotnet run -- sourceflow …`, after `SourceFlowCli.TryRunAsync` in `Program.cs`), or from +this repository (`dotnet run --project src/Tooling/SourceFlow.Tool -- …`); see the +[CLI README](docs/v3.0.0/reference/SourceFlow.Tool-README.md). + +Start the demo, the [TravelBooking sample](samples/TravelBooking): the Bookings service on http://localhost:8080, the +Hotels service on http://localhost:8081, SourceFlow Studio (read-only) on http://localhost:5080 and the Aspire dashboard on +http://localhost:18888, with PostgreSQL and LocalStack (SNS/SQS) between the services: + +```bash +docker compose up -d --build +HOTEL=0193a7a0-0000-7000-8000-000000000001 +BOOKING=0193a7a0-0000-7000-8000-0000000000b1 +curl -X POST http://localhost:8081/hotels/$HOTEL -H 'Content-Type: application/json' -d '{ "name": "Seaview", "rooms": 1 }' +curl -X POST http://localhost:8080/bookings/$BOOKING -H 'Content-Type: application/json' \ + -d "{ \"hotelId\": \"$HOTEL\", \"guest\": \"Ada Lovelace\", \"nights\": 2 }" +curl -X POST http://localhost:8080/bookings/$BOOKING/confirm -H 'Content-Type: application/json' -d '{}' +``` -```csharp -services.UseSourceFlow(); +The [sample's README](samples/TravelBooking/README.md) walks through it. To edit the trip-booking workflow in SourceFlow +Studio: -services.UseSourceFlowAws( - options => { options.Region = RegionEndpoint.USEast1; }, - bus => bus - .Send.Command(q => q.Queue("orders.fifo")) - .Listen.To.CommandQueue("orders.fifo")); +```bash +dotnet run --project src/Tooling/SourceFlow.Tool -- studio --workspace samples/TravelBooking ``` -#### Multi-Instance Deployments (Recommended for Production) +## Documentation -For multi-instance deployments, use the SQL-based idempotency service to ensure duplicate detection across all instances: +- **[Documentation index](docs/v3.0.0/reference/README.md)**: package READMEs, architecture, guides. +- **[Wiki: the complete guide](docs/v3.0.0/reference/wiki.md)**: concepts, getting started, every feature, best practices, FAQ. +- **Guides**: [workflows](docs/v3.0.0/reference/guides/workflows.md), [workflow DSL reference](docs/v3.0.0/reference/guides/workflow-dsl-reference.md), + [OpenTelemetry](docs/v3.0.0/reference/guides/opentelemetry.md), [reading generated code](docs/v3.0.0/reference/guides/reading-generated-code.md), + [migrating from v2](docs/v3.0.0/reference/guides/migrating-from-v2.md). +- **Design**: the [design documents](docs/v3.0.0/engineering/Design/README.md) and [architecture decision records](docs/v3.0.0/engineering/ADRs/README.md). -```csharp -services.UseSourceFlow(); - -// Register Entity Framework stores with SQL-based idempotency -services.AddSourceFlowEfStores(connectionString); -services.AddSourceFlowIdempotency( - connectionString: connectionString, - cleanupIntervalMinutes: 60); - -// Configure cloud integration (AWS or Azure) -services.UseSourceFlowAws( - options => { options.Region = RegionEndpoint.USEast1; }, - bus => bus - .Send.Command(q => q.Queue("orders.fifo")) - .Listen.To.CommandQueue("orders.fifo")); -``` - -**Benefits of SQL-Based Idempotency:** -- ✅ Distributed duplicate detection across multiple instances -- ✅ Automatic cleanup of expired records -- ✅ Database-backed persistence for reliability -- ✅ Supports SQL Server, PostgreSQL, MySQL, SQLite +## Companion Book -For more details, see: -- [AWS Cloud Integration](docs/aws-integration.md.md) -- [SQL-Based Idempotency Service](docs/SQL-Based-Idempotency-Service.md) -- [Cloud Integration Testing guide](docs/Cloud-Integration-Testing.md) + + From Problems to Patterns: Domain-Driven Design and Event Sourcing in .NET + -### Developer Guide -This comprehensive guide provides detailed information about the SourceFlow.Net framework, covering everything from basic concepts to advanced implementation patterns and troubleshooting guidelines. +**From Problems to Patterns — Domain-Driven Design and Event Sourcing in .NET** +*By Najaf A. Shaikh · First Edition, 2026* -Please click on [Developer Guide](https://github.com/CodeShayk/SourceFlow.Net/wiki) for complete details. +The complete, runnable companion code for all 32 chapters of the book is available in the [dd-event-sourcing-dotnet-samples](https://github.com/CodeShayk/dd-event-sourcing-dotnet-samples) repository. Every code example builds and all tests pass. The code evolves chapter by chapter through a single Bank Account domain — starting from a naive CRUD implementation and ending with a containerised, observable, event-sourced system built on **SourceFlow.Net**. ## Support @@ -181,11 +217,12 @@ If you are having problems, please let me know by [raising a new issue](https:// This project is licensed with the [MIT license](LICENSE). ## Contributing -We welcome contributions! Please see our Contributing Guide for details. -- 🐛 Bug Reports - Create an [issue](https://github.com/CodeShayk/sourceflow.net/issues/new/choose) -- 💡 Feature Requests - Start a [discussion](https://github.com/CodeShayk/SourceFlow.Net/discussions) -- 📝 Documentation - Help improve our [docs](https://github.com/CodeShayk/SourceFlow.Net/wiki) -- 💻 Code - Submit [pull](https://github.com/CodeShayk/SourceFlow.Net/pulls) requests + +We welcome contributions! Please see the [contributing guide](CONTRIBUTING.md) for details. +- Bug reports: create an [issue](https://github.com/CodeShayk/sourceflow.net/issues/new/choose) +- Feature requests: start a [discussion](https://github.com/CodeShayk/SourceFlow.Net/discussions) +- Documentation: help improve the [docs](docs/v3.0.0/reference/README.md) +- Code: submit [pull requests](https://github.com/CodeShayk/SourceFlow.Net/pulls) ## Credits Thank you for reading. Please fork, explore, contribute and report. Happy Coding !! :) diff --git a/SECURITY.md b/SECURITY.md index 034e8480..c029938e 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,21 +1,39 @@ # Security Policy -## Supported Versions +## Supported versions -Use this section to tell people about which versions of your project are -currently being supported with security updates. +| Version | Supported with security fixes | +|---------|-------------------------------| +| 3.x | Yes: fixes go to the latest 3.x minor release (3.0 pre-releases: the latest alpha or release candidate) | +| 2.0.x | Yes, until 12 months after 3.0 is generally available | +| 1.x and earlier | No: upgrade to 2.0.x or 3.x | -| Version | Supported | -| ------- | ------------------ | -| 5.1.x | :white_check_mark: | -| 5.0.x | :x: | -| 4.0.x | :white_check_mark: | -| < 4.0 | :x: | +## Reporting a vulnerability -## Reporting a Vulnerability +Please do not report security vulnerabilities in public issues, discussions or pull requests. -Use this section to tell people how to report a vulnerability. +Report them privately through GitHub: open the repository's **Security** tab and choose +**[Report a vulnerability](https://github.com/CodeShayk/SourceFlow.Net/security/advisories/new)**. Include: -Tell them where to go, how often they can expect to get an update on a -reported vulnerability, what to expect if the vulnerability is accepted or -declined, etc. +- the affected package(s) and version(s); +- a description of the vulnerability and its impact; +- steps or a minimal project to reproduce it; +- any known workaround. + +## What happens next + +1. We acknowledge the report and may ask for more detail in the private advisory. +2. We confirm whether it is a vulnerability and assess its severity. If we decline it, we explain why. +3. We prepare a fix privately, release it for every supported version, and publish a GitHub Security Advisory (with a + CVE when warranted) that credits you, unless you prefer otherwise. + +Please keep the report confidential until the advisory is published. + +## How releases are protected + +- Packages are built deterministically in CI with SourceLink and author-signed for releases; each release carries a + CycloneDX SBOM per package and a build provenance attestation. +- Pull requests run CodeQL, dependency review and the full test gate; dependencies are kept current by Renovate. + +See the [security and compliance guide](docs/v3.0.0/reference/Security-and-Compliance-Guide.md) for how to run +SourceFlow.Net securely. diff --git a/SourceFlow.Net.sln b/SourceFlow.Net.sln deleted file mode 100644 index e53a5f0f..00000000 --- a/SourceFlow.Net.sln +++ /dev/null @@ -1,167 +0,0 @@ - -Microsoft Visual Studio Solution File, Format Version 12.00 -# Visual Studio Version 18 -VisualStudioVersion = 18.0.11205.157 -MinimumVisualStudioVersion = 10.0.40219.1 -Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "src", "src", "{02EA681E-C7D8-13C7-8484-4AC65E1B71E8}" -EndProject -Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "tests", "tests", "{653DCB25-EC82-421B-86F7-1DD8879B3926}" -EndProject -Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "misc", "misc", "{4F977993-F413-4BA5-809B-6688EC654606}" - ProjectSection(SolutionItems) = preProject - .gitignore = .gitignore - GitVersion.yml = GitVersion.yml - LICENSE = LICENSE - README.md = README.md - EndProjectSection -EndProject -Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "SourceFlow.Core.Tests", "tests\SourceFlow.Core.Tests\SourceFlow.Core.Tests.csproj", "{60461B85-D00F-4A09-9AA6-A9D566FA6EA4}" -EndProject -Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "SourceFlow", "src\SourceFlow\SourceFlow.csproj", "{C0724CCD-8965-4BE3-B66C-458973D5EFA1}" -EndProject -Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "SourceFlow.Cloud.AWS", "src\SourceFlow.Cloud.AWS\SourceFlow.Cloud.AWS.csproj", "{0F38C793-2301-43A2-A18A-7E86F06D0052}" -EndProject -Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "github", "github", "{F81A2C7A-08CF-4E53-B064-5C5190F8A22B}" - ProjectSection(SolutionItems) = preProject - .github\workflows\Master-Build.yml = .github\workflows\Master-Build.yml - .github\workflows\Master-CodeQL.yml = .github\workflows\Master-CodeQL.yml - .github\workflows\PR-CI.yml = .github\workflows\PR-CI.yml - .github\workflows\PR-CodeQL.yml = .github\workflows\PR-CodeQL.yml - .github\workflows\Pre-release-CI.yml = .github\workflows\Pre-release-CI.yml - .github\workflows\Release-CI.yml = .github\workflows\Release-CI.yml - EndProjectSection -EndProject -Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "SourceFlow.Stores.EntityFramework", "src\SourceFlow.Stores.EntityFramework\SourceFlow.Stores.EntityFramework.csproj", "{C8765CB0-C453-0848-D98B-B0CF4E5D986F}" -EndProject -Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "SourceFlow.Cloud.AWS.Tests", "tests\SourceFlow.Cloud.AWS.Tests\SourceFlow.Cloud.AWS.Tests.csproj", "{0A833B33-8C55-4364-8D70-9A31994A6F61}" -EndProject -Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "SourceFlow.Stores.EntityFramework.Tests", "tests\SourceFlow.Stores.EntityFramework.Tests\SourceFlow.Stores.EntityFramework.Tests.csproj", "{C56C4BC2-6BDC-EB3D-FC92-F9633530A501}" -EndProject -Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "SourceFlow.Cloud.GCP", "src\SourceFlow.Cloud.GCP\SourceFlow.Cloud.GCP.csproj", "{8864B03A-260C-4CD4-B6F3-77797CF2EF06}" -EndProject -Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "SourceFlow.Cloud.GCP.Tests", "tests\SourceFlow.Cloud.GCP.Tests\SourceFlow.Cloud.GCP.Tests.csproj", "{110350B5-0DDC-413F-852B-AA1B8022EEDC}" -EndProject -Global - GlobalSection(SolutionConfigurationPlatforms) = preSolution - Debug|Any CPU = Debug|Any CPU - Debug|x64 = Debug|x64 - Debug|x86 = Debug|x86 - Release|Any CPU = Release|Any CPU - Release|x64 = Release|x64 - Release|x86 = Release|x86 - EndGlobalSection - GlobalSection(ProjectConfigurationPlatforms) = postSolution - {60461B85-D00F-4A09-9AA6-A9D566FA6EA4}.Debug|Any CPU.ActiveCfg = Debug|Any CPU - {60461B85-D00F-4A09-9AA6-A9D566FA6EA4}.Debug|Any CPU.Build.0 = Debug|Any CPU - {60461B85-D00F-4A09-9AA6-A9D566FA6EA4}.Debug|x64.ActiveCfg = Debug|Any CPU - {60461B85-D00F-4A09-9AA6-A9D566FA6EA4}.Debug|x64.Build.0 = Debug|Any CPU - {60461B85-D00F-4A09-9AA6-A9D566FA6EA4}.Debug|x86.ActiveCfg = Debug|Any CPU - {60461B85-D00F-4A09-9AA6-A9D566FA6EA4}.Debug|x86.Build.0 = Debug|Any CPU - {60461B85-D00F-4A09-9AA6-A9D566FA6EA4}.Release|Any CPU.ActiveCfg = Release|Any CPU - {60461B85-D00F-4A09-9AA6-A9D566FA6EA4}.Release|Any CPU.Build.0 = Release|Any CPU - {60461B85-D00F-4A09-9AA6-A9D566FA6EA4}.Release|x64.ActiveCfg = Release|Any CPU - {60461B85-D00F-4A09-9AA6-A9D566FA6EA4}.Release|x64.Build.0 = Release|Any CPU - {60461B85-D00F-4A09-9AA6-A9D566FA6EA4}.Release|x86.ActiveCfg = Release|Any CPU - {60461B85-D00F-4A09-9AA6-A9D566FA6EA4}.Release|x86.Build.0 = Release|Any CPU - {C0724CCD-8965-4BE3-B66C-458973D5EFA1}.Debug|Any CPU.ActiveCfg = Debug|Any CPU - {C0724CCD-8965-4BE3-B66C-458973D5EFA1}.Debug|Any CPU.Build.0 = Debug|Any CPU - {C0724CCD-8965-4BE3-B66C-458973D5EFA1}.Debug|x64.ActiveCfg = Debug|Any CPU - {C0724CCD-8965-4BE3-B66C-458973D5EFA1}.Debug|x64.Build.0 = Debug|Any CPU - {C0724CCD-8965-4BE3-B66C-458973D5EFA1}.Debug|x86.ActiveCfg = Debug|Any CPU - {C0724CCD-8965-4BE3-B66C-458973D5EFA1}.Debug|x86.Build.0 = Debug|Any CPU - {C0724CCD-8965-4BE3-B66C-458973D5EFA1}.Release|Any CPU.ActiveCfg = Release|Any CPU - {C0724CCD-8965-4BE3-B66C-458973D5EFA1}.Release|Any CPU.Build.0 = Release|Any CPU - {C0724CCD-8965-4BE3-B66C-458973D5EFA1}.Release|x64.ActiveCfg = Release|Any CPU - {C0724CCD-8965-4BE3-B66C-458973D5EFA1}.Release|x64.Build.0 = Release|Any CPU - {C0724CCD-8965-4BE3-B66C-458973D5EFA1}.Release|x86.ActiveCfg = Release|Any CPU - {C0724CCD-8965-4BE3-B66C-458973D5EFA1}.Release|x86.Build.0 = Release|Any CPU - {0F38C793-2301-43A2-A18A-7E86F06D0052}.Debug|Any CPU.ActiveCfg = Debug|Any CPU - {0F38C793-2301-43A2-A18A-7E86F06D0052}.Debug|Any CPU.Build.0 = Debug|Any CPU - {0F38C793-2301-43A2-A18A-7E86F06D0052}.Debug|x64.ActiveCfg = Debug|Any CPU - {0F38C793-2301-43A2-A18A-7E86F06D0052}.Debug|x64.Build.0 = Debug|Any CPU - {0F38C793-2301-43A2-A18A-7E86F06D0052}.Debug|x86.ActiveCfg = Debug|Any CPU - {0F38C793-2301-43A2-A18A-7E86F06D0052}.Debug|x86.Build.0 = Debug|Any CPU - {0F38C793-2301-43A2-A18A-7E86F06D0052}.Release|Any CPU.ActiveCfg = Release|Any CPU - {0F38C793-2301-43A2-A18A-7E86F06D0052}.Release|Any CPU.Build.0 = Release|Any CPU - {0F38C793-2301-43A2-A18A-7E86F06D0052}.Release|x64.ActiveCfg = Release|Any CPU - {0F38C793-2301-43A2-A18A-7E86F06D0052}.Release|x64.Build.0 = Release|Any CPU - {0F38C793-2301-43A2-A18A-7E86F06D0052}.Release|x86.ActiveCfg = Release|Any CPU - {0F38C793-2301-43A2-A18A-7E86F06D0052}.Release|x86.Build.0 = Release|Any CPU - {C8765CB0-C453-0848-D98B-B0CF4E5D986F}.Debug|Any CPU.ActiveCfg = Debug|Any CPU - {C8765CB0-C453-0848-D98B-B0CF4E5D986F}.Debug|Any CPU.Build.0 = Debug|Any CPU - {C8765CB0-C453-0848-D98B-B0CF4E5D986F}.Debug|x64.ActiveCfg = Debug|Any CPU - {C8765CB0-C453-0848-D98B-B0CF4E5D986F}.Debug|x64.Build.0 = Debug|Any CPU - {C8765CB0-C453-0848-D98B-B0CF4E5D986F}.Debug|x86.ActiveCfg = Debug|Any CPU - {C8765CB0-C453-0848-D98B-B0CF4E5D986F}.Debug|x86.Build.0 = Debug|Any CPU - {C8765CB0-C453-0848-D98B-B0CF4E5D986F}.Release|Any CPU.ActiveCfg = Release|Any CPU - {C8765CB0-C453-0848-D98B-B0CF4E5D986F}.Release|Any CPU.Build.0 = Release|Any CPU - {C8765CB0-C453-0848-D98B-B0CF4E5D986F}.Release|x64.ActiveCfg = Release|Any CPU - {C8765CB0-C453-0848-D98B-B0CF4E5D986F}.Release|x64.Build.0 = Release|Any CPU - {C8765CB0-C453-0848-D98B-B0CF4E5D986F}.Release|x86.ActiveCfg = Release|Any CPU - {C8765CB0-C453-0848-D98B-B0CF4E5D986F}.Release|x86.Build.0 = Release|Any CPU - {0A833B33-8C55-4364-8D70-9A31994A6F61}.Debug|Any CPU.ActiveCfg = Debug|Any CPU - {0A833B33-8C55-4364-8D70-9A31994A6F61}.Debug|Any CPU.Build.0 = Debug|Any CPU - {0A833B33-8C55-4364-8D70-9A31994A6F61}.Debug|x64.ActiveCfg = Debug|Any CPU - {0A833B33-8C55-4364-8D70-9A31994A6F61}.Debug|x64.Build.0 = Debug|Any CPU - {0A833B33-8C55-4364-8D70-9A31994A6F61}.Debug|x86.ActiveCfg = Debug|Any CPU - {0A833B33-8C55-4364-8D70-9A31994A6F61}.Debug|x86.Build.0 = Debug|Any CPU - {0A833B33-8C55-4364-8D70-9A31994A6F61}.Release|Any CPU.ActiveCfg = Release|Any CPU - {0A833B33-8C55-4364-8D70-9A31994A6F61}.Release|Any CPU.Build.0 = Release|Any CPU - {0A833B33-8C55-4364-8D70-9A31994A6F61}.Release|x64.ActiveCfg = Release|Any CPU - {0A833B33-8C55-4364-8D70-9A31994A6F61}.Release|x64.Build.0 = Release|Any CPU - {0A833B33-8C55-4364-8D70-9A31994A6F61}.Release|x86.ActiveCfg = Release|Any CPU - {0A833B33-8C55-4364-8D70-9A31994A6F61}.Release|x86.Build.0 = Release|Any CPU - {C56C4BC2-6BDC-EB3D-FC92-F9633530A501}.Debug|Any CPU.ActiveCfg = Debug|Any CPU - {C56C4BC2-6BDC-EB3D-FC92-F9633530A501}.Debug|Any CPU.Build.0 = Debug|Any CPU - {C56C4BC2-6BDC-EB3D-FC92-F9633530A501}.Debug|x64.ActiveCfg = Debug|Any CPU - {C56C4BC2-6BDC-EB3D-FC92-F9633530A501}.Debug|x64.Build.0 = Debug|Any CPU - {C56C4BC2-6BDC-EB3D-FC92-F9633530A501}.Debug|x86.ActiveCfg = Debug|Any CPU - {C56C4BC2-6BDC-EB3D-FC92-F9633530A501}.Debug|x86.Build.0 = Debug|Any CPU - {C56C4BC2-6BDC-EB3D-FC92-F9633530A501}.Release|Any CPU.ActiveCfg = Release|Any CPU - {C56C4BC2-6BDC-EB3D-FC92-F9633530A501}.Release|Any CPU.Build.0 = Release|Any CPU - {C56C4BC2-6BDC-EB3D-FC92-F9633530A501}.Release|x64.ActiveCfg = Release|Any CPU - {C56C4BC2-6BDC-EB3D-FC92-F9633530A501}.Release|x64.Build.0 = Release|Any CPU - {C56C4BC2-6BDC-EB3D-FC92-F9633530A501}.Release|x86.ActiveCfg = Release|Any CPU - {C56C4BC2-6BDC-EB3D-FC92-F9633530A501}.Release|x86.Build.0 = Release|Any CPU - {8864B03A-260C-4CD4-B6F3-77797CF2EF06}.Debug|Any CPU.ActiveCfg = Debug|Any CPU - {8864B03A-260C-4CD4-B6F3-77797CF2EF06}.Debug|Any CPU.Build.0 = Debug|Any CPU - {8864B03A-260C-4CD4-B6F3-77797CF2EF06}.Debug|x64.ActiveCfg = Debug|Any CPU - {8864B03A-260C-4CD4-B6F3-77797CF2EF06}.Debug|x64.Build.0 = Debug|Any CPU - {8864B03A-260C-4CD4-B6F3-77797CF2EF06}.Debug|x86.ActiveCfg = Debug|Any CPU - {8864B03A-260C-4CD4-B6F3-77797CF2EF06}.Debug|x86.Build.0 = Debug|Any CPU - {8864B03A-260C-4CD4-B6F3-77797CF2EF06}.Release|Any CPU.ActiveCfg = Release|Any CPU - {8864B03A-260C-4CD4-B6F3-77797CF2EF06}.Release|Any CPU.Build.0 = Release|Any CPU - {8864B03A-260C-4CD4-B6F3-77797CF2EF06}.Release|x64.ActiveCfg = Release|Any CPU - {8864B03A-260C-4CD4-B6F3-77797CF2EF06}.Release|x64.Build.0 = Release|Any CPU - {8864B03A-260C-4CD4-B6F3-77797CF2EF06}.Release|x86.ActiveCfg = Release|Any CPU - {8864B03A-260C-4CD4-B6F3-77797CF2EF06}.Release|x86.Build.0 = Release|Any CPU - {110350B5-0DDC-413F-852B-AA1B8022EEDC}.Debug|Any CPU.ActiveCfg = Debug|Any CPU - {110350B5-0DDC-413F-852B-AA1B8022EEDC}.Debug|Any CPU.Build.0 = Debug|Any CPU - {110350B5-0DDC-413F-852B-AA1B8022EEDC}.Debug|x64.ActiveCfg = Debug|Any CPU - {110350B5-0DDC-413F-852B-AA1B8022EEDC}.Debug|x64.Build.0 = Debug|Any CPU - {110350B5-0DDC-413F-852B-AA1B8022EEDC}.Debug|x86.ActiveCfg = Debug|Any CPU - {110350B5-0DDC-413F-852B-AA1B8022EEDC}.Debug|x86.Build.0 = Debug|Any CPU - {110350B5-0DDC-413F-852B-AA1B8022EEDC}.Release|Any CPU.ActiveCfg = Release|Any CPU - {110350B5-0DDC-413F-852B-AA1B8022EEDC}.Release|Any CPU.Build.0 = Release|Any CPU - {110350B5-0DDC-413F-852B-AA1B8022EEDC}.Release|x64.ActiveCfg = Release|Any CPU - {110350B5-0DDC-413F-852B-AA1B8022EEDC}.Release|x64.Build.0 = Release|Any CPU - {110350B5-0DDC-413F-852B-AA1B8022EEDC}.Release|x86.ActiveCfg = Release|Any CPU - {110350B5-0DDC-413F-852B-AA1B8022EEDC}.Release|x86.Build.0 = Release|Any CPU - EndGlobalSection - GlobalSection(SolutionProperties) = preSolution - HideSolutionNode = FALSE - EndGlobalSection - GlobalSection(NestedProjects) = preSolution - {60461B85-D00F-4A09-9AA6-A9D566FA6EA4} = {653DCB25-EC82-421B-86F7-1DD8879B3926} - {C0724CCD-8965-4BE3-B66C-458973D5EFA1} = {02EA681E-C7D8-13C7-8484-4AC65E1B71E8} - {0F38C793-2301-43A2-A18A-7E86F06D0052} = {02EA681E-C7D8-13C7-8484-4AC65E1B71E8} - {C8765CB0-C453-0848-D98B-B0CF4E5D986F} = {02EA681E-C7D8-13C7-8484-4AC65E1B71E8} - {0A833B33-8C55-4364-8D70-9A31994A6F61} = {653DCB25-EC82-421B-86F7-1DD8879B3926} - {C56C4BC2-6BDC-EB3D-FC92-F9633530A501} = {653DCB25-EC82-421B-86F7-1DD8879B3926} - {8864B03A-260C-4CD4-B6F3-77797CF2EF06} = {02EA681E-C7D8-13C7-8484-4AC65E1B71E8} - {110350B5-0DDC-413F-852B-AA1B8022EEDC} = {653DCB25-EC82-421B-86F7-1DD8879B3926} - EndGlobalSection - GlobalSection(ExtensibilityGlobals) = postSolution - SolutionGuid = {D02B8992-CC81-4194-BBF7-5EC40A96C698} - EndGlobalSection -EndGlobal diff --git a/SourceFlow.slnx b/SourceFlow.slnx new file mode 100644 index 00000000..7d866c55 --- /dev/null +++ b/SourceFlow.slnx @@ -0,0 +1,99 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/deploy/dast/README.md b/deploy/dast/README.md new file mode 100644 index 00000000..713bb273 --- /dev/null +++ b/deploy/dast/README.md @@ -0,0 +1,30 @@ +# DAST: OWASP ZAP scan of the query API + +The nightly `dast` job (`.github/workflows/v3-nightly.yml`) runs the OWASP ZAP API scan against the TravelBooking +sample's Bookings service, on its per-service query API (doc 14 §9, plan 08). Any medium or high finding fails the night. + +| File | What it is | +|------|------------| +| `query-api.openapi.json` | The OpenAPI document that drives the scan. It covers `/query`, `/query/validate`, `/query/explain`, `/query/schema`, `/queries` and `/queries/{name}/v{version}`, with request examples. The endpoints are mapped as request delegates, which ASP.NET Core's OpenAPI generator skips, so this document is written by hand. Test UT-ASP-37 fails when its paths differ from the routes the API maps. | +| `zap-rules.tsv` | Rules ZAP should ignore, each with its reason. | + +The injection corpus over HTTP (QRY-57..59) runs with the end-to-end tests, in +`tests/EndToEnd/SourceFlow.EndToEnd.Tests/QueryApiScenarios.cs`. It checks that every payload is rejected with an +`SFQ01xx` or `SFQ02xx` code or runs with its values as parameters. It also checks for zero database errors, no markup +in any response, and no writes to the event, stream or document tables. + +## Running it locally + +```bash +docker compose up -d --build --wait postgres localstack hotels bookings +mkdir -p zap && cp deploy/dast/* zap/ +docker run --rm --network sourceflow-demo_default -v "$PWD/zap:/zap/wrk:rw" ghcr.io/zaproxy/zaproxy:stable \ + zap-api-scan.py -t /zap/wrk/query-api.openapi.json -f openapi -O http://bookings:8080 \ + -c zap-rules.tsv -J zap-report.json -r zap-report.html +``` + +## Latest result (WP-4.7) + +119 rules passed, with no high, medium or low findings. The first run raised one low finding: the query responses had +no `Cross-Origin-Resource-Policy` header. The query API now sends `Cross-Origin-Resource-Policy: same-origin` with its +other security headers. diff --git a/deploy/dast/query-api.openapi.json b/deploy/dast/query-api.openapi.json new file mode 100644 index 00000000..82c0d6c5 --- /dev/null +++ b/deploy/dast/query-api.openapi.json @@ -0,0 +1,85 @@ +{ + "openapi": "3.0.3", + "info": { + "title": "SourceFlow per-service query API", + "version": "1.0.0", + "description": "The endpoints mapped by MapSourceFlowQueryApi and MapDomainQueries (doc 14 §9). The OWASP ZAP API scan of the nightly DAST job is driven by this document (plan 08). A unit test keeps its paths equal to the mapped routes." + }, + "servers": [ + { "url": "http://localhost:8080" } + ], + "paths": { + "/query": { + "post": { + "operationId": "SourceFlowQuery", + "summary": "Run an ad-hoc SFQL or SQL-syntax query.", + "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryRequest" }, "example": { "query": "from readmodel \"account-summary\" | where balance > @min | project balance, status | order by balance desc", "parameters": { "min": 10 }, "pageSize": 50 } } } }, + "responses": { + "200": { "description": "Columns, rows, continuation and consistency.", "content": { "application/json": {}, "application/x-ndjson": {}, "text/csv": {} } }, + "400": { "description": "A rejected query (SFQ codes).", "content": { "application/problem+json": {} } }, + "413": { "description": "The request is too large." }, + "415": { "description": "Not JSON." }, + "429": { "description": "Rate limited (Retry-After)." } + } + } + }, + "/query/validate": { + "post": { + "operationId": "SourceFlowQueryValidate", + "summary": "Parse, bind and policy-check a query without running it.", + "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryRequest" }, "example": { "query": "SELECT balance FROM readmodel.\"account-summary\" WHERE balance > 10", "language": "sql" } } } }, + "responses": { "200": { "description": "Valid, with the result columns." }, "400": { "description": "Diagnostics." } } + } + }, + "/query/explain": { + "post": { + "operationId": "SourceFlowQueryExplain", + "summary": "Show the bound plan and the parameterised statement.", + "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryRequest" }, "example": { "query": "from readmodel \"account-summary\" | where status = 1 | project balance" } } } }, + "responses": { "200": { "description": "The engine and the statement with placeholders." }, "400": { "description": "Diagnostics." } } + } + }, + "/query/schema": { + "get": { + "operationId": "SourceFlowQuerySchema", + "summary": "The service's queryable sources and fields.", + "responses": { "200": { "description": "Events, read models, aggregates and queries." } } + } + }, + "/queries": { + "get": { + "operationId": "SourceFlowDomainQueries", + "summary": "The named domain queries.", + "responses": { "200": { "description": "The queries with their parameters and columns." } } + } + }, + "/queries/{name}/v{version}": { + "get": { + "operationId": "SourceFlowDomainQuery", + "summary": "Run a named domain query.", + "parameters": [ + { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "example": "accounts-by-status" }, + { "name": "version", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1 }, + { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer" } }, + { "name": "continuation", "in": "query", "required": false, "schema": { "type": "string" } } + ], + "responses": { "200": { "description": "Rows." }, "400": { "description": "Diagnostics." }, "404": { "description": "Unknown query." } } + } + } + }, + "components": { + "schemas": { + "QueryRequest": { + "type": "object", + "required": ["query"], + "properties": { + "query": { "type": "string", "maxLength": 8000 }, + "language": { "type": "string", "enum": ["sfql", "sql"] }, + "parameters": { "type": "object", "additionalProperties": true }, + "pageSize": { "type": "integer", "minimum": 1, "maximum": 1000 }, + "continuation": { "type": "string" } + } + } + } + } +} diff --git a/deploy/dast/zap-rules.tsv b/deploy/dast/zap-rules.tsv new file mode 100644 index 00000000..b65ce8d9 --- /dev/null +++ b/deploy/dast/zap-rules.tsv @@ -0,0 +1 @@ +10049 IGNORE (Storable and cacheable content: informational; query responses are sent with Cache-Control: no-store) diff --git a/deploy/observability/README.md b/deploy/observability/README.md new file mode 100644 index 00000000..9d42b52f --- /dev/null +++ b/deploy/observability/README.md @@ -0,0 +1,45 @@ +# Dashboards and alerts + +Generated from the instrument catalogue (`SourceFlowTelemetry.Catalogue`, doc 08 §3) by: + +```bash +dotnet sourceflow observability export --output deploy/observability +``` + +Do not edit these files by hand. A test fails when they differ from what the generator writes, and `promtool` checks +the rules in CI. + +| File | What it is | +|------|------------| +| `sourceflow-dashboard.json` | A Grafana dashboard. The first row shows the service-level objectives of doc 08 §6: write availability, p99 write latency, read-model freshness, delivery durability, and parked messages. After that there is one panel per instrument, grouped by area. Import it and choose your Prometheus data source. The `Service` variable is the `job` label (from `service.name`). | +| `sourceflow-alerts.yaml` | Prometheus alert rules for the same objectives, plus stalled subscriptions, a held log horizon and DSL workflow instances that need an operator (`SourceFlowWorkflowManualIntervention`). Severity is `page` or `warning`. | + +## Metric names + +The queries use the names the OpenTelemetry Prometheus exporter and the Collector produce: + +- Dots become underscores. +- Seconds add `_seconds`. +- Counters end in `_total`. +- Histograms are read through `_bucket`, `_sum` and `_count`. + +For example, `sourceflow.command.duration` becomes `sourceflow_command_duration_seconds_bucket`, and +`sourceflow.deadletter.parked` becomes `sourceflow_deadletter_parked_total`. If your pipeline names metrics differently, +for example without unit suffixes, adjust the generated files or the exporter. + +## Gauges + +Gauges are sampled by each instance on `SourceFlowOptions.MonitorInterval` (15 s by default): + +- **Outbox, dead letters, subscription lag, horizon age and active process managers** are read from the store. Every + instance reports the same value, so the dashboard and alerts take the `max`. +- **`sourceflow.lease.owned`** is per instance, so it is summed by `instance`. + +## Without Prometheus + +The Bank demo (`docker compose up -d` at the repository root) sends traces and metrics over OTLP to the Aspire +dashboard at . The health endpoints are: + +- `/health`: liveness. It runs no dependency checks. +- `/health/ready`: SourceFlow started, and the store and broker answer. +- `/health/sourceflow`: every SourceFlow check (doc 08 §5). diff --git a/deploy/observability/sourceflow-alerts.yaml b/deploy/observability/sourceflow-alerts.yaml new file mode 100644 index 00000000..3dfa390a --- /dev/null +++ b/deploy/observability/sourceflow-alerts.yaml @@ -0,0 +1,69 @@ +# Generated from SourceFlowTelemetry.Catalogue by `dotnet sourceflow observability export`; do not edit by hand. +# The service-level objectives of doc 08 §6. Metric names follow the OpenTelemetry Prometheus conversion. +groups: + - name: sourceflow + rules: + - alert: SourceFlowDeadLetterParked + expr: "sum by (job, consumer, reason) (increase(sourceflow_deadletter_parked_total[5m])) > 0" + for: 0m + labels: + severity: page + annotations: + summary: "{{ $labels.job }} parked a message from {{ $labels.consumer }} ({{ $labels.reason }}). Inspect it with `dotnet sourceflow dlq list`." + description: "Correctness: any parked message needs an operator (doc 08 §6)." + - alert: SourceFlowSubscriptionStalled + expr: "max by (job, sourceflow_subscription, sourceflow_partition) (sourceflow_subscription_stalled) > 0" + for: 5m + labels: + severity: page + annotations: + summary: "{{ $labels.job }}: subscription {{ $labels.sourceflow_subscription }} partition {{ $labels.sourceflow_partition }} is halted at a failing event." + description: "A Stop-policy projection is stuck on a poison event; fix it or skip the event (`dotnet sourceflow projection skip`)." + - alert: SourceFlowOutboxDelayed + expr: "max by (job) (sourceflow_outbox_age_seconds) > 60" + for: 5m + labels: + severity: page + annotations: + summary: "{{ $labels.job }}: the oldest due outbox message has waited {{ $value | humanizeDuration }}." + description: "Delivery durability SLO: max outbox age < 60 s. Check the relay and the broker." + - alert: SourceFlowReadModelsStale + expr: "max by (job) (sourceflow_subscription_lag_time_seconds) > 5" + for: 10m + labels: + severity: warning + annotations: + summary: "{{ $labels.job }}: read models are {{ $value | humanizeDuration }} behind." + description: "Read-model freshness SLO: lag time < 5 s." + - alert: SourceFlowWriteLatency + expr: "histogram_quantile(0.99, sum by (job, le) (rate(sourceflow_command_duration_seconds_bucket[5m]))) > 0.05" + for: 10m + labels: + severity: warning + annotations: + summary: "{{ $labels.job }}: p99 command latency is {{ $value | humanizeDuration }}." + description: "Write latency SLO: p99 < 50 ms." + - alert: SourceFlowWriteErrors + expr: "sum by (job) (rate(sourceflow_command_duration_seconds_count{sourceflow_outcome=\"failed\"}[30m])) / sum by (job) (rate(sourceflow_command_duration_seconds_count[30m])) > 0.001" + for: 30m + labels: + severity: page + annotations: + summary: "{{ $labels.job }}: {{ $value | humanizePercentage }} of commands fail." + description: "Write availability SLO: 99.9 % of commands succeed (business rejections and conflicts count as successes)." + - alert: SourceFlowHorizonHeld + expr: "max by (job) (sourceflow_subscription_horizon_age_seconds) > 30" + for: 5m + labels: + severity: warning + annotations: + summary: "{{ $labels.job }}: a writing transaction has held the subscription horizon for {{ $value | humanizeDuration }}." + description: "A long transaction delays every subscription (doc 05 §5.4). Find it in pg_stat_activity." + - alert: SourceFlowWorkflowManualIntervention + expr: "sum by (job, workflow, version) (increase(sourceflow_workflow_manual_intervention_total[5m])) > 0" + for: 0m + labels: + severity: page + annotations: + summary: "{{ $labels.job }}: a {{ $labels.workflow }}@{{ $labels.version }} instance needs an operator. Find it with `dotnet sourceflow workflow list --status ManualIntervention`." + description: "A workflow step or compensation failed with no automatic way forward (doc 15 §5.3, §7): resume, retry the step or abort it." diff --git a/deploy/observability/sourceflow-dashboard.json b/deploy/observability/sourceflow-dashboard.json new file mode 100644 index 00000000..bc29bf58 --- /dev/null +++ b/deploy/observability/sourceflow-dashboard.json @@ -0,0 +1,1443 @@ +{ + "__inputs": [ + { + "name": "DS_PROMETHEUS", + "label": "Prometheus", + "type": "datasource", + "pluginId": "prometheus", + "pluginName": "Prometheus" + } + ], + "title": "SourceFlow", + "uid": "sourceflow", + "description": "Generated from SourceFlowTelemetry.Catalogue by `dotnet sourceflow observability export`; do not edit by hand.", + "tags": [ + "sourceflow" + ], + "schemaVersion": 39, + "version": 1, + "editable": true, + "refresh": "30s", + "time": { + "from": "now-6h", + "to": "now" + }, + "templating": { + "list": [ + { + "name": "job", + "label": "Service", + "type": "query", + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "query": { + "query": "label_values(sourceflow_command_duration_seconds_count, job)", + "refId": "job" + }, + "includeAll": true, + "multi": true, + "current": { + "text": "All", + "value": "$__all" + }, + "refresh": 2 + } + ] + }, + "panels": [ + { + "id": 1, + "type": "row", + "title": "Service-level objectives (doc 08 §6)", + "collapsed": false, + "gridPos": { + "h": 1, + "w": 24, + "x": 0, + "y": 0 + }, + "panels": [] + }, + { + "id": 2, + "type": "stat", + "title": "Write availability", + "description": "Objective 99.9 %: commands that did not fail.", + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "gridPos": { + "h": 4, + "w": 5, + "x": 0, + "y": 1 + }, + "fieldConfig": { + "defaults": { + "unit": "percentunit" + }, + "overrides": [] + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "expr": "1 - (sum(rate(sourceflow_command_duration_seconds_count{job=~\"$job\",sourceflow_outcome=\"failed\"}[$__rate_interval])) or vector(0)) / sum(rate(sourceflow_command_duration_seconds_count{job=~\"$job\"}[$__rate_interval]))", + "legendFormat": "Write availability", + "refId": "A" + } + ] + }, + { + "id": 3, + "type": "stat", + "title": "Write latency p99", + "description": "Objective < 50 ms.", + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "gridPos": { + "h": 4, + "w": 5, + "x": 5, + "y": 1 + }, + "fieldConfig": { + "defaults": { + "unit": "s" + }, + "overrides": [] + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "expr": "histogram_quantile(0.99, sum by (le) (rate(sourceflow_command_duration_seconds_bucket{job=~\"$job\"}[$__rate_interval])))", + "legendFormat": "Write latency p99", + "refId": "A" + } + ] + }, + { + "id": 4, + "type": "stat", + "title": "Read-model freshness", + "description": "Objective < 5 s: the oldest unprocessed event.", + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "gridPos": { + "h": 4, + "w": 5, + "x": 10, + "y": 1 + }, + "fieldConfig": { + "defaults": { + "unit": "s" + }, + "overrides": [] + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "expr": "max(sourceflow_subscription_lag_time_seconds{job=~\"$job\"})", + "legendFormat": "Read-model freshness", + "refId": "A" + } + ] + }, + { + "id": 5, + "type": "stat", + "title": "Delivery durability", + "description": "Objective < 60 s: the oldest due outbox message.", + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "gridPos": { + "h": 4, + "w": 5, + "x": 15, + "y": 1 + }, + "fieldConfig": { + "defaults": { + "unit": "s" + }, + "overrides": [] + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "expr": "max(sourceflow_outbox_age_seconds{job=~\"$job\"})", + "legendFormat": "Delivery durability", + "refId": "A" + } + ] + }, + { + "id": 6, + "type": "stat", + "title": "Parked messages (1 h)", + "description": "Objective 0: page on any.", + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "gridPos": { + "h": 4, + "w": 4, + "x": 20, + "y": 1 + }, + "fieldConfig": { + "defaults": { + "unit": "short" + }, + "overrides": [] + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "expr": "sum(increase(sourceflow_deadletter_parked_total{job=~\"$job\"}[1h]))", + "legendFormat": "Parked messages (1 h)", + "refId": "A" + } + ] + }, + { + "id": 7, + "type": "row", + "title": "Commands", + "collapsed": false, + "gridPos": { + "h": 1, + "w": 24, + "x": 0, + "y": 5 + }, + "panels": [] + }, + { + "id": 8, + "type": "timeseries", + "title": "sourceflow.command.duration", + "description": "Command processing duration.", + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 0, + "y": 6 + }, + "fieldConfig": { + "defaults": { + "unit": "s" + }, + "overrides": [] + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "expr": "histogram_quantile(0.99, sum by (le, sourceflow_command_type) (rate(sourceflow_command_duration_seconds_bucket{job=~\"$job\"}[$__rate_interval])))", + "legendFormat": "p99 {{sourceflow_command_type}}", + "refId": "A" + }, + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "expr": "histogram_quantile(0.5, sum by (le, sourceflow_command_type) (rate(sourceflow_command_duration_seconds_bucket{job=~\"$job\"}[$__rate_interval])))", + "legendFormat": "p50 {{sourceflow_command_type}}", + "refId": "B" + } + ] + }, + { + "id": 9, + "type": "row", + "title": "Event store and aggregates", + "collapsed": false, + "gridPos": { + "h": 1, + "w": 24, + "x": 0, + "y": 14 + }, + "panels": [] + }, + { + "id": 10, + "type": "timeseries", + "title": "sourceflow.eventstore.append.duration", + "description": "Session commit duration.", + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 0, + "y": 15 + }, + "fieldConfig": { + "defaults": { + "unit": "s" + }, + "overrides": [] + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "expr": "histogram_quantile(0.99, sum by (le) (rate(sourceflow_eventstore_append_duration_seconds_bucket{job=~\"$job\"}[$__rate_interval])))", + "legendFormat": "p99 sourceflow.eventstore.append.duration", + "refId": "A" + }, + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "expr": "histogram_quantile(0.5, sum by (le) (rate(sourceflow_eventstore_append_duration_seconds_bucket{job=~\"$job\"}[$__rate_interval])))", + "legendFormat": "p50 sourceflow.eventstore.append.duration", + "refId": "B" + } + ] + }, + { + "id": 11, + "type": "timeseries", + "title": "sourceflow.eventstore.append.events", + "description": "Events per append.", + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 12, + "y": 15 + }, + "fieldConfig": { + "defaults": { + "unit": "short" + }, + "overrides": [] + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "expr": "sum by (sourceflow_aggregate_type) (rate(sourceflow_eventstore_append_events_sum{job=~\"$job\"}[$__rate_interval])) / sum by (sourceflow_aggregate_type) (rate(sourceflow_eventstore_append_events_count{job=~\"$job\"}[$__rate_interval]))", + "legendFormat": "mean {{sourceflow_aggregate_type}}", + "refId": "A" + } + ] + }, + { + "id": 12, + "type": "timeseries", + "title": "sourceflow.eventstore.concurrency_conflicts", + "description": "Optimistic concurrency conflicts.", + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 0, + "y": 23 + }, + "fieldConfig": { + "defaults": { + "unit": "ops" + }, + "overrides": [] + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "expr": "sum by (sourceflow_aggregate_type) (rate(sourceflow_eventstore_concurrency_conflicts_total{job=~\"$job\"}[$__rate_interval]))", + "legendFormat": "{{sourceflow_aggregate_type}}", + "refId": "A" + } + ] + }, + { + "id": 13, + "type": "timeseries", + "title": "sourceflow.aggregate.load.events", + "description": "Events folded per aggregate load.", + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 12, + "y": 23 + }, + "fieldConfig": { + "defaults": { + "unit": "short" + }, + "overrides": [] + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "expr": "sum by (sourceflow_aggregate_type) (rate(sourceflow_aggregate_load_events_sum{job=~\"$job\"}[$__rate_interval])) / sum by (sourceflow_aggregate_type) (rate(sourceflow_aggregate_load_events_count{job=~\"$job\"}[$__rate_interval]))", + "legendFormat": "mean {{sourceflow_aggregate_type}}", + "refId": "A" + } + ] + }, + { + "id": 14, + "type": "timeseries", + "title": "sourceflow.aggregate.cache.hits", + "description": "Aggregate cache lookups by result (hit, miss, stale).", + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 0, + "y": 31 + }, + "fieldConfig": { + "defaults": { + "unit": "ops" + }, + "overrides": [] + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "expr": "sum by (sourceflow_aggregate_type) (rate(sourceflow_aggregate_cache_hits_total{job=~\"$job\"}[$__rate_interval]))", + "legendFormat": "{{sourceflow_aggregate_type}}", + "refId": "A" + } + ] + }, + { + "id": 15, + "type": "timeseries", + "title": "sourceflow.snapshot.written", + "description": "Snapshots written in the background.", + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 12, + "y": 31 + }, + "fieldConfig": { + "defaults": { + "unit": "ops" + }, + "overrides": [] + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "expr": "sum by (sourceflow_aggregate_type) (rate(sourceflow_snapshot_written_total{job=~\"$job\"}[$__rate_interval]))", + "legendFormat": "{{sourceflow_aggregate_type}}", + "refId": "A" + } + ] + }, + { + "id": 16, + "type": "timeseries", + "title": "sourceflow.snapshot.dropped", + "description": "Snapshots dropped because the queue was full or the write failed.", + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 0, + "y": 39 + }, + "fieldConfig": { + "defaults": { + "unit": "ops" + }, + "overrides": [] + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "expr": "sum by (sourceflow_aggregate_type) (rate(sourceflow_snapshot_dropped_total{job=~\"$job\"}[$__rate_interval]))", + "legendFormat": "{{sourceflow_aggregate_type}}", + "refId": "A" + } + ] + }, + { + "id": 17, + "type": "row", + "title": "Outbox, inbox and retries", + "collapsed": false, + "gridPos": { + "h": 1, + "w": 24, + "x": 0, + "y": 47 + }, + "panels": [] + }, + { + "id": 18, + "type": "timeseries", + "title": "sourceflow.outbox.pending", + "description": "Undelivered outbox messages per partition.", + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 0, + "y": 48 + }, + "fieldConfig": { + "defaults": { + "unit": "short" + }, + "overrides": [] + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "expr": "max by (sourceflow_partition) (sourceflow_outbox_pending{job=~\"$job\"})", + "legendFormat": "{{sourceflow_partition}}", + "refId": "A" + } + ] + }, + { + "id": 19, + "type": "timeseries", + "title": "sourceflow.outbox.age", + "description": "How long the oldest due outbox message has waited (durability SLO).", + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 12, + "y": 48 + }, + "fieldConfig": { + "defaults": { + "unit": "s" + }, + "overrides": [] + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "expr": "max by (sourceflow_partition) (sourceflow_outbox_age_seconds{job=~\"$job\"})", + "legendFormat": "{{sourceflow_partition}}", + "refId": "A" + } + ] + }, + { + "id": 20, + "type": "timeseries", + "title": "sourceflow.outbox.dispatch.duration", + "description": "Outbox batch dispatch duration.", + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 0, + "y": 56 + }, + "fieldConfig": { + "defaults": { + "unit": "s" + }, + "overrides": [] + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "expr": "histogram_quantile(0.99, sum by (le, messaging_system) (rate(sourceflow_outbox_dispatch_duration_seconds_bucket{job=~\"$job\"}[$__rate_interval])))", + "legendFormat": "p99 {{messaging_system}}", + "refId": "A" + }, + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "expr": "histogram_quantile(0.5, sum by (le, messaging_system) (rate(sourceflow_outbox_dispatch_duration_seconds_bucket{job=~\"$job\"}[$__rate_interval])))", + "legendFormat": "p50 {{messaging_system}}", + "refId": "B" + } + ] + }, + { + "id": 21, + "type": "timeseries", + "title": "sourceflow.inbox.duplicates", + "description": "Duplicates absorbed by the inbox.", + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 12, + "y": 56 + }, + "fieldConfig": { + "defaults": { + "unit": "ops" + }, + "overrides": [] + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "expr": "sum by (messaging_consumer_group_name) (rate(sourceflow_inbox_duplicates_total{job=~\"$job\"}[$__rate_interval]))", + "legendFormat": "{{messaging_consumer_group_name}}", + "refId": "A" + } + ] + }, + { + "id": 22, + "type": "timeseries", + "title": "sourceflow.retry.attempts", + "description": "Retry attempts.", + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 0, + "y": 64 + }, + "fieldConfig": { + "defaults": { + "unit": "ops" + }, + "overrides": [] + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "expr": "sum by (stage) (rate(sourceflow_retry_attempts_total{job=~\"$job\"}[$__rate_interval]))", + "legendFormat": "{{stage}}", + "refId": "A" + } + ] + }, + { + "id": 23, + "type": "row", + "title": "Dead letters", + "collapsed": false, + "gridPos": { + "h": 1, + "w": 24, + "x": 0, + "y": 72 + }, + "panels": [] + }, + { + "id": 24, + "type": "timeseries", + "title": "sourceflow.deadletter.parked", + "description": "Messages parked to dead letters.", + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 0, + "y": 73 + }, + "fieldConfig": { + "defaults": { + "unit": "ops" + }, + "overrides": [] + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "expr": "sum by (consumer) (rate(sourceflow_deadletter_parked_total{job=~\"$job\"}[$__rate_interval]))", + "legendFormat": "{{consumer}}", + "refId": "A" + } + ] + }, + { + "id": 25, + "type": "timeseries", + "title": "sourceflow.deadletter.replayed", + "description": "Dead letters replayed by an operator.", + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 12, + "y": 73 + }, + "fieldConfig": { + "defaults": { + "unit": "ops" + }, + "overrides": [] + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "expr": "sum by (consumer) (rate(sourceflow_deadletter_replayed_total{job=~\"$job\"}[$__rate_interval]))", + "legendFormat": "{{consumer}}", + "refId": "A" + } + ] + }, + { + "id": 26, + "type": "timeseries", + "title": "sourceflow.deadletter.discarded", + "description": "Dead letters discarded by an operator.", + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 0, + "y": 81 + }, + "fieldConfig": { + "defaults": { + "unit": "ops" + }, + "overrides": [] + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "expr": "sum by (consumer) (rate(sourceflow_deadletter_discarded_total{job=~\"$job\"}[$__rate_interval]))", + "legendFormat": "{{consumer}}", + "refId": "A" + } + ] + }, + { + "id": 27, + "type": "timeseries", + "title": "sourceflow.deadletter.count", + "description": "Parked dead letters per consumer.", + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 12, + "y": 81 + }, + "fieldConfig": { + "defaults": { + "unit": "short" + }, + "overrides": [] + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "expr": "max by (consumer) (sourceflow_deadletter_count{job=~\"$job\"})", + "legendFormat": "{{consumer}}", + "refId": "A" + } + ] + }, + { + "id": 28, + "type": "row", + "title": "Subscriptions", + "collapsed": false, + "gridPos": { + "h": 1, + "w": 24, + "x": 0, + "y": 89 + }, + "panels": [] + }, + { + "id": 29, + "type": "timeseries", + "title": "sourceflow.subscription.lag", + "description": "Events not yet processed per subscription partition.", + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 0, + "y": 90 + }, + "fieldConfig": { + "defaults": { + "unit": "short" + }, + "overrides": [] + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "expr": "max by (sourceflow_subscription, sourceflow_partition) (sourceflow_subscription_lag{job=~\"$job\"})", + "legendFormat": "{{sourceflow_subscription}} {{sourceflow_partition}}", + "refId": "A" + } + ] + }, + { + "id": 30, + "type": "timeseries", + "title": "sourceflow.subscription.lag_time", + "description": "Age of the oldest unprocessed event per subscription partition (freshness SLO).", + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 12, + "y": 90 + }, + "fieldConfig": { + "defaults": { + "unit": "s" + }, + "overrides": [] + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "expr": "max by (sourceflow_subscription, sourceflow_partition) (sourceflow_subscription_lag_time_seconds{job=~\"$job\"})", + "legendFormat": "{{sourceflow_subscription}} {{sourceflow_partition}}", + "refId": "A" + } + ] + }, + { + "id": 31, + "type": "timeseries", + "title": "sourceflow.subscription.horizon_age", + "description": "How long the oldest writing transaction has held the subscription horizon back.", + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 0, + "y": 98 + }, + "fieldConfig": { + "defaults": { + "unit": "s" + }, + "overrides": [] + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "expr": "max (sourceflow_subscription_horizon_age_seconds{job=~\"$job\"})", + "legendFormat": "sourceflow.subscription.horizon_age", + "refId": "A" + } + ] + }, + { + "id": 32, + "type": "timeseries", + "title": "sourceflow.subscription.stalled", + "description": "Subscription partitions halted at a failing event (Stop policy).", + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 12, + "y": 98 + }, + "fieldConfig": { + "defaults": { + "unit": "short" + }, + "overrides": [] + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "expr": "max by (sourceflow_subscription, sourceflow_partition) (sourceflow_subscription_stalled{job=~\"$job\"})", + "legendFormat": "{{sourceflow_subscription}} {{sourceflow_partition}}", + "refId": "A" + } + ] + }, + { + "id": 33, + "type": "timeseries", + "title": "sourceflow.subscription.partition_mismatch", + "description": "Subscriptions this node refuses because its partition count differs from the stored one (doc 06 §3).", + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 0, + "y": 106 + }, + "fieldConfig": { + "defaults": { + "unit": "short" + }, + "overrides": [] + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "expr": "max by (sourceflow_subscription) (sourceflow_subscription_partition_mismatch{job=~\"$job\"})", + "legendFormat": "{{sourceflow_subscription}}", + "refId": "A" + } + ] + }, + { + "id": 34, + "type": "timeseries", + "title": "sourceflow.subscription.batch.duration", + "description": "Subscription batch duration.", + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 12, + "y": 106 + }, + "fieldConfig": { + "defaults": { + "unit": "s" + }, + "overrides": [] + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "expr": "histogram_quantile(0.99, sum by (le, sourceflow_subscription) (rate(sourceflow_subscription_batch_duration_seconds_bucket{job=~\"$job\"}[$__rate_interval])))", + "legendFormat": "p99 {{sourceflow_subscription}}", + "refId": "A" + }, + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "expr": "histogram_quantile(0.5, sum by (le, sourceflow_subscription) (rate(sourceflow_subscription_batch_duration_seconds_bucket{job=~\"$job\"}[$__rate_interval])))", + "legendFormat": "p50 {{sourceflow_subscription}}", + "refId": "B" + } + ] + }, + { + "id": 35, + "type": "row", + "title": "Process managers and leases", + "collapsed": false, + "gridPos": { + "h": 1, + "w": 24, + "x": 0, + "y": 114 + }, + "panels": [] + }, + { + "id": 36, + "type": "timeseries", + "title": "sourceflow.process.active", + "description": "Process-manager instances not completed, per process type.", + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 0, + "y": 115 + }, + "fieldConfig": { + "defaults": { + "unit": "short" + }, + "overrides": [] + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "expr": "max by (process_type) (sourceflow_process_active{job=~\"$job\"})", + "legendFormat": "{{process_type}}", + "refId": "A" + } + ] + }, + { + "id": 37, + "type": "timeseries", + "title": "sourceflow.lease.owned", + "description": "Subscription partition leases this node owns.", + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 12, + "y": 115 + }, + "fieldConfig": { + "defaults": { + "unit": "short" + }, + "overrides": [] + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "expr": "sum by (instance) (sourceflow_lease_owned{job=~\"$job\"})", + "legendFormat": "{{instance}}", + "refId": "A" + } + ] + }, + { + "id": 38, + "type": "row", + "title": "Workflows", + "collapsed": false, + "gridPos": { + "h": 1, + "w": 24, + "x": 0, + "y": 123 + }, + "panels": [] + }, + { + "id": 39, + "type": "timeseries", + "title": "sourceflow.workflow.transitions", + "description": "Workflow transitions by kind (success, failure, retry, timeout, compensate, manual, complete).", + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 0, + "y": 124 + }, + "fieldConfig": { + "defaults": { + "unit": "ops" + }, + "overrides": [] + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "expr": "sum by (workflow) (rate(sourceflow_workflow_transitions_total{job=~\"$job\"}[$__rate_interval]))", + "legendFormat": "{{workflow}}", + "refId": "A" + } + ] + }, + { + "id": 40, + "type": "timeseries", + "title": "sourceflow.workflow.active", + "description": "Workflow instances not finished, per workflow version and status.", + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 12, + "y": 124 + }, + "fieldConfig": { + "defaults": { + "unit": "short" + }, + "overrides": [] + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "expr": "max by (workflow, version, status) (sourceflow_workflow_active{job=~\"$job\"})", + "legendFormat": "{{workflow}} {{version}} {{status}}", + "refId": "A" + } + ] + }, + { + "id": 41, + "type": "timeseries", + "title": "sourceflow.workflow.manual_intervention", + "description": "Workflow instances that entered manual intervention (alert on any).", + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 0, + "y": 132 + }, + "fieldConfig": { + "defaults": { + "unit": "ops" + }, + "overrides": [] + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "expr": "sum by (workflow) (rate(sourceflow_workflow_manual_intervention_total{job=~\"$job\"}[$__rate_interval]))", + "legendFormat": "{{workflow}}", + "refId": "A" + } + ] + }, + { + "id": 42, + "type": "row", + "title": "Messaging (semantic conventions)", + "collapsed": false, + "gridPos": { + "h": 1, + "w": 24, + "x": 0, + "y": 140 + }, + "panels": [] + }, + { + "id": 43, + "type": "timeseries", + "title": "messaging.client.operation.duration", + "description": "Duration of a broker send or publish call.", + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 0, + "y": 141 + }, + "fieldConfig": { + "defaults": { + "unit": "s" + }, + "overrides": [] + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "expr": "histogram_quantile(0.99, sum by (le, messaging_system) (rate(messaging_client_operation_duration_seconds_bucket{job=~\"$job\"}[$__rate_interval])))", + "legendFormat": "p99 {{messaging_system}}", + "refId": "A" + }, + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "expr": "histogram_quantile(0.5, sum by (le, messaging_system) (rate(messaging_client_operation_duration_seconds_bucket{job=~\"$job\"}[$__rate_interval])))", + "legendFormat": "p50 {{messaging_system}}", + "refId": "B" + } + ] + }, + { + "id": 44, + "type": "timeseries", + "title": "messaging.client.sent.messages", + "description": "Messages sent to the broker.", + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 12, + "y": 141 + }, + "fieldConfig": { + "defaults": { + "unit": "ops" + }, + "overrides": [] + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "expr": "sum by (messaging_system) (rate(messaging_client_sent_messages_total{job=~\"$job\"}[$__rate_interval]))", + "legendFormat": "{{messaging_system}}", + "refId": "A" + } + ] + }, + { + "id": 45, + "type": "timeseries", + "title": "messaging.client.consumed.messages", + "description": "Messages received from the broker.", + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 0, + "y": 149 + }, + "fieldConfig": { + "defaults": { + "unit": "ops" + }, + "overrides": [] + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "expr": "sum by (messaging_system) (rate(messaging_client_consumed_messages_total{job=~\"$job\"}[$__rate_interval]))", + "legendFormat": "{{messaging_system}}", + "refId": "A" + } + ] + }, + { + "id": 46, + "type": "timeseries", + "title": "messaging.process.duration", + "description": "Received message processing duration.", + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 12, + "y": 149 + }, + "fieldConfig": { + "defaults": { + "unit": "s" + }, + "overrides": [] + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "expr": "histogram_quantile(0.99, sum by (le, messaging_system) (rate(messaging_process_duration_seconds_bucket{job=~\"$job\"}[$__rate_interval])))", + "legendFormat": "p99 {{messaging_system}}", + "refId": "A" + }, + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "expr": "histogram_quantile(0.5, sum by (le, messaging_system) (rate(messaging_process_duration_seconds_bucket{job=~\"$job\"}[$__rate_interval])))", + "legendFormat": "p50 {{messaging_system}}", + "refId": "B" + } + ] + } + ] +} diff --git a/deploy/topology/.gitignore b/deploy/topology/.gitignore new file mode 100644 index 00000000..34939a4a --- /dev/null +++ b/deploy/topology/.gitignore @@ -0,0 +1,4 @@ +.terraform/ +.terraform.lock.hcl +*.tfstate +*.tfstate.* diff --git a/deploy/topology/README.md b/deploy/topology/README.md new file mode 100644 index 00000000..71bb2e6f --- /dev/null +++ b/deploy/topology/README.md @@ -0,0 +1,75 @@ +# Topology as code + +These modules create a service's broker resources from its topology export, so production services can run with +`ProvisioningMode.Validate` and describe-only permissions (ADR-017, doc 07 §5). + +```bash +dotnet sourceflow topology export --output accounts.topology.json +``` + +The export names every resource the transport would create, in the provider's own terms. A module only reads it; it +never computes a name, so the module and the service cannot disagree. `topology.schema.json` is the export's JSON Schema. + +| Folder | Provider | Creates | +|--------|----------|---------| +| `terraform/aws` | Amazon SQS and SNS | Endpoint queue with a redrive policy to its dead-letter queue (FIFO when ordered), published topics, raw-delivery subscriptions with filter policies, and the queue policy for the subscribed topics. The `runtime_policy_json` output is the service's least-privilege IAM policy. | +| `terraform/gcp` | Google Cloud Pub/Sub | Command topic and subscription, dead-letter topic and subscription, published topics, one subscription per subscribed topic. Grants the Pub/Sub service agent what dead-lettering needs (`grant_service_agent`), and the service's identity what it needs at runtime (`runtime_member`, optional). | +| `terraform/azure` | Azure Service Bus | Endpoint queue, published topics, and a forwarding subscription per subscribed topic with its rules, in an existing namespace. | +| `bicep/servicebus.bicep` | Azure Service Bus | The same as `terraform/azure`, for Bicep and ARM deployments. | + +## Using a module + +```hcl +module "accounts_topology" { + source = "github.com/CodeShayk/SourceFlow.Net//deploy/topology/terraform/aws?ref=v3.0.0" + topology = file("${path.module}/accounts.topology.json") +} +``` + +```bicep +module accounts 'servicebus.bicep' = { + name: 'accounts-topology' + params: { + namespaceName: 'my-namespace' + topology: loadJsonContent('accounts.topology.json') + } +} +``` + +A topic belongs to the service that publishes it. The subscriber's module looks a subscribed topic up rather than +creating it, so apply the publisher's stack first. In a single stack holding every service, set +`create_subscribed_topics = true` (Bicep: `createSubscribedTopics`). + +Each module checks that the export is for its provider and is schema version 1. + +## Notes per provider + +- **Azure.** ARM creates a match-everything rule called `$Default` with every subscription. The export names each + subscription's first rule `$Default`, and the modules overwrite it rather than adding a rule beside it. The Terraform + module uses `azapi_update_resource` for this. `Validate` compares the filters, not the rule names. +- **Azure permissions.** At runtime a service reads its queue's settings, which Service Bus allows only with the Manage + right. Give the service Azure Service Bus Data Owner on its queue, or let it provision itself. +- **Google Cloud.** Pub/Sub accepts 5 to 100 delivery attempts. A lower limit is in the `sf-max-deliveries` label, and + the receiver enforces it itself. + +## Fixtures and tests + +`fixtures/{transport}/*.json` are the exports of the conformance kit's topology fixtures (`TopologyFixtures` in +`SourceFlow.Testing`): an endpoint alone, the TCK provisioning topology, ordering, every kind of filter, and a publisher +and subscriber sharing a topic. They are generated by the libraries, and a test fails when they drift. To regenerate +them, run the cloud tests with `SOURCEFLOW_APPROVE=1`. + +| Test | What it checks | +|------|----------------| +| `terraform test` in each `terraform/*` folder | Every fixture against mock providers: resource counts, settings, the wrong-provider check | +| IAC-01 | `terraform/aws` applied to LocalStack; the result passes the AWS transport's `Validate` | +| IAC-02 | `terraform/gcp` applied to the Pub/Sub emulator; the result passes the Google Cloud transport's `Validate` | +| IAC-03 | Runs each module's `terraform test` suite | +| IAC-04 | `bicep build` of the module for every Azure fixture | +| UT-TOP-12 | `ProvisionAsync(CreateIfMissing)` on each emulator creates every owned resource the export describes | + +The Service Bus emulator has no ARM endpoint, so the Azure modules are not applied in CI. The mock-provider suite, +the Bicep build and UT-TOP-12 cover them instead. + +The IaC tests run in the `iac` job of `v3-pr`. Locally they use `terraform` on the path, or, with `SOURCEFLOW_IAC=1`, +the pinned `hashicorp/terraform` image in Docker. diff --git a/deploy/topology/bicep/servicebus.bicep b/deploy/topology/bicep/servicebus.bicep new file mode 100644 index 00000000..3551638c --- /dev/null +++ b/deploy/topology/bicep/servicebus.bicep @@ -0,0 +1,98 @@ +// SourceFlow topology on Azure Service Bus (doc 07 §5, ADR-017). +// +// Creates what `ProvisioningMode.CreateIfMissing` would create for one service, from the JSON written by +// `dotnet sourceflow topology export` with the Azure transport, in an existing namespace: the endpoint queue, the +// topics the service publishes, and on each subscribed topic a subscription that forwards to the queue, with the +// filter's rules. A subscription's first rule is named $Default in the export, so it replaces the match-everything +// rule ARM creates with every subscription. Names and filters come from the export. +// +// Usage: +// module accounts 'servicebus.bicep' = { +// name: 'accounts-topology' +// params: { +// namespaceName: 'my-namespace' +// topology: loadJsonContent('accounts.topology.json') +// } +// } + +@description('The name of an existing Service Bus namespace (Standard or Premium tier) in the deployment\'s resource group.') +param namespaceName string + +@description('The JSON written by `dotnet sourceflow topology export` with the Azure transport (loadJsonContent).') +param topology object + +@description('Also create the topics the service subscribes to but does not publish (a single deployment holding every service).') +param createSubscribedTopics bool = false + +var resources = topology.resources +var queues = filter(resources, r => r.kind == 'queue' && r.owned && r.role == 'endpoint') +var topics = filter(resources, r => r.kind == 'topic' && (r.owned || createSubscribedTopics)) +var subscriptions = filter(resources, r => r.kind == 'subscription') +var rules = filter(resources, r => r.kind == 'rule') + +resource namespace 'Microsoft.ServiceBus/namespaces@2022-10-01-preview' existing = { + name: namespaceName +} + +resource queue 'Microsoft.ServiceBus/namespaces/queues@2022-10-01-preview' = [for q in queues: { + parent: namespace + name: q.name + properties: { + requiresSession: q.properties.requiresSession + maxDeliveryCount: q.properties.maxDeliveryCount + lockDuration: q.properties.lockDuration + defaultMessageTimeToLive: q.properties.defaultMessageTimeToLive + deadLetteringOnMessageExpiration: q.properties.deadLetteringOnMessageExpiration + requiresDuplicateDetection: q.properties.requiresDuplicateDetection + duplicateDetectionHistoryTimeWindow: q.properties.duplicateDetectionHistoryTimeWindow ?? 'PT10M' + } +}] + +resource topic 'Microsoft.ServiceBus/namespaces/topics@2022-10-01-preview' = [for t in topics: { + parent: namespace + name: t.name + properties: { + defaultMessageTimeToLive: t.properties.defaultMessageTimeToLive + } +}] + +#disable-next-line use-parent-property +resource subscription 'Microsoft.ServiceBus/namespaces/topics/subscriptions@2022-10-01-preview' = [for s in subscriptions: { + name: '${namespaceName}/${s.properties.topic}/${s.properties.subscription}' + properties: { + forwardTo: s.properties.forwardTo + defaultMessageTimeToLive: s.properties.defaultMessageTimeToLive + maxDeliveryCount: 10 + } + dependsOn: [ + queue + topic + ] +}] + +#disable-next-line use-parent-property +resource rule 'Microsoft.ServiceBus/namespaces/topics/subscriptions/rules@2022-10-01-preview' = [for r in rules: { + name: '${namespaceName}/${r.properties.topic}/${r.properties.subscription}/${r.properties.rule}' + properties: r.properties.filterType == 'CorrelationFilter' + ? { + filterType: 'CorrelationFilter' + correlationFilter: { + properties: r.properties.correlationProperties + } + } + : { + filterType: 'SqlFilter' + sqlFilter: { + sqlExpression: r.properties.sqlExpression + } + } + dependsOn: [ + subscription + ] +}] + +@description('The names of the queues created.') +output queueNames array = [for q in queues: q.name] + +@description('The names of the topics created.') +output topicNames array = [for t in topics: t.name] diff --git a/deploy/topology/fixtures/aws/filtered.json b/deploy/topology/fixtures/aws/filtered.json new file mode 100644 index 00000000..0551ea8f --- /dev/null +++ b/deploy/topology/fixtures/aws/filtered.json @@ -0,0 +1,166 @@ +{ + "schemaVersion": 1, + "service": "filtered", + "transport": "aws_sqs", + "endpoint": { + "name": "filtered", + "ordered": false, + "maxDeliveries": 10, + "commands": [] + }, + "publishes": [], + "subscribes": [ + { + "topic": "everything", + "filter": null + }, + { + "topic": "prefixed", + "filter": "type LIKE 'tck.%' OR type LIKE 'payments.%'" + }, + { + "topic": "tenant", + "filter": "type = 'tck.tenant.v1' AND sftenant = 'eu'" + }, + { + "topic": "typed", + "filter": "type IN ('tck.also.v2', 'tck.wanted.v1')" + } + ], + "sends": [], + "resources": [ + { + "kind": "queue", + "name": "dev-filtered-dlq", + "logical": "filtered", + "owned": true, + "role": "dead-letter", + "properties": { + "allowTopics": [], + "deadLetterQueue": null, + "fifo": false, + "maxReceiveCount": null, + "messageRetentionSeconds": 1209600 + } + }, + { + "kind": "queue", + "name": "dev-filtered", + "logical": "filtered", + "owned": true, + "role": "endpoint", + "properties": { + "allowTopics": [ + "dev-everything", + "dev-prefixed", + "dev-tenant", + "dev-typed" + ], + "deadLetterQueue": "dev-filtered-dlq", + "fifo": false, + "maxReceiveCount": 10, + "messageRetentionSeconds": 1209600 + } + }, + { + "kind": "topic", + "name": "dev-typed", + "logical": "typed", + "owned": false, + "role": "topic", + "properties": { + "fifo": false + } + }, + { + "kind": "topic", + "name": "dev-prefixed", + "logical": "prefixed", + "owned": false, + "role": "topic", + "properties": { + "fifo": false + } + }, + { + "kind": "topic", + "name": "dev-tenant", + "logical": "tenant", + "owned": false, + "role": "topic", + "properties": { + "fifo": false + } + }, + { + "kind": "topic", + "name": "dev-everything", + "logical": "everything", + "owned": false, + "role": "topic", + "properties": { + "fifo": false + } + }, + { + "kind": "subscription", + "name": "dev-typed/dev-filtered", + "logical": "typed → filtered", + "owned": true, + "role": "subscription", + "properties": { + "filterPolicy": "{\"ce_type\":[\"tck.also.v2\",\"tck.wanted.v1\"]}", + "filterPolicyScope": "MessageAttributes", + "protocol": "sqs", + "queue": "dev-filtered", + "rawMessageDelivery": true, + "topic": "dev-typed" + } + }, + { + "kind": "subscription", + "name": "dev-prefixed/dev-filtered", + "logical": "prefixed → filtered", + "owned": true, + "role": "subscription", + "properties": { + "filterPolicy": "{\"ce_type\":[{\"prefix\":\"payments.\"},{\"prefix\":\"tck.\"}]}", + "filterPolicyScope": "MessageAttributes", + "protocol": "sqs", + "queue": "dev-filtered", + "rawMessageDelivery": true, + "topic": "dev-prefixed" + } + }, + { + "kind": "subscription", + "name": "dev-tenant/dev-filtered", + "logical": "tenant → filtered", + "owned": true, + "role": "subscription", + "properties": { + "filterPolicy": null, + "filterPolicyScope": null, + "protocol": "sqs", + "queue": "dev-filtered", + "rawMessageDelivery": true, + "topic": "dev-tenant" + } + }, + { + "kind": "subscription", + "name": "dev-everything/dev-filtered", + "logical": "everything → filtered", + "owned": true, + "role": "subscription", + "properties": { + "filterPolicy": null, + "filterPolicyScope": null, + "protocol": "sqs", + "queue": "dev-filtered", + "rawMessageDelivery": true, + "topic": "dev-everything" + } + } + ] +} diff --git a/deploy/topology/fixtures/aws/full.json b/deploy/topology/fixtures/aws/full.json new file mode 100644 index 00000000..5040f7cd --- /dev/null +++ b/deploy/topology/fixtures/aws/full.json @@ -0,0 +1,92 @@ +{ + "schemaVersion": 1, + "service": "full", + "transport": "aws_sqs", + "endpoint": { + "name": "full", + "ordered": false, + "maxDeliveries": 7, + "commands": [] + }, + "publishes": [ + { + "topic": "full-out", + "ordered": false, + "messages": [] + } + ], + "subscribes": [ + { + "topic": "full-in", + "filter": "type LIKE 'tck.%'" + } + ], + "sends": [], + "resources": [ + { + "kind": "queue", + "name": "dev-full-dlq", + "logical": "full", + "owned": true, + "role": "dead-letter", + "properties": { + "allowTopics": [], + "deadLetterQueue": null, + "fifo": false, + "maxReceiveCount": null, + "messageRetentionSeconds": 1209600 + } + }, + { + "kind": "queue", + "name": "dev-full", + "logical": "full", + "owned": true, + "role": "endpoint", + "properties": { + "allowTopics": [ + "dev-full-in" + ], + "deadLetterQueue": "dev-full-dlq", + "fifo": false, + "maxReceiveCount": 7, + "messageRetentionSeconds": 1209600 + } + }, + { + "kind": "topic", + "name": "dev-full-out", + "logical": "full-out", + "owned": true, + "role": "topic", + "properties": { + "fifo": false + } + }, + { + "kind": "topic", + "name": "dev-full-in", + "logical": "full-in", + "owned": false, + "role": "topic", + "properties": { + "fifo": false + } + }, + { + "kind": "subscription", + "name": "dev-full-in/dev-full", + "logical": "full-in → full", + "owned": true, + "role": "subscription", + "properties": { + "filterPolicy": "{\"ce_type\":[{\"prefix\":\"tck.\"}]}", + "filterPolicyScope": "MessageAttributes", + "protocol": "sqs", + "queue": "dev-full", + "rawMessageDelivery": true, + "topic": "dev-full-in" + } + } + ] +} diff --git a/deploy/topology/fixtures/aws/minimal.json b/deploy/topology/fixtures/aws/minimal.json new file mode 100644 index 00000000..15531f31 --- /dev/null +++ b/deploy/topology/fixtures/aws/minimal.json @@ -0,0 +1,44 @@ +{ + "schemaVersion": 1, + "service": "minimal", + "transport": "aws_sqs", + "endpoint": { + "name": "minimal", + "ordered": false, + "maxDeliveries": 10, + "commands": [] + }, + "publishes": [], + "subscribes": [], + "sends": [], + "resources": [ + { + "kind": "queue", + "name": "dev-minimal-dlq", + "logical": "minimal", + "owned": true, + "role": "dead-letter", + "properties": { + "allowTopics": [], + "deadLetterQueue": null, + "fifo": false, + "maxReceiveCount": null, + "messageRetentionSeconds": 1209600 + } + }, + { + "kind": "queue", + "name": "dev-minimal", + "logical": "minimal", + "owned": true, + "role": "endpoint", + "properties": { + "allowTopics": [], + "deadLetterQueue": "dev-minimal-dlq", + "fifo": false, + "maxReceiveCount": 10, + "messageRetentionSeconds": 1209600 + } + } + ] +} diff --git a/deploy/topology/fixtures/aws/ordered.json b/deploy/topology/fixtures/aws/ordered.json new file mode 100644 index 00000000..dd0eeb9e --- /dev/null +++ b/deploy/topology/fixtures/aws/ordered.json @@ -0,0 +1,110 @@ +{ + "schemaVersion": 1, + "service": "ordered", + "transport": "aws_sqs", + "endpoint": { + "name": "ordered", + "ordered": true, + "maxDeliveries": 5, + "commands": [] + }, + "publishes": [ + { + "topic": "ordered-out", + "ordered": true, + "messages": [] + } + ], + "subscribes": [ + { + "topic": "ordered-in", + "filter": "type = 'tck.ordered.v1'" + } + ], + "sends": [ + { + "endpoint": "minimal", + "commands": [] + } + ], + "resources": [ + { + "kind": "queue", + "name": "dev-ordered-dlq.fifo", + "logical": "ordered", + "owned": true, + "role": "dead-letter", + "properties": { + "allowTopics": [], + "deadLetterQueue": null, + "fifo": true, + "maxReceiveCount": null, + "messageRetentionSeconds": 1209600 + } + }, + { + "kind": "queue", + "name": "dev-ordered.fifo", + "logical": "ordered", + "owned": true, + "role": "endpoint", + "properties": { + "allowTopics": [ + "dev-ordered-in.fifo" + ], + "deadLetterQueue": "dev-ordered-dlq.fifo", + "fifo": true, + "maxReceiveCount": 5, + "messageRetentionSeconds": 1209600 + } + }, + { + "kind": "topic", + "name": "dev-ordered-out.fifo", + "logical": "ordered-out", + "owned": true, + "role": "topic", + "properties": { + "fifo": true + } + }, + { + "kind": "topic", + "name": "dev-ordered-in.fifo", + "logical": "ordered-in", + "owned": false, + "role": "topic", + "properties": { + "fifo": true + } + }, + { + "kind": "subscription", + "name": "dev-ordered-in.fifo/dev-ordered.fifo", + "logical": "ordered-in → ordered", + "owned": true, + "role": "subscription", + "properties": { + "filterPolicy": "{\"ce_type\":[\"tck.ordered.v1\"]}", + "filterPolicyScope": "MessageAttributes", + "protocol": "sqs", + "queue": "dev-ordered.fifo", + "rawMessageDelivery": true, + "topic": "dev-ordered-in.fifo" + } + }, + { + "kind": "queue", + "name": "dev-minimal", + "logical": "minimal", + "owned": false, + "role": "remote-endpoint", + "properties": { + "candidates": [ + "dev-minimal", + "dev-minimal.fifo" + ] + } + } + ] +} diff --git a/deploy/topology/fixtures/aws/publisher.json b/deploy/topology/fixtures/aws/publisher.json new file mode 100644 index 00000000..43659a1c --- /dev/null +++ b/deploy/topology/fixtures/aws/publisher.json @@ -0,0 +1,78 @@ +{ + "schemaVersion": 1, + "service": "publisher", + "transport": "aws_sqs", + "endpoint": { + "name": "publisher", + "ordered": false, + "maxDeliveries": 10, + "commands": [] + }, + "publishes": [ + { + "topic": "shared", + "ordered": false, + "messages": [] + } + ], + "subscribes": [], + "sends": [ + { + "endpoint": "subscriber", + "commands": [] + } + ], + "resources": [ + { + "kind": "queue", + "name": "dev-publisher-dlq", + "logical": "publisher", + "owned": true, + "role": "dead-letter", + "properties": { + "allowTopics": [], + "deadLetterQueue": null, + "fifo": false, + "maxReceiveCount": null, + "messageRetentionSeconds": 1209600 + } + }, + { + "kind": "queue", + "name": "dev-publisher", + "logical": "publisher", + "owned": true, + "role": "endpoint", + "properties": { + "allowTopics": [], + "deadLetterQueue": "dev-publisher-dlq", + "fifo": false, + "maxReceiveCount": 10, + "messageRetentionSeconds": 1209600 + } + }, + { + "kind": "topic", + "name": "dev-shared", + "logical": "shared", + "owned": true, + "role": "topic", + "properties": { + "fifo": false + } + }, + { + "kind": "queue", + "name": "dev-subscriber", + "logical": "subscriber", + "owned": false, + "role": "remote-endpoint", + "properties": { + "candidates": [ + "dev-subscriber", + "dev-subscriber.fifo" + ] + } + } + ] +} diff --git a/deploy/topology/fixtures/aws/subscriber.json b/deploy/topology/fixtures/aws/subscriber.json new file mode 100644 index 00000000..f2ef0422 --- /dev/null +++ b/deploy/topology/fixtures/aws/subscriber.json @@ -0,0 +1,76 @@ +{ + "schemaVersion": 1, + "service": "subscriber", + "transport": "aws_sqs", + "endpoint": { + "name": "subscriber", + "ordered": false, + "maxDeliveries": 10, + "commands": [] + }, + "publishes": [], + "subscribes": [ + { + "topic": "shared", + "filter": "type = 'tck.shared.v1'" + } + ], + "sends": [], + "resources": [ + { + "kind": "queue", + "name": "dev-subscriber-dlq", + "logical": "subscriber", + "owned": true, + "role": "dead-letter", + "properties": { + "allowTopics": [], + "deadLetterQueue": null, + "fifo": false, + "maxReceiveCount": null, + "messageRetentionSeconds": 1209600 + } + }, + { + "kind": "queue", + "name": "dev-subscriber", + "logical": "subscriber", + "owned": true, + "role": "endpoint", + "properties": { + "allowTopics": [ + "dev-shared" + ], + "deadLetterQueue": "dev-subscriber-dlq", + "fifo": false, + "maxReceiveCount": 10, + "messageRetentionSeconds": 1209600 + } + }, + { + "kind": "topic", + "name": "dev-shared", + "logical": "shared", + "owned": false, + "role": "topic", + "properties": { + "fifo": false + } + }, + { + "kind": "subscription", + "name": "dev-shared/dev-subscriber", + "logical": "shared → subscriber", + "owned": true, + "role": "subscription", + "properties": { + "filterPolicy": "{\"ce_type\":[\"tck.shared.v1\"]}", + "filterPolicyScope": "MessageAttributes", + "protocol": "sqs", + "queue": "dev-subscriber", + "rawMessageDelivery": true, + "topic": "dev-shared" + } + } + ] +} diff --git a/deploy/topology/fixtures/azure/filtered.json b/deploy/topology/fixtures/azure/filtered.json new file mode 100644 index 00000000..aed654eb --- /dev/null +++ b/deploy/topology/fixtures/azure/filtered.json @@ -0,0 +1,235 @@ +{ + "schemaVersion": 1, + "service": "filtered", + "transport": "servicebus", + "endpoint": { + "name": "filtered", + "ordered": false, + "maxDeliveries": 10, + "commands": [] + }, + "publishes": [], + "subscribes": [ + { + "topic": "everything", + "filter": null + }, + { + "topic": "prefixed", + "filter": "type LIKE 'tck.%' OR type LIKE 'payments.%'" + }, + { + "topic": "tenant", + "filter": "type = 'tck.tenant.v1' AND sftenant = 'eu'" + }, + { + "topic": "typed", + "filter": "type IN ('tck.also.v2', 'tck.wanted.v1')" + } + ], + "sends": [], + "resources": [ + { + "kind": "queue", + "name": "dev-filtered", + "logical": "filtered", + "owned": true, + "role": "endpoint", + "properties": { + "deadLetteringOnMessageExpiration": true, + "defaultMessageTimeToLive": "P14D", + "duplicateDetectionHistoryTimeWindow": null, + "lockDuration": "PT30S", + "maxDeliveryCount": 10, + "requiresDuplicateDetection": false, + "requiresSession": false + } + }, + { + "kind": "topic", + "name": "dev-typed", + "logical": "typed", + "owned": false, + "role": "topic", + "properties": { + "defaultMessageTimeToLive": "P14D" + } + }, + { + "kind": "topic", + "name": "dev-prefixed", + "logical": "prefixed", + "owned": false, + "role": "topic", + "properties": { + "defaultMessageTimeToLive": "P14D" + } + }, + { + "kind": "topic", + "name": "dev-tenant", + "logical": "tenant", + "owned": false, + "role": "topic", + "properties": { + "defaultMessageTimeToLive": "P14D" + } + }, + { + "kind": "topic", + "name": "dev-everything", + "logical": "everything", + "owned": false, + "role": "topic", + "properties": { + "defaultMessageTimeToLive": "P14D" + } + }, + { + "kind": "subscription", + "name": "dev-typed/dev-filtered", + "logical": "typed → filtered", + "owned": true, + "role": "subscription", + "properties": { + "defaultMessageTimeToLive": "P14D", + "forwardTo": "dev-filtered", + "subscription": "dev-filtered", + "topic": "dev-typed" + } + }, + { + "kind": "rule", + "name": "dev-typed/dev-filtered/$Default", + "logical": "typed → filtered", + "owned": true, + "role": "rule", + "properties": { + "correlationProperties": { + "cloudEvents:type": "tck.also.v2" + }, + "filterType": "CorrelationFilter", + "rule": "$Default", + "sqlExpression": null, + "subscription": "dev-filtered", + "topic": "dev-typed" + } + }, + { + "kind": "rule", + "name": "dev-typed/dev-filtered/sf-type-1", + "logical": "typed → filtered", + "owned": true, + "role": "rule", + "properties": { + "correlationProperties": { + "cloudEvents:type": "tck.wanted.v1" + }, + "filterType": "CorrelationFilter", + "rule": "sf-type-1", + "sqlExpression": null, + "subscription": "dev-filtered", + "topic": "dev-typed" + } + }, + { + "kind": "subscription", + "name": "dev-prefixed/dev-filtered", + "logical": "prefixed → filtered", + "owned": true, + "role": "subscription", + "properties": { + "defaultMessageTimeToLive": "P14D", + "forwardTo": "dev-filtered", + "subscription": "dev-filtered", + "topic": "dev-prefixed" + } + }, + { + "kind": "rule", + "name": "dev-prefixed/dev-filtered/$Default", + "logical": "prefixed → filtered", + "owned": true, + "role": "rule", + "properties": { + "correlationProperties": null, + "filterType": "SqlFilter", + "rule": "$Default", + "sqlExpression": "[cloudEvents:type] LIKE 'payments.%'", + "subscription": "dev-filtered", + "topic": "dev-prefixed" + } + }, + { + "kind": "rule", + "name": "dev-prefixed/dev-filtered/sf-prefix-1", + "logical": "prefixed → filtered", + "owned": true, + "role": "rule", + "properties": { + "correlationProperties": null, + "filterType": "SqlFilter", + "rule": "sf-prefix-1", + "sqlExpression": "[cloudEvents:type] LIKE 'tck.%'", + "subscription": "dev-filtered", + "topic": "dev-prefixed" + } + }, + { + "kind": "subscription", + "name": "dev-tenant/dev-filtered", + "logical": "tenant → filtered", + "owned": true, + "role": "subscription", + "properties": { + "defaultMessageTimeToLive": "P14D", + "forwardTo": "dev-filtered", + "subscription": "dev-filtered", + "topic": "dev-tenant" + } + }, + { + "kind": "rule", + "name": "dev-tenant/dev-filtered/$Default", + "logical": "tenant → filtered", + "owned": true, + "role": "rule", + "properties": { + "correlationProperties": null, + "filterType": "SqlFilter", + "rule": "$Default", + "sqlExpression": "1=1", + "subscription": "dev-filtered", + "topic": "dev-tenant" + } + }, + { + "kind": "subscription", + "name": "dev-everything/dev-filtered", + "logical": "everything → filtered", + "owned": true, + "role": "subscription", + "properties": { + "defaultMessageTimeToLive": "P14D", + "forwardTo": "dev-filtered", + "subscription": "dev-filtered", + "topic": "dev-everything" + } + }, + { + "kind": "rule", + "name": "dev-everything/dev-filtered/$Default", + "logical": "everything → filtered", + "owned": true, + "role": "rule", + "properties": { + "correlationProperties": null, + "filterType": "SqlFilter", + "rule": "$Default", + "sqlExpression": "1=1", + "subscription": "dev-filtered", + "topic": "dev-everything" + } + } + ] +} diff --git a/deploy/topology/fixtures/azure/full.json b/deploy/topology/fixtures/azure/full.json new file mode 100644 index 00000000..0a5988d4 --- /dev/null +++ b/deploy/topology/fixtures/azure/full.json @@ -0,0 +1,91 @@ +{ + "schemaVersion": 1, + "service": "full", + "transport": "servicebus", + "endpoint": { + "name": "full", + "ordered": false, + "maxDeliveries": 7, + "commands": [] + }, + "publishes": [ + { + "topic": "full-out", + "ordered": false, + "messages": [] + } + ], + "subscribes": [ + { + "topic": "full-in", + "filter": "type LIKE 'tck.%'" + } + ], + "sends": [], + "resources": [ + { + "kind": "queue", + "name": "dev-full", + "logical": "full", + "owned": true, + "role": "endpoint", + "properties": { + "deadLetteringOnMessageExpiration": true, + "defaultMessageTimeToLive": "P14D", + "duplicateDetectionHistoryTimeWindow": null, + "lockDuration": "PT30S", + "maxDeliveryCount": 7, + "requiresDuplicateDetection": false, + "requiresSession": false + } + }, + { + "kind": "topic", + "name": "dev-full-out", + "logical": "full-out", + "owned": true, + "role": "topic", + "properties": { + "defaultMessageTimeToLive": "P14D" + } + }, + { + "kind": "topic", + "name": "dev-full-in", + "logical": "full-in", + "owned": false, + "role": "topic", + "properties": { + "defaultMessageTimeToLive": "P14D" + } + }, + { + "kind": "subscription", + "name": "dev-full-in/dev-full", + "logical": "full-in → full", + "owned": true, + "role": "subscription", + "properties": { + "defaultMessageTimeToLive": "P14D", + "forwardTo": "dev-full", + "subscription": "dev-full", + "topic": "dev-full-in" + } + }, + { + "kind": "rule", + "name": "dev-full-in/dev-full/$Default", + "logical": "full-in → full", + "owned": true, + "role": "rule", + "properties": { + "correlationProperties": null, + "filterType": "SqlFilter", + "rule": "$Default", + "sqlExpression": "[cloudEvents:type] LIKE 'tck.%'", + "subscription": "dev-full", + "topic": "dev-full-in" + } + } + ] +} diff --git a/deploy/topology/fixtures/azure/minimal.json b/deploy/topology/fixtures/azure/minimal.json new file mode 100644 index 00000000..00a1cba1 --- /dev/null +++ b/deploy/topology/fixtures/azure/minimal.json @@ -0,0 +1,32 @@ +{ + "schemaVersion": 1, + "service": "minimal", + "transport": "servicebus", + "endpoint": { + "name": "minimal", + "ordered": false, + "maxDeliveries": 10, + "commands": [] + }, + "publishes": [], + "subscribes": [], + "sends": [], + "resources": [ + { + "kind": "queue", + "name": "dev-minimal", + "logical": "minimal", + "owned": true, + "role": "endpoint", + "properties": { + "deadLetteringOnMessageExpiration": true, + "defaultMessageTimeToLive": "P14D", + "duplicateDetectionHistoryTimeWindow": null, + "lockDuration": "PT30S", + "maxDeliveryCount": 10, + "requiresDuplicateDetection": false, + "requiresSession": false + } + } + ] +} diff --git a/deploy/topology/fixtures/azure/ordered.json b/deploy/topology/fixtures/azure/ordered.json new file mode 100644 index 00000000..e05df7a6 --- /dev/null +++ b/deploy/topology/fixtures/azure/ordered.json @@ -0,0 +1,106 @@ +{ + "schemaVersion": 1, + "service": "ordered", + "transport": "servicebus", + "endpoint": { + "name": "ordered", + "ordered": true, + "maxDeliveries": 5, + "commands": [] + }, + "publishes": [ + { + "topic": "ordered-out", + "ordered": true, + "messages": [] + } + ], + "subscribes": [ + { + "topic": "ordered-in", + "filter": "type = 'tck.ordered.v1'" + } + ], + "sends": [ + { + "endpoint": "minimal", + "commands": [] + } + ], + "resources": [ + { + "kind": "queue", + "name": "dev-ordered", + "logical": "ordered", + "owned": true, + "role": "endpoint", + "properties": { + "deadLetteringOnMessageExpiration": true, + "defaultMessageTimeToLive": "P14D", + "duplicateDetectionHistoryTimeWindow": null, + "lockDuration": "PT30S", + "maxDeliveryCount": 5, + "requiresDuplicateDetection": false, + "requiresSession": true + } + }, + { + "kind": "topic", + "name": "dev-ordered-out", + "logical": "ordered-out", + "owned": true, + "role": "topic", + "properties": { + "defaultMessageTimeToLive": "P14D" + } + }, + { + "kind": "topic", + "name": "dev-ordered-in", + "logical": "ordered-in", + "owned": false, + "role": "topic", + "properties": { + "defaultMessageTimeToLive": "P14D" + } + }, + { + "kind": "subscription", + "name": "dev-ordered-in/dev-ordered", + "logical": "ordered-in → ordered", + "owned": true, + "role": "subscription", + "properties": { + "defaultMessageTimeToLive": "P14D", + "forwardTo": "dev-ordered", + "subscription": "dev-ordered", + "topic": "dev-ordered-in" + } + }, + { + "kind": "rule", + "name": "dev-ordered-in/dev-ordered/$Default", + "logical": "ordered-in → ordered", + "owned": true, + "role": "rule", + "properties": { + "correlationProperties": { + "cloudEvents:type": "tck.ordered.v1" + }, + "filterType": "CorrelationFilter", + "rule": "$Default", + "sqlExpression": null, + "subscription": "dev-ordered", + "topic": "dev-ordered-in" + } + }, + { + "kind": "queue", + "name": "dev-minimal", + "logical": "minimal", + "owned": false, + "role": "remote-endpoint", + "properties": {} + } + ] +} diff --git a/deploy/topology/fixtures/azure/publisher.json b/deploy/topology/fixtures/azure/publisher.json new file mode 100644 index 00000000..a4e637a6 --- /dev/null +++ b/deploy/topology/fixtures/azure/publisher.json @@ -0,0 +1,61 @@ +{ + "schemaVersion": 1, + "service": "publisher", + "transport": "servicebus", + "endpoint": { + "name": "publisher", + "ordered": false, + "maxDeliveries": 10, + "commands": [] + }, + "publishes": [ + { + "topic": "shared", + "ordered": false, + "messages": [] + } + ], + "subscribes": [], + "sends": [ + { + "endpoint": "subscriber", + "commands": [] + } + ], + "resources": [ + { + "kind": "queue", + "name": "dev-publisher", + "logical": "publisher", + "owned": true, + "role": "endpoint", + "properties": { + "deadLetteringOnMessageExpiration": true, + "defaultMessageTimeToLive": "P14D", + "duplicateDetectionHistoryTimeWindow": null, + "lockDuration": "PT30S", + "maxDeliveryCount": 10, + "requiresDuplicateDetection": false, + "requiresSession": false + } + }, + { + "kind": "topic", + "name": "dev-shared", + "logical": "shared", + "owned": true, + "role": "topic", + "properties": { + "defaultMessageTimeToLive": "P14D" + } + }, + { + "kind": "queue", + "name": "dev-subscriber", + "logical": "subscriber", + "owned": false, + "role": "remote-endpoint", + "properties": {} + } + ] +} diff --git a/deploy/topology/fixtures/azure/subscriber.json b/deploy/topology/fixtures/azure/subscriber.json new file mode 100644 index 00000000..19c339da --- /dev/null +++ b/deploy/topology/fixtures/azure/subscriber.json @@ -0,0 +1,77 @@ +{ + "schemaVersion": 1, + "service": "subscriber", + "transport": "servicebus", + "endpoint": { + "name": "subscriber", + "ordered": false, + "maxDeliveries": 10, + "commands": [] + }, + "publishes": [], + "subscribes": [ + { + "topic": "shared", + "filter": "type = 'tck.shared.v1'" + } + ], + "sends": [], + "resources": [ + { + "kind": "queue", + "name": "dev-subscriber", + "logical": "subscriber", + "owned": true, + "role": "endpoint", + "properties": { + "deadLetteringOnMessageExpiration": true, + "defaultMessageTimeToLive": "P14D", + "duplicateDetectionHistoryTimeWindow": null, + "lockDuration": "PT30S", + "maxDeliveryCount": 10, + "requiresDuplicateDetection": false, + "requiresSession": false + } + }, + { + "kind": "topic", + "name": "dev-shared", + "logical": "shared", + "owned": false, + "role": "topic", + "properties": { + "defaultMessageTimeToLive": "P14D" + } + }, + { + "kind": "subscription", + "name": "dev-shared/dev-subscriber", + "logical": "shared → subscriber", + "owned": true, + "role": "subscription", + "properties": { + "defaultMessageTimeToLive": "P14D", + "forwardTo": "dev-subscriber", + "subscription": "dev-subscriber", + "topic": "dev-shared" + } + }, + { + "kind": "rule", + "name": "dev-shared/dev-subscriber/$Default", + "logical": "shared → subscriber", + "owned": true, + "role": "rule", + "properties": { + "correlationProperties": { + "cloudEvents:type": "tck.shared.v1" + }, + "filterType": "CorrelationFilter", + "rule": "$Default", + "sqlExpression": null, + "subscription": "dev-subscriber", + "topic": "dev-shared" + } + } + ] +} diff --git a/deploy/topology/fixtures/gcp/filtered.json b/deploy/topology/fixtures/gcp/filtered.json new file mode 100644 index 00000000..ea8c8611 --- /dev/null +++ b/deploy/topology/fixtures/gcp/filtered.json @@ -0,0 +1,199 @@ +{ + "schemaVersion": 1, + "service": "filtered", + "transport": "gcp_pubsub", + "endpoint": { + "name": "filtered", + "ordered": false, + "maxDeliveries": 10, + "commands": [] + }, + "publishes": [], + "subscribes": [ + { + "topic": "everything", + "filter": null + }, + { + "topic": "prefixed", + "filter": "type LIKE 'tck.%' OR type LIKE 'payments.%'" + }, + { + "topic": "tenant", + "filter": "type = 'tck.tenant.v1' AND sftenant = 'eu'" + }, + { + "topic": "typed", + "filter": "type IN ('tck.also.v2', 'tck.wanted.v1')" + } + ], + "sends": [], + "resources": [ + { + "kind": "topic", + "name": "dev-filtered+dlq", + "logical": "filtered", + "owned": true, + "role": "dead-letter", + "properties": {} + }, + { + "kind": "subscription", + "name": "dev-filtered+dlq", + "logical": "filtered", + "owned": true, + "role": "dead-letter", + "properties": { + "ackDeadlineSeconds": 30, + "deadLetterTopic": null, + "enableMessageOrdering": false, + "expires": false, + "filter": "", + "labels": {}, + "maxDeliveryAttempts": null, + "messageRetentionDuration": "604800s", + "topic": "dev-filtered+dlq" + } + }, + { + "kind": "topic", + "name": "dev-filtered+in", + "logical": "filtered", + "owned": true, + "role": "endpoint", + "properties": {} + }, + { + "kind": "subscription", + "name": "dev-filtered", + "logical": "filtered", + "owned": true, + "role": "endpoint", + "properties": { + "ackDeadlineSeconds": 30, + "deadLetterTopic": "dev-filtered+dlq", + "enableMessageOrdering": false, + "expires": false, + "filter": "", + "labels": { + "sf-max-deliveries": "10" + }, + "maxDeliveryAttempts": 10, + "messageRetentionDuration": "604800s", + "topic": "dev-filtered+in" + } + }, + { + "kind": "topic", + "name": "dev-typed", + "logical": "typed", + "owned": false, + "role": "topic", + "properties": {} + }, + { + "kind": "topic", + "name": "dev-prefixed", + "logical": "prefixed", + "owned": false, + "role": "topic", + "properties": {} + }, + { + "kind": "topic", + "name": "dev-tenant", + "logical": "tenant", + "owned": false, + "role": "topic", + "properties": {} + }, + { + "kind": "topic", + "name": "dev-everything", + "logical": "everything", + "owned": false, + "role": "topic", + "properties": {} + }, + { + "kind": "subscription", + "name": "dev-filtered~typed", + "logical": "typed → filtered", + "owned": true, + "role": "subscription", + "properties": { + "ackDeadlineSeconds": 30, + "deadLetterTopic": "dev-filtered+dlq", + "enableMessageOrdering": false, + "expires": false, + "filter": "attributes.ce-type = \"tck.also.v2\" OR attributes.ce-type = \"tck.wanted.v1\"", + "labels": { + "sf-max-deliveries": "10" + }, + "maxDeliveryAttempts": 10, + "messageRetentionDuration": "604800s", + "topic": "dev-typed" + } + }, + { + "kind": "subscription", + "name": "dev-filtered~prefixed", + "logical": "prefixed → filtered", + "owned": true, + "role": "subscription", + "properties": { + "ackDeadlineSeconds": 30, + "deadLetterTopic": "dev-filtered+dlq", + "enableMessageOrdering": false, + "expires": false, + "filter": "hasPrefix(attributes.ce-type, \"payments.\") OR hasPrefix(attributes.ce-type, \"tck.\")", + "labels": { + "sf-max-deliveries": "10" + }, + "maxDeliveryAttempts": 10, + "messageRetentionDuration": "604800s", + "topic": "dev-prefixed" + } + }, + { + "kind": "subscription", + "name": "dev-filtered~tenant", + "logical": "tenant → filtered", + "owned": true, + "role": "subscription", + "properties": { + "ackDeadlineSeconds": 30, + "deadLetterTopic": "dev-filtered+dlq", + "enableMessageOrdering": false, + "expires": false, + "filter": "", + "labels": { + "sf-max-deliveries": "10" + }, + "maxDeliveryAttempts": 10, + "messageRetentionDuration": "604800s", + "topic": "dev-tenant" + } + }, + { + "kind": "subscription", + "name": "dev-filtered~everything", + "logical": "everything → filtered", + "owned": true, + "role": "subscription", + "properties": { + "ackDeadlineSeconds": 30, + "deadLetterTopic": "dev-filtered+dlq", + "enableMessageOrdering": false, + "expires": false, + "filter": "", + "labels": { + "sf-max-deliveries": "10" + }, + "maxDeliveryAttempts": 10, + "messageRetentionDuration": "604800s", + "topic": "dev-everything" + } + } + ] +} diff --git a/deploy/topology/fixtures/gcp/full.json b/deploy/topology/fixtures/gcp/full.json new file mode 100644 index 00000000..25552327 --- /dev/null +++ b/deploy/topology/fixtures/gcp/full.json @@ -0,0 +1,117 @@ +{ + "schemaVersion": 1, + "service": "full", + "transport": "gcp_pubsub", + "endpoint": { + "name": "full", + "ordered": false, + "maxDeliveries": 7, + "commands": [] + }, + "publishes": [ + { + "topic": "full-out", + "ordered": false, + "messages": [] + } + ], + "subscribes": [ + { + "topic": "full-in", + "filter": "type LIKE 'tck.%'" + } + ], + "sends": [], + "resources": [ + { + "kind": "topic", + "name": "dev-full+dlq", + "logical": "full", + "owned": true, + "role": "dead-letter", + "properties": {} + }, + { + "kind": "subscription", + "name": "dev-full+dlq", + "logical": "full", + "owned": true, + "role": "dead-letter", + "properties": { + "ackDeadlineSeconds": 30, + "deadLetterTopic": null, + "enableMessageOrdering": false, + "expires": false, + "filter": "", + "labels": {}, + "maxDeliveryAttempts": null, + "messageRetentionDuration": "604800s", + "topic": "dev-full+dlq" + } + }, + { + "kind": "topic", + "name": "dev-full+in", + "logical": "full", + "owned": true, + "role": "endpoint", + "properties": {} + }, + { + "kind": "subscription", + "name": "dev-full", + "logical": "full", + "owned": true, + "role": "endpoint", + "properties": { + "ackDeadlineSeconds": 30, + "deadLetterTopic": "dev-full+dlq", + "enableMessageOrdering": false, + "expires": false, + "filter": "", + "labels": { + "sf-max-deliveries": "7" + }, + "maxDeliveryAttempts": 7, + "messageRetentionDuration": "604800s", + "topic": "dev-full+in" + } + }, + { + "kind": "topic", + "name": "dev-full-out", + "logical": "full-out", + "owned": true, + "role": "topic", + "properties": {} + }, + { + "kind": "topic", + "name": "dev-full-in", + "logical": "full-in", + "owned": false, + "role": "topic", + "properties": {} + }, + { + "kind": "subscription", + "name": "dev-full~full-in", + "logical": "full-in → full", + "owned": true, + "role": "subscription", + "properties": { + "ackDeadlineSeconds": 30, + "deadLetterTopic": "dev-full+dlq", + "enableMessageOrdering": false, + "expires": false, + "filter": "hasPrefix(attributes.ce-type, \"tck.\")", + "labels": { + "sf-max-deliveries": "7" + }, + "maxDeliveryAttempts": 7, + "messageRetentionDuration": "604800s", + "topic": "dev-full-in" + } + } + ] +} diff --git a/deploy/topology/fixtures/gcp/minimal.json b/deploy/topology/fixtures/gcp/minimal.json new file mode 100644 index 00000000..46e4ad63 --- /dev/null +++ b/deploy/topology/fixtures/gcp/minimal.json @@ -0,0 +1,70 @@ +{ + "schemaVersion": 1, + "service": "minimal", + "transport": "gcp_pubsub", + "endpoint": { + "name": "minimal", + "ordered": false, + "maxDeliveries": 10, + "commands": [] + }, + "publishes": [], + "subscribes": [], + "sends": [], + "resources": [ + { + "kind": "topic", + "name": "dev-minimal+dlq", + "logical": "minimal", + "owned": true, + "role": "dead-letter", + "properties": {} + }, + { + "kind": "subscription", + "name": "dev-minimal+dlq", + "logical": "minimal", + "owned": true, + "role": "dead-letter", + "properties": { + "ackDeadlineSeconds": 30, + "deadLetterTopic": null, + "enableMessageOrdering": false, + "expires": false, + "filter": "", + "labels": {}, + "maxDeliveryAttempts": null, + "messageRetentionDuration": "604800s", + "topic": "dev-minimal+dlq" + } + }, + { + "kind": "topic", + "name": "dev-minimal+in", + "logical": "minimal", + "owned": true, + "role": "endpoint", + "properties": {} + }, + { + "kind": "subscription", + "name": "dev-minimal", + "logical": "minimal", + "owned": true, + "role": "endpoint", + "properties": { + "ackDeadlineSeconds": 30, + "deadLetterTopic": "dev-minimal+dlq", + "enableMessageOrdering": false, + "expires": false, + "filter": "", + "labels": { + "sf-max-deliveries": "10" + }, + "maxDeliveryAttempts": 10, + "messageRetentionDuration": "604800s", + "topic": "dev-minimal+in" + } + } + ] +} diff --git a/deploy/topology/fixtures/gcp/ordered.json b/deploy/topology/fixtures/gcp/ordered.json new file mode 100644 index 00000000..821b25b9 --- /dev/null +++ b/deploy/topology/fixtures/gcp/ordered.json @@ -0,0 +1,130 @@ +{ + "schemaVersion": 1, + "service": "ordered", + "transport": "gcp_pubsub", + "endpoint": { + "name": "ordered", + "ordered": true, + "maxDeliveries": 5, + "commands": [] + }, + "publishes": [ + { + "topic": "ordered-out", + "ordered": true, + "messages": [] + } + ], + "subscribes": [ + { + "topic": "ordered-in", + "filter": "type = 'tck.ordered.v1'" + } + ], + "sends": [ + { + "endpoint": "minimal", + "commands": [] + } + ], + "resources": [ + { + "kind": "topic", + "name": "dev-ordered+dlq", + "logical": "ordered", + "owned": true, + "role": "dead-letter", + "properties": {} + }, + { + "kind": "subscription", + "name": "dev-ordered+dlq", + "logical": "ordered", + "owned": true, + "role": "dead-letter", + "properties": { + "ackDeadlineSeconds": 30, + "deadLetterTopic": null, + "enableMessageOrdering": false, + "expires": false, + "filter": "", + "labels": {}, + "maxDeliveryAttempts": null, + "messageRetentionDuration": "604800s", + "topic": "dev-ordered+dlq" + } + }, + { + "kind": "topic", + "name": "dev-ordered+in", + "logical": "ordered", + "owned": true, + "role": "endpoint", + "properties": {} + }, + { + "kind": "subscription", + "name": "dev-ordered", + "logical": "ordered", + "owned": true, + "role": "endpoint", + "properties": { + "ackDeadlineSeconds": 30, + "deadLetterTopic": "dev-ordered+dlq", + "enableMessageOrdering": true, + "expires": false, + "filter": "", + "labels": { + "sf-max-deliveries": "5" + }, + "maxDeliveryAttempts": 5, + "messageRetentionDuration": "604800s", + "topic": "dev-ordered+in" + } + }, + { + "kind": "topic", + "name": "dev-ordered-out", + "logical": "ordered-out", + "owned": true, + "role": "topic", + "properties": {} + }, + { + "kind": "topic", + "name": "dev-ordered-in", + "logical": "ordered-in", + "owned": false, + "role": "topic", + "properties": {} + }, + { + "kind": "subscription", + "name": "dev-ordered~ordered-in", + "logical": "ordered-in → ordered", + "owned": true, + "role": "subscription", + "properties": { + "ackDeadlineSeconds": 30, + "deadLetterTopic": "dev-ordered+dlq", + "enableMessageOrdering": true, + "expires": false, + "filter": "attributes.ce-type = \"tck.ordered.v1\"", + "labels": { + "sf-max-deliveries": "5" + }, + "maxDeliveryAttempts": 5, + "messageRetentionDuration": "604800s", + "topic": "dev-ordered-in" + } + }, + { + "kind": "topic", + "name": "dev-minimal+in", + "logical": "minimal", + "owned": false, + "role": "remote-endpoint", + "properties": {} + } + ] +} diff --git a/deploy/topology/fixtures/gcp/publisher.json b/deploy/topology/fixtures/gcp/publisher.json new file mode 100644 index 00000000..d7cba445 --- /dev/null +++ b/deploy/topology/fixtures/gcp/publisher.json @@ -0,0 +1,97 @@ +{ + "schemaVersion": 1, + "service": "publisher", + "transport": "gcp_pubsub", + "endpoint": { + "name": "publisher", + "ordered": false, + "maxDeliveries": 10, + "commands": [] + }, + "publishes": [ + { + "topic": "shared", + "ordered": false, + "messages": [] + } + ], + "subscribes": [], + "sends": [ + { + "endpoint": "subscriber", + "commands": [] + } + ], + "resources": [ + { + "kind": "topic", + "name": "dev-publisher+dlq", + "logical": "publisher", + "owned": true, + "role": "dead-letter", + "properties": {} + }, + { + "kind": "subscription", + "name": "dev-publisher+dlq", + "logical": "publisher", + "owned": true, + "role": "dead-letter", + "properties": { + "ackDeadlineSeconds": 30, + "deadLetterTopic": null, + "enableMessageOrdering": false, + "expires": false, + "filter": "", + "labels": {}, + "maxDeliveryAttempts": null, + "messageRetentionDuration": "604800s", + "topic": "dev-publisher+dlq" + } + }, + { + "kind": "topic", + "name": "dev-publisher+in", + "logical": "publisher", + "owned": true, + "role": "endpoint", + "properties": {} + }, + { + "kind": "subscription", + "name": "dev-publisher", + "logical": "publisher", + "owned": true, + "role": "endpoint", + "properties": { + "ackDeadlineSeconds": 30, + "deadLetterTopic": "dev-publisher+dlq", + "enableMessageOrdering": false, + "expires": false, + "filter": "", + "labels": { + "sf-max-deliveries": "10" + }, + "maxDeliveryAttempts": 10, + "messageRetentionDuration": "604800s", + "topic": "dev-publisher+in" + } + }, + { + "kind": "topic", + "name": "dev-shared", + "logical": "shared", + "owned": true, + "role": "topic", + "properties": {} + }, + { + "kind": "topic", + "name": "dev-subscriber+in", + "logical": "subscriber", + "owned": false, + "role": "remote-endpoint", + "properties": {} + } + ] +} diff --git a/deploy/topology/fixtures/gcp/subscriber.json b/deploy/topology/fixtures/gcp/subscriber.json new file mode 100644 index 00000000..1286ea6d --- /dev/null +++ b/deploy/topology/fixtures/gcp/subscriber.json @@ -0,0 +1,103 @@ +{ + "schemaVersion": 1, + "service": "subscriber", + "transport": "gcp_pubsub", + "endpoint": { + "name": "subscriber", + "ordered": false, + "maxDeliveries": 10, + "commands": [] + }, + "publishes": [], + "subscribes": [ + { + "topic": "shared", + "filter": "type = 'tck.shared.v1'" + } + ], + "sends": [], + "resources": [ + { + "kind": "topic", + "name": "dev-subscriber+dlq", + "logical": "subscriber", + "owned": true, + "role": "dead-letter", + "properties": {} + }, + { + "kind": "subscription", + "name": "dev-subscriber+dlq", + "logical": "subscriber", + "owned": true, + "role": "dead-letter", + "properties": { + "ackDeadlineSeconds": 30, + "deadLetterTopic": null, + "enableMessageOrdering": false, + "expires": false, + "filter": "", + "labels": {}, + "maxDeliveryAttempts": null, + "messageRetentionDuration": "604800s", + "topic": "dev-subscriber+dlq" + } + }, + { + "kind": "topic", + "name": "dev-subscriber+in", + "logical": "subscriber", + "owned": true, + "role": "endpoint", + "properties": {} + }, + { + "kind": "subscription", + "name": "dev-subscriber", + "logical": "subscriber", + "owned": true, + "role": "endpoint", + "properties": { + "ackDeadlineSeconds": 30, + "deadLetterTopic": "dev-subscriber+dlq", + "enableMessageOrdering": false, + "expires": false, + "filter": "", + "labels": { + "sf-max-deliveries": "10" + }, + "maxDeliveryAttempts": 10, + "messageRetentionDuration": "604800s", + "topic": "dev-subscriber+in" + } + }, + { + "kind": "topic", + "name": "dev-shared", + "logical": "shared", + "owned": false, + "role": "topic", + "properties": {} + }, + { + "kind": "subscription", + "name": "dev-subscriber~shared", + "logical": "shared → subscriber", + "owned": true, + "role": "subscription", + "properties": { + "ackDeadlineSeconds": 30, + "deadLetterTopic": "dev-subscriber+dlq", + "enableMessageOrdering": false, + "expires": false, + "filter": "attributes.ce-type = \"tck.shared.v1\"", + "labels": { + "sf-max-deliveries": "10" + }, + "maxDeliveryAttempts": 10, + "messageRetentionDuration": "604800s", + "topic": "dev-shared" + } + } + ] +} diff --git a/deploy/topology/fixtures/in-memory/filtered.json b/deploy/topology/fixtures/in-memory/filtered.json new file mode 100644 index 00000000..1bd1ecc1 --- /dev/null +++ b/deploy/topology/fixtures/in-memory/filtered.json @@ -0,0 +1,132 @@ +{ + "schemaVersion": 1, + "service": "filtered", + "transport": "sourceflow.inmemory", + "endpoint": { + "name": "filtered", + "ordered": false, + "maxDeliveries": 10, + "commands": [] + }, + "publishes": [], + "subscribes": [ + { + "topic": "everything", + "filter": null + }, + { + "topic": "prefixed", + "filter": "type LIKE 'tck.%' OR type LIKE 'payments.%'" + }, + { + "topic": "tenant", + "filter": "type = 'tck.tenant.v1' AND sftenant = 'eu'" + }, + { + "topic": "typed", + "filter": "type IN ('tck.also.v2', 'tck.wanted.v1')" + } + ], + "sends": [], + "resources": [ + { + "kind": "queue", + "name": "filtered", + "logical": "filtered", + "owned": true, + "role": "endpoint", + "properties": { + "maxDeliveries": 10, + "ordered": false + } + }, + { + "kind": "topic", + "name": "typed", + "logical": "typed", + "owned": false, + "role": "topic", + "properties": { + "ordered": false + } + }, + { + "kind": "topic", + "name": "prefixed", + "logical": "prefixed", + "owned": false, + "role": "topic", + "properties": { + "ordered": false + } + }, + { + "kind": "topic", + "name": "tenant", + "logical": "tenant", + "owned": false, + "role": "topic", + "properties": { + "ordered": false + } + }, + { + "kind": "topic", + "name": "everything", + "logical": "everything", + "owned": false, + "role": "topic", + "properties": { + "ordered": false + } + }, + { + "kind": "subscription", + "name": "typed/filtered", + "logical": "typed → filtered", + "owned": true, + "role": "subscription", + "properties": { + "endpoint": "filtered", + "filter": "type IN ('tck.also.v2', 'tck.wanted.v1')", + "topic": "typed" + } + }, + { + "kind": "subscription", + "name": "prefixed/filtered", + "logical": "prefixed → filtered", + "owned": true, + "role": "subscription", + "properties": { + "endpoint": "filtered", + "filter": "type LIKE 'tck.%' OR type LIKE 'payments.%'", + "topic": "prefixed" + } + }, + { + "kind": "subscription", + "name": "tenant/filtered", + "logical": "tenant → filtered", + "owned": true, + "role": "subscription", + "properties": { + "endpoint": "filtered", + "filter": "type = 'tck.tenant.v1' AND sftenant = 'eu'", + "topic": "tenant" + } + }, + { + "kind": "subscription", + "name": "everything/filtered", + "logical": "everything → filtered", + "owned": true, + "role": "subscription", + "properties": { + "endpoint": "filtered", + "filter": null, + "topic": "everything" + } + } + ] +} diff --git a/deploy/topology/fixtures/in-memory/full.json b/deploy/topology/fixtures/in-memory/full.json new file mode 100644 index 00000000..c3587980 --- /dev/null +++ b/deploy/topology/fixtures/in-memory/full.json @@ -0,0 +1,70 @@ +{ + "schemaVersion": 1, + "service": "full", + "transport": "sourceflow.inmemory", + "endpoint": { + "name": "full", + "ordered": false, + "maxDeliveries": 7, + "commands": [] + }, + "publishes": [ + { + "topic": "full-out", + "ordered": false, + "messages": [] + } + ], + "subscribes": [ + { + "topic": "full-in", + "filter": "type LIKE 'tck.%'" + } + ], + "sends": [], + "resources": [ + { + "kind": "queue", + "name": "full", + "logical": "full", + "owned": true, + "role": "endpoint", + "properties": { + "maxDeliveries": 7, + "ordered": false + } + }, + { + "kind": "topic", + "name": "full-out", + "logical": "full-out", + "owned": true, + "role": "topic", + "properties": { + "ordered": false + } + }, + { + "kind": "topic", + "name": "full-in", + "logical": "full-in", + "owned": false, + "role": "topic", + "properties": { + "ordered": false + } + }, + { + "kind": "subscription", + "name": "full-in/full", + "logical": "full-in → full", + "owned": true, + "role": "subscription", + "properties": { + "endpoint": "full", + "filter": "type LIKE 'tck.%'", + "topic": "full-in" + } + } + ] +} diff --git a/deploy/topology/fixtures/in-memory/minimal.json b/deploy/topology/fixtures/in-memory/minimal.json new file mode 100644 index 00000000..4543d181 --- /dev/null +++ b/deploy/topology/fixtures/in-memory/minimal.json @@ -0,0 +1,27 @@ +{ + "schemaVersion": 1, + "service": "minimal", + "transport": "sourceflow.inmemory", + "endpoint": { + "name": "minimal", + "ordered": false, + "maxDeliveries": 10, + "commands": [] + }, + "publishes": [], + "subscribes": [], + "sends": [], + "resources": [ + { + "kind": "queue", + "name": "minimal", + "logical": "minimal", + "owned": true, + "role": "endpoint", + "properties": { + "maxDeliveries": 10, + "ordered": false + } + } + ] +} diff --git a/deploy/topology/fixtures/in-memory/ordered.json b/deploy/topology/fixtures/in-memory/ordered.json new file mode 100644 index 00000000..13de1116 --- /dev/null +++ b/deploy/topology/fixtures/in-memory/ordered.json @@ -0,0 +1,75 @@ +{ + "schemaVersion": 1, + "service": "ordered", + "transport": "sourceflow.inmemory", + "endpoint": { + "name": "ordered", + "ordered": true, + "maxDeliveries": 5, + "commands": [] + }, + "publishes": [ + { + "topic": "ordered-out", + "ordered": true, + "messages": [] + } + ], + "subscribes": [ + { + "topic": "ordered-in", + "filter": "type = 'tck.ordered.v1'" + } + ], + "sends": [ + { + "endpoint": "minimal", + "commands": [] + } + ], + "resources": [ + { + "kind": "queue", + "name": "ordered", + "logical": "ordered", + "owned": true, + "role": "endpoint", + "properties": { + "maxDeliveries": 5, + "ordered": true + } + }, + { + "kind": "topic", + "name": "ordered-out", + "logical": "ordered-out", + "owned": true, + "role": "topic", + "properties": { + "ordered": true + } + }, + { + "kind": "topic", + "name": "ordered-in", + "logical": "ordered-in", + "owned": false, + "role": "topic", + "properties": { + "ordered": true + } + }, + { + "kind": "subscription", + "name": "ordered-in/ordered", + "logical": "ordered-in → ordered", + "owned": true, + "role": "subscription", + "properties": { + "endpoint": "ordered", + "filter": "type = 'tck.ordered.v1'", + "topic": "ordered-in" + } + } + ] +} diff --git a/deploy/topology/fixtures/in-memory/publisher.json b/deploy/topology/fixtures/in-memory/publisher.json new file mode 100644 index 00000000..491d5534 --- /dev/null +++ b/deploy/topology/fixtures/in-memory/publisher.json @@ -0,0 +1,48 @@ +{ + "schemaVersion": 1, + "service": "publisher", + "transport": "sourceflow.inmemory", + "endpoint": { + "name": "publisher", + "ordered": false, + "maxDeliveries": 10, + "commands": [] + }, + "publishes": [ + { + "topic": "shared", + "ordered": false, + "messages": [] + } + ], + "subscribes": [], + "sends": [ + { + "endpoint": "subscriber", + "commands": [] + } + ], + "resources": [ + { + "kind": "queue", + "name": "publisher", + "logical": "publisher", + "owned": true, + "role": "endpoint", + "properties": { + "maxDeliveries": 10, + "ordered": false + } + }, + { + "kind": "topic", + "name": "shared", + "logical": "shared", + "owned": true, + "role": "topic", + "properties": { + "ordered": false + } + } + ] +} diff --git a/deploy/topology/fixtures/in-memory/subscriber.json b/deploy/topology/fixtures/in-memory/subscriber.json new file mode 100644 index 00000000..cd868e2f --- /dev/null +++ b/deploy/topology/fixtures/in-memory/subscriber.json @@ -0,0 +1,54 @@ +{ + "schemaVersion": 1, + "service": "subscriber", + "transport": "sourceflow.inmemory", + "endpoint": { + "name": "subscriber", + "ordered": false, + "maxDeliveries": 10, + "commands": [] + }, + "publishes": [], + "subscribes": [ + { + "topic": "shared", + "filter": "type = 'tck.shared.v1'" + } + ], + "sends": [], + "resources": [ + { + "kind": "queue", + "name": "subscriber", + "logical": "subscriber", + "owned": true, + "role": "endpoint", + "properties": { + "maxDeliveries": 10, + "ordered": false + } + }, + { + "kind": "topic", + "name": "shared", + "logical": "shared", + "owned": false, + "role": "topic", + "properties": { + "ordered": false + } + }, + { + "kind": "subscription", + "name": "shared/subscriber", + "logical": "shared → subscriber", + "owned": true, + "role": "subscription", + "properties": { + "endpoint": "subscriber", + "filter": "type = 'tck.shared.v1'", + "topic": "shared" + } + } + ] +} diff --git a/deploy/topology/terraform/aws/main.tf b/deploy/topology/terraform/aws/main.tf new file mode 100644 index 00000000..5a94521b --- /dev/null +++ b/deploy/topology/terraform/aws/main.tf @@ -0,0 +1,189 @@ +# SourceFlow topology on Amazon SQS and SNS (doc 07 §5, ADR-017). +# +# Creates what `ProvisioningMode.CreateIfMissing` would create for one service, from the JSON written by +# `dotnet sourceflow topology export` with the AWS transport: the endpoint queue with a redrive policy to its +# dead-letter queue (FIFO when ordered), the topics the service publishes, raw-delivery subscriptions with the +# filter policies, and the queue policy that lets the subscribed topics send. The service can then run with +# `ProvisioningMode.Validate` and describe-only permissions (`runtime_policy_json`). +# +# Names, ordering and filters come from the export; this module computes none of them. + +terraform { + required_version = ">= 1.5" + required_providers { + aws = { + source = "hashicorp/aws" + version = ">= 6.0" + } + } +} + +locals { + topology = jsondecode(var.topology) + # Another transport's export has other properties: nothing is read from it, and the precondition below reports it. + resources = [for r in local.topology.resources : r if local.topology.transport == "aws_sqs"] + + dead_letter_queues = { + for r in local.resources : r.name => { + fifo = r.properties.fifo + retention = r.properties.messageRetentionSeconds + } if r.kind == "queue" && r.owned && r.role == "dead-letter" + } + + endpoint_queues = { + for r in local.resources : r.name => { + fifo = r.properties.fifo + retention = r.properties.messageRetentionSeconds + dead_letter_queue = r.properties.deadLetterQueue + max_receive_count = r.properties.maxReceiveCount + allow_topics = tolist(r.properties.allowTopics) + } if r.kind == "queue" && r.owned && r.role == "endpoint" + } + + remote_queues = flatten([ + for r in local.resources : tolist(r.properties.candidates) if r.kind == "queue" && !r.owned && r.role == "remote-endpoint" + ]) + + created_topics = { + for r in local.resources : r.name => { fifo = r.properties.fifo } + if r.kind == "topic" && (r.owned || var.create_subscribed_topics) + } + + existing_topics = toset([ + for r in local.resources : r.name if r.kind == "topic" && !(r.owned || var.create_subscribed_topics) + ]) + + published_topics = toset([for r in local.resources : r.name if r.kind == "topic" && r.owned]) + + subscriptions = { + for r in local.resources : r.name => { + topic = r.properties.topic + queue = r.properties.queue + raw_message_delivery = r.properties.rawMessageDelivery + filter_policy = r.properties.filterPolicy + filter_policy_scope = r.properties.filterPolicyScope + } if r.kind == "subscription" + } + + topic_arns = merge( + { for name, topic in aws_sns_topic.topic : name => topic.arn }, + { for name, topic in data.aws_sns_topic.existing : name => topic.arn }, + ) +} + +resource "terraform_data" "transport" { + input = local.topology.transport + + lifecycle { + precondition { + condition = local.topology.transport == "aws_sqs" && local.topology.schemaVersion == 1 + error_message = "The topology export is for '${coalesce(local.topology.transport, "no transport")}' (schema ${local.topology.schemaVersion}); this module needs an aws_sqs export with schemaVersion 1." + } + } +} + +resource "aws_sqs_queue" "dead_letter" { + for_each = local.dead_letter_queues + + name = each.key + fifo_queue = each.value.fifo ? true : null + message_retention_seconds = each.value.retention + sqs_managed_sse_enabled = true + tags = var.tags +} + +resource "aws_sqs_queue" "endpoint" { + for_each = local.endpoint_queues + + name = each.key + fifo_queue = each.value.fifo ? true : null + message_retention_seconds = each.value.retention + sqs_managed_sse_enabled = true + redrive_policy = jsonencode({ + deadLetterTargetArn = aws_sqs_queue.dead_letter[each.value.dead_letter_queue].arn + maxReceiveCount = each.value.max_receive_count + }) + tags = var.tags +} + +resource "aws_sns_topic" "topic" { + for_each = local.created_topics + + name = each.key + fifo_topic = each.value.fifo ? true : null + tags = var.tags +} + +# Topics the service subscribes to but does not publish belong to their publishers' stacks. +data "aws_sns_topic" "existing" { + for_each = local.existing_topics + + name = each.value +} + +resource "aws_sqs_queue_policy" "endpoint" { + for_each = { for name, queue in local.endpoint_queues : name => queue if length(queue.allow_topics) > 0 } + + queue_url = aws_sqs_queue.endpoint[each.key].id + policy = jsonencode({ + Version = "2012-10-17" + Statement = [{ + Sid = "sourceflow-sns-to-sqs" + Effect = "Allow" + Principal = { Service = "sns.amazonaws.com" } + Action = "sqs:SendMessage" + Resource = aws_sqs_queue.endpoint[each.key].arn + Condition = { ArnEquals = { "aws:SourceArn" = [for topic in each.value.allow_topics : local.topic_arns[topic]] } } + }] + }) +} + +resource "aws_sns_topic_subscription" "subscription" { + for_each = local.subscriptions + + topic_arn = local.topic_arns[each.value.topic] + protocol = "sqs" + endpoint = aws_sqs_queue.endpoint[each.value.queue].arn + raw_message_delivery = each.value.raw_message_delivery + filter_policy = each.value.filter_policy + filter_policy_scope = each.value.filter_policy_scope + + depends_on = [aws_sqs_queue_policy.endpoint] +} + +locals { + # arn:{partition}:sqs:{region}:{account}, from the endpoint queue (no STS call). + queue_arn_prefix = try(join(":", slice(split(":", one([for name, queue in aws_sqs_queue.endpoint : queue.arn])), 0, 5)), null) + + # The service at runtime: receive and settle on its queues, publish to its topics, send to remote endpoints, and + # describe everything for ProvisioningMode.Validate. No create, delete or set permission. + runtime_statements = concat( + [{ + Sid = "Receive" + Effect = "Allow" + Action = ["sqs:ReceiveMessage", "sqs:DeleteMessage", "sqs:ChangeMessageVisibility", "sqs:GetQueueAttributes", "sqs:GetQueueUrl", "sqs:SendMessage"] + Resource = concat( + [for name, queue in aws_sqs_queue.endpoint : queue.arn], + [for name, queue in aws_sqs_queue.dead_letter : queue.arn], + ) + }], + length(local.published_topics) == 0 ? [] : [{ + Sid = "Publish" + Effect = "Allow" + Action = ["sns:Publish", "sns:GetTopicAttributes"] + Resource = [for name in local.published_topics : local.topic_arns[name]] + }], + length(local.remote_queues) == 0 ? [] : [{ + Sid = "Send" + Effect = "Allow" + Action = ["sqs:SendMessage", "sqs:GetQueueUrl", "sqs:GetQueueAttributes"] + Resource = [for name in local.remote_queues : "${local.queue_arn_prefix}:${name}"] + }], + [{ + Sid = "Describe" + Effect = "Allow" + Action = ["sqs:GetQueueUrl", "sqs:GetQueueAttributes", "sqs:ListQueues", "sns:ListTopics", "sns:GetTopicAttributes", "sns:ListSubscriptionsByTopic", "sns:GetSubscriptionAttributes"] + Resource = ["*"] + }], + ) +} diff --git a/deploy/topology/terraform/aws/outputs.tf b/deploy/topology/terraform/aws/outputs.tf new file mode 100644 index 00000000..546817ec --- /dev/null +++ b/deploy/topology/terraform/aws/outputs.tf @@ -0,0 +1,28 @@ +output "queue_urls" { + description = "The URLs of the service's queues (endpoint and dead letters), by name." + value = merge( + { for name, queue in aws_sqs_queue.endpoint : name => queue.url }, + { for name, queue in aws_sqs_queue.dead_letter : name => queue.url }, + ) +} + +output "queue_arns" { + description = "The ARNs of the service's queues, by name." + value = merge( + { for name, queue in aws_sqs_queue.endpoint : name => queue.arn }, + { for name, queue in aws_sqs_queue.dead_letter : name => queue.arn }, + ) +} + +output "topic_arns" { + description = "The ARNs of the topics the service publishes or subscribes to, by name." + value = local.topic_arns +} + +output "runtime_policy_json" { + description = "An IAM policy for the service at runtime with ProvisioningMode.Validate: receive and settle, publish, send to remote endpoints, and describe. Attach it to the service's role." + value = jsonencode({ + Version = "2012-10-17" + Statement = local.runtime_statements + }) +} diff --git a/deploy/topology/terraform/aws/tests/fixtures.tftest.hcl b/deploy/topology/terraform/aws/tests/fixtures.tftest.hcl new file mode 100644 index 00000000..5bc80b89 --- /dev/null +++ b/deploy/topology/terraform/aws/tests/fixtures.tftest.hcl @@ -0,0 +1,103 @@ +# Plans and applies the module against a mock provider for the committed fixtures (deploy/topology/fixtures/aws). +# The emulator test (tests/Cloud/SourceFlow.Cloud.Tests/Topology) applies it to LocalStack and validates the result +# with the transport. + +mock_provider "aws" { + mock_data "aws_sns_topic" { + defaults = { arn = "arn:aws:sns:eu-west-1:123456789012:mock" } + } + mock_resource "aws_sns_topic" { + defaults = { arn = "arn:aws:sns:eu-west-1:123456789012:mock" } + } + mock_resource "aws_sqs_queue" { + defaults = { + arn = "arn:aws:sqs:eu-west-1:123456789012:mock" + id = "https://sqs.eu-west-1.amazonaws.com/123456789012/mock" + url = "https://sqs.eu-west-1.amazonaws.com/123456789012/mock" + } + } +} + +variables { + create_subscribed_topics = true +} + +run "full" { + variables { + topology = file("../../fixtures/aws/full.json") + } + + assert { + condition = length(aws_sqs_queue.endpoint) == 1 && length(aws_sqs_queue.dead_letter) == 1 && length(aws_sns_topic.topic) == 2 && length(aws_sns_topic_subscription.subscription) == 1 + error_message = "full: endpoint, dead letters, two topics, one subscription" + } + + assert { + condition = jsondecode(aws_sqs_queue.endpoint["dev-full"].redrive_policy).maxReceiveCount == 7 + error_message = "full: the redrive policy has the topology's delivery limit" + } + + assert { + condition = aws_sns_topic_subscription.subscription["dev-full-in/dev-full"].raw_message_delivery && aws_sns_topic_subscription.subscription["dev-full-in/dev-full"].filter_policy_scope == "MessageAttributes" + error_message = "full: raw delivery with a message-attribute filter policy" + } + + assert { + condition = length(aws_sqs_queue_policy.endpoint) == 1 + error_message = "full: the queue policy lets the subscribed topic send" + } +} + +run "ordered" { + variables { + topology = file("../../fixtures/aws/ordered.json") + } + + assert { + condition = aws_sqs_queue.endpoint["dev-ordered.fifo"].fifo_queue && aws_sqs_queue.dead_letter["dev-ordered-dlq.fifo"].fifo_queue && aws_sns_topic.topic["dev-ordered-out.fifo"].fifo_topic + error_message = "ordered: FIFO queues and topics" + } + + assert { + condition = strcontains(output.runtime_policy_json, "arn:aws:sqs:eu-west-1:123456789012:dev-minimal.fifo") + error_message = "ordered: the runtime policy may send to both candidates of the remote endpoint" + } +} + +run "filtered" { + variables { + topology = file("../../fixtures/aws/filtered.json") + } + + assert { + condition = length(aws_sns_topic_subscription.subscription) == 4 + error_message = "filtered: four subscriptions" + } + + assert { + condition = aws_sns_topic_subscription.subscription["dev-tenant/dev-filtered"].filter_policy == null && aws_sns_topic_subscription.subscription["dev-everything/dev-filtered"].filter_policy == null + error_message = "filtered: no policy where SNS cannot express the filter (the receiver evaluates it)" + } +} + +run "subscriber_uses_the_publishers_topic" { + variables { + topology = file("../../fixtures/aws/subscriber.json") + create_subscribed_topics = false + } + + assert { + condition = length(aws_sns_topic.topic) == 0 && length(data.aws_sns_topic.existing) == 1 + error_message = "subscriber: the shared topic is looked up, not created" + } +} + +run "wrong_transport" { + command = plan + + variables { + topology = file("../../fixtures/gcp/minimal.json") + } + + expect_failures = [terraform_data.transport] +} diff --git a/deploy/topology/terraform/aws/variables.tf b/deploy/topology/terraform/aws/variables.tf new file mode 100644 index 00000000..9246afd3 --- /dev/null +++ b/deploy/topology/terraform/aws/variables.tf @@ -0,0 +1,16 @@ +variable "topology" { + description = "The JSON written by `dotnet sourceflow topology export` for the service, with the AWS transport (for example file(\"accounts.topology.json\"))." + type = string +} + +variable "create_subscribed_topics" { + description = "Also create the topics the service subscribes to but does not publish. Leave false when each publisher's stack creates its topics; set true for a single stack holding every service." + type = bool + default = false +} + +variable "tags" { + description = "Tags for every queue and topic." + type = map(string) + default = {} +} diff --git a/deploy/topology/terraform/azure/main.tf b/deploy/topology/terraform/azure/main.tf new file mode 100644 index 00000000..6c07fc3b --- /dev/null +++ b/deploy/topology/terraform/azure/main.tf @@ -0,0 +1,159 @@ +# SourceFlow topology on Azure Service Bus (doc 07 §5, ADR-017). +# +# Creates what `ProvisioningMode.CreateIfMissing` would create for one service, from the JSON written by +# `dotnet sourceflow topology export` with the Azure transport, in an existing namespace: the endpoint queue (sessions +# when ordered, the delivery limit, lock, time to live, dead-lettering on expiry, duplicate detection when configured), +# the topics the service publishes, and on each subscribed topic a subscription that forwards to the queue, with the +# filter's rules. +# +# ARM creates a match-everything rule called $Default with every subscription. The export names each subscription's +# first rule $Default, and this module overwrites that rule (azapi_update_resource) instead of adding one beside it; +# the other rules are ordinary rule resources. Names and filters come from the export. + +terraform { + required_version = ">= 1.5" + required_providers { + azurerm = { + source = "hashicorp/azurerm" + version = ">= 3.90" + } + azapi = { + source = "Azure/azapi" + version = ">= 2.0" + } + } +} + +locals { + topology = jsondecode(var.topology) + # Another transport's export has other properties: nothing is read from it, and the precondition below reports it. + resources = [for r in local.topology.resources : r if local.topology.transport == "servicebus"] + + queues = { + for r in local.resources : r.name => { + requires_session = r.properties.requiresSession + max_delivery_count = r.properties.maxDeliveryCount + lock_duration = r.properties.lockDuration + default_message_ttl = r.properties.defaultMessageTimeToLive + dead_lettering_on_message_expiration = r.properties.deadLetteringOnMessageExpiration + requires_duplicate_detection = r.properties.requiresDuplicateDetection + duplicate_detection_history_time_window = r.properties.duplicateDetectionHistoryTimeWindow + } if r.kind == "queue" && r.owned && r.role == "endpoint" + } + + created_topics = { + for r in local.resources : r.name => { default_message_ttl = r.properties.defaultMessageTimeToLive } + if r.kind == "topic" && (r.owned || var.create_subscribed_topics) + } + + existing_topics = toset([for r in local.resources : r.name if r.kind == "topic" && !(r.owned || var.create_subscribed_topics)]) + + topic_ids = merge( + { for name, topic in azurerm_servicebus_topic.topic : name => topic.id }, + { for name, topic in data.azurerm_servicebus_topic.existing : name => topic.id }, + ) + + subscriptions = { + for r in local.resources : r.name => { + topic = r.properties.topic + subscription = r.properties.subscription + forward_to = r.properties.forwardTo + default_message_ttl = r.properties.defaultMessageTimeToLive + } if r.kind == "subscription" + } + + rules = { + for r in local.resources : r.name => { + subscription = "${r.properties.topic}/${r.properties.subscription}" + rule = r.properties.rule + filter_type = r.properties.filterType + sql_expression = r.properties.sqlExpression + correlation_properties = r.properties.correlationProperties == null ? null : tomap(r.properties.correlationProperties) + } if r.kind == "rule" + } +} + +resource "terraform_data" "transport" { + input = local.topology.transport + + lifecycle { + precondition { + condition = local.topology.transport == "servicebus" && local.topology.schemaVersion == 1 + error_message = "The topology export is for '${coalesce(local.topology.transport, "no transport")}' (schema ${local.topology.schemaVersion}); this module needs a servicebus export with schemaVersion 1." + } + } +} + +resource "azurerm_servicebus_queue" "endpoint" { + for_each = local.queues + + name = each.key + namespace_id = var.namespace_id + requires_session = each.value.requires_session + max_delivery_count = each.value.max_delivery_count + lock_duration = each.value.lock_duration + default_message_ttl = each.value.default_message_ttl + dead_lettering_on_message_expiration = each.value.dead_lettering_on_message_expiration + requires_duplicate_detection = each.value.requires_duplicate_detection + duplicate_detection_history_time_window = each.value.duplicate_detection_history_time_window +} + +resource "azurerm_servicebus_topic" "topic" { + for_each = local.created_topics + + name = each.key + namespace_id = var.namespace_id + default_message_ttl = each.value.default_message_ttl +} + +# Topics the service subscribes to but does not publish belong to their publishers' stacks. +data "azurerm_servicebus_topic" "existing" { + for_each = local.existing_topics + + name = each.value + namespace_id = var.namespace_id +} + +resource "azurerm_servicebus_subscription" "subscription" { + for_each = local.subscriptions + + name = each.value.subscription + topic_id = local.topic_ids[each.value.topic] + forward_to = each.value.forward_to + default_message_ttl = each.value.default_message_ttl + max_delivery_count = 10 + + depends_on = [azurerm_servicebus_queue.endpoint] +} + +# The first rule of each subscription replaces the $Default rule ARM created with it. +resource "azapi_update_resource" "default_rule" { + for_each = { for name, rule in local.rules : name => rule if rule.rule == "$Default" } + + type = "Microsoft.ServiceBus/namespaces/topics/subscriptions/rules@2021-11-01" + name = "$Default" + parent_id = azurerm_servicebus_subscription.subscription[each.value.subscription].id + body = { + properties = merge( + { filterType = each.value.filter_type }, + each.value.filter_type == "SqlFilter" ? { sqlFilter = { sqlExpression = each.value.sql_expression } } : {}, + each.value.filter_type == "CorrelationFilter" ? { correlationFilter = { properties = each.value.correlation_properties } } : {}, + ) + } +} + +resource "azurerm_servicebus_subscription_rule" "rule" { + for_each = { for name, rule in local.rules : name => rule if rule.rule != "$Default" } + + name = each.value.rule + subscription_id = azurerm_servicebus_subscription.subscription[each.value.subscription].id + filter_type = each.value.filter_type + sql_filter = each.value.filter_type == "SqlFilter" ? each.value.sql_expression : null + + dynamic "correlation_filter" { + for_each = each.value.filter_type == "CorrelationFilter" ? [each.value.correlation_properties] : [] + content { + properties = correlation_filter.value + } + } +} diff --git a/deploy/topology/terraform/azure/outputs.tf b/deploy/topology/terraform/azure/outputs.tf new file mode 100644 index 00000000..ad24210d --- /dev/null +++ b/deploy/topology/terraform/azure/outputs.tf @@ -0,0 +1,14 @@ +output "queue_ids" { + description = "The resource ids of the service's queues, by name." + value = { for name, queue in azurerm_servicebus_queue.endpoint : name => queue.id } +} + +output "topic_ids" { + description = "The resource ids of the topics the service publishes or subscribes to, by name." + value = local.topic_ids +} + +output "subscription_ids" { + description = "The resource ids of the service's subscriptions, by topic/subscription." + value = { for name, subscription in azurerm_servicebus_subscription.subscription : name => subscription.id } +} diff --git a/deploy/topology/terraform/azure/tests/fixtures.tftest.hcl b/deploy/topology/terraform/azure/tests/fixtures.tftest.hcl new file mode 100644 index 00000000..431699ab --- /dev/null +++ b/deploy/topology/terraform/azure/tests/fixtures.tftest.hcl @@ -0,0 +1,119 @@ +# Plans and applies the module against mock providers for the committed fixtures (deploy/topology/fixtures/azure): +# every expression is evaluated and every resource count checked, without an Azure subscription. + +mock_provider "azurerm" { + mock_resource "azurerm_servicebus_queue" { + defaults = { id = "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/sourceflow/providers/Microsoft.ServiceBus/namespaces/sourceflow/queues/mock" } + } + mock_resource "azurerm_servicebus_topic" { + defaults = { id = "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/sourceflow/providers/Microsoft.ServiceBus/namespaces/sourceflow/topics/mock" } + } + mock_data "azurerm_servicebus_topic" { + defaults = { id = "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/sourceflow/providers/Microsoft.ServiceBus/namespaces/sourceflow/topics/mock" } + } + mock_resource "azurerm_servicebus_subscription" { + defaults = { id = "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/sourceflow/providers/Microsoft.ServiceBus/namespaces/sourceflow/topics/mock/subscriptions/mock" } + } +} +mock_provider "azapi" {} + +variables { + namespace_id = "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/sourceflow/providers/Microsoft.ServiceBus/namespaces/sourceflow" + create_subscribed_topics = true +} + +run "minimal" { + variables { + topology = file("../../fixtures/azure/minimal.json") + } + + assert { + condition = length(azurerm_servicebus_queue.endpoint) == 1 && length(azurerm_servicebus_topic.topic) == 0 && length(azurerm_servicebus_subscription.subscription) == 0 + error_message = "minimal: one queue, nothing else" + } + + assert { + condition = azurerm_servicebus_queue.endpoint["dev-minimal"].requires_session == false && azurerm_servicebus_queue.endpoint["dev-minimal"].max_delivery_count == 10 + error_message = "minimal: an unordered queue with the default delivery limit" + } +} + +run "full" { + variables { + topology = file("../../fixtures/azure/full.json") + } + + assert { + condition = azurerm_servicebus_queue.endpoint["dev-full"].max_delivery_count == 7 && azurerm_servicebus_queue.endpoint["dev-full"].lock_duration == "PT30S" + error_message = "full: the topology's delivery limit and the lock" + } + + assert { + condition = azurerm_servicebus_subscription.subscription["dev-full-in/dev-full"].forward_to == "dev-full" + error_message = "full: the subscription forwards to the endpoint queue" + } + + assert { + condition = azapi_update_resource.default_rule["dev-full-in/dev-full/$Default"].body.properties.sqlFilter.sqlExpression == "[cloudEvents:type] LIKE 'tck.%'" + error_message = "full: the prefix filter replaces the $Default rule" + } +} + +run "ordered" { + variables { + topology = file("../../fixtures/azure/ordered.json") + } + + assert { + condition = azurerm_servicebus_queue.endpoint["dev-ordered"].requires_session && azurerm_servicebus_queue.endpoint["dev-ordered"].max_delivery_count == 5 + error_message = "ordered: sessions on" + } + + assert { + condition = azapi_update_resource.default_rule["dev-ordered-in/dev-ordered/$Default"].body.properties.correlationFilter.properties["cloudEvents:type"] == "tck.ordered.v1" + error_message = "ordered: an exact-type correlation rule" + } +} + +run "filtered" { + variables { + topology = file("../../fixtures/azure/filtered.json") + } + + assert { + condition = length(azurerm_servicebus_subscription.subscription) == 4 && length(azapi_update_resource.default_rule) == 4 && length(azurerm_servicebus_subscription_rule.rule) == 2 + error_message = "filtered: four subscriptions, four $Default rules and two more rules" + } + + assert { + condition = azapi_update_resource.default_rule["dev-tenant/dev-filtered/$Default"].body.properties.sqlFilter.sqlExpression == "1=1" + error_message = "filtered: a filter Service Bus cannot express matches everything (the receiver evaluates it)" + } + + assert { + condition = azurerm_servicebus_subscription_rule.rule["dev-typed/dev-filtered/sf-type-1"].filter_type == "CorrelationFilter" + error_message = "filtered: the second exact type is a correlation rule" + } +} + +run "subscriber_uses_the_publishers_topic" { + variables { + topology = file("../../fixtures/azure/subscriber.json") + create_subscribed_topics = false + } + + assert { + condition = length(azurerm_servicebus_topic.topic) == 0 && length(data.azurerm_servicebus_topic.existing) == 1 + error_message = "subscriber: the shared topic is looked up, not created" + } +} + +run "wrong_transport" { + command = plan + + variables { + topology = file("../../fixtures/aws/minimal.json") + } + + expect_failures = [terraform_data.transport] +} diff --git a/deploy/topology/terraform/azure/variables.tf b/deploy/topology/terraform/azure/variables.tf new file mode 100644 index 00000000..8f29a1d6 --- /dev/null +++ b/deploy/topology/terraform/azure/variables.tf @@ -0,0 +1,15 @@ +variable "namespace_id" { + description = "The resource id of the Service Bus namespace (Standard or Premium tier: topics need Standard)." + type = string +} + +variable "topology" { + description = "The JSON written by `dotnet sourceflow topology export` for the service, with the Azure transport (for example file(\"accounts.topology.json\"))." + type = string +} + +variable "create_subscribed_topics" { + description = "Also create the topics the service subscribes to but does not publish. Leave false when each publisher's stack creates its topics; set true for a single stack holding every service." + type = bool + default = false +} diff --git a/deploy/topology/terraform/gcp/main.tf b/deploy/topology/terraform/gcp/main.tf new file mode 100644 index 00000000..f4b3512b --- /dev/null +++ b/deploy/topology/terraform/gcp/main.tf @@ -0,0 +1,166 @@ +# SourceFlow topology on Google Cloud Pub/Sub (doc 07 §5, ADR-017). +# +# Creates what `ProvisioningMode.CreateIfMissing` would create for one service, from the JSON written by +# `dotnet sourceflow topology export` with the Google Cloud transport: the endpoint's command topic and subscription, +# its dead-letter topic and subscription, the topics the service publishes, and one subscription per subscribed topic +# (ordering, dead-letter policy, delivery-limit label, filter, no expiry). +# +# It also grants the Pub/Sub service agent what dead-lettering needs (publisher on the dead-letter topic, subscriber on +# each subscription with a dead-letter policy), and optionally the service's own identity what it needs at runtime with +# `ProvisioningMode.Validate` (`runtime_member`). Names, ordering and filters come from the export. + +terraform { + required_version = ">= 1.5" + required_providers { + google = { + source = "hashicorp/google" + version = ">= 5.0" + } + } +} + +locals { + topology = jsondecode(var.topology) + # Another transport's export has other properties: nothing is read from it, and the precondition below reports it. + resources = [for r in local.topology.resources : r if local.topology.transport == "gcp_pubsub"] + + created_topics = toset([ + for r in local.resources : r.name if r.kind == "topic" && r.role != "remote-endpoint" && (r.owned || var.create_subscribed_topics) + ]) + + subscriptions = { + for r in local.resources : r.name => { + role = r.role + topic = r.properties.topic + ack_deadline_seconds = r.properties.ackDeadlineSeconds + enable_message_ordering = r.properties.enableMessageOrdering + message_retention_duration = r.properties.messageRetentionDuration + filter = r.properties.filter + labels = tomap(r.properties.labels) + dead_letter_topic = r.properties.deadLetterTopic + max_delivery_attempts = r.properties.maxDeliveryAttempts + } if r.kind == "subscription" + } + + dead_letter_topics = toset([for r in local.resources : r.name if r.kind == "topic" && r.role == "dead-letter"]) + published_topics = toset([for r in local.resources : r.name if r.kind == "topic" && r.role == "topic" && r.owned]) + remote_topics = toset([for r in local.resources : r.name if r.kind == "topic" && r.role == "remote-endpoint"]) + all_topics = toset([for r in local.resources : r.name if r.kind == "topic" && r.role != "remote-endpoint"]) + + service_agent = var.grant_service_agent ? "serviceAccount:service-${data.google_project.project[0].number}@gcp-sa-pubsub.iam.gserviceaccount.com" : null +} + +resource "terraform_data" "transport" { + input = local.topology.transport + + lifecycle { + precondition { + condition = local.topology.transport == "gcp_pubsub" && local.topology.schemaVersion == 1 + error_message = "The topology export is for '${coalesce(local.topology.transport, "no transport")}' (schema ${local.topology.schemaVersion}); this module needs a gcp_pubsub export with schemaVersion 1." + } + } +} + +resource "google_pubsub_topic" "topic" { + for_each = local.created_topics + + project = var.project + name = each.value + labels = var.labels +} + +resource "google_pubsub_subscription" "subscription" { + for_each = local.subscriptions + + project = var.project + name = each.key + topic = "projects/${var.project}/topics/${each.value.topic}" + ack_deadline_seconds = each.value.ack_deadline_seconds + enable_message_ordering = each.value.enable_message_ordering + message_retention_duration = each.value.message_retention_duration + filter = each.value.filter == "" ? null : each.value.filter + labels = merge(var.labels, each.value.labels) + + expiration_policy { + ttl = "" # never expires + } + + dynamic "dead_letter_policy" { + for_each = each.value.dead_letter_topic == null ? [] : [each.value] + content { + dead_letter_topic = "projects/${var.project}/topics/${dead_letter_policy.value.dead_letter_topic}" + max_delivery_attempts = dead_letter_policy.value.max_delivery_attempts + } + } + + depends_on = [google_pubsub_topic.topic] +} + +# ---------------------------------------------------------------- the Pub/Sub service agent (dead-lettering) + +data "google_project" "project" { + count = var.grant_service_agent ? 1 : 0 + project_id = var.project +} + +resource "google_pubsub_topic_iam_member" "service_agent_publisher" { + for_each = var.grant_service_agent ? local.dead_letter_topics : toset([]) + + project = var.project + topic = google_pubsub_topic.topic[each.value].name + role = "roles/pubsub.publisher" + member = local.service_agent +} + +resource "google_pubsub_subscription_iam_member" "service_agent_subscriber" { + for_each = var.grant_service_agent ? toset([for name, s in local.subscriptions : name if s.dead_letter_topic != null]) : toset([]) + + project = var.project + subscription = google_pubsub_subscription.subscription[each.value].name + role = "roles/pubsub.subscriber" + member = local.service_agent +} + +# ---------------------------------------------------------------- the service at runtime (optional) + +resource "google_pubsub_subscription_iam_member" "runtime_subscriber" { + for_each = var.runtime_member == null ? toset([]) : toset(keys(local.subscriptions)) + + project = var.project + subscription = google_pubsub_subscription.subscription[each.value].name + role = "roles/pubsub.subscriber" + member = var.runtime_member +} + +resource "google_pubsub_subscription_iam_member" "runtime_viewer" { + for_each = var.runtime_member == null ? toset([]) : toset(keys(local.subscriptions)) + + project = var.project + subscription = google_pubsub_subscription.subscription[each.value].name + role = "roles/pubsub.viewer" + member = var.runtime_member +} + +# Publishes events, sends commands to remote endpoints, and moves malformed messages to its dead-letter topic. +resource "google_pubsub_topic_iam_member" "runtime_publisher" { + for_each = var.runtime_member == null ? toset([]) : setunion(local.published_topics, local.remote_topics, local.dead_letter_topics) + + project = var.project + topic = each.value + role = "roles/pubsub.publisher" + member = var.runtime_member + + depends_on = [google_pubsub_topic.topic] +} + +# Validate reads every topic of the topology. +resource "google_pubsub_topic_iam_member" "runtime_viewer" { + for_each = var.runtime_member == null ? toset([]) : local.all_topics + + project = var.project + topic = each.value + role = "roles/pubsub.viewer" + member = var.runtime_member + + depends_on = [google_pubsub_topic.topic] +} diff --git a/deploy/topology/terraform/gcp/outputs.tf b/deploy/topology/terraform/gcp/outputs.tf new file mode 100644 index 00000000..28c77ea9 --- /dev/null +++ b/deploy/topology/terraform/gcp/outputs.tf @@ -0,0 +1,9 @@ +output "topic_ids" { + description = "The full names of the topics this module created, by topic id." + value = { for name, topic in google_pubsub_topic.topic : name => topic.id } +} + +output "subscription_ids" { + description = "The full names of the service's subscriptions, by subscription id." + value = { for name, subscription in google_pubsub_subscription.subscription : name => subscription.id } +} diff --git a/deploy/topology/terraform/gcp/tests/fixtures.tftest.hcl b/deploy/topology/terraform/gcp/tests/fixtures.tftest.hcl new file mode 100644 index 00000000..6f46ba97 --- /dev/null +++ b/deploy/topology/terraform/gcp/tests/fixtures.tftest.hcl @@ -0,0 +1,95 @@ +# Plans and applies the module against a mock provider for the committed fixtures (deploy/topology/fixtures/gcp). +# The emulator test (tests/Cloud/SourceFlow.Cloud.Tests/Topology) applies it to the Pub/Sub emulator and validates the +# result with the transport. + +mock_provider "google" { + mock_data "google_project" { + defaults = { number = "123456789" } + } +} + +variables { + project = "sourceflow" + create_subscribed_topics = true +} + +run "full" { + variables { + topology = file("../../fixtures/gcp/full.json") + } + + assert { + condition = length(google_pubsub_topic.topic) == 4 && length(google_pubsub_subscription.subscription) == 3 + error_message = "full: dead-letter, command, published and subscribed topics; dead-letter, endpoint and topic subscriptions" + } + + assert { + condition = google_pubsub_subscription.subscription["dev-full"].dead_letter_policy[0].max_delivery_attempts == 7 && google_pubsub_subscription.subscription["dev-full"].labels["sf-max-deliveries"] == "7" + error_message = "full: the dead-letter policy and the delivery-limit label" + } + + assert { + condition = length(google_pubsub_subscription.subscription["dev-full+dlq"].dead_letter_policy) == 0 + error_message = "full: the dead-letter subscription has no dead-letter policy" + } + + assert { + condition = length(google_pubsub_topic_iam_member.service_agent_publisher) == 1 && length(google_pubsub_subscription_iam_member.service_agent_subscriber) == 2 + error_message = "full: the service agent may publish dead letters and read the subscriptions with a policy" + } + + assert { + condition = google_pubsub_topic_iam_member.service_agent_publisher["dev-full+dlq"].member == "serviceAccount:service-123456789@gcp-sa-pubsub.iam.gserviceaccount.com" + error_message = "full: the grant goes to the project's Pub/Sub service agent" + } +} + +run "ordered" { + variables { + topology = file("../../fixtures/gcp/ordered.json") + runtime_member = "serviceAccount:ordered@sourceflow.iam.gserviceaccount.com" + } + + assert { + condition = google_pubsub_subscription.subscription["dev-ordered"].enable_message_ordering && google_pubsub_subscription.subscription["dev-ordered"].dead_letter_policy[0].max_delivery_attempts == 5 + error_message = "ordered: ordering on, delivery limit 5" + } + + assert { + condition = contains(keys(google_pubsub_topic_iam_member.runtime_publisher), "dev-minimal+in") && contains(keys(google_pubsub_topic_iam_member.runtime_publisher), "dev-ordered-out") + error_message = "ordered: the service may publish its topic and send to the remote endpoint" + } +} + +run "filtered" { + variables { + topology = file("../../fixtures/gcp/filtered.json") + } + + assert { + condition = google_pubsub_subscription.subscription["dev-filtered~tenant"].filter == null && google_pubsub_subscription.subscription["dev-filtered~typed"].filter != null + error_message = "filtered: a native filter where Pub/Sub can express it" + } +} + +run "subscriber_uses_the_publishers_topic" { + variables { + topology = file("../../fixtures/gcp/subscriber.json") + create_subscribed_topics = false + } + + assert { + condition = length(google_pubsub_topic.topic) == 2 + error_message = "subscriber: only its own command and dead-letter topics" + } +} + +run "wrong_transport" { + command = plan + + variables { + topology = file("../../fixtures/azure/minimal.json") + } + + expect_failures = [terraform_data.transport] +} diff --git a/deploy/topology/terraform/gcp/variables.tf b/deploy/topology/terraform/gcp/variables.tf new file mode 100644 index 00000000..319b7904 --- /dev/null +++ b/deploy/topology/terraform/gcp/variables.tf @@ -0,0 +1,33 @@ +variable "project" { + description = "The Google Cloud project id (GcpTransportOptions.ProjectId)." + type = string +} + +variable "topology" { + description = "The JSON written by `dotnet sourceflow topology export` for the service, with the Google Cloud transport (for example file(\"accounts.topology.json\"))." + type = string +} + +variable "create_subscribed_topics" { + description = "Also create the topics the service subscribes to but does not publish. Leave false when each publisher's stack creates its topics; set true for a single stack holding every service." + type = bool + default = false +} + +variable "grant_service_agent" { + description = "Grant the project's Pub/Sub service agent publisher on the dead-letter topic and subscriber on each subscription with a dead-letter policy, which dead-lettering needs. Without it the receiver still enforces the delivery limit itself." + type = bool + default = true +} + +variable "runtime_member" { + description = "The service's identity (for example serviceAccount:accounts@my-project.iam.gserviceaccount.com). When set, it gets subscriber and viewer on its subscriptions, publisher on its published topics, remote endpoints and dead-letter topic, and viewer on every topic of the topology: what it needs with ProvisioningMode.Validate." + type = string + default = null +} + +variable "labels" { + description = "Labels for every topic and subscription." + type = map(string) + default = {} +} diff --git a/deploy/topology/topology.schema.json b/deploy/topology/topology.schema.json new file mode 100644 index 00000000..265c1ce1 --- /dev/null +++ b/deploy/topology/topology.schema.json @@ -0,0 +1,236 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://github.com/CodeShayk/SourceFlow.Net/blob/v3.0.0/deploy/topology/topology.schema.json", + "title": "SourceFlow topology export", + "description": "What `dotnet sourceflow topology export` (TopologyExport.ToJson) writes for one service: its logical topology and, when the transport describes them, the broker resources in the provider's terms (doc 07 §5, ADR-017).", + "type": "object", + "additionalProperties": false, + "required": ["schemaVersion", "service", "transport", "endpoint", "publishes", "subscribes", "sends"], + "properties": { + "schemaVersion": { "const": 1 }, + "service": { "$ref": "#/$defs/name" }, + "transport": { + "description": "The transport's messaging.system name (aws_sqs, gcp_pubsub, servicebus, sourceflow.inmemory); null when the transport does not describe its resources.", + "type": ["string", "null"] + }, + "endpoint": { + "type": "object", + "additionalProperties": false, + "required": ["name", "ordered", "maxDeliveries", "commands"], + "properties": { + "name": { "$ref": "#/$defs/name" }, + "ordered": { "type": "boolean" }, + "maxDeliveries": { "type": "integer", "minimum": 1 }, + "commands": { "$ref": "#/$defs/names", "description": "CloudEvents types the service owns and receives on its endpoint." } + } + }, + "publishes": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "required": ["topic", "ordered", "messages"], + "properties": { + "topic": { "$ref": "#/$defs/name" }, + "ordered": { "type": "boolean" }, + "messages": { "$ref": "#/$defs/names" } + } + } + }, + "subscribes": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "required": ["topic", "filter"], + "properties": { + "topic": { "$ref": "#/$defs/name" }, + "filter": { "type": ["string", "null"], "description": "The CloudEvents SQL filter, or null for every event." } + } + } + }, + "sends": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "required": ["endpoint", "commands"], + "properties": { + "endpoint": { "$ref": "#/$defs/name" }, + "commands": { "$ref": "#/$defs/names" } + } + } + }, + "resources": { + "description": "The broker resources, in creation order. Owned resources belong to this service's infrastructure as code; the others (subscribed topics, remote endpoints) to their owners'.", + "type": "array", + "items": { "$ref": "#/$defs/resource" } + } + }, + "allOf": [ + { "if": { "properties": { "transport": { "const": "aws_sqs" } }, "required": ["transport"] }, "then": { "properties": { "resources": { "items": { "$ref": "#/$defs/aws" } } } } }, + { "if": { "properties": { "transport": { "const": "gcp_pubsub" } }, "required": ["transport"] }, "then": { "properties": { "resources": { "items": { "$ref": "#/$defs/gcp" } } } } }, + { "if": { "properties": { "transport": { "const": "servicebus" } }, "required": ["transport"] }, "then": { "properties": { "resources": { "items": { "$ref": "#/$defs/azure" } } } } } + ], + "$defs": { + "name": { "type": "string", "minLength": 1 }, + "names": { "type": "array", "items": { "$ref": "#/$defs/name" }, "uniqueItems": true }, + "duration": { "type": "string", "pattern": "^P(?!$)(\\d+D)?(T(?=\\d)(\\d+H)?(\\d+M)?(\\d+(\\.\\d+)?S)?)?$" }, + "resource": { + "type": "object", + "additionalProperties": false, + "required": ["kind", "name", "logical", "owned", "role", "properties"], + "properties": { + "kind": { "enum": ["queue", "topic", "subscription", "rule"] }, + "name": { "$ref": "#/$defs/name" }, + "logical": { "$ref": "#/$defs/name" }, + "owned": { "type": "boolean" }, + "role": { "enum": ["endpoint", "dead-letter", "topic", "subscription", "rule", "remote-endpoint"] }, + "properties": { "type": "object" } + } + }, + "aws": { + "oneOf": [ + { + "properties": { + "kind": { "const": "queue" }, + "role": { "enum": ["endpoint", "dead-letter"] }, + "name": { "pattern": "^[A-Za-z0-9_-]{1,80}$|^[A-Za-z0-9_-]{1,75}\\.fifo$" }, + "properties": { + "type": "object", + "required": ["fifo", "messageRetentionSeconds", "deadLetterQueue", "maxReceiveCount", "allowTopics"], + "properties": { + "fifo": { "type": "boolean" }, + "messageRetentionSeconds": { "type": "integer", "minimum": 60, "maximum": 1209600 }, + "deadLetterQueue": { "type": ["string", "null"] }, + "maxReceiveCount": { "type": ["integer", "null"], "minimum": 1 }, + "allowTopics": { "$ref": "#/$defs/names" } + } + } + } + }, + { + "properties": { + "kind": { "const": "queue" }, + "role": { "const": "remote-endpoint" }, + "owned": { "const": false }, + "properties": { "type": "object", "required": ["candidates"], "properties": { "candidates": { "$ref": "#/$defs/names" } } } + } + }, + { + "properties": { + "kind": { "const": "topic" }, + "name": { "pattern": "^[A-Za-z0-9_-]{1,256}$|^[A-Za-z0-9_-]{1,251}\\.fifo$" }, + "properties": { "type": "object", "required": ["fifo"], "properties": { "fifo": { "type": "boolean" } } } + } + }, + { + "properties": { + "kind": { "const": "subscription" }, + "properties": { + "type": "object", + "required": ["topic", "queue", "protocol", "rawMessageDelivery", "filterPolicy", "filterPolicyScope"], + "properties": { + "protocol": { "const": "sqs" }, + "rawMessageDelivery": { "const": true }, + "filterPolicy": { "type": ["string", "null"] }, + "filterPolicyScope": { "enum": ["MessageAttributes", null] } + } + } + } + } + ] + }, + "gcp": { + "oneOf": [ + { + "properties": { + "kind": { "const": "topic" }, + "name": { "pattern": "^[A-Za-z][A-Za-z0-9._~+%-]{2,254}$" }, + "properties": { "type": "object", "maxProperties": 0 } + } + }, + { + "properties": { + "kind": { "const": "subscription" }, + "name": { "pattern": "^[A-Za-z][A-Za-z0-9._~+%-]{2,254}$" }, + "properties": { + "type": "object", + "required": ["topic", "ackDeadlineSeconds", "enableMessageOrdering", "messageRetentionDuration", "filter", "expires", "labels", "deadLetterTopic", "maxDeliveryAttempts"], + "properties": { + "ackDeadlineSeconds": { "type": "integer", "minimum": 10, "maximum": 600 }, + "enableMessageOrdering": { "type": "boolean" }, + "messageRetentionDuration": { "type": "string", "pattern": "^\\d+s$" }, + "filter": { "type": "string" }, + "expires": { "const": false }, + "labels": { "type": "object", "additionalProperties": { "type": "string" } }, + "deadLetterTopic": { "type": ["string", "null"] }, + "maxDeliveryAttempts": { "type": ["integer", "null"], "minimum": 5, "maximum": 100 } + } + } + } + } + ] + }, + "azure": { + "oneOf": [ + { + "properties": { + "kind": { "const": "queue" }, + "role": { "const": "endpoint" }, + "properties": { + "type": "object", + "required": ["requiresSession", "maxDeliveryCount", "lockDuration", "defaultMessageTimeToLive", "deadLetteringOnMessageExpiration", "requiresDuplicateDetection", "duplicateDetectionHistoryTimeWindow"], + "properties": { + "requiresSession": { "type": "boolean" }, + "maxDeliveryCount": { "type": "integer", "minimum": 1 }, + "lockDuration": { "$ref": "#/$defs/duration" }, + "defaultMessageTimeToLive": { "$ref": "#/$defs/duration" }, + "deadLetteringOnMessageExpiration": { "type": "boolean" }, + "requiresDuplicateDetection": { "type": "boolean" }, + "duplicateDetectionHistoryTimeWindow": { "oneOf": [{ "$ref": "#/$defs/duration" }, { "type": "null" }] } + } + } + } + }, + { + "properties": { + "kind": { "const": "queue" }, + "role": { "const": "remote-endpoint" }, + "owned": { "const": false } + } + }, + { + "properties": { + "kind": { "const": "topic" }, + "properties": { "type": "object", "required": ["defaultMessageTimeToLive"], "properties": { "defaultMessageTimeToLive": { "$ref": "#/$defs/duration" } } } + } + }, + { + "properties": { + "kind": { "const": "subscription" }, + "properties": { + "type": "object", + "required": ["topic", "subscription", "forwardTo", "defaultMessageTimeToLive"], + "properties": { "subscription": { "type": "string", "maxLength": 50 } } + } + } + }, + { + "properties": { + "kind": { "const": "rule" }, + "properties": { + "type": "object", + "required": ["topic", "subscription", "rule", "filterType", "correlationProperties", "sqlExpression"], + "properties": { + "filterType": { "enum": ["CorrelationFilter", "SqlFilter"] }, + "correlationProperties": { "type": ["object", "null"], "additionalProperties": { "type": "string" } }, + "sqlExpression": { "type": ["string", "null"] } + } + } + } + } + ] + } + } +} diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 00000000..6567ba64 --- /dev/null +++ b/docker-compose.yml @@ -0,0 +1,13 @@ +# SourceFlow.Net v3 demo: the TravelBooking sample (samples/TravelBooking): the Bookings and Hotels services on +# PostgreSQL and LocalStack, the trip-booking workflow between them, SourceFlow Studio and the Aspire dashboard. +# +# docker compose up -d --build # build the images from this checkout +# docker compose up -d # or pull the published images (ghcr.io) +# docker compose down -v # stop the demo and delete its data +# +# Bookings http://localhost:8080 · Hotels http://localhost:8081 · Studio http://localhost:5080 · Aspire http://localhost:18888 +# The walkthrough is in samples/TravelBooking/README.md. +name: sourceflow-demo + +include: + - samples/TravelBooking/docker-compose.yml diff --git a/docs/Architecture/01-Architecture-Overview.md b/docs/legacy-version/Architecture/01-Architecture-Overview.md similarity index 100% rename from docs/Architecture/01-Architecture-Overview.md rename to docs/legacy-version/Architecture/01-Architecture-Overview.md diff --git a/docs/Architecture/02-Command-Flow-Analysis.md b/docs/legacy-version/Architecture/02-Command-Flow-Analysis.md similarity index 100% rename from docs/Architecture/02-Command-Flow-Analysis.md rename to docs/legacy-version/Architecture/02-Command-Flow-Analysis.md diff --git a/docs/Architecture/03-Event-Flow-Analysis.md b/docs/legacy-version/Architecture/03-Event-Flow-Analysis.md similarity index 100% rename from docs/Architecture/03-Event-Flow-Analysis.md rename to docs/legacy-version/Architecture/03-Event-Flow-Analysis.md diff --git a/docs/Architecture/04-Current-Dispatching-Patterns.md b/docs/legacy-version/Architecture/04-Current-Dispatching-Patterns.md similarity index 100% rename from docs/Architecture/04-Current-Dispatching-Patterns.md rename to docs/legacy-version/Architecture/04-Current-Dispatching-Patterns.md diff --git a/docs/Architecture/05-Store-Persistence-Architecture.md b/docs/legacy-version/Architecture/05-Store-Persistence-Architecture.md similarity index 100% rename from docs/Architecture/05-Store-Persistence-Architecture.md rename to docs/legacy-version/Architecture/05-Store-Persistence-Architecture.md diff --git a/docs/Architecture/06-Cloud-Core-Consolidation.md b/docs/legacy-version/Architecture/06-Cloud-Core-Consolidation.md similarity index 100% rename from docs/Architecture/06-Cloud-Core-Consolidation.md rename to docs/legacy-version/Architecture/06-Cloud-Core-Consolidation.md diff --git a/docs/Architecture/07-AWS-Cloud-Architecture.md b/docs/legacy-version/Architecture/07-AWS-Cloud-Architecture.md similarity index 100% rename from docs/Architecture/07-AWS-Cloud-Architecture.md rename to docs/legacy-version/Architecture/07-AWS-Cloud-Architecture.md diff --git a/docs/Architecture/README.md b/docs/legacy-version/Architecture/README.md similarity index 100% rename from docs/Architecture/README.md rename to docs/legacy-version/Architecture/README.md diff --git a/docs/Cloud-Integration-Testing.md b/docs/legacy-version/Cloud-Integration-Testing.md similarity index 100% rename from docs/Cloud-Integration-Testing.md rename to docs/legacy-version/Cloud-Integration-Testing.md diff --git a/docs/Cloud-Message-Idempotency-Guide.md b/docs/legacy-version/Cloud-Message-Idempotency-Guide.md similarity index 100% rename from docs/Cloud-Message-Idempotency-Guide.md rename to docs/legacy-version/Cloud-Message-Idempotency-Guide.md diff --git a/docs/GitHub-Actions-Setup.md b/docs/legacy-version/GitHub-Actions-Setup.md similarity index 100% rename from docs/GitHub-Actions-Setup.md rename to docs/legacy-version/GitHub-Actions-Setup.md diff --git a/docs/Misc/ENHANCEMENTS.md b/docs/legacy-version/Misc/ENHANCEMENTS.md similarity index 100% rename from docs/Misc/ENHANCEMENTS.md rename to docs/legacy-version/Misc/ENHANCEMENTS.md diff --git a/docs/Misc/OBSERVABILITY_AND_PERFORMANCE.md b/docs/legacy-version/Misc/OBSERVABILITY_AND_PERFORMANCE.md similarity index 100% rename from docs/Misc/OBSERVABILITY_AND_PERFORMANCE.md rename to docs/legacy-version/Misc/OBSERVABILITY_AND_PERFORMANCE.md diff --git a/docs/SourceFlow.Cloud.AWS-README.md b/docs/legacy-version/SourceFlow.Cloud.AWS-README.md similarity index 100% rename from docs/SourceFlow.Cloud.AWS-README.md rename to docs/legacy-version/SourceFlow.Cloud.AWS-README.md diff --git a/docs/SourceFlow.Cloud.GCP-README.md b/docs/legacy-version/SourceFlow.Cloud.GCP-README.md similarity index 100% rename from docs/SourceFlow.Cloud.GCP-README.md rename to docs/legacy-version/SourceFlow.Cloud.GCP-README.md diff --git a/docs/SourceFlow.Net-README.md b/docs/legacy-version/SourceFlow.Net-README.md similarity index 100% rename from docs/SourceFlow.Net-README.md rename to docs/legacy-version/SourceFlow.Net-README.md diff --git a/docs/SourceFlow.Stores.EntityFramework-README.md b/docs/legacy-version/SourceFlow.Stores.EntityFramework-README.md similarity index 100% rename from docs/SourceFlow.Stores.EntityFramework-README.md rename to docs/legacy-version/SourceFlow.Stores.EntityFramework-README.md diff --git a/docs/Versions/v1.0.0/CHANGELOG.md b/docs/legacy-version/Versions/v1.0.0/CHANGELOG.md similarity index 100% rename from docs/Versions/v1.0.0/CHANGELOG.md rename to docs/legacy-version/Versions/v1.0.0/CHANGELOG.md diff --git a/docs/Versions/v2.0.0/CHANGELOG.md b/docs/legacy-version/Versions/v2.0.0/CHANGELOG.md similarity index 100% rename from docs/Versions/v2.0.0/CHANGELOG.md rename to docs/legacy-version/Versions/v2.0.0/CHANGELOG.md diff --git a/docs/aws-integration.md b/docs/legacy-version/aws-integration.md similarity index 100% rename from docs/aws-integration.md rename to docs/legacy-version/aws-integration.md diff --git a/docs/wiki.md b/docs/legacy-version/wiki.md similarity index 100% rename from docs/wiki.md rename to docs/legacy-version/wiki.md diff --git a/docs/product/01-Product-Vision-and-Scope.md b/docs/product/01-Product-Vision-and-Scope.md new file mode 100644 index 00000000..75fbfd17 --- /dev/null +++ b/docs/product/01-Product-Vision-and-Scope.md @@ -0,0 +1,129 @@ +# 01 — Product Vision and Scope + +## 1. Problem + +.NET teams applying Domain-Driven Design, CQRS and an append-only history of state changes tend to rebuild the same plumbing for every service: + +- a way to send a command to the right handler and record that it happened; +- a way to rebuild an entity's state by replaying that history; +- a way to publish domain events to in-process read models and to other services; +- persistence for the write model, the history and the read models; +- and, once the service is distributed, cloud queues and topics, duplicate-message handling, dead letters, encryption and tracing. + +This plumbing is easy to get subtly wrong, and it ties domain code to infrastructure. + +## 2. Vision + +SourceFlow.Net is a lightweight, extensible .NET framework that gives a team the whole command→state→event→view loop from **one registration call**. It keeps domain code free of infrastructure. Moving from a single process to a distributed, multi-cloud deployment should be a **configuration change, not a domain-code change**. + +## 3. The core model in one paragraph + +SourceFlow.Net is **command-sourced**: the durable log is the sequence of *commands* applied to each entity, not a stream of events. An **Aggregate** sends a command. The **Command Bus** gives it the next per-entity sequence number, dispatches it to **Sagas** (which load the entity, change it and persist the new state), and then appends the command to the **Command Store**. Sagas raise **Events**, which go through an **Event Queue** to **Views** (which update denormalised **View Models**) and back to **Aggregates**. Replaying an entity's commands through the same pipeline rebuilds its state. With a cloud provider configured, chosen commands and events also travel over queues and topics to other bounded contexts. + +```mermaid +flowchart LR + A[Aggregate] -- Send(command) --> CB[Command Bus] + CB -- seq no. --> CS[(Command Store)] + CB --> CD[Command Dispatchers] + CD -- local --> S[Saga] + CD -- routed --> Q[[Cloud queue]] + S -- get/persist --> ES[(Entity Store)] + S -- Raise(event) --> EQ[Event Queue] + EQ --> ED[Event Dispatchers] + ED -- local --> V[View] --> VS[(View Model Store)] + ED -- local --> A + ED -- routed --> T[[Cloud topic]] +``` + +## 4. Users + +| Persona | Needs | Main touchpoints | +|---------|-------|------------------| +| **Domain developer** | Model aggregates, sagas and views without writing plumbing. Get type safety and testability. | `Aggregate`, `Saga`, `View`, `Command`, `Event`, `UseSourceFlow()` | +| **Platform / DevOps engineer** | Run services on AWS or GCP with automatic provisioning, health checks, tracing, encryption and safe retries. | `UseSourceFlowAws()`, `UseSourceFlowGcp()`, options classes, health checks, OpenTelemetry | +| **Persistence integrator** | Back the stores with a relational database, possibly a different engine per store. | `AddSourceFlowEfStores*()`, `AddSourceFlowIdempotency*()` | +| **Framework extender** | Add a store, a cloud provider or cross-cutting middleware. | `ICommandStore`, `IEntityStore`, `IViewModelStore`, `ICommandDispatcher`, `IEventDispatcher`, the four middleware interfaces, `IIdempotencyService`, `IMessageEncryption` | +| **Learner / book reader** | A readable reference implementation of DDD, CQRS and command sourcing that goes with the companion book. | Samples in tests, architecture docs | + +## 5. Goals + +| ID | Goal | How we know it's met | +|----|------|----------------------| +| G1 | A working local command→saga→event→view flow with one registration call | `services.UseSourceFlow(assemblies)` plus store registrations runs the end-to-end test scenario (see `tests/SourceFlow.Core.Tests/E2E`) | +| G2 | Rebuild any entity from its command history | `ICommandPublisher.ReplayCommands(id)` reproduces the entity and its view models | +| G3 | Distribute commands and events across services with no domain-code change | Adding `UseSourceFlowAws(...)` or `UseSourceFlowGcp(...)` with a bus configuration routes the chosen message types, and sagas and views stay unchanged | +| G4 | Same routing API on every cloud provider | One `BusConfigurationBuilder` drives both the AWS and GCP providers | +| G5 | Production-grade operations | Idempotency, dead-letter capture, envelope encryption, health checks and OpenTelemetry traces and metrics are available on every provider | +| G6 | Pluggable persistence | Any store can be replaced by implementing one interface. The EF Core package supports SQL Server out of the box and any EF provider through a callback | +| G7 | Broad .NET reach | The core library targets .NET Standard 2.0 and 2.1 plus .NET 8, 9 and 10 | + +## 6. Non-goals (current scope) + +- **Not an event store.** Events are not persisted. Only commands, entity snapshots (current state) and view models are. +- **No snapshotting** of the command log, and no log compaction or archiving. +- **No message-schema versioning or upcasting** for stored commands or wire messages. Types are identified by assembly-qualified name. +- **No query API** beyond `IViewModelStore.Get(id)`. Querying read models is left to the application. +- **No hosted UI or admin console** (for example for dead-letter replay). +- **No distributed transactions** across the command log, entity store and event dispatch. +- **Azure provider**: on the roadmap but not built (see §9). + +## 7. Product composition + +| Package | Version | Target frameworks | Purpose | Key dependencies | +|---------|---------|-------------------|---------|------------------| +| `SourceFlow.Net` | 2.0.0 | netstandard2.0, netstandard2.1, net8.0, net9.0, net10.0 | Core framework: domain model, pipelines, store contracts, DI, telemetry, **cloud abstractions** (bus configuration, idempotency, dead letters, circuit breaker, encryption contracts, masking, cloud telemetry) | System.Text.Json, M.E.DependencyInjection/Logging abstractions, OpenTelemetry 1.14 | +| `SourceFlow.Stores.EntityFramework` | 2.0.0 | net8.0, net9.0, net10.0 | EF Core 9 implementations of the command, entity and view-model stores, plus the idempotency service | EF Core 9 (+ SqlServer), Polly 8, OpenTelemetry | +| `SourceFlow.Cloud.AWS` | 2.0.0 | netstandard2.1, net8.0, net9.0, net10.0 | Commands over Amazon SQS, events over Amazon SNS→SQS, KMS encryption, health check | AWSSDK SQS/SNS/KMS 3.7 | +| `SourceFlow.Cloud.GCP` | 2.0.0-beta.1 | net8.0, net9.0, net10.0 | Commands and events over Google Cloud Pub/Sub, Cloud KMS encryption, health check, emulator support | Google.Cloud.PubSub.V1 3.17, Google.Cloud.Kms.V1 3.16 | + +Since v2.0.0, cloud abstractions live in the core package under `SourceFlow.Cloud.*`. The separate `SourceFlow.Cloud.Core` package is gone (see [v2.0.0 changelog](../legacy-version/Versions/v2.0.0/CHANGELOG.md)). + +## 8. Key user journeys + +### J1 — Handle a command locally +1. The application resolves an aggregate (for example through `IAggregateFactory.Create()`) and calls a domain method. +2. The aggregate builds a `Command` that references the target entity (by id, or as a new entity) and calls `Send`. +3. The command bus runs dispatch middleware, assigns the next sequence number, dispatches to every saga that implements `IHandles`, then appends the command to the command store. +4. The saga loads or creates the entity, applies the change, persists it and, if it implements `IHandlesWithEvent`, raises the event. +5. The event queue sends the event to every view implementing `IProjectOn` (which persist view models) and every aggregate implementing `ISubscribes`. + +### J2 — Rebuild an entity +1. The application calls `aggregate.ReplayCommands(entityId)`. +2. The bus loads the entity's commands in sequence order, marks each as a replay, and re-dispatches them without assigning new sequence numbers or re-appending them. +3. Sagas and views reapply the changes, which rebuilds the entity and its projections. + +### J3 — Send a command to another service +1. At startup, the service declares in a `BusConfigurationBuilder` which commands go to which queue, which events go to which topic, which queues it listens on and which topics it subscribes to. +2. A bootstrapper resolves or creates the cloud resources before the listeners start. +3. Routed commands and events are serialised and published. The receiving service's listener deserialises each message and hands it to its local sagas, or to its views and aggregates. + +### J4 — Run safely in production +1. The operator chooses an idempotency backend: in-memory for a single instance, EF for several instances, or a custom one. +2. The operator turns on telemetry and exports traces and metrics over OTLP. +3. The operator adds the provider health check to the host's health endpoint. +4. Optionally, the operator turns on KMS envelope encryption, dead-letter capture and a circuit breaker. On AWS these are opt-in today; see [GAP-01](06-Gaps-Risks-and-Open-Questions.md#gap-01). + +## 9. Roadmap (from README and changelogs) + +| Release | Date | Scope | +|---------|------|-------| +| v1.0.0 | 29 Nov 2025 | Core command sourcing, CQRS, sagas, views, EF stores | +| v2.0.0 | 15 Mar 2026 (README); changelog says "TBC" | Cloud.Core merged into the core package (namespace break), AWS provider, idempotency builder, EF idempotency store | +| GCP provider | 2.0.0-beta.1 (latest commit) | Pub/Sub provider with emulator-based CI | +| Azure provider | TBC | Service Bus provider with Azurite-based tests (announced, not built) | + +## 10. Glossary + +| Term | Meaning in SourceFlow.Net | +|------|---------------------------| +| **Entity** | Write-model state object implementing `IEntity` (integer `Id`). Persisted whole in the entity store. | +| **Aggregate** | Domain façade for one entity type (`Aggregate`). Sends commands and reacts to events. Does **not** change state directly. | +| **Saga** | Command handler for one entity type (`Saga`). Loads the entity, applies the command, persists it and raises events. Can publish follow-up commands. | +| **Command** | An intent to change one entity: `Command` with an `EntityRef` (id + `IsNew`), a payload and metadata. The unit of the durable log. | +| **Event** | A notification that an entity changed: `Event` whose payload is the entity. Not persisted. | +| **View / View model** | A projection (`View`) that turns events into a denormalised read model (`IViewModel`). | +| **Command log / store** | Append-only, per-entity ordered record of commands (`ICommandStore`). | +| **Replay** | Re-dispatching an entity's stored commands to rebuild state (`Metadata.IsReplay = true`). | +| **Dispatcher** | Pluggable outbound transport for commands (`ICommandDispatcher`) or events (`IEventDispatcher`). Local and cloud dispatchers run side by side. | +| **Bus configuration** | Code-first routing table: command type → queue, event type → topic, plus the queues this service listens on and the topics it subscribes to. | +| **Bootstrapper** | Hosted service that turns short queue and topic names into provider resource identifiers, creating them if needed. | diff --git a/docs/product/02-Core-Framework-Requirements.md b/docs/product/02-Core-Framework-Requirements.md new file mode 100644 index 00000000..3b8bd8a1 --- /dev/null +++ b/docs/product/02-Core-Framework-Requirements.md @@ -0,0 +1,113 @@ +# 02 — Core Framework Requirements (`SourceFlow.Net`) + +Source root: [`src/SourceFlow`](../../src/SourceFlow). The status legend is in the [README](README.md#status-values). + +--- + +## 1. Domain modelling (`DOM`) + +| ID | Requirement | Status | Source | +|----|-------------|--------|--------| +| DOM-01 | Every write-model entity shall implement `IEntity` with a settable integer `Id`. | Implemented | [IEntity.cs](../../src/SourceFlow/IEntity.cs) | +| DOM-02 | The framework shall provide `Aggregate` as a base for domain façades. It exposes a protected `Send(command)` and a public `ReplayCommands(entityId)`, and rejects null commands. | Implemented | [Aggregate.cs](../../src/SourceFlow/Aggregate/Aggregate.cs) | +| DOM-03 | An aggregate shall be able to react to an event type by implementing `ISubscribes.On(event)`. | Implemented | [ISubscribes.cs](../../src/SourceFlow/Aggregate/ISubscribes.cs), [Aggregate/EventSubscriber.cs](../../src/SourceFlow/Aggregate/EventSubscriber.cs) | +| DOM-04 | Consumers shall be able to resolve aggregates through `IAggregateFactory.Create()`, backed by the DI container. | Implemented | [AggregateFactory.cs](../../src/SourceFlow/Impl/AggregateFactory.cs) | +| DOM-05 | The framework shall provide `Saga`. A saga declares which commands it handles by implementing `IHandles`; it receives the current entity and the command and returns the updated entity. | Implemented | [Saga.cs](../../src/SourceFlow/Saga/Saga.cs), [IHandles.cs](../../src/SourceFlow/Saga/IHandles.cs) | +| DOM-06 | Before calling a handler, the saga shall create a fresh entity (with the command's entity id) when `command.Entity.IsNew` is true, and otherwise load it from the entity store. | Implemented | `Saga.Handle` | +| DOM-07 | After a handler returns a non-null entity, the saga shall persist it through the entity store. | Implemented | `Saga.Handle` | +| DOM-08 | A saga shall be able to declare "handling command C raises event E" by implementing `IHandlesWithEvent`. The framework then builds E (with a parameterless constructor, or one taking the entity), sets its payload to the entity, and raises it. | Partial — failures while building or raising the event are logged and swallowed ([GAP-07](06-Gaps-Risks-and-Open-Questions.md#gap-07)) | `Saga.RaiseEvent` | +| DOM-09 | A saga shall be able to publish follow-up commands (`Publish`) and raise events explicitly (`Raise`). `Raise` shall reject events with no payload. | Implemented | `Saga.Publish`, `Saga.Raise` | +| DOM-10 | The framework shall provide `View`. A view declares which events it projects by implementing `IProjectOn.On(event)`, which returns the view model to persist (or null to skip). | Implemented | [View.cs](../../src/SourceFlow/Projections/View.cs), [IProjectOn.cs](../../src/SourceFlow/Projections/IProjectOn.cs) | +| DOM-11 | Views shall be able to read and write view models through protected `Find(id)` and `Persist(model)` helpers. | Implemented | `View.Find`, `View.Persist` | +| DOM-12 | Every view model shall implement `IViewModel` with a settable integer `Id`. | Implemented | [IViewModel.cs](../../src/SourceFlow/Projections/IViewModel.cs) | +| DOM-13 | Command and event handler matching shall be type-exact: a saga or view receives a message only if it implements the handler interface for that message's runtime type. | Implemented | `Saga.CanHandle`, `View.CanHandle` | + +## 2. Commands, command bus, command log and replay (`CMD`) + +| ID | Requirement | Status | Source | +|----|-------------|--------|--------| +| CMD-01 | A command shall carry a `Name` (defaults to its type name), a strongly typed `Payload` (`IPayload`), an `EntityRef` (`Id`, `IsNew`) and `Metadata`. | Implemented | [Command.cs](../../src/SourceFlow/Messaging/Commands/Command.cs), [ICommand.cs](../../src/SourceFlow/Messaging/Commands/ICommand.cs) | +| CMD-02 | `Metadata` shall carry a unique `EventId` (GUID), `OccurredOn` (UTC), `SequenceNo`, `IsReplay` and an open `Properties` dictionary. | Implemented | [IMetadata.cs](../../src/SourceFlow/Messaging/IMetadata.cs) | +| CMD-03 | `Command` shall provide constructors for: an existing entity (id), a new entity, and an explicit id plus new-entity flag. | Implemented | `Command` constructors | +| CMD-04 | `ICommandPublisher.Publish` shall reject a null command and a command with no entity reference. | Implemented | [CommandPublisher.cs](../../src/SourceFlow/Messaging/Commands/Impl/CommandPublisher.cs) | +| CMD-05 | For every non-replay command, the command bus shall assign `SequenceNo` = (highest stored sequence number for that entity) + 1, starting at 1. | Partial — reads the entity's full history on every command, and the read and append are not atomic ([GAP-05](06-Gaps-Risks-and-Open-Questions.md#gap-05), [NFR-PERF-03](05-Non-Functional-Requirements.md)) | [CommandBus.cs](../../src/SourceFlow/Messaging/Bus/Impl/CommandBus.cs), [CommandStoreAdapter.cs](../../src/SourceFlow/Impl/CommandStoreAdapter.cs) | +| CMD-06 | The command bus shall dispatch each command to **all** registered `ICommandDispatcher`s at once and wait for all of them. | Implemented | `CommandBus.CoreDispatch` | +| CMD-07 | After a non-replay command has been dispatched successfully, the bus shall append it to the command store. If dispatch throws, the command shall not be appended. | Implemented | `CommandBus.CoreDispatch` | +| CMD-08 | The local `CommandDispatcher` shall pass each command to every `ICommandSubscriber`. The saga subscriber shall call every saga that can handle it, concurrently. | Implemented | [CommandDispatcher.cs](../../src/SourceFlow/Messaging/Commands/Impl/CommandDispatcher.cs), [Saga/CommandSubscriber.cs](../../src/SourceFlow/Saga/CommandSubscriber.cs) | +| CMD-09 | The command store adapter shall turn commands into `CommandData` (assembly-qualified command and payload type names, JSON payload of the concrete payload type, JSON metadata, timestamp) and back. | Implemented | `CommandStoreAdapter.SerializeCommand` / `DeserializeCommand` | +| CMD-10 | `ReplayCommands(entityId)` shall load the entity's commands in ascending sequence order, set `IsReplay = true` on each, and re-dispatch them one after another through the full pipeline (middleware and every dispatcher), without assigning new sequence numbers or appending again. | Partial — cloud dispatchers do not check `IsReplay`, so replayed commands can be re-published ([GAP-06](06-Gaps-Risks-and-Open-Questions.md#gap-06)) | `CommandBus.Replay` | +| CMD-11 | To be replayable, a command type shall be constructible through a **public parameterless constructor**. The framework shall fail loudly, not silently, when a stored command cannot be rebuilt. | Partial — the requirement is unstated, and commands that cannot be rebuilt are **silently skipped** ([GAP-04](06-Gaps-Risks-and-Open-Questions.md#gap-04)) | `CommandStoreAdapter.DeserializeCommands` | +| CMD-12 | A command that creates an entity shall be logged under that entity's real id. Either the caller supplies the id, or the framework assigns it and writes it back to the command before it is appended. | **Not met** — new-entity commands without a caller-assigned id are logged under id 0 ([GAP-20](06-Gaps-Risks-and-Open-Questions.md#gap-20)) | `CommandBus.CoreDispatch`, `Saga.InitialiseEntity` | +| CMD-13 | A command received from another service shall be sequenced and logged by the service that owns the entity, so that the owner can replay it. | **Not met** — cloud listeners call the subscriber directly, bypassing the bus ([GAP-19](06-Gaps-Risks-and-Open-Questions.md#gap-19)) | AWS and GCP command listeners | + +## 3. Events and the event pipeline (`EVT`) + +| ID | Requirement | Status | Source | +|----|-------------|--------|--------| +| EVT-01 | An event shall carry a `Name`, `Metadata`, and the changed entity as its `Payload` (`Event`). | Implemented | [Event.cs](../../src/SourceFlow/Messaging/Events/Event.cs) | +| EVT-02 | `IEventQueue.Enqueue` shall reject null events, run the event dispatch middleware, then dispatch to **all** registered `IEventDispatcher`s concurrently. | Implemented | [EventQueue.cs](../../src/SourceFlow/Messaging/Events/Impl/EventQueue.cs) | +| EVT-03 | The local `EventDispatcher` shall pass each event to every `IEventSubscriber`. Out of the box there are two: the aggregate subscriber (DOM-03) and the projection subscriber (DOM-10). | Implemented | [EventDispatcher.cs](../../src/SourceFlow/Messaging/Events/Impl/EventDispatcher.cs) | +| EVT-04 | The projection subscriber shall call every view that can handle the event concurrently, and persist each non-null view model it gets back. | Implemented | [Projections/EventSubscriber.cs](../../src/SourceFlow/Projections/EventSubscriber.cs) | +| EVT-05 | Events are transient: the framework shall not persist them. Read models are rebuilt by replaying commands (CMD-10). | Implemented (by design) | — | + +## 4. Store contracts and adapters (`STO`) + +| ID | Requirement | Status | Source | +|----|-------------|--------|--------| +| STO-01 | `ICommandStore` shall support `Append(CommandData)` and `Load(entityId)`, returning commands in sequence order. | Implemented | [ICommandStore.cs](../../src/SourceFlow/ICommandStore.cs) | +| STO-02 | `IEntityStore` shall support `Get(id)`, `Persist(entity)` (an upsert) and `Delete(entity)` for any `IEntity`. | Implemented | [IEntityStore.cs](../../src/SourceFlow/IEntityStore.cs) | +| STO-03 | `IViewModelStore` shall support `Get(id)`, `Persist(model)` (an upsert) and `Delete(model)` for any `IViewModel`. | Implemented | [IViewModelStore.cs](../../src/SourceFlow/IViewModelStore.cs) | +| STO-04 | The framework shall wrap each store in an adapter that adds serialisation (for the command store) and optional tracing, so that store implementers deal only with plain data. | Implemented | [Impl/](../../src/SourceFlow/Impl) | +| STO-05 | Consumers and tests shall be able to supply their own adapter implementations. The framework registers the defaults only if none is registered. | Implemented | `TryAddScoped` in [IocExtensions.cs](../../src/SourceFlow/IocExtensions.cs) | +| STO-06 | Store contracts shall define what happens when something is not found (for example, `Get` throws or returns null). | Partial — not specified; the EF store throws `InvalidOperationException` ([GAP-15](06-Gaps-Risks-and-Open-Questions.md#gap-15)) | — | + +## 5. Registration and discovery (`REG`) + +| ID | Requirement | Status | Source | +|----|-------------|--------|--------| +| REG-01 | `services.UseSourceFlow(params Assembly[])` shall register the whole local pipeline in one call. | Implemented | [IocExtensions.cs](../../src/SourceFlow/IocExtensions.cs) | +| REG-02 | When no assemblies are given, the framework shall scan the SourceFlow assembly and the calling assembly. | Implemented | `UseSourceFlow` | +| REG-03 | Scanning shall find and register every public, concrete, non-generic `IAggregate`, `ISaga` and `IView`, each under its marker interface, its concrete type and every other public interface it implements. | Implemented | `AddImplementationAsInterfaces` | +| REG-04 | Scanning shall register the **first** implementation it finds of `ICommandStore`, `IEntityStore` and `IViewModelStore`, and shall not override one that is already registered. | Implemented | `AddFirstImplementationAsInterface` | +| REG-05 | Consumers shall be able to choose the service lifetime for discovered domain types (the default is Singleton). | Partial — Singleton domain types depend on Scoped adapters and publishers, a captive-dependency risk ([GAP-08](06-Gaps-Risks-and-Open-Questions.md#gap-08)) | `UseSourceFlow(services, lifetime, …)` | +| REG-06 | The framework shall break the publisher↔saga/aggregate dependency cycle by injecting `Lazy`. | Implemented | `UseSourceFlow` | +| REG-07 | Scanning shall tolerate assemblies whose types cannot all be loaded, by registering the types that did load. | Partial — the `ReflectionTypeLoadException` handler calls `GetTypes()` again inside the `catch` block, so the exception escapes and registration fails. It should use `ex.Types` ([GAP-16](06-Gaps-Risks-and-Open-Questions.md#gap-16)) | `GetImplementedTypes` | + +## 6. Middleware and extension points (`EXT`) + +| ID | Requirement | Status | Source | +|----|-------------|--------|--------| +| EXT-01 | The framework shall offer four middleware hooks, each `InvokeAsync(message, next)`: `ICommandDispatchMiddleware` (around the command bus), `ICommandSubscribeMiddleware` (around saga dispatch), `IEventDispatchMiddleware` (around the event queue) and `IEventSubscribeMiddleware` (around each event subscriber). | Implemented | [Messaging/](../../src/SourceFlow/Messaging) | +| EXT-02 | Middleware shall run in registration order (first registered is outermost) and be able to short-circuit by not calling `next`. | Implemented | Pipeline built over `middlewares.Reverse()` in the bus, queue and subscribers | +| EXT-03 | Middleware shall be registered through standard DI (`services.AddSingleton()` and so on). | Implemented — no helper methods; covered by tests in `tests/SourceFlow.Core.Tests/Middleware` | — | +| EXT-04 | New transports shall plug in by registering more `ICommandDispatcher` / `IEventDispatcher` implementations, which run alongside the local ones. | Implemented | Used by the AWS and GCP providers | + +## 7. Domain observability (`OBS`) + +| ID | Requirement | Status | Source | +|----|-------------|--------|--------| +| OBS-01 | Domain telemetry shall be **off by default** (`DomainObservabilityOptions.Enabled = false`), so it adds no overhead or behaviour change unless switched on. | Implemented | [DomainTelemetryService.cs](../../src/SourceFlow/Observability/DomainTelemetryService.cs) | +| OBS-02 | `services.AddSourceFlowTelemetry(serviceName, version)` or `AddSourceFlowTelemetry(options => …)` shall switch telemetry on and register the SourceFlow ActivitySource and Meter with OpenTelemetry. | Implemented | [OpenTelemetryExtensions.cs](../../src/SourceFlow/Observability/OpenTelemetryExtensions.cs) | +| OBS-03 | The framework shall emit spans for command bus dispatch and replay, command dispatcher send, event queue enqueue, event dispatch, store adapter operations and serialisation. | Implemented | Span names `sourceflow.commandbus.dispatch`, `sourceflow.commandbus.replay`, `sourceflow.eventqueue.enqueue`, `sourceflow.entitystore.*`, `sourceflow.viewmodelstore.*`, `sourceflow.domain.command.*` | +| OBS-04 | The framework shall emit the metrics `sourceflow.domain.commands.executed`, `…sagas.executed`, `…entities.created`, `…serialization.operations` (counters) and `…operation.duration`, `…serialization.duration` (histograms). | Partial — `sagas.executed` is defined but never recorded; `commands.executed` is recorded twice per command (by the bus and by the store adapter); `entities.created` goes up on every persist, updates included ([GAP-14](06-Gaps-Risks-and-Open-Questions.md#gap-14)) | `DomainTelemetryService` | +| OBS-05 | The framework shall provide exporter helpers for console and OTLP, resource attributes, and batch-processing tuning. | Implemented | `AddSourceFlowConsoleExporter`, `AddSourceFlowOtlpExporter`, `AddSourceFlowResourceAttributes`, `ConfigureSourceFlowBatchProcessing` | +| OBS-06 | All pipeline components shall write structured `Action=…` log entries through `ILogger`. | Implemented | Throughout | + +## 8. Performance helpers (`PERF`) + +| ID | Requirement | Status | Source | +|----|-------------|--------|--------| +| PERF-01 | JSON serialisation of commands shall use pooled buffers to cut allocations. | Implemented | [ByteArrayPool.cs](../../src/SourceFlow/Performance/ByteArrayPool.cs) | +| PERF-02 | Fan-out to subscribers shall use pooled task buffers. | Implemented | [TaskBufferPool.cs](../../src/SourceFlow/Performance/TaskBufferPool.cs) | + +--- + +## Acceptance scenarios (core) + +These come from the end-to-end tests in [`tests/SourceFlow.Core.Tests/E2E`](../../tests/SourceFlow.Core.Tests/E2E) (the bank-account sample). + +1. **Create.** When `AccountAggregate.CreateAccount(id, "Holder", 100)` is called, `AccountSaga` creates a `BankAccount` with balance 100, persists it, and raises `AccountCreated`. `AccountView` then writes an `AccountViewModel`, and the command store holds one command with `SequenceNo = 1`. +2. **Mutate.** When a deposit of 50 follows, the entity balance becomes 150, `AccountUpdated` is raised, the view model is updated, and the command is stored with `SequenceNo = 2`. +3. **Validate.** When a saga handler throws (for example, a deposit of 0 or below), the command is **not** appended and no event is raised. +4. **Replay.** When `ReplayCommands(id)` is called on an entity with N stored commands, the sagas and views reach the same final state, and the command store still holds exactly N commands. +5. **Middleware.** With middleware registered in the order M1, M2, a published command passes M1 → M2 → core. A middleware that does not call `next` stops dispatch and append. diff --git a/docs/product/03-Persistence-EntityFramework-Requirements.md b/docs/product/03-Persistence-EntityFramework-Requirements.md new file mode 100644 index 00000000..06024bc2 --- /dev/null +++ b/docs/product/03-Persistence-EntityFramework-Requirements.md @@ -0,0 +1,58 @@ +# 03 — Persistence Requirements (`SourceFlow.Stores.EntityFramework`) + +Source root: [`src/SourceFlow.Stores.EntityFramework`](../../src/SourceFlow.Stores.EntityFramework). Targets net8.0, net9.0 and net10.0 on EF Core 9. The status legend is in the [README](README.md#status-values). + +--- + +## 1. Store implementations + +| ID | Requirement | Status | Source | +|----|-------------|--------|--------| +| EF-01 | The package shall implement `ICommandStore`, `IEntityStore` and `IViewModelStore` on EF Core, each with its own `DbContext` (`CommandDbContext`, `EntityDbContext`, `ViewModelDbContext`). | Implemented | [Stores/](../../src/SourceFlow.Stores.EntityFramework/Stores) | +| EF-02 | `EfCommandStore.Append` shall insert one row per command. `Load(entityId)` shall return that entity's commands in ascending `SequenceNo` order, read without change tracking. | Implemented | [EfCommandStore.cs](../../src/SourceFlow.Stores.EntityFramework/Stores/EfCommandStore.cs) | +| EF-03 | The command table shall enforce a **unique (EntityId, SequenceNo)** index, so two writers cannot both append the same sequence number. It shall also index `EntityId` and `Timestamp`. | Implemented | [CommandRecord.cs](../../src/SourceFlow.Stores.EntityFramework/Models/CommandRecord.cs) | +| EF-04 | `EfEntityStore` and `EfViewModelStore` shall `Persist` as an upsert (update if the id exists, insert if not), reject ids ≤ 0 on `Get` and `Delete`, and throw `InvalidOperationException` when a requested row does not exist. | Implemented | [EfEntityStore.cs](../../src/SourceFlow.Stores.EntityFramework/Stores/EfEntityStore.cs), [EfStoreBase.cs](../../src/SourceFlow.Stores.EntityFramework/Stores/EfStoreBase.cs) | +| EF-05 | Entity and view-model types shall be mapped at runtime, without a hand-written `DbContext`. They are registered explicitly (`RegisterEntityType()`, `RegisterViewModelType()`) or by assembly scan (`RegisterAssembly`), keyed on `Id`. | Implemented — the registrations are **process-wide static** state ([GAP-17](06-Gaps-Risks-and-Open-Questions.md#gap-17)) | [EntityDbContext.cs](../../src/SourceFlow.Stores.EntityFramework/EntityDbContext.cs), [ViewModelDbContext.cs](../../src/SourceFlow.Stores.EntityFramework/ViewModelDbContext.cs) | +| EF-06 | A helper shall create tables for runtime-registered entity and view-model types. | Partial — `DbContextMigrationHelper` emits `CREATE TABLE IF NOT EXISTS "…"`, which works on SQLite and PostgreSQL but not SQL Server. It also ignores the table-naming convention and swallows errors | [DbContextMigrationHelper.cs](../../src/SourceFlow.Stores.EntityFramework/Migrations/DbContextMigrationHelper.cs) | + +## 2. Configuration and database providers + +| ID | Requirement | Status | Source | +|----|-------------|--------|--------| +| EF-10 | `AddSourceFlowEfStores(connectionString)` shall register all three stores on one SQL Server connection string. | Implemented | [ServiceCollectionExtensions.cs](../../src/SourceFlow.Stores.EntityFramework/Extensions/ServiceCollectionExtensions.cs) | +| EF-11 | `AddSourceFlowEfStores(commandCs, entityCs, viewModelCs)` shall let each store use its own SQL Server database. | Implemented | same | +| EF-12 | `AddSourceFlowEfStores(IConfiguration)` and `AddSourceFlowEfStores(Action)` shall bind connection strings, naming, resilience and observability from configuration or code. A per-store connection string overrides `DefaultConnectionString`, and a store with neither shall fail with a clear error. | Implemented | [SourceFlowEfOptions.cs](../../src/SourceFlow.Stores.EntityFramework/Options/SourceFlowEfOptions.cs) | +| EF-13 | `AddSourceFlowEfStoresWithCustomProvider(Action)` shall support any EF Core provider (PostgreSQL, SQLite, MySQL and so on) for all stores. | Implemented | same | +| EF-14 | `AddSourceFlowEfStoresWithCustomProviders(cmd, entity, viewModel)` shall allow a **different provider per store** (for example, commands on PostgreSQL and view models on SQL Server). | Implemented | same | +| EF-15 | Table names shall be configurable per store: casing (PascalCase, camelCase, snake_case, lowercase or UPPERCASE), pluralisation, prefix, suffix, and an optional schema. | Implemented | [TableNamingConvention.cs](../../src/SourceFlow.Stores.EntityFramework/Options/TableNamingConvention.cs) | + +## 3. Resilience and observability + +| ID | Requirement | Status | Source | +|----|-------------|--------|--------| +| EF-20 | Every store operation shall run through a Polly pipeline with a configurable timeout (default 30 s), retry (default 3 attempts, exponential backoff with jitter, 1 s base, 30 s cap) and circuit breaker (5 failures, 30 s break, 2 successes to close). Each stage can be switched off. | Implemented | [DatabaseResiliencePolicy.cs](../../src/SourceFlow.Stores.EntityFramework/Services/DatabaseResiliencePolicy.cs), [ResilienceOptions.cs](../../src/SourceFlow.Stores.EntityFramework/Options/ResilienceOptions.cs) | +| EF-21 | Retries shall cover transient failures only. A constraint violation (such as a duplicate `(EntityId, SequenceNo)`) shall not be retried. | Partial — the retry predicate includes every `DbUpdateException`, constraint violations included ([GAP-05](06-Gaps-Risks-and-Open-Questions.md#gap-05)) | `DatabaseResiliencePolicy` | +| EF-22 | Store operations shall emit OpenTelemetry spans (`sourceflow.ef.*`) and metrics. SQL text shall be left out of traces by default (`IncludeSqlInTraces = false`). | Implemented | [DatabaseTelemetryService.cs](../../src/SourceFlow.Stores.EntityFramework/Services/DatabaseTelemetryService.cs), [ObservabilityOptions.cs](../../src/SourceFlow.Stores.EntityFramework/Options/ObservabilityOptions.cs) | + +## 4. Idempotency store (cloud support) + +| ID | Requirement | Status | Source | +|----|-------------|--------|--------| +| EF-30 | `AddSourceFlowIdempotency(connectionString, cleanupIntervalMinutes = 60)` shall register a SQL Server–backed `IIdempotencyService` that several service instances can share. | Implemented | [EfIdempotencyService.cs](../../src/SourceFlow.Stores.EntityFramework/Services/EfIdempotencyService.cs) | +| EF-31 | `AddSourceFlowIdempotencyWithCustomProvider(configure, interval)` shall support any EF provider for the idempotency table. | Implemented | `ServiceCollectionExtensions` | +| EF-32 | The idempotency table shall be keyed on `IdempotencyKey` and indexed on `ExpiresAt`. `HasProcessed` shall ignore expired records. | Implemented | [IdempotencyDbContext.cs](../../src/SourceFlow.Stores.EntityFramework/IdempotencyDbContext.cs) | +| EF-33 | `MarkAsProcessed` shall be an upsert. A concurrent insert of the same key by another instance shall be treated as success, not as an error. | Implemented | `EfIdempotencyService.MarkAsProcessedAsync` | +| EF-34 | A hosted cleanup service shall delete expired idempotency records on the configured interval, in batches of up to 1,000. | Implemented | [IdempotencyCleanupService.cs](../../src/SourceFlow.Stores.EntityFramework/Services/IdempotencyCleanupService.cs) | +| EF-35 | The core package shall be able to turn on EF idempotency without a compile-time reference (`IdempotencyConfigurationBuilder.UseEFIdempotency`), and shall fail with an install hint when the EF package is missing. | Implemented — through reflection | [IdempotencyConfigurationBuilder.cs](../../src/SourceFlow/Cloud/Configuration/IdempotencyConfigurationBuilder.cs) | + +--- + +## Acceptance scenarios (persistence) + +From [`tests/SourceFlow.Stores.EntityFramework.Tests`](../../tests/SourceFlow.Stores.EntityFramework.Tests), run on SQLite. + +1. **Ordering.** When commands with sequence numbers 1..N are appended for entity X, `Load(X)` returns exactly those N, in order, and none for other entities. +2. **Uniqueness.** When a second command is appended with the same `(EntityId, SequenceNo)`, the append fails and no duplicate row exists. +3. **Upsert.** When `Persist` is called on an entity whose id already exists, the row is updated, not duplicated. +4. **End to end.** The bank-account scenario from [doc 02](02-Core-Framework-Requirements.md#acceptance-scenarios-core) passes with all three stores backed by EF, including replay. +5. **Idempotency.** After `MarkAsProcessed(k, ttl)`, `HasProcessed(k)` returns true until `ttl` passes and false afterwards. Cleanup removes the expired row. diff --git a/docs/product/04-Cloud-Messaging-Requirements.md b/docs/product/04-Cloud-Messaging-Requirements.md new file mode 100644 index 00000000..7bf76ee6 --- /dev/null +++ b/docs/product/04-Cloud-Messaging-Requirements.md @@ -0,0 +1,143 @@ +# 04 — Cloud Messaging Requirements + +This document covers the cloud abstractions in the core package ([`src/SourceFlow/Cloud`](../../src/SourceFlow/Cloud)) and the two providers, [`SourceFlow.Cloud.AWS`](../../src/SourceFlow.Cloud.AWS) and [`SourceFlow.Cloud.GCP`](../../src/SourceFlow.Cloud.GCP). The status legend is in the [README](README.md#status-values). + +--- + +## 1. Concept + +A service talks to other bounded contexts through four kinds of route, declared once at startup: + +| Direction | Builder call | Meaning | AWS resource | GCP resource | +|-----------|--------------|---------|--------------|--------------| +| Outbound command | `.Send.Command(q => q.Queue("orders.fifo"))` | Commands of type T go to this queue | SQS queue | Pub/Sub topic | +| Outbound event | `.Raise.Event(t => t.Topic("order-events"))` | Events of type T go to this topic | SNS topic | Pub/Sub topic | +| Inbound commands | `.Listen.To.CommandQueue("orders.fifo")` | This service handles commands arriving here | SQS queue (polled) | Pull subscription `orders.fifo-sub` | +| Inbound events | `.Subscribe.To.Topic("payment-events")` | This service handles events from this topic | SNS→SQS subscription on the **first** listen queue | Pull subscription `payment-events-sub` | + +Cloud dispatchers run **alongside** the local dispatchers (EXT-04). A routed command is sent to the cloud **and** handled by any matching local saga. This "hybrid" behaviour is intended and documented in [Architecture 04](../legacy-version/Architecture/04-Current-Dispatching-Patterns.md#hybrid-processing-pattern). A message type with no route is skipped by the cloud dispatcher. + +--- + +## 2. Bus configuration and bootstrapping (`BUS`) + +| ID | Requirement | Status | Source | +|----|-------------|--------|--------| +| BUS-01 | One provider-neutral fluent builder (`BusConfigurationBuilder`) shall declare all four kinds of route, and every provider shall consume it. | Implemented | [BusConfiguration.cs](../../src/SourceFlow/Cloud/Configuration/BusConfiguration.cs) | +| BUS-02 | Routes shall take **short names only**. The builder shall reject empty names, URLs (`http(s)://…`) and ARNs (`arn:…`) with an error that shows the expected form. | Implemented | `CommandEndpointBuilder.Queue`, `EventEndpointBuilder.Topic`, `ListenToConfigurationBuilder`, `SubscribeToConfigurationBuilder` | +| BUS-03 | Routing lookups (`ShouldRoute`, `GetQueueName`, `GetTopicName`, listening queues, subscribed topics) shall throw a clear error if called before bootstrapping. | Implemented | `BusConfiguration.EnsureResolved` | +| BUS-04 | Asking for the queue or topic of an unrouted type shall throw an error that shows the builder call needed to fix it. | Implemented | same | +| BUS-05 | Each provider shall register a bootstrapper as a hosted service, **before** its listeners, that resolves every short name to a full resource id and creates any missing resource (get-or-create, safe to repeat). | Implemented | [AwsBusBootstrapper.cs](../../src/SourceFlow.Cloud.AWS/Infrastructure/AwsBusBootstrapper.cs), [GcpBusBootstrapper.cs](../../src/SourceFlow.Cloud.GCP/Infrastructure/GcpBusBootstrapper.cs) | +| BUS-06 | Bootstrapping shall fail fast on configuration that cannot work: on AWS, subscribing to topics with no listen queue; on GCP, a missing `ProjectId`. | Implemented | bootstrappers | +| BUS-07 | Teams that manage infrastructure as code shall be able to switch off automatic resource creation (validate only). | Planned / not implemented ([GAP-12](06-Gaps-Risks-and-Open-Questions.md#gap-12)) | — | + +## 3. Idempotency (`IDM`) + +| ID | Requirement | Status | Source | +|----|-------------|--------|--------| +| IDM-01 | The core shall define `IIdempotencyService` with `HasProcessed`, `MarkAsProcessed(key, ttl)`, `Remove` and `GetStatistics`. | Implemented | [IIdempotencyService.cs](../../src/SourceFlow/Cloud/Configuration/IIdempotencyService.cs) | +| IDM-02 | An in-memory implementation with TTL expiry and a cleanup service that runs every minute shall be the default when nothing else is configured. | Implemented | [InMemoryIdempotencyService.cs](../../src/SourceFlow/Cloud/Configuration/InMemoryIdempotencyService.cs) | +| IDM-03 | `IdempotencyConfigurationBuilder` shall offer `UseInMemory()`, `UseEFIdempotency(cs, interval)`, `UseCustom()` and `UseCustom(factory)`, and each provider's registration call shall accept it. | Implemented | [IdempotencyConfigurationBuilder.cs](../../src/SourceFlow/Cloud/Configuration/IdempotencyConfigurationBuilder.cs) | +| IDM-04 | Every inbound listener shall check the idempotency service **before** handling a message, mark the message processed (24 h TTL) **after** handling it successfully, and acknowledge and drop duplicates. | Partial — only the AWS `*Enhanced` listeners do this, and they are not registered by default. The default AWS listeners and the GCP listeners never consult the idempotency service, even though it is registered ([GAP-01](06-Gaps-Risks-and-Open-Questions.md#gap-01)) | [AwsSqsCommandListenerEnhanced.cs](../../src/SourceFlow.Cloud.AWS/Messaging/Commands/AwsSqsCommandListenerEnhanced.cs) | +| IDM-05 | The idempotency key shall identify the **logical message**, not one transport delivery, so that a producer retry is also caught. | Partial — the key is `"{type}:{transport MessageId}"`. `Metadata.EventId` (a GUID set when the message is created) would identify the logical message ([GAP-09](06-Gaps-Risks-and-Open-Questions.md#gap-09)) | same | + +## 4. Dead-letter handling (`DLQ`) + +| ID | Requirement | Status | Source | +|----|-------------|--------|--------| +| DLQ-01 | The core shall define a provider-neutral `DeadLetterRecord` (message id, body, type, reason, error, source, provider, delivery count, exception details, metadata, replay state), plus `IDeadLetterStore` with save, get, query (filter and page), count, mark-replayed, delete and purge-older-than. | Implemented | [DeadLetter/](../../src/SourceFlow/Cloud/DeadLetter) | +| DLQ-02 | An in-memory `IDeadLetterStore` shall be provided. | Implemented — but not registered by any provider ([GAP-01](06-Gaps-Risks-and-Open-Questions.md#gap-01)) | [InMemoryDeadLetterStore.cs](../../src/SourceFlow/Cloud/DeadLetter/InMemoryDeadLetterStore.cs) | +| DLQ-03 | Listeners shall write a dead-letter record when a message is missing its type attribute, names a type that cannot be resolved, fails to deserialise, or fails processing after more than 3 deliveries. | Opt-in (AWS `*Enhanced` listeners only) | `AwsSqsCommandListenerEnhanced.CreateDeadLetterRecord` | +| DLQ-04 | A background monitor shall poll the configured dead-letter queues (every 60 s by default), record their messages, raise alerts above a threshold (default 10), and support filtered replay back to the source queue. | Opt-in (AWS only; not registered) | [AwsDeadLetterMonitor.cs](../../src/SourceFlow.Cloud.AWS/Monitoring/AwsDeadLetterMonitor.cs) | +| DLQ-05 | `IDeadLetterProcessor` (process, replay with a filter, statistics) shall have at least one implementation per provider. | Not implemented — the interface has no implementation ([GAP-11](06-Gaps-Risks-and-Open-Questions.md#gap-11)) | [IDeadLetterProcessor.cs](../../src/SourceFlow/Cloud/DeadLetter/IDeadLetterProcessor.cs) | +| DLQ-06 | Bootstrapping shall be able to set up native dead-letter routing (SQS redrive policy, Pub/Sub dead-letter topic). | Not implemented ([GAP-11](06-Gaps-Risks-and-Open-Questions.md#gap-11)) | — | +| DLQ-07 | Messages that can never succeed ("poison" messages: unknown type, bad JSON) shall not be redelivered forever. | Implemented — the default listeners delete or acknowledge them after logging. Without the opt-in AWS listeners, no dead-letter record is kept | listeners | + +## 5. Resilience (`RES`) + +| ID | Requirement | Status | Source | +|----|-------------|--------|--------| +| RES-01 | The core shall provide a circuit breaker (Closed → Open → HalfOpen) with failure threshold (default 5), open duration (1 min), success threshold to close (2), operation timeout (30 s), handled and ignored exception lists, state-change events, manual `Trip` and `Reset`, and statistics. | Implemented | [CircuitBreaker.cs](../../src/SourceFlow/Cloud/Resilience/CircuitBreaker.cs), [CircuitBreakerOptions.cs](../../src/SourceFlow/Cloud/Resilience/CircuitBreakerOptions.cs) | +| RES-02 | Outbound cloud dispatchers shall run through the circuit breaker and throw `CircuitBreakerOpenException` while it is open. | Opt-in (AWS `*Enhanced` dispatchers only) | [AwsSqsCommandDispatcherEnhanced.cs](../../src/SourceFlow.Cloud.AWS/Messaging/Commands/AwsSqsCommandDispatcherEnhanced.cs) | +| RES-03 | Listener poll loops shall survive transport errors, backing off exponentially (2ⁿ s, capped at 60 s), and reset after a successful receive. | Implemented (AWS and GCP) | listeners | +| RES-04 | Messages that fail during processing shall **not** be acknowledged, so the transport redelivers them (SQS after the visibility timeout, Pub/Sub after the ack deadline). | Implemented | listeners | +| RES-05 | The SDK retry settings in provider options (`MaxRetries`, `RetryDelay`) shall be applied to the cloud clients. | Not implemented — the options are not applied ([GAP-03](06-Gaps-Risks-and-Open-Questions.md#gap-03)) | `AwsOptions`, `GcpOptions` | + +## 6. Message security (`SEC`) + +| ID | Requirement | Status | Source | +|----|-------------|--------|--------| +| SEC-01 | The core shall define `IMessageEncryption` (`EncryptAsync`, `DecryptAsync`, `AlgorithmName`, `KeyIdentifier`), `EncryptionOptions`, and `MessageDecryptionException`. | Implemented | [Security/](../../src/SourceFlow/Cloud/Security) | +| SEC-02 | Each provider shall implement **envelope encryption**: a data key from the provider's KMS, AES-256-GCM over the message body, and a JSON envelope (wrapped key, nonce, tag, ciphertext). Data keys shall be cached (300 s by default; 0 turns caching off). | Implemented (AWS KMS, GCP Cloud KMS) | [AwsKmsMessageEncryption.cs](../../src/SourceFlow.Cloud.AWS/Security/AwsKmsMessageEncryption.cs), [GcpKmsMessageEncryption.cs](../../src/SourceFlow.Cloud.GCP/Security/GcpKmsMessageEncryption.cs) | +| SEC-03 | When an `IMessageEncryption` is registered, dispatchers shall encrypt outbound bodies and listeners shall decrypt inbound bodies. | Opt-in (AWS `*Enhanced` only); not wired on GCP ([GAP-01](06-Gaps-Risks-and-Open-Questions.md#gap-01)) | — | +| SEC-04 | Properties marked `[SensitiveData(type)]` shall be masked in logs, by type: credit card, email, phone, SSN, personal name, IP address, password, API key, or custom. Masking shall be lazy, so values are formatted only when the log line is written. | Implemented (utility); used by AWS `*Enhanced` only | [SensitiveDataMasker.cs](../../src/SourceFlow/Cloud/Security/SensitiveDataMasker.cs) | +| SEC-05 | Credentials shall come from the provider SDK's standard credential chain. Credential fields in configuration shall be marked obsolete. | Implemented (AWS: `AccessKeyId`, `SecretAccessKey`, `SessionToken` are `[Obsolete]`; GCP: Application Default Credentials) | [AwsOptions.cs](../../src/SourceFlow.Cloud.AWS/Configuration/AwsOptions.cs) | +| SEC-06 | Wire messages shall not let a remote sender instantiate arbitrary types. | Partial — listeners resolve types from the assembly-qualified name in the message attributes, with no allow-list. Only types routed in the bus configuration should be accepted ([GAP-10](06-Gaps-Risks-and-Open-Questions.md#gap-10)) | listeners | + +## 7. Cloud telemetry and health (`CTL`) + +| ID | Requirement | Status | Source | +|----|-------------|--------|--------| +| CTL-01 | The core shall provide a `SourceFlow.Cloud` ActivitySource and semantic-convention constants (`messaging.*`, `sourceflow.*`, `cloud.*`). | Implemented | [CloudActivitySource.cs](../../src/SourceFlow/Cloud/Observability/CloudActivitySource.cs) | +| CTL-02 | The core shall provide `CloudMetrics`: counters for commands dispatched, processed, succeeded and failed, events published and received, and duplicates detected; histograms for dispatch, processing and publish duration and message size; gauges for queue depth, DLQ depth and active processors. | Implemented (utility); recorded by AWS `*Enhanced` only | [CloudMetrics.cs](../../src/SourceFlow/Cloud/Observability/CloudMetrics.cs) | +| CTL-03 | Trace context (`traceparent`) shall travel with messages so that one trace covers the sending and receiving services. | Partial — the AWS enhanced components read and write `traceparent`; the default AWS components and the GCP components do not | `AwsSqsCommandListenerEnhanced.ExtractTraceParent` | +| CTL-04 | Each provider shall register an `IHealthCheck` that checks the messaging endpoint can be reached. | Implemented (AWS: SQS and SNS; GCP: Pub/Sub) | [AwsHealthCheck.cs](../../src/SourceFlow.Cloud.AWS/Infrastructure/AwsHealthCheck.cs), [GcpHealthCheck.cs](../../src/SourceFlow.Cloud.GCP/Infrastructure/GcpHealthCheck.cs) | + +--- + +## 8. AWS provider (`AWS`) — `SourceFlow.Cloud.AWS` 2.0.0 + +| ID | Requirement | Status | Source | +|----|-------------|--------|--------| +| AWS-01 | `services.UseSourceFlowAws(configureOptions, configureBus, configureIdempotency?)` shall register options, SQS and SNS clients, bus configuration, idempotency, dispatchers, bootstrapper, listeners and health check. | Implemented | [IocExtensions.cs](../../src/SourceFlow.Cloud.AWS/IocExtensions.cs) | +| AWS-02 | `AwsOptions.Region` shall select the region for every AWS client. | **Not implemented** — the clients come from `AddAWSService()` (SDK default config), and the factories that would apply `Region` and `MaxRetries` are never called ([GAP-03](06-Gaps-Risks-and-Open-Questions.md#gap-03)) | [SqsClientFactory.cs](../../src/SourceFlow.Cloud.AWS/Infrastructure/SqsClientFactory.cs) | +| AWS-03 | `EnableCommandRouting` and `EnableEventRouting` shall switch outbound routing on or off. | Not implemented — the options exist but nothing reads them ([GAP-03](06-Gaps-Risks-and-Open-Questions.md#gap-03)) | `AwsOptions` | +| AWS-04 | The bootstrapper shall get or create every SQS queue. A name ending in `.fifo` shall create a FIFO queue with content-based deduplication. | Implemented | `AwsBusBootstrapper.GetOrCreateQueueAsync` | +| AWS-05 | The bootstrapper shall create the SNS topics and subscribe each subscribed topic to the **first** listen queue. | Partial — subscriptions are created without `RawMessageDelivery`, although the docs say it is set; events and commands then share one queue ([GAP-02](06-Gaps-Risks-and-Open-Questions.md#gap-02)) | `AwsBusBootstrapper` | +| AWS-06 | The command dispatcher shall send camelCase JSON with the attributes `CommandType` (assembly-qualified name), `EntityId` and `SequenceNo`, using `MessageGroupId = EntityId` so that FIFO queues keep per-entity order. | Implemented | [AwsSqsCommandDispatcher.cs](../../src/SourceFlow.Cloud.AWS/Messaging/Commands/AwsSqsCommandDispatcher.cs) | +| AWS-07 | The event dispatcher shall publish camelCase JSON to SNS with the attributes `EventType` and `EventName`, and the subject set to the event name. | Implemented | [AwsSnsEventDispatcher.cs](../../src/SourceFlow.Cloud.AWS/Messaging/Events/AwsSnsEventDispatcher.cs) | +| AWS-08 | Listeners shall long-poll each queue in its own loop (wait 20 s, up to 10 messages, 300 s visibility timeout, all configurable), handle each message in a new DI scope, and delete it after it succeeds. | Implemented | [AwsSqsCommandListener.cs](../../src/SourceFlow.Cloud.AWS/Messaging/Commands/AwsSqsCommandListener.cs), [AwsSnsEventListener.cs](../../src/SourceFlow.Cloud.AWS/Messaging/Events/AwsSnsEventListener.cs) | +| AWS-09 | The event listener shall unwrap the SNS notification envelope before deserialising the event, and deliver the event to every `IEventSubscriber`. | Implemented | `AwsSnsEventListener.ProcessMessage` | +| AWS-10 | The provider shall offer a production pipeline (idempotency, dead-letter records, KMS decryption, circuit breaker, metrics, trace propagation, masked logging) **selectable through the registration API**. | Opt-in — the `*Enhanced` classes exist but `UseSourceFlowAws` has no switch for them ([GAP-01](06-Gaps-Risks-and-Open-Questions.md#gap-01)) | `Messaging/*/*Enhanced.cs` | +| AWS-11 | The provider shall be tested against LocalStack (unit and integration categories) in CI. | Implemented | [Master-Build.yml](../../.github/workflows/Master-Build.yml), `tests/SourceFlow.Cloud.AWS.Tests` | + +## 9. GCP provider (`GCP`) — `SourceFlow.Cloud.GCP` 2.0.0-beta.1 + +| ID | Requirement | Status | Source | +|----|-------------|--------|--------| +| GCP-01 | `services.UseSourceFlowGcp(configureOptions, configureBus, configureIdempotency?)` shall register Pub/Sub publisher and subscriber clients, bus configuration, idempotency, dispatchers, bootstrapper, listeners (each can be switched off with `EnableCommandListener` / `EnableEventListener`) and health check. | Implemented | [IocExtensions.cs](../../src/SourceFlow.Cloud.GCP/IocExtensions.cs) | +| GCP-02 | Clients shall pick up the Pub/Sub emulator automatically when `PUBSUB_EMULATOR_HOST` is set. | Implemented | [PubSubClientFactory.cs](../../src/SourceFlow.Cloud.GCP/Infrastructure/PubSubClientFactory.cs) | +| GCP-03 | The bootstrapper shall make sure that a topic exists for every command queue name and event topic name, and that a pull subscription named `{name}{SubscriptionSuffix}` (default `-sub`) exists for every listen queue and subscribed topic, using the configured ack deadline (default 60 s). | Implemented | [GcpBusBootstrapper.cs](../../src/SourceFlow.Cloud.GCP/Infrastructure/GcpBusBootstrapper.cs) | +| GCP-04 | Each service subscribing to a topic shall get its own copy of every event (fan-out). | Partial — the subscription name comes only from the topic name and suffix, so two services with the default suffix **share** one subscription and compete for events ([GAP-13](06-Gaps-Risks-and-Open-Questions.md#gap-13)) | `GcpBusBootstrapper.SubscriptionId` | +| GCP-05 | Commands shall be published with `OrderingKey = EntityId` and delivered in order per entity. | Partial — the ordering key is set, but subscriptions are not created with message ordering enabled, so order is not guaranteed ([GAP-13](06-Gaps-Risks-and-Open-Questions.md#gap-13)) | [PubSubCommandDispatcher.cs](../../src/SourceFlow.Cloud.GCP/Messaging/Commands/PubSubCommandDispatcher.cs) | +| GCP-06 | Listeners shall pull up to `MaxMessagesPerPull` (default 10), wait `EmptyPullDelay` (1 s) when nothing arrives, acknowledge on success or poison message, and leave failures unacknowledged so they are redelivered. | Implemented | [PubSubCommandListener.cs](../../src/SourceFlow.Cloud.GCP/Messaging/Commands/PubSubCommandListener.cs), [PubSubEventListener.cs](../../src/SourceFlow.Cloud.GCP/Messaging/Events/PubSubEventListener.cs) | +| GCP-07 | The provider shall reach feature parity with AWS on idempotency, dead letters, encryption wiring, circuit breaker and trace propagation before it leaves beta. | Not met ([GAP-01](06-Gaps-Risks-and-Open-Questions.md#gap-01)) | — | +| GCP-08 | The provider shall be tested against the Pub/Sub emulator in CI. | Implemented | [GCP-Build.yml](../../.github/workflows/GCP-Build.yml) | + +## 10. Provider parity matrix + +| Capability | AWS (default wiring) | AWS (`*Enhanced`, manual wiring) | GCP | +|------------|:---:|:---:|:---:| +| Route, send and publish | ✔ | ✔ | ✔ | +| Auto-provision resources | ✔ | ✔ | ✔ | +| Per-entity ordering | ✔ (FIFO queues) | ✔ | ✘ (ordering not enabled on subscriptions) | +| Idempotent receive | ✘ | ✔ | ✘ | +| Dead-letter records | ✘ | ✔ | ✘ | +| Envelope encryption | ✘ | ✔ | ✘ (class exists, not wired) | +| Circuit breaker on send | ✘ | ✔ | ✘ | +| Cloud metrics and trace propagation | ✘ | ✔ | ✘ | +| Health check | ✔ | ✔ | ✔ | +| Emulator / local CI | LocalStack | LocalStack | Pub/Sub emulator | +| Azure Service Bus | — | — | — (Planned as a separate provider) | + +--- + +## Acceptance scenarios (cloud) + +1. **Config validation.** `.Send.Command(q => q.Queue("https://…"))` throws `ArgumentException` at startup and names the expected short form. +2. **Bootstrap.** On an empty LocalStack, or the Pub/Sub emulator, startup creates every declared queue, topic and subscription. Starting again creates nothing new and succeeds. +3. **Command round-trip.** Service A routes `CreateOrder` to `orders.fifo`. Service B listens there. Publishing in A leads to B's `OrderSaga` handling the command exactly once, and the message is deleted or acknowledged. +4. **Event fan-out.** Services B and C both subscribe to `order-events`. An event raised in A reaches B's views **and** C's views. (This fails today on GCP with the default suffix — GAP-13.) +5. **Poison message.** A message with an unknown `CommandType` is logged and removed, and is not redelivered. +6. **Transient failure.** A saga that throws once leaves the message unacknowledged. It is redelivered after the visibility timeout or ack deadline, and handled once. +7. **Duplicate.** With idempotency wired, the same transport message delivered twice is handled once, and `sourceflow.duplicates.detected` goes up. diff --git a/docs/product/05-Non-Functional-Requirements.md b/docs/product/05-Non-Functional-Requirements.md new file mode 100644 index 00000000..b87302f0 --- /dev/null +++ b/docs/product/05-Non-Functional-Requirements.md @@ -0,0 +1,89 @@ +# 05 — Non-Functional Requirements + +The status legend is in the [README](README.md#status-values). Where a requirement is about a guarantee, the **Current behaviour** column says what the code actually provides today, because the difference matters to anyone designing on top of it. + +--- + +## 1. Compatibility and platform (`NFR-CMP`) + +| ID | Requirement | Status / current behaviour | +|----|-------------|----------------------------| +| NFR-CMP-01 | The core package shall target .NET Standard 2.0 and 2.1 and .NET 8, 9 and 10, so that .NET Framework 4.6.2+ and modern .NET can both use it. | Implemented ([SourceFlow.csproj](../../src/SourceFlow/SourceFlow.csproj)). The README badge still lists .NET Framework 4.6.2 for v1 | +| NFR-CMP-02 | The EF package shall target .NET 8, 9 and 10. | Implemented. The README badges also claim .NET Standard 2.0/2.1 for this package, which the csproj does not target ([GAP-18](06-Gaps-Risks-and-Open-Questions.md#gap-18)) | +| NFR-CMP-03 | The AWS package shall target .NET Standard 2.1 and .NET 8, 9 and 10; the GCP package shall target .NET 8, 9 and 10. | Implemented | +| NFR-CMP-04 | Packages shall integrate with `Microsoft.Extensions.*` (DependencyInjection, Logging, Hosting, Options, HealthChecks) and add no other container or logging framework. | Implemented | +| NFR-CMP-05 | Breaking API or namespace changes shall only ship in a major version, with a migration guide in the changelog. | Implemented for v2.0.0 (Cloud.Core → `SourceFlow.Cloud.*`; see the [changelog](../legacy-version/Versions/v2.0.0/CHANGELOG.md)) | +| NFR-CMP-06 | Stored commands shall stay readable after commands or payloads are renamed, moved or given a new assembly version. | **Not met.** Types are stored and resolved by assembly-qualified name, and commands that fail to load are skipped silently ([GAP-04](06-Gaps-Risks-and-Open-Questions.md#gap-04)) | + +## 2. Delivery and consistency guarantees (`NFR-REL`) + +| ID | Requirement | Current behaviour | +|----|-------------|-------------------| +| NFR-REL-01 | **Per-entity ordering.** Commands for one entity shall be handled and logged in the order they were sent. | In-process: yes, provided callers do not publish concurrently for the same entity. AWS: yes with FIFO queues (`MessageGroupId = EntityId`). GCP: **not guaranteed** (GAP-13) | +| NFR-REL-02 | **Per-entity sequence integrity.** Concurrent writers to one entity shall never both apply a change. One shall win and the other shall be rejected **before** side effects. | **Partial.** The EF unique index rejects the second append, but only **after** its saga has already changed and persisted the entity and raised events ([GAP-05](06-Gaps-Risks-and-Open-Questions.md#gap-05)) | +| NFR-REL-03 | **Atomicity.** Persisting the entity and appending the command shall commit or fail together. Events shall be published only after the commit (outbox pattern or equivalent). | **Not met.** The order is: saga persists the entity → event raised → bus appends the command, each step separate. A failure partway leaves them inconsistent (GAP-05) | +| NFR-REL-04 | **Cloud delivery.** Inbound messages shall be processed at least once, and handlers shall see each logical message effectively once. | At-least-once: yes (ack/delete only after success). Effectively-once: only with the opt-in AWS enhanced listeners (GAP-01), and only per transport message id (GAP-09) | +| NFR-REL-05 | **Replay safety.** Replay shall have no external side effects: no cloud publishes and no new commands logged. | **Not met.** Cloud dispatchers do not check `IsReplay`, and commands published from sagas during replay are new, non-replay commands ([GAP-06](06-Gaps-Risks-and-Open-Questions.md#gap-06)) | +| NFR-REL-06 | **Failure visibility.** No failure on the main path shall be swallowed silently. | **Partial.** Saga event-raising errors are logged and swallowed (GAP-07). Command deserialisation errors are swallowed without a log (GAP-04). The AWS event listener carries on when one subscriber throws synchronously | +| NFR-REL-07 | **Graceful shutdown.** Listeners shall stop polling when the host is cancelled, and messages in flight shall go back to the transport rather than being lost. | Implemented. Cancellation ends the loops, and messages not yet acknowledged are redelivered | + +## 3. Security (`NFR-SEC`) + +| ID | Requirement | Status / current behaviour | +|----|-------------|----------------------------| +| NFR-SEC-01 | No secrets in configuration. Cloud credentials shall come from the SDK credential chain or workload identity. | Implemented (SEC-05) | +| NFR-SEC-02 | Message bodies in transit and at rest in the broker shall be encryptable with customer-managed KMS keys using authenticated encryption (AES-256-GCM). | Implemented as components; wired only through the opt-in AWS enhanced pipeline (SEC-03) | +| NFR-SEC-03 | PII and secrets marked `[SensitiveData]` shall never appear unmasked in logs written by the framework. | Partial. Masking exists, but the default dispatchers and listeners do not use it. They log type names and ids, not payloads | +| NFR-SEC-04 | Deserialising inbound messages shall be restricted to the message types declared in the bus configuration. | **Not met** ([GAP-10](06-Gaps-Risks-and-Open-Questions.md#gap-10)) | +| NFR-SEC-05 | SQL text and parameter values shall be left out of telemetry by default. | Implemented (`IncludeSqlInTraces = false`) | +| NFR-SEC-06 | The repository shall run static security analysis on master and release branches. | Implemented (CodeQL workflows), with a [SECURITY.md](../../SECURITY.md) disclosure policy | + +## 4. Performance and scalability (`NFR-PERF`) + +| ID | Requirement | Status / current behaviour | +|----|-------------|----------------------------| +| NFR-PERF-01 | Fan-out to sagas, views and dispatchers shall run concurrently. | Implemented (`Task.WhenAll`, `TaskBufferPool`) | +| NFR-PERF-02 | Serialisation on the hot path shall reuse pooled buffers. | Implemented (`ByteArrayPool`) | +| NFR-PERF-03 | Assigning the next sequence number shall cost O(1) with respect to the entity's history length. | **Not met.** Each command loads and deserialises the entity's whole history to find the highest sequence number (`CommandStoreAdapter.GetNextSequenceNo`). Cost grows linearly with history length ([GAP-05](06-Gaps-Risks-and-Open-Questions.md#gap-05)) | +| NFR-PERF-04 | Reflection used for dispatch shall be cached per type. | Implemented in the cloud listeners (`_typeCache`, `_methodInfoCache`). Saga event raising and replay use reflection without a cache | +| NFR-PERF-05 | Telemetry shall cost close to nothing when switched off. | Implemented (domain telemetry is off by default; the store adapters skip tracing when no telemetry service is present) | +| NFR-PERF-06 | Cloud listeners shall scale out horizontally (competing consumers) with no coordination beyond the broker. | Implemented for commands. For events on AWS, all instances of a service share one queue, which is correct. Shared idempotency needs the EF backend (IDM-03) | +| NFR-PERF-07 | Message size shall be checked against the target broker's limit (for example, SNS 256 KB, Pub/Sub 10 MB) before sending, with a clear error. | Not enforced. `EncryptionOptions.MaxMessageSize` (256 KB) is defined but never checked | + +## 5. Observability and operability (`NFR-OPS`) + +| ID | Requirement | Status / current behaviour | +|----|-------------|----------------------------| +| NFR-OPS-01 | Every pipeline stage shall be traceable with OpenTelemetry and exportable over OTLP. | Implemented (OBS-02..05) | +| NFR-OPS-02 | One distributed trace shall cover sender and receiver across a cloud hop. | Partial (CTL-03) | +| NFR-OPS-03 | Each cloud provider shall expose a standard ASP.NET Core health check. | Implemented (CTL-04) | +| NFR-OPS-04 | Startup shall fail fast, with a clear message, on invalid routing or provider configuration. | Implemented (BUS-02, BUS-04, BUS-06). Exception: provider options that are silently ignored (GAP-03) | +| NFR-OPS-05 | Logs shall be structured (message templates with named properties) and use a consistent `Action=` vocabulary. | Implemented. Some messages are copied from elsewhere and misleading, for example the projection subscriber logging "No Sagas Found" ([GAP-14](06-Gaps-Risks-and-Open-Questions.md#gap-14)) | +| NFR-OPS-06 | Operators shall be able to inspect and replay dead-lettered messages. | Partial — only through the opt-in AWS monitor; no `IDeadLetterProcessor` implementation (GAP-11) | + +## 6. Testability (`NFR-TST`) + +| ID | Requirement | Status / current behaviour | +|----|-------------|----------------------------| +| NFR-TST-01 | Every framework seam shall be an interface that can be replaced through DI, including the store adapters. | Implemented (STO-05) | +| NFR-TST-02 | The repository shall ship an end-to-end reference scenario that runs in memory, and the same scenario on EF. | Implemented (bank-account E2E in Core.Tests and Stores.EntityFramework.Tests) | +| NFR-TST-03 | Cloud providers shall have unit tests with no external dependencies, plus integration tests against local emulators (LocalStack, the Pub/Sub emulator), split by `Category` trait. | Implemented. AWS: about 80 test files covering unit, integration, performance and security. GCP: about 8 files (beta) | +| NFR-TST-04 | CI shall run unit tests on every push to master and integration tests against the emulators. | Implemented ([Master-Build.yml](../../.github/workflows/Master-Build.yml), [GCP-Build.yml](../../.github/workflows/GCP-Build.yml)) | +| NFR-TST-05 | Duplicated code shall be tracked. | Configured ([.jscpd.json](../../.jscpd.json)). The basic and `*Enhanced` AWS classes are near-copies of each other | + +## 7. Packaging, versioning and release (`NFR-RE`) + +| ID | Requirement | Status / current behaviour | +|----|-------------|----------------------------| +| NFR-RE-01 | Versions shall follow SemVer and be computed by GitVersion from the branch: master is stable; `release/*` gets a `beta` tag; `develop` gets `beta`; `pre-release/*` gets `alpha`; PRs get `PullRequest.N`. | Implemented ([GitVersion.yml](../../GitVersion.yml)) | +| NFR-RE-02 | Packages shall be published only from an explicit `release-packages` tag. Branch builds produce pre-release versions only. | Implemented (Release-CI). Publishing to NuGet.org is currently switched off; packages go to GitHub Packages | +| NFR-RE-03 | Each package's csproj shall carry an accurate `Description`, used as the NuGet listing. | Partial — the core description says ".NET 9.0 and .NET 10.0" and leaves out .NET 8. The EF description says "SQL Server support", although any provider works (EF-13) | +| NFR-RE-04 | Each release shall have a changelog under `docs/Versions//`. | Implemented for v1.0.0 and v2.0.0. The v2.0.0 changelog still says "Release Date: TBC", while the README says 15 Mar 2026 | + +## 8. Documentation (`NFR-DOC`) + +| ID | Requirement | Status / current behaviour | +|----|-------------|----------------------------| +| NFR-DOC-01 | Each package shall have a README covering install, registration, configuration options and an end-to-end example. | Implemented (`docs/*-README.md`) | +| NFR-DOC-02 | Architecture docs shall describe the command flow, event flow, dispatching patterns, persistence and cloud architecture. | Implemented ([docs/Architecture](../legacy-version/Architecture)) | +| NFR-DOC-03 | Documentation shall match the code. | Partial — see [GAP-02](06-Gaps-Risks-and-Open-Questions.md#gap-02) (RawMessageDelivery), [GAP-03](06-Gaps-Risks-and-Open-Questions.md#gap-03) (Region), [GAP-18](06-Gaps-Risks-and-Open-Questions.md#gap-18) (target frameworks) | diff --git a/docs/product/06-Gaps-Risks-and-Open-Questions.md b/docs/product/06-Gaps-Risks-and-Open-Questions.md new file mode 100644 index 00000000..341187aa --- /dev/null +++ b/docs/product/06-Gaps-Risks-and-Open-Questions.md @@ -0,0 +1,231 @@ +# 06 — Gaps, Risks and Open Questions + +These findings came out of reading the code against the requirements in docs 02–05 and against the project's own documentation. Each one gives the **evidence** (where to look), the **impact**, and a **suggested change**. Items marked *verify* are strongly suggested by the code but have not been reproduced against a live environment. + +**Priority:** **P1** breaks correctness or a stated guarantee, or blocks production use. **P2** is a significant functional, operational or security shortfall. **P3** affects quality, accuracy or documentation. + +## Summary + +| ID | Title | Area | Priority | +|----|-------|------|----------| +| [GAP-01](#gap-01) | Production messaging pipeline is built but not wired | Cloud | P1 | +| [GAP-02](#gap-02) | AWS events and commands share one queue without raw delivery | AWS | P1 *(verify)* | +| [GAP-03](#gap-03) | Provider options that are silently ignored (incl. AWS Region) | Cloud | P1 | +| [GAP-04](#gap-04) | Command rebuild contract is implicit and failures are silent | Core | P1 | +| [GAP-05](#gap-05) | Sequence assignment is O(n), racy, and not atomic with side effects | Core / EF | P1 | +| [GAP-06](#gap-06) | Replay causes external side effects | Core / Cloud | P1 | +| [GAP-19](#gap-19) | Cloud-received commands are not logged by the owning service | Core / Cloud | P1 | +| [GAP-20](#gap-20) | New-entity commands are logged under id 0 unless the caller assigns an id | Core | P1 | +| [GAP-13](#gap-13) | GCP: shared subscriptions across services, no ordering, no hardening | GCP | P1 (for GA) | +| [GAP-07](#gap-07) | Saga event-raising failures are swallowed | Core | P2 | +| [GAP-08](#gap-08) | Singleton domain types capture Scoped dependencies | Core | P2 | +| [GAP-09](#gap-09) | Idempotency key is per delivery, not per logical message | Cloud | P2 | +| [GAP-10](#gap-10) | No allow-list for inbound message types | Cloud / Security | P2 | +| [GAP-11](#gap-11) | Dead-letter story is incomplete | Cloud | P2 | +| [GAP-12](#gap-12) | Auto-provisioning cannot be switched off | Cloud / Security | P2 | +| [GAP-14](#gap-14) | Metric and log inaccuracies | Observability | P3 | +| [GAP-15](#gap-15) | Store "not found" semantics are unspecified | Core | P3 | +| [GAP-16](#gap-16) | Assembly-scan fallback rethrows | Core | P3 | +| [GAP-17](#gap-17) | EF runtime type registration is process-global | EF | P3 | +| [GAP-18](#gap-18) | Documentation and package-metadata drift | Docs | P3 | + +--- + +## P1 findings + +### GAP-01 +**Production messaging pipeline is built but not wired.** *(IDM-04, DLQ-02..04, RES-02, SEC-03, CTL-02/03, AWS-10, GCP-07)* + +- **Evidence.** + - `UseSourceFlowAws` registers the basic `AwsSqsCommandDispatcher`, `AwsSnsEventDispatcher`, `AwsSqsCommandListener` and `AwsSnsEventListener` ([IocExtensions.cs](../../src/SourceFlow.Cloud.AWS/IocExtensions.cs)). + - The `*Enhanced` versions, which add idempotency, dead-letter records, decryption, circuit breaker, metrics, trace propagation and masked logging, are never registered. + - Nothing registers what the enhanced versions depend on: `IDeadLetterStore`, `ICircuitBreaker`, `CloudTelemetry`, `CloudMetrics`, `SensitiveDataMasker`, `IMessageEncryption`. `AwsDeadLetterMonitor` isn't registered either. + - `IIdempotencyService` **is** registered by both providers, but no default listener uses it. + - The GCP provider has no enhanced pipeline at all, and `GcpKmsMessageEncryption` is never wired. +- **Impact.** Users who follow the README and configure idempotency (for example `UseEFIdempotency`) believe they are protected against duplicates, but they are not. The AWS changelog lists these as features of the package. +- **Suggested change.** + 1. Merge the basic and enhanced classes into one implementation whose features switch on according to which services are registered (or through options). + 2. Have `UseSourceFlowAws` and `UseSourceFlowGcp` register safe defaults for every dependency: in-memory dead-letter store, a circuit breaker, telemetry and the masker. + 3. Add opt-in calls such as `.WithKmsEncryption(...)` and `.WithDeadLetterMonitor(...)`. + 4. Bring GCP to parity before GA. + +### GAP-02 +**AWS events and commands share one queue without raw delivery.** *(AWS-05)* — *verify* + +- **Evidence.** + - `AwsBusBootstrapper` subscribes every subscribed SNS topic to the **first** listen queue, and that same queue URL is used for both command listening and event listening. + - `SubscribeRequest` does not set `RawMessageDelivery`, although [SourceFlow.Cloud.AWS-README.md](../legacy-version/SourceFlow.Cloud.AWS-README.md) and [07-AWS-Cloud-Architecture.md](../legacy-version/Architecture/07-AWS-Cloud-Architecture.md) both show it as `true`. + - So `AwsSqsCommandListener` and `AwsSnsEventListener` poll the same queue. When the command listener gets an SNS envelope, it finds no `CommandType` attribute, logs an error and returns **without deleting** the message. When the event listener gets a command, it finds no `EventType` and does the same. +- **Impact.** + - Messages bounce between the two consumers. Each wrong pickup delays the message by the visibility timeout (300 s by default) and adds to its receive count. With a redrive policy, valid messages can end up dead-lettered. + - Error logs fill with false alarms. + - Separately, AWS only lets FIFO topics deliver to FIFO queues. The documented example (`orders.fifo` as the listen queue, `order-events` as the topic) may fail against real AWS even though LocalStack accepts it. +- **Suggested change.** Use a dedicated event queue per service (for example `{service}-events`), or teach a single listener to tell the two kinds of message apart and route them. Set `RawMessageDelivery` deliberately. Validate FIFO/standard compatibility when bootstrapping. + +### GAP-03 +**Provider options that are silently ignored.** *(RES-05, AWS-02, AWS-03)* + +- **Evidence.** + - AWS clients are registered with `services.AddAWSService()` and `()`, which read the SDK's default configuration (the `AWS` config section and environment). + - `SqsClientFactory` and `SnsClientFactory`, which would apply `AwsOptions.Region` and `MaxRetries`, are never called. + - `AwsOptions.EnableCommandRouting`, `EnableEventRouting` and `RetryDelay` are never read. + - `GcpOptions.EnableCommandRouting`, `EnableEventRouting`, `MaxRetries` and `RetryDelay` are never read. +- **Impact.** `options.Region = RegionEndpoint.EUWest1`, the first line of every documented example, has no effect. The service can create and use resources in an unexpected region or account with no warning. +- **Suggested change.** Build the clients from `AwsOptions`, or call `services.AddDefaultAWSOptions(...)` from them. Either honour or delete every unused option. Add a test asserting that configured options reach the client config. + +### GAP-04 +**Command rebuild contract is implicit and failures are silent.** *(CMD-11, NFR-CMP-06)* + +- **Evidence.** + - `CommandStoreAdapter.DeserializeCommand` rebuilds commands with `Activator.CreateInstance(commandType)`, which needs a **public parameterless constructor**, and resolves types with `Type.GetType(assemblyQualifiedName)`. + - `DeserializeCommands` wraps each one in `try { … } catch { continue; }`. + - The core sample `CreateAccount` has no parameterless constructor. The EF test copies add one. +- **Impact.** + - Replay silently leaves out commands that cannot be rebuilt, for example after a rename or namespace move, or because of a missing constructor. The rebuilt state is then wrong, with no error. + - `GetNextSequenceNo` uses the same `Load`, so skipped commands also produce **wrong sequence numbers**. That causes unique-key violations on EF, or duplicate sequence numbers on stores without the constraint. +- **Suggested change.** + - Document the constructor requirement and check it at registration time (scan command types). + - Log at error level and surface failures, for example with a `ReplayResult` or a strict mode that throws. + - Store a stable logical type name (such as `[CommandName("orders.create.v1")]`) with a type registry, not the assembly-qualified name. + - Add an upcaster hook for payload versioning. + +### GAP-05 +**Sequence assignment is O(n), racy, and not atomic with side effects.** *(CMD-05, EF-21, NFR-REL-02/03, NFR-PERF-03)* + +- **Evidence.** + - [CommandBus.CoreDispatch](../../src/SourceFlow/Messaging/Bus/Impl/CommandBus.cs) does three things in order: (1) `GetNextSequenceNo` (load and deserialise the full history, then max + 1); (2) dispatch to the sagas, which persist the entity and raise events; (3) `Append`. + - The EF unique index on `(EntityId, SequenceNo)` catches a concurrent duplicate only at step 3, after step 2's side effects. + - `DatabaseResiliencePolicy` retries every `DbUpdateException`, including that constraint violation, and the failed `CommandRecord` stays tracked between attempts. +- **Impact.** Two concurrent commands for one entity can both change it. One then fails to log, so the history no longer reproduces the state. Latency also grows with the length of each entity's history. +- **Suggested change.** + - Reserve the sequence number first: optimistic concurrency on an entity version column, or append before handling, with the handler running inside the same transaction. + - Get `MAX(SequenceNo)` through a store method (add `ICommandStore.GetLastSequenceNo`). + - Put the entity persist and the command append in one unit of work. + - Publish events after commit (outbox). + - Exclude unique-constraint violations from retries. + +### GAP-06 +**Replay causes external side effects.** *(CMD-10, NFR-REL-05)* + +- **Evidence.** + - Replay sends commands through **every** `ICommandDispatcher`, and neither `AwsSqsCommandDispatcher` nor `PubSubCommandDispatcher` checks `Metadata.IsReplay`. + - Sagas raise events during replay. `IsReplay` lives on the command, not the event, so cloud event dispatchers publish them again. + - Any `Publish` a saga makes during replay creates a **new**, non-replay command, which gets a new sequence number and is appended. +- **Impact.** Rebuilding one entity can re-send commands and events to other services and grow the log. +- **Suggested change.** Carry an ambient replay context (an AsyncLocal, or a flag copied onto raised events and published commands). Cloud dispatchers should skip it. Saga `Publish` and `Raise` should be suppressed or redirected during replay. Add a test asserting that replay produces no outbound messages and no new log rows. + +### GAP-19 +**Cloud-received commands are not logged by the owning service.** *(G2, G3, CMD-07)* + +- **Evidence.** `AwsSqsCommandListener` and `PubSubCommandListener` call `ICommandSubscriber.Subscribe` directly, not `ICommandBus.Publish`. The receiving service therefore assigns no sequence number, appends nothing to its command store, and runs no `ICommandDispatchMiddleware`. The **sender** appends the command to *its* store, with a sequence number computed from *its* store. +- **Impact.** In a distributed deployment, the service that owns the entity cannot replay it, and sequence numbers depend on whoever sent the command. Goal G2 (rebuild any entity) fails once commands cross a service boundary. +- **Suggested change.** Decide where the command log lives (see Q2). If it lives in the owner, route inbound commands through a receive-side bus path that assigns the sequence, appends and runs the middleware, but does not re-dispatch to the cloud. Have the sender skip appending commands it routes away. + +### GAP-20 +**New-entity commands are logged under id 0 unless the caller assigns an id.** *(DOM-06, CMD-05)* + +- **Evidence.** + - `Command(bool newEntity, payload)` sets `Entity.Id = 0`. + - The bus computes the sequence number and appends using `command.Entity.Id`. + - The saga creates the entity with that id and persists it. The EF store inserts it, so a database-generated key is possible. + - Nothing writes the real id back to the command. The sample works only because `AccountAggregate.CreateAccount` sets `command.Entity.Id = accountId` explicitly. +- **Impact.** Every unassigned "create" command goes into the log under entity 0, sharing one sequence. Replaying the real entity misses its creation command. +- **Suggested change.** Require ids assigned by the caller or the framework for new entities (validate `IsNew && Id == 0` in `CommandPublisher`), or write the persisted id back to the command before appending. Consider supporting `Guid` ids (see Q4). + +### GAP-13 +**GCP: shared subscriptions across services, no ordering, no hardening.** *(GCP-04, GCP-05, GCP-07)* + +- **Evidence.** + - Subscription ids are `{topic}{SubscriptionSuffix}`, default `-sub`, so two services subscribing to `order-events` both use `order-events-sub` and **compete** for events instead of each receiving a copy. + - `PubSubCommandDispatcher` sets `OrderingKey`, but `CreateSubscriptionAsync` doesn't enable message ordering, and the publisher isn't configured for ordering. + - There is no idempotency check, no dead-letter policy and no encryption wiring (GAP-01). +- **Impact.** Event fan-out between bounded contexts, the main reason to subscribe to a topic, silently breaks with default settings. Per-entity order isn't guaranteed. +- **Suggested change.** Name subscriptions after the service (add `GcpOptions.ServiceName`, or make the suffix required). Create subscriptions with `EnableMessageOrdering = true` and turn on publisher ordering. Configure a dead-letter topic. Wire idempotency, encryption and trace propagation. + +--- + +## P2 findings + +### GAP-07 +**Saga event-raising failures are swallowed.** *(DOM-08, NFR-REL-06)* +- **Evidence.** In `Saga.RaiseEvent`, the whole build-and-raise step sits inside `try { … } catch (Exception ex) { logger.LogError(…) }`. That includes view-projection and event-dispatch failures, because `Raise` awaits the event queue. +- **Impact.** The entity is persisted and the command is appended, but views and other services never see the event. They drift out of sync, with nothing to trigger a retry. +- **Suggested change.** Let exceptions from building the event bubble up (they are programming errors). Make dispatch failure behaviour a deliberate policy: fail the command, or hand off to an outbox or retry. + +### GAP-08 +**Singleton domain types capture Scoped dependencies.** *(REG-05)* +- **Evidence.** `UseSourceFlow` registers aggregates, sagas and views as **Singleton** by default. They take `Lazy` and `IEntityStoreAdapter` / `IViewModelStoreAdapter`, which are registered **Scoped**. The event subscribers are Singletons that hold `IEnumerable` and `IEnumerable`. +- **Impact.** With scope validation on (the ASP.NET Core default in Development), resolution throws. With it off, singletons keep the first scope's adapters and their EF `DbContext`, which is not thread-safe and lives for the whole process. +- **Suggested change.** Default domain types to Scoped, or resolve the scoped collaborators per call through `IServiceScopeFactory`. Add a test with `ValidateScopes = true`. + +### GAP-09 +**Idempotency key is per delivery, not per logical message.** *(IDM-05)* +- **Evidence.** The key is `$"{type}:{message.MessageId}"`. A producer that retries a send gets a new transport `MessageId`. +- **Suggested change.** Key on `Metadata.EventId`, which is set once when the command or event is created and already travels in the body. Keep the transport id as a fallback. + +### GAP-10 +**No allow-list for inbound message types.** *(SEC-06, NFR-SEC-04)* +- **Evidence.** Listeners call `Type.GetType(attribute)` on the `CommandType` / `EventType` attribute and deserialise into whatever type that resolves to, so long as it is an `ICommand` or `IEvent`. +- **Impact.** System.Text.Json limits gadget-style attacks. Even so, anyone who can write to a queue can make the service create, and run sagas for, any command type it has loaded, including commands that are meant to stay internal. +- **Suggested change.** Accept only the types declared in the bus configuration, or registered as receivable, and dead-letter everything else. + +### GAP-11 +**Dead-letter story is incomplete.** *(DLQ-05, DLQ-06, NFR-OPS-06)* +- **Evidence.** + - `IDeadLetterProcessor` has no implementation. + - The only `IDeadLetterStore` is in-memory and isn't registered. + - Bootstrappers don't configure an SQS redrive policy or a Pub/Sub dead-letter topic, and the "> 3 receives" threshold in the AWS enhanced listener is hard-coded. +- **Suggested change.** Add native DLQ configuration to the bus builder (for example `.Queue("orders.fifo").WithDeadLetter(maxReceives: 5)`). Provide an EF-backed `IDeadLetterStore` and a provider `IDeadLetterProcessor`. Make the thresholds options. + +### GAP-12 +**Auto-provisioning cannot be switched off.** *(BUS-07)* +- **Evidence.** The bootstrappers always call create/subscribe APIs (`CreateQueue`, `CreateTopic`, `Subscribe`, `CreateSubscription`). +- **Impact.** Runtime credentials need create permissions, which breaks least privilege. Configuration managed in Terraform or CloudFormation (redrive, encryption, retention) can drift from what the code creates. +- **Suggested change.** Add a `ProvisioningMode` option: `CreateIfMissing` (the default), `ValidateOnly` (fail if missing) or `None`. + +--- + +## P3 findings + +### GAP-14 +**Metric and log inaccuracies.** *(OBS-04, NFR-OPS-05)* +- `sourceflow.domain.sagas.executed` is never recorded. +- `commands.executed` is recorded by both `CommandBus` and `CommandStoreAdapter.Append`, so it counts twice. +- `entities.created` goes up on every persist, updates included, and is recorded inside a tag-setting callback. +- `Projections.EventSubscriber` logs "No Sagas Found" with `Action=Command_Dispatcher`. +- `EventDispatcher` logs `subscribers.GetType()` (the collection) rather than the individual subscriber. +- The spelling `Event_Disptcher_Aggregate` is wrong. + +### GAP-15 +**Store "not found" semantics are unspecified.** *(STO-06)* +The interfaces don't say whether `Get` returns null or throws. The EF stores throw `InvalidOperationException`, while custom stores might return null and cause a `NullReferenceException` inside a saga handler. Pick one behaviour (for example `TryGet`, or a dedicated `EntityNotFoundException`) and document it. + +### GAP-16 +**Assembly-scan fallback rethrows.** *(REG-07)* +In `IocExtensions.GetImplementedTypes`, the `catch (ReflectionTypeLoadException)` block calls `a.GetTypes()` again, which throws again and escapes. Use `ex.Types.Where(t => t != null)`. + +### GAP-17 +**EF runtime type registration is process-global.** *(EF-05)* +`EntityDbContext` and `ViewModelDbContext` keep registered types and assemblies in `static HashSet`s. Two hosts in one process (common in integration tests) share them and can interfere. Move the registrations into options held by the DI container. + +### GAP-18 +**Documentation and package-metadata drift.** *(NFR-DOC-03, NFR-RE-03/04, NFR-CMP-02)* +- RawMessageDelivery is documented but not set (GAP-02). `options.Region` is documented but not applied (GAP-03). +- README badges claim .NET Standard targets for the EF package, which its csproj does not have. +- The core csproj description leaves out .NET 8. The EF description says SQL Server only. +- The v2.0.0 changelog says "Release Date: TBC", but the README gives 15 Mar 2026. The changelog doesn't mention the GCP provider, which now exists (beta). +- The README sells "Event Sourcing Foundation — Event-first design with full audit trail", but the product is command-sourced and events aren't stored (see Q1). + +--- + +## Open questions for product decisions + +| # | Question | Why it matters | +|---|----------|----------------| +| Q1 | **Command sourcing or event sourcing?** Should the product say clearly that it is *command-sourced*, or should it move toward storing events (with snapshots and upcasters)? | Positioning, the companion book's narrative, audit guarantees, and whether events need a schema policy. | +| Q2 | **Where does the authoritative command log live** when commands cross services: with the sender or with the owning service? | Decides the fix for GAP-19 and how replay works in a distributed system. | +| Q3 | **Should hybrid dispatch be the default?** Today a routed command is also handled by any matching local saga. Many users expect "routed means remote only". | A per-route option (`.Queue(...).RemoteOnly()`) would prevent double handling without relying on idempotency. | +| Q4 | **What id strategy?** `IEntity.Id` and `IViewModel.Id` are `int`. Should the framework support `Guid` or string ids and generate ids for new entities? | Distributed id allocation, GAP-20, and cross-service references. | +| Q5 | **GA bar for GCP.** Is parity with AWS (GAP-01, GAP-13) required before 2.0.0 GA, or will it ship as beta? | Release planning and changelog accuracy. | +| Q6 | **Azure provider scope and date.** The README lists it as v2.0.0 (TBC). Is it still in scope for 2.x? | Roadmap communication. | +| Q7 | **Consistency model.** Should the framework offer transactional guarantees (unit of work plus outbox), or document eventual consistency and leave it to the user? | Drives the fixes for GAP-05 and GAP-07, and the store contract changes they need. | diff --git a/docs/product/07-Workflow-Designer-Requirements.md b/docs/product/07-Workflow-Designer-Requirements.md new file mode 100644 index 00000000..030a9208 --- /dev/null +++ b/docs/product/07-Workflow-Designer-Requirements.md @@ -0,0 +1,99 @@ +# 07 — Workflow DSL and Visual Designer Requirements (new for v3) + +| | | +|---|---| +| **Origin** | Product request, 2026-11-10. This is a **new** requirement, not reverse-engineered from v2 code. | +| **Status of every requirement below** | **Planned** | +| **Design** | [v3 design doc 15](../v3.0.0/engineering/Design/15-Workflow-DSL-and-Studio.md), [ADR-024](../v3.0.0/engineering/ADRs/ADR-024-workflow-dsl-compiled-to-process-managers.md), [ADR-025](../v3.0.0/engineering/ADRs/ADR-025-studio-react-spa-with-shared-wasm-core.md) | + +## 1. Problem + +A business process usually spans several services. Order fulfilment, for example, touches Orders, Payments, Inventory and Shipping, each owning its own aggregates. + +In v2 the "saga" was only a command handler (product doc 02, DOM-05). In v3 a process manager is plain C# ([ADR-020](../v3.0.0/engineering/ADRs/ADR-020-process-managers-with-durable-state-and-timers.md)). Either way, nobody can **see** the end-to-end workflow: + +- which events move it forward; +- what happens when a step is rejected or times out; +- how many times a step is retried; +- what gets undone, and in which order, when the process can't complete. + +Domain experts can't review it, and engineers can't check it for missing failure paths. Competing products leave this to code, or to commercial tools (doc 13 of the v3 design). + +## 2. Users + +| Persona | Need | +|---------|------| +| Domain expert / product owner | Read, and ideally sketch, a business workflow across services in business terms | +| Domain developer | Design a saga with all failure, retry and compensation paths; generate correct process-manager code and tests from it | +| Architect / reviewer | See the whole business domain: services, aggregates, who owns which command, which events flow where; review workflow changes in pull requests | +| Operator (later release) | See where live workflow instances are, which are stuck, and resume or abort them | + +## 3. Functional requirements + +### 3.1 Domain model ingestion (`WFD-1x`) + +| ID | Requirement | +|----|-------------| +| WFD-10 | The tool shall load a **business domain workspace**: a set of services that together form one business domain. | +| WFD-11 | For each service it shall read a machine-readable **service manifest**: service name, endpoint, aggregates, the commands each aggregate decides, the events each command can produce, the rejections each command can return, process managers, projections, published integration events and subscriptions. | +| WFD-12 | Manifests shall be produced from the code and its routing configuration, never hand-written, so the diagram can't drift from the code. | +| WFD-13 | The tool shall show a **domain map**: services, their aggregates, command ownership, and event and integration-event flows between services, including choreographed chains with no orchestrator. | + +### 3.2 Workflow definition: the DSL (`WFD-2x`) + +| ID | Requirement | +|----|-------------| +| WFD-20 | Workflows (orchestrated sagas) shall be defined in a **text DSL** stored in the repository. The DSL is the source of truth; the visual designer edits the DSL. | +| WFD-21 | A workflow shall be expressed as a **state machine driven by events**: states, transitions triggered by events (domain or integration), optional guard conditions, and steps that send commands to a named service's aggregate. | +| WFD-22 | Every step shall declare its **success** transition(s) and its **failure** handling: rejection codes, timeouts and unexpected errors. | +| WFD-23 | A step may declare a **business retry policy**: which failures to retry, maximum attempts, and backoff. This is distinct from the infrastructure retries the runtime already performs. | +| WFD-24 | A step may declare a **compensation** (rollback) action. When the workflow fails, completed steps are compensated **in reverse order**. Compensations have their own retry policy. | +| WFD-25 | A step may be marked as the **pivot** (point of no return). Failures after the pivot use forward recovery (retry or alternative path), never compensation. | +| WFD-26 | A failed compensation shall move the workflow to **manual intervention**, which raises an alert and lets an operator resume or abort the instance. | +| WFD-27 | Every wait for an event shall have a **timeout** (or an explicit, justified "no timeout"). | +| WFD-28 | The tool shall **validate** a workflow against the domain manifests: every referenced command, event and service exists; the named service owns the command; cross-service events are published and subscribed; every state is reachable; terminal states exist; every failure path is handled. | +| WFD-29 | Each workflow shall be **compiled into a SourceFlow process manager** owned by exactly one service (the orchestrator), using the standard runtime: no separate workflow engine. | + +### 3.3 Visual designer (`WFD-3x`) + +| ID | Requirement | +|----|-------------| +| WFD-30 | A **React** web application shall render workflows as **state-machine diagrams**, with success, failure, retry and compensation paths visually distinct. | +| WFD-31 | It shall render a **swimlane (sequence) view** per service, showing commands and events over time for a chosen path. | +| WFD-32 | It shall support **visual editing**: add, remove or connect states and steps from a palette of commands and events taken from the manifests; edit properties; with lossless round trip to the DSL text, which is shown side by side. | +| WFD-33 | It shall **simulate** a workflow: choose the outcome of each step (success, specific rejection, timeout) and see the resulting path, the commands sent, the retries and the compensation sequence. | +| WFD-34 | It shall **generate test specifications** (process-manager Given/When/Then specs) from simulated paths, including every failure and compensation path. | +| WFD-35 | It shall **export** diagrams (SVG, PNG, Mermaid) and offer a BPMN 2.0 export for stakeholders who use BPMN tools. | +| WFD-36 | It shall run **locally** against the repository (`dotnet sourceflow studio`) and also as a **read-only static build**, for example in documentation or as a diagram diff on pull requests. | +| WFD-37 | *(Later release)* An **observe mode** shall overlay live instance counts per state, stuck instances and recent failures, using the service's own query API (respecting the query boundary in product Q2). | + +## 4. Non-functional requirements (`WFD-NFR`) + +| ID | Requirement | +|----|-------------| +| WFD-NFR-1 | **Separate utility.** It is not part of the runtime packages and adds no runtime dependency to services. Generated process managers depend only on SourceFlow v3 packages. | +| WFD-NFR-2 | **One semantics.** Validation and simulation in the designer give exactly the same results as the build-time validator and code generator. | +| WFD-NFR-3 | **Performance.** Opening a workspace of 20 services and 50 workflows takes under 3 s. A 200-state workflow lays out and renders in under 1 s. | +| WFD-NFR-4 | **Accessibility.** WCAG 2.1 AA, including keyboard-only editing and a non-colour encoding of path types. | +| WFD-NFR-5 | **Security.** It works offline. The local server binds to localhost only by default. No telemetry is sent anywhere. Git is the only storage. | +| WFD-NFR-6 | **Versioned DSL.** The DSL has a schema version. Breaking changes need a new version and a migration command. | + +## 5. Acceptance scenarios + +1. **Visualise.** Given the Orders, Payments, Inventory and Shipping services, opening the workspace shows the domain map with correct command ownership and integration-event flows. +2. **Design.** A developer draws "order fulfilment": + - reserve stock → charge payment (retry three times on `payment.declined`, every 10 minutes); + - **pivot**: create shipment; + - complete. + Validation reports an error until every step has a timeout, and until "reserve stock" has a compensation. +3. **Rollback.** In simulation, when payment fails after three retries, the designer shows the compensation path: release stock, then cancel the order, ending in `Compensated`. +4. **Generate.** Building the Orders service produces a process manager from the DSL. The generated specs cover all five paths: success, retry-then-success, compensated, timeout and manual intervention. All pass. +5. **Run.** The end-to-end test runs the generated workflow across the four services on the in-memory and cloud transports, with the same outcomes as the simulation. + +## 6. Open questions + +| # | Question | Proposed answer | +|---|----------|-----------------| +| WQ1 | Ship with 3.0.0 GA or on its own release train? | **Own release train** ("SourceFlow Studio 1.0"). It isn't release-blocking for 3.0.0, but is targeted to be ready at GA (v3 design doc 12) | +| WQ2 | BPMN import as well as export? | Export only. BPMN semantics don't map cleanly to aggregate-owned commands | +| WQ3 | Observe mode in Studio 1.0? | No. It comes in 1.1, after the query API and dashboards have settled | diff --git a/docs/product/README.md b/docs/product/README.md new file mode 100644 index 00000000..b4e7090e --- /dev/null +++ b/docs/product/README.md @@ -0,0 +1,61 @@ +# SourceFlow.Net — Product Requirements + +This folder holds the product requirements for SourceFlow.Net. They were **reverse-engineered from the source code** at commit `086673b` (master, 10 Nov 2026, version 2.0.0) and cross-checked against the existing architecture docs, READMEs, changelogs and tests. + +They record two things: + +1. **What the product must do.** Each requirement is a testable "shall" statement. +2. **What the code does today.** Each requirement has a status and a link to the code that implements it, so the documents can double as a gap analysis. + +## Documents + +| # | Document | Covers | +|---|----------|--------| +| 01 | [Product Vision and Scope](01-Product-Vision-and-Scope.md) | Problem, vision, users, goals, non-goals, packages, key concepts, user journeys, roadmap | +| 02 | [Core Framework Requirements](02-Core-Framework-Requirements.md) | Domain model (aggregates, sagas, views), the command and event pipelines, command log and replay, store contracts, DI registration, middleware, telemetry | +| 03 | [Persistence (Entity Framework) Requirements](03-Persistence-EntityFramework-Requirements.md) | EF Core stores, database providers, schema, naming, resilience, idempotency store | +| 04 | [Cloud Messaging Requirements](04-Cloud-Messaging-Requirements.md) | Bus configuration, bootstrapping, AWS (SQS/SNS), GCP (Pub/Sub), idempotency, dead letters, encryption, circuit breaker, health, cloud telemetry | +| 05 | [Non-Functional Requirements](05-Non-Functional-Requirements.md) | Compatibility, delivery and consistency guarantees, security, performance, observability, testability, packaging and release | +| 06 | [Gaps, Risks and Open Questions](06-Gaps-Risks-and-Open-Questions.md) | Places where the code falls short of a requirement or of its own docs, with evidence and a suggested fix | +| 07 | [Workflow DSL and Visual Designer Requirements](07-Workflow-Designer-Requirements.md) | **New for v3.** Saga DSL and a React state-machine designer spanning the services of a business domain: success, failure, retry and rollback paths | + +## Requirement IDs + +Each requirement has a stable ID: `-`. Areas: + +| Prefix | Area | Doc | +|--------|------|-----| +| `DOM` | Domain modelling (aggregates, sagas, views, entities) | 02 | +| `CMD` | Command model, bus, command log, replay | 02 | +| `EVT` | Event model and event pipeline | 02 | +| `STO` | Store contracts and adapters | 02 | +| `REG` | Dependency-injection registration and discovery | 02 | +| `EXT` | Middleware and extension points | 02 | +| `OBS` | Domain observability | 02 | +| `EF` | Entity Framework persistence | 03 | +| `BUS` | Cloud bus configuration and bootstrapping | 04 | +| `IDM` | Idempotency (duplicate-message detection) | 04 | +| `DLQ` | Dead-letter handling | 04 | +| `RES` | Resilience (retry, circuit breaker) | 04 | +| `SEC` | Message security (encryption, masking, credentials) | 04 | +| `CTL` | Cloud telemetry and health | 04 | +| `AWS` | AWS provider | 04 | +| `GCP` | GCP provider | 04 | +| `NFR` | Non-functional | 05 | +| `GAP` | Gap or risk finding | 06 | +| `WFD` | Workflow DSL and visual designer (new requirement, status Planned) | 07 | + +## Status values + +| Status | Meaning | +|--------|---------| +| **Implemented** | Built, wired by the standard registration call, and covered by tests or clearly exercised. | +| **Partial** | Built, but incomplete or with a caveat that matters. The caveat is noted, usually with a `GAP` reference. | +| **Opt-in** | The code exists but the standard registration call does not wire it. Consumers must register it themselves. | +| **Planned** | On the published roadmap but not in the code. | + +## Maintaining these documents + +- When behaviour changes, update the requirement's status and source link in the same pull request. +- When a `GAP` item is fixed, mark it **Resolved** in doc 06 and update the requirement it references. +- Keep requirement IDs stable. Retire an ID by striking it through rather than renumbering. diff --git a/docs/v3.0.0/engineering/ADRs/ADR-001-target-dotnet-10-and-csharp-14.md b/docs/v3.0.0/engineering/ADRs/ADR-001-target-dotnet-10-and-csharp-14.md new file mode 100644 index 00000000..ff9d411b --- /dev/null +++ b/docs/v3.0.0/engineering/ADRs/ADR-001-target-dotnet-10-and-csharp-14.md @@ -0,0 +1,23 @@ +# ADR-001: Target .NET 10 and C# 14 only + +| | | +|---|---| +| **Status** | Proposed | +| **Date** | 2026-11-10 | +| **Deciders** | v3 architecture review | + +## Context + +v2 multi-targets netstandard2.0, netstandard2.1 and net8–10 (NFR-CMP-01). That blocks `static abstract` interface members, `FrozenDictionary`, `TimeProvider`, `Guid.CreateVersion7`, `System.Threading.Lock`, metric instrument advice, keyed DI, the `IHostedLifecycleService` ordering, and full Native AOT annotations. It also needs `#if` branches (see the v2 `IocExtensions` in the AWS provider). + +## Decision + +Every package targets `net10.0` and is compiled with C# 14 (extension members, the `field` keyword, null-conditional assignment). Packages are annotated `IsAotCompatible=true` and `IsTrimmable=true`. + +## Alternatives + +(a) Keep net8 LTS as well. That doubles the test matrix and loses .NET 9/10 APIs. Rejected because .NET 10 is the current LTS, released Nov 2025. (b) Keep netstandard. Rejected: it forces reflection-based designs. + +## Consequences + +(+) Smaller, faster code; AOT; one build. (−) .NET Framework and older runtimes stay on v2. v2 receives security fixes for 12 months after v3 GA ([doc 12](../Design/12-Migration-Delivery-and-Traceability.md)). diff --git a/docs/v3.0.0/engineering/ADRs/ADR-002-event-sourcing-replaces-command-sourcing.md b/docs/v3.0.0/engineering/ADRs/ADR-002-event-sourcing-replaces-command-sourcing.md new file mode 100644 index 00000000..c4a2786c --- /dev/null +++ b/docs/v3.0.0/engineering/ADRs/ADR-002-event-sourcing-replaces-command-sourcing.md @@ -0,0 +1,30 @@ +# ADR-002: Event sourcing replaces command sourcing + +| | | +|---|---| +| **Status** | Accepted (product sign-off 2026-11-10) | +| **Date** | 2026-11-10 | +| **Deciders** | v3 architecture review | + +## Context + +v2 logs commands and rebuilds state by re-running sagas. Replay therefore runs today's business logic, clock and dependencies against old intents, so it is non-deterministic. It also re-publishes to the cloud (GAP-06), silently drops commands that can't be rebuilt (GAP-04), and can't be atomic with the entity snapshot (GAP-05). Events, which are the facts, are not stored at all (EVT-05). + +## Decision + +Events are the system of record, in append-only streams, one stream per aggregate instance. State = `fold(Evolve, Initial, events)`. Commands are transient. Optionally they are recorded only as inbox entries (for idempotency) and in event metadata (`causationId`), which keeps the audit trail of *which command caused which events*. + +## Alternatives + +- (a) Keep command sourcing but make it deterministic. That isn't possible in general, because handlers call services and read the clock. +- (b) A state-stored aggregate with an outbox, with no event store. That is simpler but loses history, temporal queries and rebuildable projections, which are the product's reason to exist. +- (c) Offer both modes. That doubles the core surface (YAGNI). A state-stored mode could come later on top of the same storage session. + +## Consequences + +- (+) Replay becomes a pure fold, so projections rebuild with no side effects. There is a full audit trail. The correct model matches the companion book's narrative. +- (−) A breaking conceptual change for v2 users, handled by the migration tool, which imports genesis events. Event schema evolution becomes a first-class concern ([ADR-005](ADR-005-logical-message-type-names-and-registry.md)). + +## Traces + +Q1, GAP-04, GAP-05, GAP-06, GAP-07, GAP-20, EVT-05. diff --git a/docs/v3.0.0/engineering/ADRs/ADR-003-aggregates-as-pure-deciders-decide-evolve.md b/docs/v3.0.0/engineering/ADRs/ADR-003-aggregates-as-pure-deciders-decide-evolve.md new file mode 100644 index 00000000..63a8a832 --- /dev/null +++ b/docs/v3.0.0/engineering/ADRs/ADR-003-aggregates-as-pure-deciders-decide-evolve.md @@ -0,0 +1,30 @@ +# ADR-003: Aggregates as pure deciders (decide/evolve) + +| | | +|---|---| +| **Status** | Proposed | +| **Date** | 2026-11-10 | +| **Deciders** | v3 architecture review | + +## Context + +In v2, behaviour was spread across an `Aggregate` façade (sends commands), a `Saga` (mutates the entity, persists it, raises events) and reflection-built events. That mixes responsibilities and needs DI for domain objects, which caused GAP-08. + +## Decision + +An aggregate is an immutable `record` that carries state and two kinds of pure method: +- `Decision Decide(TCommand, DecisionContext)`: validate the command and return events or a rejection. +- `TSelf When(TEvent)`: apply one event to produce the next state. + +The generator writes the dispatch switches. For logic that needs dependencies (I/O), a user writes an `ICommandHandler` that gathers the inputs and then calls a pure method. `DecisionContext` exposes `Now` (from `TimeProvider`), `Version`, `Metadata` and `CommandId`, so decisions stay deterministic in tests. + +## Alternatives + +- (a) A mutable OO aggregate with `Apply` and an uncommitted-events list (Eventuous or Marten style). Familiar, but it hides mutation, makes concurrency retries need careful resets, and is harder to test. +- (b) A fully functional decider with static abstracts only. Pure, but unfamiliar to many C# developers. +- The chosen design uses records with instance methods plus generation: functional semantics with idiomatic C#. + +## Consequences + +- (+) Given/When/Then tests with no DI or mocks. Concurrency retry is trivially safe. Aggregates aren't DI services, so lifetime bugs go away (GAP-08). +- (−) Developers learn the `Decision`/`When` idiom. Analyzers guide them (for example SF0004, "When must be side-effect free": it flags I/O APIs). diff --git a/docs/v3.0.0/engineering/ADRs/ADR-004-source-generation-instead-of-reflection.md b/docs/v3.0.0/engineering/ADRs/ADR-004-source-generation-instead-of-reflection.md new file mode 100644 index 00000000..4b6b6a28 --- /dev/null +++ b/docs/v3.0.0/engineering/ADRs/ADR-004-source-generation-instead-of-reflection.md @@ -0,0 +1,29 @@ +# ADR-004: Compile-time source generation instead of runtime reflection + +| | | +|---|---| +| **Status** | Proposed | +| **Date** | 2026-11-10 | +| **Deciders** | v3 architecture review | + +## Context + +v2 scans assemblies with reflection (REG-03, GAP-16), builds generic methods with `MakeGenericMethod` on every message, instantiates types with `Activator.CreateInstance`, and resolves `Type.GetType` from wire strings. That is slow, not trimmable, and fails at runtime instead of at build time. + +## Decision + +Incremental source generators produce: +- per module: a `[SourceFlowModule]` registration (handlers, projections, process managers, type registry entries); +- per aggregate: the `Evolve` and `Decide` switches and the command→stream-id extractor; +- per message assembly: **no** JSON context. Roslyn generators can't see each other's output, so a SourceFlow-generated `[JsonSerializable]` context would never be processed by the System.Text.Json generator. Each module instead **declares** its own `JsonSerializerContext` (`[SourceFlowModule(typeof(AccountsJsonContext))]`). Analyzer SF0010 checks that every message, document and process-state type in the module is listed, and a code fix adds missing entries (design correction DC-1, found during the implementation spike); +- strongly typed id types (`Parse`, `TryFormat`, a JSON converter, a stream-id formatter). + +Analyzers enforce the contracts (§ SF diagnostics in [doc 03](../Design/03-Domain-Programming-Model.md#9-analyzers)). The runtime uses `FrozenDictionary` lookups built from the generated tables. + +## Alternatives + +Reflection with caching (v2 listeners). It still isn't AOT-safe and still fails late. + +## Consequences + +(+) AOT, faster startup, errors at compile time. (−) Generator maintenance cost; users need the generator in their build (it ships inside `SourceFlow.Net` under `analyzers/dotnet/cs`; it targets `netstandard2.0` as a compiler plugin, the only non-`net10.0` project, see [ADR-027](ADR-027-single-core-package-with-extensibility-spis-and-categorised-adapters.md)). diff --git a/docs/v3.0.0/engineering/ADRs/ADR-005-logical-message-type-names-and-registry.md b/docs/v3.0.0/engineering/ADRs/ADR-005-logical-message-type-names-and-registry.md new file mode 100644 index 00000000..59c6cd5a --- /dev/null +++ b/docs/v3.0.0/engineering/ADRs/ADR-005-logical-message-type-names-and-registry.md @@ -0,0 +1,23 @@ +# ADR-005: Stable logical message type names, with a registry as allow-list + +| | | +|---|---| +| **Status** | Proposed | +| **Date** | 2026-11-10 | +| **Deciders** | v3 architecture review | + +## Context + +v2 identifies stored and wire types by CLR assembly-qualified name (GAP-04, NFR-CMP-06), and listeners instantiate whatever type the sender names (GAP-10). + +## Decision + +Every message carries `[MessageType("bank.account.deposited", Version = 1)]`. The registry maps `(name, version)` ↔ CLR type and is built **only** from generated module registrations. Unknown names are rejected before deserialisation. Schema evolution works in two ways: additive changes rely on the tolerant reader (STJ ignores unknown members, and missing members get defaults), and breaking changes go through **upcasters** (`IUpcaster`), which the registry chains when reading. Renaming the CLR type doesn't affect stored data. + +## Alternatives + +(a) CLR full names without the assembly: still breaks on rename or move. (b) A schema registry service (Avro or Protobuf): heavyweight, and JSON is the norm for this audience. A pluggable `IMessageSerializer` keeps this option open. + +## Consequences + +(+) Refactoring-safe storage and wire formats; secure deserialisation. (−) Authors must name their messages. The analyzer SF0001 flags a missing `[MessageType]`. diff --git a/docs/v3.0.0/engineering/ADRs/ADR-006-transactional-outbox-and-inbox-for-effectively-once.md b/docs/v3.0.0/engineering/ADRs/ADR-006-transactional-outbox-and-inbox-for-effectively-once.md new file mode 100644 index 00000000..9611042e --- /dev/null +++ b/docs/v3.0.0/engineering/ADRs/ADR-006-transactional-outbox-and-inbox-for-effectively-once.md @@ -0,0 +1,32 @@ +# ADR-006: Transactional outbox and inbox for effectively-once processing + +| | | +|---|---| +| **Status** | Accepted (product sign-off 2026-11-10) | +| **Date** | 2026-11-10 | +| **Deciders** | v3 architecture review | + +## Context + +v2 publishes to the broker outside any transaction. Idempotency is an opt-in check on transport message ids, and in practice isn't wired (GAP-01, GAP-09). + +## Decision + +- **Outbox.** Every outbound message (integration events, remote commands, scheduled messages) is written to `sf_outbox` in the *same* transaction as the events that caused it. A relay publishes it and deletes it after the broker acknowledges. +- **Inbox.** Every handled inbound message records `(consumer, messageId)` in `sf_inbox` in the same transaction as its effects. A duplicate is detected inside that transaction (unique key), rolled back, and acknowledged. +- The `messageId` is the **logical** id (UUIDv7 assigned at creation, carried in the envelope), so producer retries are deduplicated too. +- The inbox is always on for transport-received messages, and on for local `SendAsync` when an idempotency key is supplied. + +## Alternatives + +- (a) Broker-native exactly-once (SQS FIFO dedup, ASB duplicate detection, Pub/Sub exactly-once). Its windows are limited (5 min on SQS FIFO), it is inconsistent across clouds, and it doesn't cover the database side. It stays as a complementary layer. +- (b) Log tailing (reading `$all` to publish) instead of an outbox table. That avoids the double write, but can't carry remote commands or timers, and it couples publication to event types. Rejected for uniformity; [doc 04](../Design/04-Messaging-Pipeline.md#7-outbox) explains why. + +## Consequences + +- (+) No lost or phantom messages. Effectively-once processing. A broker outage doesn't fail commands. +- (−) One extra insert per outbound message. A relay process to run. Inbox retention must exceed the broker redelivery window (default 14 days). + +## Traces + +Q7, GAP-01, GAP-09, IDM-04, IDM-05, NFR-REL-03/04. diff --git a/docs/v3.0.0/engineering/ADRs/ADR-007-single-command-ownership-route-local-xor-remote.md b/docs/v3.0.0/engineering/ADRs/ADR-007-single-command-ownership-route-local-xor-remote.md new file mode 100644 index 00000000..3c93bfce --- /dev/null +++ b/docs/v3.0.0/engineering/ADRs/ADR-007-single-command-ownership-route-local-xor-remote.md @@ -0,0 +1,34 @@ +# ADR-007: Single command ownership: route local XOR remote + +| | | +|---|---| +| **Status** | Accepted (product sign-off 2026-11-10) | +| **Date** | 2026-11-10 | +| **Deciders** | v3 architecture review | + +## Context + +v2 runs every dispatcher, so a routed command also runs locally ("hybrid", Q3). Remote receivers bypass the bus, so the owner never logs the command (GAP-19). + +## Decision + +- Each command type has **exactly one** handler, owned by exactly one service. +- A service either *owns* a command type (it has a local handler, and remote senders route to this service's endpoint) or *routes* it (no local handler is allowed). +- Startup validation and an analyzer (where both are in one compilation) reject a command type that is both handled and routed, or neither. +- A received command goes through the **same** command processor as a local one, so the owner appends, sequences and can replay its streams. + +## Alternatives + +Keep hybrid behind a flag. Rejected: it needs idempotency to stay correct, it surprises users, and there is no known use case. + +## Consequences + +(+) Clear ownership, and the history lives with the owner. (−) Moving a command between services means changing its route, which is a deliberate act. + +## Product sign-off (2026-11-10) + +Q2 and Q3 were accepted, with one added requirement for Q2: **querying events is modelled within the owning service's domain and business boundary.** Ownership therefore covers reads as well as writes. Only the owning service queries its streams. It does so through query models expressed in its own domain vocabulary ([ADR-023](ADR-023-sfql-query-language-with-cesql-predicates.md), [doc 14 §1.1](../Design/14-Query-Side-and-SFQL.md#11-query-ownership-the-service-boundary-q2)). + +## Traces + +Q2, Q3, GAP-19, CMD-13. diff --git a/docs/v3.0.0/engineering/ADRs/ADR-008-optimistic-concurrency-with-automatic-re-decide.md b/docs/v3.0.0/engineering/ADRs/ADR-008-optimistic-concurrency-with-automatic-re-decide.md new file mode 100644 index 00000000..8fdd658d --- /dev/null +++ b/docs/v3.0.0/engineering/ADRs/ADR-008-optimistic-concurrency-with-automatic-re-decide.md @@ -0,0 +1,26 @@ +# ADR-008: Optimistic concurrency with automatic re-decide + +| | | +|---|---| +| **Status** | Proposed | +| **Date** | 2026-11-10 | +| **Deciders** | v3 architecture review | + +## Context + +v2 computes `max(seq)+1` by loading the full history (O(n), racy) and detects conflicts only after side effects (GAP-05). + +## Decision + +- The load returns the stream version `v`. The append requires `expected = v`; the storage adapter enforces it atomically (a conditional update of the stream row, with a unique `(stream_id, version)` constraint as backstop). +- On conflict, the command processor discards the decision and re-runs load→decide, up to `MaxConcurrencyRetries` times (default 3), with full-jitter backoff (5–50 ms). +- Business invariants are re-checked against fresh state automatically. +- Callers may also pass `ExpectedVersion` explicitly to get *their own* optimistic check (for example, from an HTTP `If-Match` header). + +## Alternatives + +(a) Pessimistic locking (`SELECT … FOR UPDATE` on the stream): serialises writers and holds locks during `Decide`. Rejected for the default; it may become a per-aggregate option for very hot streams later. (b) Single-writer actors per stream: needs cluster membership, which is out of scope. + +## Consequences + +(+) O(1) sequencing. No partial side effects, because everything is in one transaction. (−) Hot streams can churn under heavy contention. The `eventstore.concurrency_conflicts` metric makes this visible, and partition-key routing reduces contention. diff --git a/docs/v3.0.0/engineering/ADRs/ADR-009-event-store-on-adonet-postgresql-first.md b/docs/v3.0.0/engineering/ADRs/ADR-009-event-store-on-adonet-postgresql-first.md new file mode 100644 index 00000000..876f2467 --- /dev/null +++ b/docs/v3.0.0/engineering/ADRs/ADR-009-event-store-on-adonet-postgresql-first.md @@ -0,0 +1,26 @@ +# ADR-009: Event store on raw ADO.NET; PostgreSQL first + +| | | +|---|---| +| **Status** | Proposed | +| **Date** | 2026-11-10 | +| **Deciders** | v3 architecture review | + +## Context + +v2 used EF Core for every store. An event store needs exact control over locking, ordering, batching and transaction IDs, which an ORM hides. + +## Decision + +- The event store, outbox, inbox, checkpoints, leases and dead letters are written with hand-tuned SQL over `NpgsqlDataSource` and `Microsoft.Data.SqlClient`. +- Each command commits in **one round trip**, using `NpgsqlBatch` or a single SQL Server batch. +- PostgreSQL is the reference implementation: `jsonb`, `xid8` and LISTEN/NOTIFY suit event sourcing well. SQL Server ships in the same milestone set (M4). +- EF Core is supported for **read models** (`SourceFlow.Storage.EntityFrameworkCore`), which can share the transaction through a connection the storage session provides. + +## Alternatives + +(a) EF Core everywhere: simpler for contributors, but slower and gives no control. (b) KurrentDB (EventStoreDB) only: excellent, but a second operational system for most teams. It remains a viable future adapter behind the same ports. + +## Consequences + +(+) Performance and correctness under our control. (−) SQL per provider must be maintained. The storage conformance kit protects against drift between providers. diff --git a/docs/v3.0.0/engineering/ADRs/ADR-010-commit-ordered-global-position-for-gap-free.md b/docs/v3.0.0/engineering/ADRs/ADR-010-commit-ordered-global-position-for-gap-free.md new file mode 100644 index 00000000..fb316bf3 --- /dev/null +++ b/docs/v3.0.0/engineering/ADRs/ADR-010-commit-ordered-global-position-for-gap-free.md @@ -0,0 +1,26 @@ +# ADR-010: Commit-ordered global position for gap-free subscriptions + +| | | +|---|---| +| **Status** | Proposed | +| **Date** | 2026-11-10 | +| **Deciders** | v3 architecture review | + +## Context + +An identity or sequence column is allocated at insert time, not at commit time. A reader can see position 12 committed while 11 is still in flight, move its checkpoint past 11, and lose it forever. v2 had no global reads at all. + +## Decision + +A subscription reads only events whose transaction is known to be complete, in an order that later commits can't change: +- **PostgreSQL**: each event stores `tx_id xid8 DEFAULT pg_current_xact_id()`. The position is `(tx_id, seq)`. Reads ask for `tx_id < pg_snapshot_xmin(pg_current_snapshot())` ordered by `(tx_id, seq)`. Every transaction below `xmin` has finished, so that prefix is final. +- **SQL Server**: each event has a `rowversion`. Reads ask for `rv < MIN_ACTIVE_ROWVERSION()` ordered by `rv`. +- An append always writes the stream row first, so the transaction id is acquired under the stream lock and per-stream order matches global order ([doc 05 §5](../Design/05-Event-Store-and-Persistence.md#5-global-ordering-and-the-safe-horizon)). + +## Alternatives + +(a) Gap detection with a timeout (wait N ms for missing numbers): heuristic, and loses events under long transactions. (b) A single-writer sequencer that assigns positions after commit: an extra hop and a single point of failure. + +## Consequences + +(+) Provably gap-free, with no timeouts. (−) A long-running transaction on the event database delays subscription progress (not correctness). The `subscription.horizon_age` metric exposes it. Position is a composite value type (`GlobalPosition`). diff --git a/docs/v3.0.0/engineering/ADRs/ADR-011-cloudevents-envelope-and-w3c-trace-context.md b/docs/v3.0.0/engineering/ADRs/ADR-011-cloudevents-envelope-and-w3c-trace-context.md new file mode 100644 index 00000000..eb57190f --- /dev/null +++ b/docs/v3.0.0/engineering/ADRs/ADR-011-cloudevents-envelope-and-w3c-trace-context.md @@ -0,0 +1,26 @@ +# ADR-011: CloudEvents 1.0 envelope and W3C trace context + +| | | +|---|---| +| **Status** | Proposed | +| **Date** | 2026-11-10 | +| **Deciders** | v3 architecture review | + +## Context + +v2 uses provider-specific attributes (`CommandType` as an AQN, `EventName`). Formats differ between providers, and trace context is mostly not propagated (CTL-03). + +## Decision + +- One `MessageEnvelope` model, mapped to CloudEvents 1.0 attributes: `id`, `source`, `type`, `specversion`, `subject`, `time` and `datacontenttype`. *As built (CR-60):* the version travels in `type` (`{name}.v{version}`, for example `bank.account.deposited.v1`), not in `dataschema`. +- SourceFlow extensions: `sfcorrelationid`, `sfcausationid`, `sfpartitionkey`, `sfstreamversion`, `sfenc`, `sftenant`. *As built:* also `sfactor` (who caused it), `sfattempt` (a delayed-retry re-send, doc 04 §9.2) and `sfheaders` (user headers, a JSON object). Extensions that don't fit a broker's attribute budget travel together in one `sfext` attribute (a JSON object); the required attributes never move there. +- Trace context uses the CloudEvents distributed-tracing extension (`traceparent`, `tracestate`). +- Transports use **binary content mode** (attributes in native headers, data in the body) where the broker supports enough headers, and structured mode otherwise. + +## Alternatives + +A bespoke envelope: no interoperability with non-.NET consumers. + +## Consequences + +(+) Interoperable with CloudEvents SDKs in any language, and observable end to end. (−) Header budget limits: SQS has 10 message attributes, which is enough for the 8–9 mapped attributes; anything more goes in structured mode. diff --git a/docs/v3.0.0/engineering/ADRs/ADR-012-one-middleware-abstraction-for-all-stages.md b/docs/v3.0.0/engineering/ADRs/ADR-012-one-middleware-abstraction-for-all-stages.md new file mode 100644 index 00000000..a439763d --- /dev/null +++ b/docs/v3.0.0/engineering/ADRs/ADR-012-one-middleware-abstraction-for-all-stages.md @@ -0,0 +1,24 @@ +# ADR-012: One middleware abstraction for all stages + +| | | +|---|---| +| **Status** | Proposed | +| **Date** | 2026-11-10 | +| **Deciders** | v3 architecture review | + +## Context + +v2 has four near-identical middleware interfaces (EXT-01), each building its own pipeline. + +## Decision + +One interface, `IMessageMiddleware`, with `ValueTask InvokeAsync(MessageContext ctx, MessageDelegate next)`. `ctx.Stage` is one of `Send`, `Handle`, `Receive`, `Publish` or `Project`. Registration can filter by stage and message type. Pipelines are composed once per (stage, message type) and cached in a `FrozenDictionary`. Built-in behaviours are themselves middleware: telemetry, logging scope, redaction, payload protection, inbox, validation and retry. + +**Amendment (WP-C.15, CR-46).** +- **All five stages run.** Send in the command sender; Handle in the command processor, for local and remote commands; Receive in the receive endpoint, after a built-in deserialisation step; Publish in the outbox relay; Project in the subscription engine. +- **Publish and Project run only when middleware is registered for them.** +- **Some built-ins stay in place.** Telemetry, the inbox, the transaction and retry stay where they were, not in the middleware chain (doc 04 §4.1). + +## Consequences + +(+) DRY, one mental model, cheap composition. (−) Middleware authors check `ctx.Stage` when they care about it. diff --git a/docs/v3.0.0/engineering/ADRs/ADR-013-use-platform-libraries-delete-bespoke-equivalents.md b/docs/v3.0.0/engineering/ADRs/ADR-013-use-platform-libraries-delete-bespoke-equivalents.md new file mode 100644 index 00000000..3ca501ca --- /dev/null +++ b/docs/v3.0.0/engineering/ADRs/ADR-013-use-platform-libraries-delete-bespoke-equivalents.md @@ -0,0 +1,37 @@ +# ADR-013: Use platform libraries; delete bespoke equivalents + +| | | +|---|---| +| **Status** | Proposed | +| **Date** | 2026-11-10 | +| **Deciders** | v3 architecture review | + +## Context + +v2 ships its own circuit breaker, log masker, buffer pools and telemetry wrappers. That code duplicates libraries the .NET platform already maintains, carries its own bugs (for example the metrics in GAP-14), and is unfamiliar to users who already know the platform versions. + +## Decision + +Replace every bespoke utility with the platform standard: + +| v2 bespoke | v3 uses | +|---|---| +| `CircuitBreaker`, ad-hoc retries | Polly v8 `ResiliencePipeline` through `Microsoft.Extensions.Resilience` | +| `SensitiveDataMasker` | `Microsoft.Extensions.Compliance.Redaction` with data-classification attributes | +| `DateTime.UtcNow` | `TimeProvider` (testable with `FakeTimeProvider`) | +| Manual metric and tracing wrappers | `ActivitySource`, `Meter`, `InstrumentAdvice`, OpenTelemetry SDK extension points | +| `ByteArrayPool`, `TaskBufferPool` | `ArrayPool`, `IBufferWriter`, `RecyclableMemoryStream` where streams are required | +| Reflection-based option binding | The configuration binding source generator and `[OptionsValidator]` | + +## Alternatives + +Keep and fix the v2 utilities. Rejected: no product requirement is met better by owning them (DRY, YAGNI). + +## Consequences + +- (+) Less code to own. Users already know these libraries. Bug fixes and security patches come from the platform. +- (−) A dependency on Polly, which is already the norm in .NET services. + +## Traces + +GAP-14, RES-01, SEC-04, PERF-01, PERF-02. diff --git a/docs/v3.0.0/engineering/ADRs/ADR-014-transport-spi-and-conformance-kit-parity-required.md b/docs/v3.0.0/engineering/ADRs/ADR-014-transport-spi-and-conformance-kit-parity-required.md new file mode 100644 index 00000000..cdb935ea --- /dev/null +++ b/docs/v3.0.0/engineering/ADRs/ADR-014-transport-spi-and-conformance-kit-parity-required.md @@ -0,0 +1,29 @@ +# ADR-014: Transport SPI and conformance kit; parity required for GA + +| | | +|---|---| +| **Status** | Accepted (product sign-off 2026-11-10) | +| **Date** | 2026-11-10 | +| **Deciders** | v3 architecture review | + +## Context + +v2 providers diverge in behaviour (doc 04 §10 parity matrix), ignore options (GAP-03), and the GCP fan-out is broken (GAP-13). + +## Decision + +- A small SPI ([doc 07](../Design/07-Cloud-Transports.md#2-transport-spi)): send, publish, receive (with settle operations), provision, and capabilities. +- Behaviour that the core can supply (retries, dead-lettering, inbox, encryption, telemetry) is implemented **once in the core**, not in each transport. +- A **Transport Conformance Kit** (about 40 scenarios) must pass for AWS SNS/SQS, Azure Service Bus, Google Pub/Sub and the in-memory transport before GA. + +## Consequences + +(+) Parity by construction; new transports are cheap. (−) The core can only rely on the lowest common denominator of broker features. Optional capabilities (native delay, sessions) are declared through `TransportCapabilities` and the core falls back when one is missing. + +## Product sign-off (2026-11-10) + +Q5 and Q6 are answered **"new version 3.0.0"**. AWS SNS/SQS, Azure Service Bus and Google Pub/Sub all ship GA in 3.0.0, and each one blocks the release until it passes the TCK. The earlier option of moving Azure to 3.1 is withdrawn ([doc 12 §5](../Design/12-Migration-Delivery-and-Traceability.md#5-delivery-plan)). + +## Traces + +Q5, Q6, GAP-01, GAP-02, GAP-03, GAP-13. diff --git a/docs/v3.0.0/engineering/ADRs/ADR-015-strongly-typed-caller-assigned-ids-uuidv7-default.md b/docs/v3.0.0/engineering/ADRs/ADR-015-strongly-typed-caller-assigned-ids-uuidv7-default.md new file mode 100644 index 00000000..9b647c6f --- /dev/null +++ b/docs/v3.0.0/engineering/ADRs/ADR-015-strongly-typed-caller-assigned-ids-uuidv7-default.md @@ -0,0 +1,34 @@ +# ADR-015: Strongly typed, caller-assigned ids (UUIDv7 default) + +| | | +|---|---| +| **Status** | Accepted (product sign-off 2026-11-10) | +| **Date** | 2026-11-10 | +| **Deciders** | v3 architecture review | + +## Context + +v2 uses `int Id` everywhere and logs new-entity commands under id 0 (GAP-20, Q4). + +## Decision + +- Aggregate ids are generated value types: `[StronglyTypedId] public readonly partial record struct AccountId(Guid Value);`. String and long variants are supported. +- The default factory is `Guid.CreateVersion7(timeProvider.GetUtcNow())`: time-ordered, which suits B-tree indexes. +- Ids are assigned **by the caller** before the command is sent. A default or empty id is rejected with `InvalidCommand`. + *As built (WP-C.8, CR-16):* so is any id that could not be read back from its stream id. `IStronglyTypedId.IsValid` is false for: + - a default id; + - an Int64 id that is zero or negative; + - a string id that is empty, too long, or contains a dash, whitespace or a control character. + + These checks apply to such an id: + - a send returns `Rejected` with `sourceflow.invalid_command`; + - `ToStreamSegment()` throws; + - the generated JSON converter refuses to write it; + - `StreamId.For` refuses a segment with a dash. + + So such an id is never stored (GEN-66, GEN-67). +- Stream id = `{aggregateName}-{id}`, for example `bank-account-0193a…`. + +## Consequences + +(+) Commands are idempotent and routable before they are handled; no database-generated keys. (−) Users must generate ids (one call). diff --git a/docs/v3.0.0/engineering/ADRs/ADR-016-projections-inline-or-async-with-partitioned-fenced.md b/docs/v3.0.0/engineering/ADRs/ADR-016-projections-inline-or-async-with-partitioned-fenced.md new file mode 100644 index 00000000..5809b7ac --- /dev/null +++ b/docs/v3.0.0/engineering/ADRs/ADR-016-projections-inline-or-async-with-partitioned-fenced.md @@ -0,0 +1,25 @@ +# ADR-016: Projections: inline or async, with partitioned, fenced subscriptions + +| | | +|---|---| +| **Status** | Accepted (product sign-off 2026-11-10) | +| **Date** | 2026-11-10 | +| **Deciders** | v3 architecture review | + +## Context + +v2 projects synchronously and in memory at publish time. If the process crashes between commit and projection, the event is lost; there is no checkpoint and no rebuild. + +## Decision + +- **Inline** projections run inside the command's transaction (same database), giving read-your-writes and strong consistency. Use them sparingly, because they add latency to the write. +- **Async** projections and process managers run on the subscription engine: + - read the commit-ordered log; + - P partitions per subscription (`hash(stream_id) mod P`), default 1; + - one lease per partition, carrying a fencing token; + - checkpoint written in the same transaction as the read-model changes when they share a database (exactly-once); otherwise idempotent writes keyed on the stream version. +- **Rebuilds** are blue/green: project into a new table version, catch up, then switch atomically. + +## Consequences + +(+) Durable, scalable, rebuildable read models. (−) Eventual consistency for async projections, which is explicit and measured (`subscription.lag`). diff --git a/docs/v3.0.0/engineering/ADRs/ADR-017-provisioning-modes-and-topology-as-data.md b/docs/v3.0.0/engineering/ADRs/ADR-017-provisioning-modes-and-topology-as-data.md new file mode 100644 index 00000000..a392d767 --- /dev/null +++ b/docs/v3.0.0/engineering/ADRs/ADR-017-provisioning-modes-and-topology-as-data.md @@ -0,0 +1,30 @@ +# ADR-017: Provisioning modes and topology as data + +| | | +|---|---| +| **Status** | Proposed | +| **Date** | 2026-11-10 | +| **Deciders** | v3 architecture review | + +## Context + +v2 always creates resources at startup, so runtime credentials need create permissions and resources drift from infrastructure-as-code (GAP-12). + +## Decision + +Routing produces a `Topology` model (endpoints, topics, subscriptions, dead-letter queues, ordering, encryption). `ProvisioningMode` is one of: +- `CreateIfMissing` (the default in Development); +- `Validate` (the default in Production): check existence and compatible configuration, and fail fast otherwise; +- `None`. + +`dotnet sourceflow topology export --format json` writes the model out for IaC. + +**Amendment (WP-C.13, CR-41).** +- **Encryption is a transport option.** It isn't part of the topology model. On AWS, `RequireEncryption` and `KmsKeyId` apply; on Google Cloud, `KmsKeyName`. +- **Validate checks it there.** It reports `Unencrypted` resources, and `CreateIfMissing` creates them encrypted. +- **Azure Service Bus is not checked.** Its customer-managed key is a namespace property that only Azure Resource Manager shows, so it is required at deployment instead, with Azure Policy or the IaC modules. +- **Existing resources are never changed.** On AWS, a queue policy keeps every statement except SourceFlow's own, which is merged by its Sid (CR-24). + +## Consequences + +(+) Least privilege, and drift is detected at startup. (−) Production teams must create resources through IaC or a release step. diff --git a/docs/v3.0.0/engineering/ADRs/ADR-018-business-rejections-are-values-not-exceptions.md b/docs/v3.0.0/engineering/ADRs/ADR-018-business-rejections-are-values-not-exceptions.md new file mode 100644 index 00000000..484be695 --- /dev/null +++ b/docs/v3.0.0/engineering/ADRs/ADR-018-business-rejections-are-values-not-exceptions.md @@ -0,0 +1,19 @@ +# ADR-018: Business rejections are values, not exceptions + +| | | +|---|---| +| **Status** | Proposed | +| **Date** | 2026-11-10 | +| **Deciders** | v3 architecture review | + +## Context + +v2 sagas signal business rule violations by throwing `ArgumentException` or `InvalidOperationException`. A rule violation is an expected outcome, not a defect. Using exceptions for it costs a stack capture on a common path. It also makes a rejection indistinguishable from an infrastructure failure, so cloud listeners retry an invalid command until it is dead-lettered. + +## Decision + +`Decide` returns `Decision.Reject(Error)` for expected rule violations. The command processor returns `CommandResult.Rejected(error)` and appends nothing. Exceptions are reserved for defects and infrastructure failures. For received commands, a rejection is a *handled* outcome: the inbox is recorded, the message is acknowledged, an optional `CommandRejected` reply or event is sent, and nothing is retried. + +## Consequences + +(+) No exception cost on a common path. Rejections are explicit in tests and telemetry (`outcome=rejected`). Poison retries of invalid commands are avoided. (−) Callers must handle the result. `CommandResult.ThrowIfNotAccepted()` exists for convenience. diff --git a/docs/v3.0.0/engineering/ADRs/ADR-019-telemetry-always-on-with-standard-semantic-conventions.md b/docs/v3.0.0/engineering/ADRs/ADR-019-telemetry-always-on-with-standard-semantic-conventions.md new file mode 100644 index 00000000..6f03c9d3 --- /dev/null +++ b/docs/v3.0.0/engineering/ADRs/ADR-019-telemetry-always-on-with-standard-semantic-conventions.md @@ -0,0 +1,21 @@ +# ADR-019: Telemetry always on, with standard semantic conventions + +| | | +|---|---| +| **Status** | Proposed | +| **Date** | 2026-11-10 | +| **Deciders** | v3 architecture review | + +## Context + +v2 telemetry is off by default (OBS-01), some metrics are wrong (GAP-14), and the cloud path isn't traced (CTL-03). + +## Decision + +- The `SourceFlow` ActivitySource and Meter are always created. Their cost without a listener is close to zero (a null-activity check, and instruments without listeners). +- Spans and metrics follow the OpenTelemetry messaging semantic conventions, at a pinned semconv version. Upgrades are opt-in through `OTEL_SEMCONV_STABILITY_OPT_IN`. +- High-cardinality values (stream id, message id) go only on spans, **never** as metric tags. + +## Consequences + +(+) Observability out of the box. (−) Semconv changes need managing. A pinned version and the opt-in env var follow OTel guidance. diff --git a/docs/v3.0.0/engineering/ADRs/ADR-020-process-managers-with-durable-state-and-timers.md b/docs/v3.0.0/engineering/ADRs/ADR-020-process-managers-with-durable-state-and-timers.md new file mode 100644 index 00000000..97ebe6c5 --- /dev/null +++ b/docs/v3.0.0/engineering/ADRs/ADR-020-process-managers-with-durable-state-and-timers.md @@ -0,0 +1,30 @@ +# ADR-020: Process managers with durable state and timers replace "Saga" + +| | | +|---|---| +| **Status** | Proposed | +| **Date** | 2026-11-10 | +| **Deciders** | v3 architecture review | + +## Context + +v2's "Saga" was really a command handler. Long-running coordination across aggregates or services had no first-class support, timeouts included. + +## Decision + +- A **process manager** is a record with `Reaction React(TEvent, ReactionContext)` methods. A `Reaction` carries the new state, commands to send, timers to schedule, and completion. +- Events are correlated to an instance through generated `CorrelateBy` functions. +- The instance state is persisted as a document with a version (optimistic concurrency) in the same transaction as its outbox commands, timers, inbox entry and checkpoint. +- Timers are scheduled outbox messages (`deliver_at`) delivered back to the process manager as `TimeoutElapsed`. + +## Alternatives + +(a) Event-sourced process state: possible, but adds storage and replay complexity without a clear benefit. (b) An external workflow engine (Temporal, Dapr Workflows): far heavier. Users can still integrate one. + +## Consequences + +(+) Coordination is durable and testable (Given events → Then commands). (−) A new concept for v2 users. The migration guide maps v2 Saga → v3 aggregate `Decide` + process manager. + +## Amendment (2026-11-10) + +Process managers may also be **generated from the workflow DSL** ([ADR-024](ADR-024-workflow-dsl-compiled-to-process-managers.md)). The runtime contract defined here is unchanged; the DSL adds declarative retries, compensation, a pivot and manual intervention on top of it. diff --git a/docs/v3.0.0/engineering/ADRs/ADR-021-dynamic-consistency-boundaries-dcb-in-3-1.md b/docs/v3.0.0/engineering/ADRs/ADR-021-dynamic-consistency-boundaries-dcb-in-3-1.md new file mode 100644 index 00000000..a4af16c2 --- /dev/null +++ b/docs/v3.0.0/engineering/ADRs/ADR-021-dynamic-consistency-boundaries-dcb-in-3-1.md @@ -0,0 +1,48 @@ +# ADR-021: Dynamic consistency boundaries (DCB) — schema-ready in 3.0, API in 3.1 + +| | | +|---|---| +| **Status** | Proposed | +| **Date** | 2026-11-10 | +| **Deciders** | v3 architecture review | + +## Context + +Some business rules span more than one aggregate: "a username is unique", "a course can't exceed capacity *and* a student can't exceed their course limit". With stream-per-aggregate consistency ([ADR-008](ADR-008-optimistic-concurrency-with-automatic-re-decide.md), ES-R2), teams handle these with oversized aggregates, reservation process managers, or eventual compensation. The industry has started adopting **Dynamic Consistency Boundaries**. Axon Framework 5 and Axon Server 2025.x support them, KurrentDB 25.1 added multi-stream appends, and Cratis Chronicle and the dcb.events community specify them ([competitive analysis](../Design/13-Competitive-Analysis.md)). In DCB, a decision reads the events matching a *query* (event types + tags), and the append succeeds only if no new matching event has been committed since the read. + +## Decision + +**3.0 (schema-ready, no new API):** +- `events.tags text[] NOT NULL DEFAULT '{}'`, with a `GIN (tags)` index created when the opt-in `EnableTags` is set. +- Event members can be marked `[Tag("account")]`. The generator emits `account:{value}` tags at append time. Stream events get the implicit tag `stream:{stream_id}`. +- Events written by 3.0 are therefore DCB-queryable in 3.1 **without data migration**. + +**3.1 (API):** +```csharp +var query = EventQuery.Types().Tagged($"course:{c}", $"student:{s}"); +var model = await store.ReadAsync(query, ct); // returns events + position P +var events = SubscriptionDecider.Decide(model.Fold(), command); // pure, as ADR-003 +await store.AppendAsync(events, AppendCondition.NoneMatching(query, after: model.Position), ct); +``` +- **PostgreSQL implementation.** + 1. Take `pg_advisory_xact_lock(hash(tag))` for each tag in the condition, in sorted order (deadlock-free). Advisory locks don't assign a transaction id, so ES-R1 still holds. + 2. Check `NOT EXISTS (… WHERE tags && @tags AND event_type = ANY(@types) AND (tx_id, seq) > @after)`. + 3. Insert. + + Every append that carries tags takes the same locks, so stream-based and DCB writers serialise on shared tags. **SQL Server** uses `sp_getapplock` per tag in the same way. +- Streams remain the default model. DCB is opt-in per decision (an `[DcbDecider]` attribute and a generated runner). + +## Alternatives + +- (a) Multi-stream appends with expected versions per stream (KurrentDB's approach). Simpler, but it still requires choosing streams up front and doesn't express "no new matching events". +- (b) Ship DCB in 3.0. Rejected for schedule risk: it needs its own conformance tests and ordering proof. +- (c) Ignore DCB. Rejected, because it is becoming a market expectation. + +## Consequences + +- (+) Cross-entity invariants without oversized aggregates. The 3.0 data is forward-compatible. +- (−) Lock and GIN-index overhead for tagged appends, measured in the 3.1 benchmarks. Tag cardinality guidance is needed (avoid hot tags). + +## Traces + +Competitive analysis C2. Product Q4 (id strategy) and Q7 (consistency) context. diff --git a/docs/v3.0.0/engineering/ADRs/ADR-022-conjoined-multi-tenancy-with-row-level-security.md b/docs/v3.0.0/engineering/ADRs/ADR-022-conjoined-multi-tenancy-with-row-level-security.md new file mode 100644 index 00000000..9e041ded --- /dev/null +++ b/docs/v3.0.0/engineering/ADRs/ADR-022-conjoined-multi-tenancy-with-row-level-security.md @@ -0,0 +1,36 @@ +# ADR-022: Conjoined multi-tenancy with row-level security in 3.0 + +| | | +|---|---| +| **Status** | Proposed | +| **Date** | 2026-11-10 | +| **Deciders** | v3 architecture review | + +## Context + +The original design treated multi-tenancy as YAGNI and only passed a `tenant` header through ([doc 01 §4](../Design/01-Architecture-Overview.md#4-deliberately-not-built-yagni-register)). The competitive analysis (C1) shows mature competitors (Marten, Wolverine, Axon) provide it, and SaaS teams treat it as a prerequisite. Bolting it on later would change primary keys in every table: a breaking schema migration. + +## Decision + +**Conjoined tenancy** (shared tables, tenant column) is built into the 3.0 schema and runtime: + +- `tenant_id text NOT NULL DEFAULT '-'` on `streams`, `events`, `snapshots`, `documents`, `process_instances`, `inbox` and `outbox`. Keys become `(tenant_id, stream_id)`, `(tenant_id, collection, id)`, and so on. The single-tenant default `'-'` costs almost nothing. +- `ITenantResolver` (for example from claims or a header) sets the ambient tenant for `SendAsync`. The tenant travels in the envelope (`sftenant`) and is restored on receive. Stream ids are tenant-scoped. +- **PostgreSQL row-level security** (opt-in, `TenantIsolation.RowLevelSecurity`): policies `USING (tenant_id = current_setting('sourceflow.tenant'))` on every table. The session runs `SET LOCAL sourceflow.tenant` per transaction. Subscription workers run as a role with `BYPASSRLS` because they process every tenant. A bug in user code or in a query (doc 14) can't leak across tenants. +- The bucket is computed from `(tenant_id, stream_id)`, so tenants spread across partitions. +- Database-per-tenant is a 3.x item, behind the same `ITenantResolver`, using `NpgsqlDataSource` per tenant. + +## Alternatives + +- (a) Database-per-tenant only: strong isolation, but a heavy operational load for many small tenants. +- (b) Schema-per-tenant: migrations multiply. +- (c) Stay with YAGNI: rejected because of the schema-break cost later. + +## Consequences + +- (+) SaaS-ready, and RLS gives defence in depth. +- (−) Wider keys (a few bytes per row). Noisy-neighbour risk in shared tables, mitigated by per-tenant metrics tags (bounded cardinality: top-N tenants, others aggregated) and the 3.x database-per-tenant path. + +## Traces + +Competitive analysis C1. Doc 01 YAGNI register updated. diff --git a/docs/v3.0.0/engineering/ADRs/ADR-023-sfql-query-language-with-cesql-predicates.md b/docs/v3.0.0/engineering/ADRs/ADR-023-sfql-query-language-with-cesql-predicates.md new file mode 100644 index 00000000..401b5ef3 --- /dev/null +++ b/docs/v3.0.0/engineering/ADRs/ADR-023-sfql-query-language-with-cesql-predicates.md @@ -0,0 +1,62 @@ +# ADR-023: SFQL — a read-only query language with CESQL-compatible predicates + +| | | +|---|---| +| **Status** | Accepted (product sign-off 2026-11-10) | +| **Date** | 2026-11-10 | +| **Deciders** | v3 architecture review | + +## Context + +In CQRS, the read side is separate from the write side. Today users can query read models only with their own SQL or EF Core, and they have no supported way to query the **event log** itself: audit ("every deposit over £10k last week"), tracing ("everything in correlation X"), analytics, support and debugging. Raw SQL against `sourceflow.events` couples users to: + +- the physical schema (`jsonb` paths, provider differences); +- versioning (renamed fields across event versions); +- encryption (crypto-shredded fields are ciphertext); +- tenancy (it is easy to forget the tenant predicate). + +It also gives no cost or safety guard. The original design listed a query language as YAGNI. The product owner has now explicitly requested one, which supersedes that entry. + +## Decision + +Define **SFQL (SourceFlow Query Language)**, specified in [doc 14](../Design/14-Query-Side-and-SFQL.md): + +1. **Read-only by grammar.** There is no DML or DDL production, so a statement can't write. +2. **Logical, not physical.** It addresses logical event types, schema fields, read-model collections and aggregates, never tables or JSON paths. +3. **Pipeline syntax.** `from | where … | project … | summarize … | order by … | take …`. It is easy to read, compose and parse with a hand-written recursive-descent parser (no dependency). +4. **CESQL v1 for expressions.** Predicates use the CloudEvents SQL Expression Language syntax and built-in functions. Over envelope attributes they evaluate with CESQL semantics, so **the same filter string can drive subscription filters** (doc 07) and queries. SFQL adds parameters, durations, decimals, timestamps, `between`, `is null` and data-path access. +5. **Statically checked** against a generated **event schema catalog** (JSON Schema 2020-12 with `x-sourceflow` extensions). Field renames across versions are resolved by the binder. +6. **Compiled** to parameterised SQL per provider (PostgreSQL, SQL Server) and interpreted for the in-memory store. Policies (tenant, PII, cost, permissions) are applied before execution. +7. **Separate read path.** A dedicated read-only connection (replicas allowed), a SELECT-only database role, and analyzers stop query use inside aggregate or projection code. + +## Alternatives + +| Option | Strengths | Why not chosen (as the primary language) | +|--------|-----------|------------------------------------------| +| Raw SQL | Full power, no new language | Physical coupling, provider differences, no versioning, PII or tenant safety, injection risk. Still available as an escape hatch for read models. | +| GraphQL | Great for UI read APIs | Weak at log, temporal and aggregate queries. Needs a schema server. A 3.x adapter over read models remains possible. | +| OData | Standard REST querying | Entity-centric. Awkward over a heterogeneous event log. | +| KQL / PRQL | Excellent pipeline ergonomics (SFQL borrows the shape) | Not embeddable as a standard, or tied to vendors. No CloudEvents alignment. | +| EventQL (EventSourcingDB) | Purpose-built for events | Tied to one database product. | +| CESQL alone | CNCF standard, CloudEvents-native | Boolean filter expressions only: no projection, aggregation, ordering or paging. **Adopted as SFQL's expression sublanguage.** | +| LINQ `IQueryable` provider | Familiar to C# developers | Large provider surface, runtime-only, not usable from CLI or HTTP. Offered instead as a *typed builder* that emits SFQL ASTs. | + +## Consequences + +- (+) One safe, portable, schema-aware way to query events and read models from C#, the CLI, or an opt-in HTTP endpoint. Interoperable filter syntax with CloudEvents tooling. +- (−) A language to specify, test and evolve. This is mitigated by a small core grammar, golden-file conformance tests, the CloudEvents CESQL TCK, and a versioned spec (`sfql/1`). + +## Product sign-off (2026-11-10): queries stay inside the service boundary + +Q2 was accepted with the requirement that **event querying is modelled within the owning service's domain and business boundary**. SFQL therefore: +1. resolves only the **service's own** catalog: its event types, its read models, its aggregates; +2. never reads another service's event log. Foreign facts are queryable only after the service has turned received integration events into its **own** read models; +3. is published to other services as a **named domain query** (a contract in the service's vocabulary), not as free-form access to its events ([doc 14 §1.1](../Design/14-Query-Side-and-SFQL.md#11-query-ownership-the-service-boundary-q2)). + +## Traces + +Q2 (sign-off). Product request (query side for CQRS). Competitive analysis (temporal queries C4). Doc 01 YAGNI register updated. + +## Amendment (2026-11-10) + +Superseded in part by [ADR-026](ADR-026-per-service-query-api-with-sql-syntax-and-injection-proof-compilation.md). SFQL gains a **SQL syntax** (a read-only `SELECT` subset) and **bounded joins**. Every service exposes the query API, with layered injection defence. Raw SQL **pass-through** remains rejected, as decided above: the SQL syntax is parsed into SFQL's own AST. diff --git a/docs/v3.0.0/engineering/ADRs/ADR-024-workflow-dsl-compiled-to-process-managers.md b/docs/v3.0.0/engineering/ADRs/ADR-024-workflow-dsl-compiled-to-process-managers.md new file mode 100644 index 00000000..058d0039 --- /dev/null +++ b/docs/v3.0.0/engineering/ADRs/ADR-024-workflow-dsl-compiled-to-process-managers.md @@ -0,0 +1,43 @@ +# ADR-024: Workflow DSL (YAML) compiled to process managers + +| | | +|---|---| +| **Status** | Proposed | +| **Date** | 2026-11-10 | +| **Deciders** | v3 architecture review | + +## Context + +The product now requires a saga DSL and a visual designer for workflows that span the services of a business domain. The workflows must show success, failure, retry and rollback paths ([product doc 07](../../../product/07-Workflow-Designer-Requirements.md)). The original design had put this in the YAGNI register ([doc 01 §4](../Design/01-Architecture-Overview.md#4-deliberately-not-built-yagni-register)), with "repeated user demand" as the trigger; that trigger has now occurred. + +v3 already has a durable process-manager runtime ([ADR-020](ADR-020-process-managers-with-durable-state-and-timers.md)): state with optimistic concurrency, outbox commands, durable timers and inbox deduplication. Command ownership is fixed ([ADR-007](ADR-007-single-command-ownership-route-local-xor-remote.md)), and rejections are values that can be replied to the sender ([ADR-018](ADR-018-business-rejections-are-values-not-exceptions.md)). + +## Decision + +1. **The source of truth is a small, versioned YAML DSL** (`sourceflow.workflow/1`), validated by a JSON Schema plus semantic rules WF-V01…V16. It has explicit domain concepts: owner service, steps sending **commands to their owning service**, awaited events, rejection codes, timeouts, business retries, compensations, a pivot, and manual intervention. +2. **Compile, don't interpret.** The Roslyn `WorkflowGenerator` turns each workflow into an ordinary `[ProcessManager]` in the owning service. There is no second execution model, and the runtime, storage, telemetry and tests are the same as for hand-written process managers. +3. **One semantic core.** `SourceFlow.Studio` (C#) implements parsing, validation, simulation and path enumeration. The generator, the CLI and the browser (through WebAssembly, ADR-025) all use it. +4. **Expressions use CESQL** (shared with SFQL and subscription filters). Anything more complex uses `$hook` partial methods written in C#, which must be pure. +5. **Versioning:** `name@version` side by side. In-flight instances finish on the version they started on. + +## Alternatives + +| Option | Why not chosen | +|--------|----------------| +| C# fluent state-machine DSL (MassTransit-style) | Code-first DSLs don't round-trip losslessly with a visual designer, and domain experts can't review them | +| A runtime workflow interpreter (engine) | A second execution model beside process managers (violates DRY and ADR-020). Harder to version in-flight instances, to make AOT-safe and to test | +| BPMN 2.0 as the DSL | Verbose XML; generic tasks don't map to aggregate-owned commands and rejection codes. **Offered as an export** | +| CNCF Serverless Workflow 1.0 | Generic function and HTTP orchestration. Commands, aggregates and compensation would need extensions, losing compile-time checks against manifests. A possible future export | +| AWS Step Functions ASL | Vendor-specific; we need a cloud-neutral format | +| SCXML / XState statecharts | Strong state semantics but no domain concepts. Statechart *visual conventions* are borrowed | + +## Consequences + +- (+) Workflows can be reviewed, diffed and tested, and their failure paths are validated at build time. Zero extra runtime machinery. +- (+) Simulation in the designer matches production exactly, because the code is shared and differential tests check it. +- (−) A DSL schema to maintain and evolve (versioned, with a migration command). +- (−) The generator now compiles the `SourceFlow.Studio` DSL sources and bundles YamlDotNet in the analyzer folder of `SourceFlow.Net`, which has to be packaged carefully (implementation risk IR-14; [ADR-027 §6](ADR-027-single-core-package-with-extensibility-spis-and-categorised-adapters.md#6-studio-and-the-generator-share-one-dsl-implementation)). + +## Traces + +WFD-20…29, WFD-NFR-1, WFD-NFR-2, WFD-NFR-6. diff --git a/docs/v3.0.0/engineering/ADRs/ADR-025-studio-react-spa-with-shared-wasm-core.md b/docs/v3.0.0/engineering/ADRs/ADR-025-studio-react-spa-with-shared-wasm-core.md new file mode 100644 index 00000000..36710ae3 --- /dev/null +++ b/docs/v3.0.0/engineering/ADRs/ADR-025-studio-react-spa-with-shared-wasm-core.md @@ -0,0 +1,43 @@ +# ADR-025: SourceFlow Studio is a React SPA with a shared WebAssembly core, hosted locally + +| | | +|---|---| +| **Status** | Proposed | +| **Date** | 2026-11-10 | +| **Deciders** | v3 architecture review | + +## Context + +The product requires the visual designer to be built in **React** (product doc 07, WFD-30…37) as a separate utility. Validation and simulation in the browser must give exactly the same results as the build-time generator (WFD-NFR-2). The tool must work offline and against git (WFD-NFR-5), and must also render read-only diagrams for documentation and pull requests (WFD-36). + +## Decision + +1. **A React 19 + TypeScript single-page application** (`web/`, npm `@sourceflow/studio`). It uses React Flow + elkjs for graphs, Monaco + monaco-yaml for text, and Radix primitives for accessibility. +2. **The semantic core is the C# `SourceFlow.Studio` library compiled to WebAssembly** (`SourceFlow.Studio.Wasm`, `[JSExport]`), running in a Web Worker. TypeScript never re-implements parsing, validation or simulation. +3. **Hosting**: + - **local**: `dotnet sourceflow studio` serves the embedded SPA and a loopback-only file API over the workspace; + - **static**: a read-only site built from a workspace; + - **CI**: a GitHub Action renders before/after SVGs for PRs. + + There is no server database: **git is the store**. +4. **The DSL text is the model.** Visual edits produce minimal YAML edits through a CST-preserving writer. + +## Alternatives + +| Option | Why not chosen | +|--------|----------------| +| Blazor WebAssembly UI | The product requirement is React. React Flow and elkjs are also stronger ecosystems for graph editors | +| Re-implementing the core in TypeScript | Two implementations of workflow semantics would drift. Shared golden tests reduce the risk but don't remove it (violates DRY) | +| Server-side validation over HTTP | Needs a running backend for the static and PR modes; latency while editing | +| Electron desktop app | Heavier to distribute; the browser plus a local `dotnet tool` covers the need | +| Hosted SaaS designer | Security and privacy concerns (code topology leaves the network); out of scope | + +## Consequences + +- (+) Identical semantics everywhere. Studio works offline. Diagrams render in docs and PRs. +- (−) The WASM bundle is a few MB, loaded lazily in a worker with a cached download (implementation risk IR-15). Requires .NET WASM build tooling in CI. +- (−) The team needs React/TypeScript skills: a dedicated lane in the implementation plan (lane F). + +## Traces + +WFD-30…37, WFD-NFR-2…5. diff --git a/docs/v3.0.0/engineering/ADRs/ADR-026-per-service-query-api-with-sql-syntax-and-injection-proof-compilation.md b/docs/v3.0.0/engineering/ADRs/ADR-026-per-service-query-api-with-sql-syntax-and-injection-proof-compilation.md new file mode 100644 index 00000000..cf4942c1 --- /dev/null +++ b/docs/v3.0.0/engineering/ADRs/ADR-026-per-service-query-api-with-sql-syntax-and-injection-proof-compilation.md @@ -0,0 +1,45 @@ +# ADR-026: Per-service query API with a SQL syntax and injection-proof compilation + +| | | +|---|---| +| **Status** | Proposed | +| **Date** | 2026-11-10 | +| **Deciders** | v3 architecture review | + +## Context + +The product now requires **every service** to expose a query API for retrieving its data. The API must validate syntax, guard against SQL and script injection, and support the basic SQL constructs: joins, filtering, grouping and ordering. SFQL ([ADR-023](ADR-023-sfql-query-language-with-cesql-predicates.md)) was pipeline-only, allowed key lookups but no general joins, and its HTTP endpoint was opt-in with ad-hoc queries disabled by default ([doc 14](../Design/14-Query-Side-and-SFQL.md)). Queries must still stay inside the owning service's boundary (product Q2, rules Q-B1…B6). + +## Decision + +1. **A query API in every service.** `MapSourceFlowQueryApi()` provides `POST /query`, `POST /query/validate`, `POST /query/explain` and `GET /query/schema`, next to the named domain queries. Mapping without an authorization policy is a startup error (fail closed). Ad-hoc queries need `sourceflow.query.adhoc`; named domain queries remain the stable contract (Q-B4). +2. **A SQL syntax for SFQL**: a read-only `SELECT` subset with `DISTINCT`, `INNER`/`LEFT` joins, `WHERE`, `GROUP BY`/`HAVING`, `ORDER BY … NULLS FIRST|LAST`, `LIMIT`/`OFFSET`, `CASE`/`CAST`/`COALESCE`, and `IN`/`EXISTS` subqueries (depth 1). It parses into the **same AST** as the pipeline syntax, which gains a `join` stage. Binder, policy, compilers and security are shared. +3. **Bounded joins.** Equality joins with an indexed key on at least one side; at most 3 joins (cap 5); tenant equality added automatically; no personal-data join keys; event-to-event joins only when both sides are bounded. +4. **Injection-proof by construction, with defence in depth**: + - the API is never a pass-through, and the grammar is an allow-list; + - generated SQL contains only templates, catalog-derived identifiers and placeholders, and **every** value from the request is a bound parameter; + - name resolution is catalog-only, and functions are allow-listed; + - no dynamic code evaluation; + - safe response encoding and headers, and errors never echo input; + - read-only role and transaction, row-level security, limits, cost ceiling, and rate limiting. + +## Alternatives + +| Option | Why not chosen | +|--------|----------------| +| Pass SQL through with a "blocklist" of dangerous keywords | Blocklists are bypassable (encodings, comments, dialect tricks). We parse into an AST and generate SQL ourselves, which is an allow-list by construction | +| Pass SQL through on a read-only database role only | Prevents writes, but not data exfiltration across tenants or services, schema discovery, or DoS. It also exposes the physical schema (breaks Q-R4) | +| GraphQL | Joins via resolvers multiply round trips. Weak for grouping and analytical queries. A second language next to SFQL | +| OData `$filter/$expand/$apply` | Supports grouping and expansion but is entity-centric and verbose. Customers asked for SQL constructs | +| Full SQL (unions, CTEs, window functions) in 3.0 | More surface to secure and test. Candidates for `sfql/1.1` once usage justifies them | + +## Consequences + +- (+) A familiar SQL syntax for analysts and BI tools, without giving up the logical model, service boundary, tenancy or personal-data rules. +- (+) A single security argument for both syntaxes. +- (−) A larger grammar and compiler, plus join planning per provider. This is mitigated by cross-provider equivalence tests, the injection corpus, fuzzing, the no-literal property test and DAST. +- (−) Ad-hoc joins can be expensive. This is mitigated by the indexed-key rule, the cost ceiling, limits and rate limiting. + +## Traces + +Product request (2026-11-10): query API per service with injection protection and basic SQL constructs. Doc 14 §4, §7.3, §9. Amends [ADR-023](ADR-023-sfql-query-language-with-cesql-predicates.md). Q2 boundary rules unchanged. diff --git a/docs/v3.0.0/engineering/ADRs/ADR-027-single-core-package-with-extensibility-spis-and-categorised-adapters.md b/docs/v3.0.0/engineering/ADRs/ADR-027-single-core-package-with-extensibility-spis-and-categorised-adapters.md new file mode 100644 index 00000000..11cf827d --- /dev/null +++ b/docs/v3.0.0/engineering/ADRs/ADR-027-single-core-package-with-extensibility-spis-and-categorised-adapters.md @@ -0,0 +1,151 @@ +# ADR-027: Single core package with extensibility SPIs, and categorised adapter packages + +| | | +|---|---| +| **Status** | Accepted | +| **Date** | 2026-11-11 | +| **Deciders** | v3 architecture review; product direction during WP-0.2 | + +## Context + +The first v3 design split the library into 18 packages. Among them were `SourceFlow.Abstractions` (domain contracts), `SourceFlow.Net` (runtime), one package per transport (`AmazonSqs`, `AzureServiceBus`, `GooglePubSub`), one per KMS (`Security.AwsKms`, `.AzureKeyVault`, `.GoogleKms`), `SourceFlow.OpenTelemetry`, `SourceFlow.Workflows.Abstractions`, `SourceFlow.Workflows` and `SourceFlow.Workflows.Wasm`. + +During the repository scaffold (WP-0.2), product direction asked for a smaller set: + +- **Categorise and consolidate** the projects. +- Make the **core a single project**, with extensibility interfaces for cloud, persistence, security and so on. +- Name the storage adapters `SourceFlow.Storage.*`. +- Name the workflow designer project `SourceFlow.Studio`. +- **Target .NET 10 only.** + +The split mainly existed so that domain assemblies would not reference the runtime. That has little value: the runtime's only dependencies are `Microsoft.Extensions.*` abstractions, and an architecture rule can enforce domain purity just as well as a package boundary can (see ARCH-04 below). + +## Decision + +### 1. One core package: `SourceFlow.Net` + +`SourceFlow.Net` contains the domain contracts, the runtime engine and every extensibility SPI. Adapter packages implement the SPIs. It absorbs the former `SourceFlow.Abstractions`, `SourceFlow.Workflows.Abstractions` and `SourceFlow.OpenTelemetry`. + +| Namespace | Role | Typical implementers | +|-----------|------|----------------------| +| `SourceFlow` | Domain contracts: `ICommand`, `IEvent`, attributes, `Decision`, `Reaction`, `Error`, ids | Domain code | +| `SourceFlow.Messaging` | Envelope, type registry, serializer contracts | — | +| `SourceFlow.Storage` | **Persistence SPI**: `IEventStore`, `IEventLogReader`, `IStorageSession`, `IOutboxStore`, `IInboxStore`, `ICheckpointStore`, `ILeaseManager`, `IDeadLetterStore`, `IDocumentStore`, plus the in-memory adapter | `SourceFlow.Storage.*` | +| `SourceFlow.Transport` | **Cloud and broker SPI**: `ITransport`, `ITransportReceiver`, `ITransportProvisioner`, `TransportCapabilities`, plus the in-memory transport | `SourceFlow.Cloud.*` | +| `SourceFlow.Security` | **Security SPI**: `IKeyProvider`, `IPayloadProtector`, `PayloadProtectionMiddleware`, personal-data erasure | `SourceFlow.Cloud.*` (KMS) | +| `SourceFlow.Query` | **Query SPI**: SFQL parser, binder and in-memory interpreter, plus `ISqlDialect` and the compiler contract | `SourceFlow.Storage.PostgreSQL`, `.SqlServer` | +| `SourceFlow.Pipeline` | `IMessageMiddleware` (ADR-012) | User code | +| `SourceFlow.Diagnostics` | `ActivitySource`, `Meter`, semantic-convention constants, health checks | — | +| `SourceFlow.Workflows` | Runtime types used by generated workflows: status, compensation entries, operator commands | Generated code | +| `SourceFlow.Hosting` | `SourceFlowBuilder` with `Use*` slots for each SPI, plus options validation | Adapter `Use*` extensions | +| `SourceFlow.Runtime` | The engine (internal) | — | + +**Amendment (WP-C.18, CR-59).** `SourceFlow.Runtime` is a public SPI namespace too, not only the internal engine. +- **The adapters' SPI lives here.** `StoragePorts`, `ITenantResolver`, `IActorAccessor`, `RoutingTable` and the routing builders are the contracts adapters and hosts use. +- **Some engine types are public.** `SourceFlowRuntime`, `CommandProcessor`, `OutboxRelay` and `SourceFlowOptions` are public so the testing library, the CLI and the adapters can reach them. Their surface is pinned by the public API approvals. +- **Why not split the namespace.** It would break every adapter for no behaviour change, so the namespace stays as built. + +### 2. The generator stays a separate build project, inside the core package + +`src/Core/SourceFlow.Generators` is a Roslyn component, so it must target `netstandard2.0` (RS1041). It loads into the compiler and the IDE, and it must not carry `Microsoft.CodeAnalysis` into applications. + +- It is packed into `SourceFlow.Net` under `analyzers/dotnet/cs` and is never published on its own. +- **It is the only project in v3 that does not target `net10.0`.** Every package ships `lib/net10.0` only. + +### 3. Adapter and utility packages, by category + +| Category (`src/…`) | Package | Contents | +|--------------------|---------|----------| +| `Core` | `SourceFlow.Net` | §1 (with the generator) | +| `Storage` | `SourceFlow.Storage.PostgreSQL` | Persistence SPI on PostgreSQL, plus the SFQL PostgreSQL compiler | +| `Storage` | `SourceFlow.Storage.SqlServer` | Persistence SPI on SQL Server, plus the SFQL SQL Server compiler | +| `Storage` | `SourceFlow.Storage.EntityFrameworkCore` | EF Core read-model projections bound to the storage session | +| `Cloud` | `SourceFlow.Cloud.Aws` | SNS/SQS transport and provisioner, AWS KMS `IKeyProvider`, health checks | +| `Cloud` | `SourceFlow.Cloud.Azure` | Service Bus transport and provisioner, Key Vault `IKeyProvider`, health checks | +| `Cloud` | `SourceFlow.Cloud.Gcp` | Pub/Sub transport and provisioner, Cloud KMS `IKeyProvider`, health checks | +| `Hosting` | `SourceFlow.AspNetCore` | `MapCommand()` and the query API endpoint | +| `Tooling` | `SourceFlow.Testing` | Specs, test host, conformance-kit bases | +| `Tooling` | `SourceFlow.Tool` | `dotnet sourceflow` CLI | +| `Workflows` | `SourceFlow.Studio` | Workflow DSL semantic core: model, YAML reader, validator, simulator, path enumerator, exporters, manifest model | +| `Workflows` | `SourceFlow.Studio.Wasm` | `browser-wasm` `[JSExport]` facade. A build output embedded in the `@sourceflow/studio` npm package and in the tool, not published to NuGet | + +That is **11 NuGet packages** instead of 18. + +**One cloud package per cloud.** A team that adopts a cloud almost always uses both its broker and its KMS, so each cloud gets one package. +- Registration stays explicit and independent: `UseAwsTransport()` and `UseAwsKms()` are separate calls. +- Mixing clouds still works. For example, AWS KMS with Azure Service Bus references both cloud packages. The cost is unused SDK assemblies, not changed behaviour. + +### 4. Dependency rules (replace design doc 01 §5) + +| Rule | Statement | +|------|-----------| +| ARCH-01 | `SourceFlow.Net` references only the BCL, `Microsoft.Extensions.*`, Polly and `Microsoft.Extensions.Resilience`. It has no cloud SDK, database driver or OpenTelemetry SDK. | +| ARCH-02 | `SourceFlow.Net` never references an adapter package, not even through reflection. | +| ARCH-03 | Adapter packages reference `SourceFlow.Net` and their own SDK only. Adapters never reference each other. | +| ARCH-04 | Domain assemblies reference only `SourceFlow.Net`. They use types from the `SourceFlow` and `SourceFlow.Workflows` namespaces only, never `Runtime`, `Storage`, `Transport`, `Security`, `Hosting` or `Diagnostics`. This keeps domain code free of infrastructure without a separate package. | + +ARCH-05 to ARCH-08 are unchanged (plan 06 §9). + +### 5. OpenTelemetry without an extra package + +The core emits through `System.Diagnostics` (an `ActivitySource` and a `Meter`, both named `SourceFlow`). It declares histogram bucket boundaries with `InstrumentAdvice` (.NET 9+), so no SDK views are needed. + +Applications subscribe with the OpenTelemetry SDK they already reference: + +```csharp +.WithTracing(t => t.AddSource(SourceFlowTelemetry.ActivitySourceName)) +.WithMetrics(m => m.AddMeter(SourceFlowTelemetry.MeterName)) +``` + +### 6. Studio and the generator share one DSL implementation + +`SourceFlow.Studio` targets `net10.0`. The generator compiles the same source files, linked from `src/Workflows/SourceFlow.Studio/Dsl/**`, into its own `netstandard2.0` assembly, with YamlDotNet bundled. + +This is one implementation compiled twice, so there is still only one definition of the semantics (WFD-NFR-2). It avoids a second multi-targeted package. The `Dsl` folder is restricted to C# features that compile on `netstandard2.0`, with polyfills for `init`, records and the nullable attributes. Implementation risk IR-14 still applies. + +### 7. Repository and test layout + +Source projects live under `src///`. Test projects are one per category, and traits select subsets in CI. + +| Test project | Covers | +|--------------|--------| +| `tests/Core/SourceFlow.Core.Tests` | Contracts, runtime, in-memory SCK and TCK, security middleware, diagnostics | +| `tests/Core/SourceFlow.Generators.Tests` | Generators and analyzers, including the workflow generator | +| `tests/Storage/SourceFlow.Storage.Tests` | SCK on PostgreSQL, SQL Server and EF Core; SFQL compilers (`Provider` trait) | +| `tests/Cloud/SourceFlow.Cloud.Tests` | Transport unit tests, TCK and KMS round trips (`Cloud` trait) | +| `tests/Hosting/SourceFlow.Hosting.Tests` | ASP.NET Core endpoints | +| `tests/Tooling/SourceFlow.Tooling.Tests` | Testing toolkit, CLI and v2 migration | +| `tests/Workflows/SourceFlow.Studio.Tests` | DSL, manifests, golden and differential suites, WASM facade | +| `tests/EndToEnd/SourceFlow.EndToEnd.Tests` | Bank E2E, workflow E2E and chaos (`Category` trait) | +| `tests/Architecture/SourceFlow.Architecture.Tests` | ARCH-01 to ARCH-08 | + +`InternalsVisibleTo` is granted to both `.Tests` and `SourceFlow..Tests`. + +### 8. Package identities + +| Package | Relation to v2 | +|---------|----------------| +| `SourceFlow.Net` | Keeps the v2 ID. | +| `SourceFlow.Cloud.Aws` | Continues `SourceFlow.Cloud.AWS`. NuGet IDs are case-insensitive, so these are the same package. | +| `SourceFlow.Cloud.Gcp` | Continues `SourceFlow.Cloud.GCP`. | +| `SourceFlow.Cloud.Azure` | Was never published from `master`. | +| `SourceFlow.Storage.EntityFrameworkCore` and `SourceFlow.Storage.PostgreSQL` | Replace `SourceFlow.Stores.EntityFramework`. Its final 2.x release note points to them (WP-6.3). | + +## Alternatives + +| Alternative | Why not | +|-------------|---------| +| Keep `SourceFlow.Abstractions` separate | Domain assemblies would avoid only `Microsoft.Extensions.*` abstractions, and ARCH-04 already enforces domain purity. It adds a package to every install and to every versioning decision. | +| Merge the generator into `SourceFlow.Net` by multi-targeting one project | The `net10.0` and `netstandard2.0` builds would be two different products sharing one file, with `#if` on every source file and custom packing rules. | +| Separate KMS and transport packages per cloud | Doubles the cloud package count for a rare mixed-cloud case that still works with one package per cloud. | +| One test project per package (the earlier plan 04 §3) | 20+ test projects slow restore and build. Category projects with traits give the same CI fan-out. | + +## Consequences + +- (+) One reference gives a user the contracts, the runtime, the in-memory adapters and the generator. There are fewer packages to version, document and release. +- (+) The SPI namespaces state the extension points clearly: a storage, cloud, security or query provider implements one namespace's interfaces and registers through one `Use*` slot. +- (+) Every runtime package targets .NET 10 only. +- (−) Domain assemblies reference the runtime assembly. ARCH-04 (namespace rule) mitigates this. +- (−) A cross-cloud KMS user pulls an unused transport SDK. +- (−) Category test projects are larger, so CI filters by trait (plan 08). +- Supersedes the package-map parts of [doc 01 §5–6](../Design/01-Architecture-Overview.md#5-logical-architecture), the packaging note in [ADR-004](ADR-004-source-generation-instead-of-reflection.md) and the package list in [ADR-024](ADR-024-workflow-dsl-compiled-to-process-managers.md) and [ADR-025](ADR-025-studio-react-spa-with-shared-wasm-core.md). diff --git a/docs/v3.0.0/engineering/ADRs/ADR-028-postgresql-payload-columns-and-adapter-refinements.md b/docs/v3.0.0/engineering/ADRs/ADR-028-postgresql-payload-columns-and-adapter-refinements.md new file mode 100644 index 00000000..749278a0 --- /dev/null +++ b/docs/v3.0.0/engineering/ADRs/ADR-028-postgresql-payload-columns-and-adapter-refinements.md @@ -0,0 +1,50 @@ +# ADR-028: PostgreSQL payload columns are `json`, plus adapter refinements found while building WP-2.1 to WP-2.4 + +| | | +|---|---| +| **Status** | Accepted | +| **Date** | 2026-11-11 | +| **Deciders** | v3 architecture review; WP-2.1 to WP-2.4 implementation | +| **Amends** | [doc 05](../Design/05-Event-Store-and-Persistence.md) §2, §3.1, §5.2, §7; [ADR-009](ADR-009-event-store-on-adonet-postgresql-first.md) | + +## Context + +Doc 05 specified `jsonb` for `events.data`, `documents.data`, `process_instances.state` and `snapshots.data`. Running the storage conformance kit against PostgreSQL 15 to 17 showed that `jsonb` breaks guarantees the kit asserts and the rest of the system relies on: + +- **It does not keep bytes.** `jsonb` stores a parsed tree. It removes insignificant whitespace, reorders keys and keeps only the last of any duplicate keys. A payload read back is therefore not the payload that was written (SCK-18, SCK-19, SCK-46, SCK-58). That matters wherever bytes are signed or hashed, or compared as idempotency evidence. It also matters wherever an upcaster or a downstream consumer must see exactly what the producer wrote. +- **It rejects valid JSON.** `jsonb` refuses the `\u0000` escape (SQLSTATE 22P05). System.Text.Json emits that escape for any string containing U+0000, so `jsonb` would reject a legal domain value when the append is committed. + +Building the adapter also settled four points that doc 05 left open or stated differently: + +1. Doc 05 had the session send `Any` and `StreamExists` to the server only as `Exact`/`NoStream`, after reading the current version first. +2. Doc 05 did not say which clock decides when an outbox row is due. +3. Doc 05 did not define whether the safe horizon is inclusive or exclusive. +4. `process_instances`, `snapshots` and `documents` had no tenant column, although the core scopes all three by tenant (ADR-022). + +## Decision + +1. **Payload columns are `json`.** This applies to `events.data`, `documents.data`, `process_instances.state` and `snapshots.data`. `json` keeps the exact text and validates it on input. It accepts `\u0000`, and it supports the same `->`, `->>` and `#>>` operators and expression indexes that SFQL and `[Queryable]` indexes use (doc 14 §7.2). + - Envelope `metadata` and outbox and dead-letter `attributes` stay `jsonb`. The adapter writes them itself and only containment and key lookups query them. + - A U+0000 character in an envelope header or actor is not supported. +2. **`Any` and `StreamExists` are atomic statements, not read-then-write.** + - `StreamExists` is an `UPDATE … WHERE NOT is_deleted AND NOT is_archived`. + - `Any` is an `INSERT … ON CONFLICT DO UPDATE`. + - Both take the stream row lock and apply to the committed version they then see. Each is still a compare-and-set on an observed version, so the ordering argument of doc 05 §5.3 holds, and it saves a round trip. +3. **Outbox due times use the configured `TimeProvider`.** `deliver_at` is business time (timers, delayed retries), like `ctx.Now`. + - Leases and fencing keep using the database clock (`now()`), as doc 05 §7.4 requires. + - So a PostgreSQL host under a fake clock fires timers when the fake clock moves. Lease expiry still follows real time. +4. **The safe horizon is inclusive.** Every position at or below `LogBatch.Horizon` is final. PostgreSQL reports `(pg_snapshot_xmin − 1, long.MaxValue)` and the in-memory store reports its last position. + - Conformance cases that assert on the log read until the horizon passes their own last commit. A database may hold the horizon back briefly while any writing transaction runs (doc 05 §5.4). +5. **Tenant columns are added.** `process_instances`, `snapshots` and `documents` carry `tenant_id` in their primary keys (ADR-022). +6. **Commit is one round trip (WP-2.10).** + - Conditional writes assert their outcome in SQL with `sf_assert` (migration V003). These are the append compare-and-set, the process-state version and the fenced checkpoint. A failed check raises SQLSTATE `SF001` with a code naming the check. + - PostgreSQL then skips the rest of the batch, including its trailing `COMMIT`. The adapter rolls back and maps the code to `ConcurrencyException`, `StreamClosedException` (diagnosed after rollback) or `LeaseLostException`. + - A successful commit therefore sends one `NpgsqlBatch` that ends with `COMMIT`. SCK-20 asserts this by counting Npgsql activities. + - Under row-level security, `BeginAsync` adds one round trip to set the tenant (ADR-022). + +## Consequences + +- Payloads round-trip byte for byte on every supported database, which the conformance kit asserts. +- `json` is cheaper to write than `jsonb`, because nothing is parsed into a binary tree. Each query that reads a payload field parses that field at query time instead. Read-side hot paths should use `[Queryable]` expression indexes, not ad-hoc scans of payload fields. +- `jsonb`-only features, namely GIN containment indexes and the `@>` and `?` operators, are not available on payload columns. SFQL compiles field predicates to `->>` and comparison operators, so the query surface is unaffected. +- `json` columns cannot be compared for equality (`json = json` does not exist). Nothing in the adapter compares payloads in SQL. diff --git a/docs/v3.0.0/engineering/ADRs/ADR-029-schema-catalog-derived-from-serializer-metadata.md b/docs/v3.0.0/engineering/ADRs/ADR-029-schema-catalog-derived-from-serializer-metadata.md new file mode 100644 index 00000000..6d47999b --- /dev/null +++ b/docs/v3.0.0/engineering/ADRs/ADR-029-schema-catalog-derived-from-serializer-metadata.md @@ -0,0 +1,48 @@ +# ADR-029: The schema catalog is derived at startup from the serializer's source-generated metadata + +| | | +|---|---| +| **Status** | Accepted | +| **Date** | 2026-11-11 | +| **Deciders** | v3 architecture review; WP-1.12 implementation | +| **Amends** | [doc 14](../Design/14-Query-Side-and-SFQL.md) §2.1 and §2.2; WBS WP-1.12 ("a generator extension that emits a JSON Schema") | + +## Context + +Doc 14 §2.1 says the source generator emits a JSON Schema 2020-12 document for every `[MessageType]`. The WBS repeats this for WP-1.12. Building the catalog showed three problems with emitting schemas from the SourceFlow generator: + +- **The generator can't see the wire contract.** System.Text.Json decides member names, ignored members, converters, number handling and nullability. The `JsonSerializerContext` and its options control that, along with any custom converters. A Roslyn generator in `netstandard2.0` would have to re-implement those rules (ADR-004, DC-1), and every mismatch would produce a schema that doesn't describe what is actually stored or sent. +- **One contract would have two sources.** The serializer already has source-generated, AOT-safe metadata for every message, document and state type. That metadata is `JsonTypeInfo`, the same one SFQL's query catalog uses (doc 14 §5). A second description written by the SourceFlow generator could drift from it. +- **Decimals aren't strings.** Doc 14 §2.1 says decimals are serialised as strings with `format: decimal`. In fact System.Text.Json writes them as JSON numbers, and the PostgreSQL compiler reads them with `::numeric`, which is exact. + +## Decision + +1. **Schemas come from `JsonTypeInfo` at runtime.** `SourceFlow.Catalog.JsonSchemaGenerator` walks the type's `JsonTypeInfo` and those of its members. It covers object properties, enumerables, dictionaries, nullable value types and `JsonPropertyInfo.IsGetNullable`/`IsRequired` for `required`. It writes JSON Schema 2020-12. Member attributes become the `x-sourceflow-queryable`, `x-sourceflow-personal-data`, `x-sourceflow-renamed-from` and `x-sourceflow-tag` extensions. + - It reads attributes through `JsonPropertyInfo.AttributeProvider`, which source generation populates, so no reflection over members is needed. The code stays AOT-compatible. +2. **Value formats follow the serializer:** + - decimals are `{"type": "number", "format": "decimal"}`; + - strongly typed ids follow their `[StronglyTypedId]` backing (uuid, string or int64); + *Amended (WP-C.8, CR-30):* the backing is what the id's generated converter reports (`IStronglyTypedIdConverter`, from the type of `Value`, also emitted as the id's static `Backing`). The schema catalog and the SFQL catalog both read it (`IdBackings.Of`), so an Int64 id is `integer` in the schema and `Integer` in SFQL. SF0022 fails the build when `[StronglyTypedId(Backing = …)]` disagrees with `Value`. + - enums are `integer` or `string`, decided by serializing a value through the enum's own `JsonTypeInfo`, so a configured string converter is respected. +3. **`SchemaCatalog.Build(RuntimeModel)` describes the whole service:** + - every registered message type and version, including `CommandRejected` replies; + - every document projection's document (`readmodel`: projection name and version); + - every process manager's state (`process-state`, version 1). +4. **Fingerprints exclude the service.** The fingerprint is the SHA-256 of the canonical schema text (keys sorted ordinally, no whitespace). `x-sourceflow` holds the type, version, kind and `upcastsTo`, but not the service or the owning aggregate. Several services that share a contract (an integration event, or a command sent to a remote owner) therefore register the same fingerprint. + *Amended (WP-C.8, CR-17): what is fingerprinted.* The fingerprint covers the schema's **structure** only (`SchemaEntry.Structure`, from `JsonSchemaGenerator.Structure`). These annotations are left out, because they don't change what is on the wire: + - the root `title`, the CLR type name, so renaming the type keeps the fingerprint (ADR-005); + - `x-sourceflow-enum`, an enum's CLR name; + - `x-sourceflow.upcastsTo`, which is set on a version when a later version and its upcaster are added (doc 03 §2.1). + + Everything else is fingerprinted: types, formats, properties, `required`, the `x-sourceflow` type, version and kind, and the queryable, personal-data, renamed-from and tag extensions. The canonical text that is stored and exported keeps the annotations. + Fingerprints registered under the earlier rule are migrated at startup, once. When a registered fingerprint differs but the stored schema, fingerprinted under the current rule, has the same structure, the entry is replaced (`ISchemaStore.ReplaceAsync`) instead of being reported as a conflict. +5. **Registration and immutability follow doc 14 §2.2.** Host startup registers the catalog through the optional `ISchemaStore` port, implemented in memory and by PostgreSQL's `schemas` table. A different fingerprint for a registered `(type, version)` fails startup with `SchemaConflictException`. `SourceFlowOptions.SchemaRegistration` can set this to `Warn` or `Off`. +6. **The SourceFlow generator emits no schemas.** The GEN-41..46 cases planned for the generator are covered by UT-CAT-01..03 against the runtime generator. + +## Consequences + +- The catalog describes exactly what the serializer writes, including custom naming policies and converters, and costs one walk over the metadata at startup. +- Tools that need schemas without running the service get them through a host: + - the CLI's `schema export` and `schema check`; + - the lock file written by `SchemaCatalog.ToLockFile()`. +- Doc 14 §2.1 is amended: decimals are numbers with `format: decimal`. diff --git a/docs/v3.0.0/engineering/ADRs/ADR-030-domain-queries-bind-at-startup.md b/docs/v3.0.0/engineering/ADRs/ADR-030-domain-queries-bind-at-startup.md new file mode 100644 index 00000000..b3969e09 --- /dev/null +++ b/docs/v3.0.0/engineering/ADRs/ADR-030-domain-queries-bind-at-startup.md @@ -0,0 +1,44 @@ +# ADR-030: Domain queries are checked in two stages: shape at build time, binding at startup + +| | | +|---|---| +| **Status** | Accepted | +| **Date** | 2026-11-11 | +| **Deciders** | v3 architecture review; WP-1.13 implementation | +| **Amends** | [doc 14](../Design/14-Query-Side-and-SFQL.md) Q-B4 ("the generator binds every `[DomainQuery]` at build time against the catalog") | + +## Context + +Doc 14 says analyzer SF0018 binds each `[DomainQuery]` against the catalog at build time, so a broken contract fails compilation. That needs two things the compiler doesn't have: + +- **The SFQL parser and binder.** They live in `SourceFlow.Net` (`net10.0`). Analyzers and generators load into the compiler as `netstandard2.0` assemblies (ADR-004, ADR-027), so they can't reference them. +- **The service's catalog.** It is built from the runtime model (ADR-029): every module the host adds, the serializer's naming policy, and its converters. A domain query in a module assembly is often bound against read models from other modules that the analyzer can't see. + +## Decision + +1. **SF0018 at build time** checks what the compilation can decide on its own, and reports an error when: + - the attribute has no name; + - the type doesn't implement `IDomainQuery`; + - the type isn't a top-level partial record or class; + - there is no `const string Sfql` (or `Sql`); + - the result has no public constructor with parameters; + - an `@parameter` in the text, outside string literals, has no matching member. +2. **Binding at startup.** `SourceFlowHost` binds every registered domain query against the service's own catalog before it reports ready, using the real parser and binder. It checks three things: + - the text binds (SFQ01xx/02xx diagnostics with positions); + - every bound parameter is a member; + - every result constructor parameter is an output column (matched case-insensitively). + + Any failure stops startup with `DomainQueryException`, whose message starts with "SF0018". A broken contract therefore fails the first test or deployment that starts the host, not the first caller. +3. **Generated runtime.** The generator emits `IDomainQueryRuntime`: + - the name, version, text and syntax; + - the parameters (camelCase member names); + - the result columns; + - `ToParameters()`; + - a typed `Materialize(QueryRow)` that converts through `DomainQueryValues`. Ids are recognised by `[StronglyTypedId]`, because the id interface comes from the same generator run. + + The module registers each query (`AddDomainQuery()`), and `IQueryService.ExecuteAsync(query)` runs it in-process. + +## Consequences + +- Some contract errors (unknown read model, missing output column) surface at host startup instead of compilation. A plain host start in a unit test catches them, as UT-QL-92 does. +- The analyzer stays small and fast, with no copy of the grammar. diff --git a/docs/v3.0.0/engineering/ADRs/ADR-031-cli-runs-store-commands-globally-and-model-commands-in-the-service.md b/docs/v3.0.0/engineering/ADRs/ADR-031-cli-runs-store-commands-globally-and-model-commands-in-the-service.md new file mode 100644 index 00000000..af3f5a75 --- /dev/null +++ b/docs/v3.0.0/engineering/ADRs/ADR-031-cli-runs-store-commands-globally-and-model-commands-in-the-service.md @@ -0,0 +1,32 @@ +# ADR-031: The CLI runs store commands as a global tool and model commands inside the service + +| | | +|---|---| +| **Status** | Accepted | +| **Date** | 2026-11-11 | +| **Deciders** | v3 architecture review; WP-4.1 implementation | +| **Amends** | WBS WP-4.1; [doc 06](../Design/06-Projections-and-Subscriptions.md) §6 (`projection rebuild`) | + +## Context + +`dotnet sourceflow` has two kinds of command: + +- **Store commands** need only the database. These are `db migrate|script`, `dlq list|show|replay|discard|purge` and `projection skip|repartition|rebuild|drop`. +- **Model commands** need the service's model. This means its modules, JSON contracts, routing and projections. These are `db index sync`, `query`, `schema check|export` and `topology export|validate`. + +A global tool can't see a service's model without loading the service's assembly by reflection. That would mean finding its modules, guessing its routing (which lives in `Program.cs`, not in modules), and matching its dependency versions. It would be fragile, and it would bypass the source-generated, AOT-safe model (ADR-004). + +## Decision + +1. **One command tree, two hosts.** `SourceFlow.Tool` holds the commands in System.CommandLine (`SourceFlowCli`). +2. **The global tool** (`dotnet sourceflow …`) runs store commands against PostgreSQL. It takes `--connection` (or `SOURCEFLOW_CONNECTION`), `--schema` and, for row-level security, `--system-connection`. Model commands explain how to run them inside the service. +3. **Inside a service**, `Program.cs` calls `if (await SourceFlowCli.TryRunAsync(args, app.Services) is { } code) return code;` before `app.Run()`. Every command then works with the service's own storage, model, routing and query service: `dotnet run --project -- sourceflow schema check --baseline schemas.lock.json`. The Bank sample does this. +4. **Without a transport, the global tool replays dead letters through the outbox.** It enqueues the original envelope, with the same message id, so the inbox still protects. The running service's relay then sends it. +5. **Projection admin needs the leases.** `projection skip`, `repartition` and `rebuild` take the partitions' leases as `sourceflow-cli`. They refuse while a running node holds them, so subscriptions must be stopped first; `skip` runs on the node that holds the lease. +6. **`projection rebuild ` is blue/green** ([ADR-032](ADR-032-blue-green-read-model-generations-behind-forward-only-aliases.md)). It requests the next generation, and the running service builds it and switches reads once it has caught up. With `--in-place`, it instead drops the generation's documents in every tenant (`IDocumentAdmin`) and resets its checkpoints; the service then replays it from the start on its next run. `projection generations` lists the aliases, `projection switch` rolls reads back to a retained generation, and `projection drop` refuses a generation that is serving or being built. + +## Consequences + +- CI can check schemas with the service's own build, and nothing is loaded by reflection. +- Operators can run store commands without deploying anything. +- An in-place rebuild serves an empty, growing read model while it catches up; the default blue/green rebuild does not. diff --git a/docs/v3.0.0/engineering/ADRs/ADR-032-blue-green-read-model-generations-behind-forward-only-aliases.md b/docs/v3.0.0/engineering/ADRs/ADR-032-blue-green-read-model-generations-behind-forward-only-aliases.md new file mode 100644 index 00000000..11f21868 --- /dev/null +++ b/docs/v3.0.0/engineering/ADRs/ADR-032-blue-green-read-model-generations-behind-forward-only-aliases.md @@ -0,0 +1,67 @@ +# ADR-032: Blue/green read-model generations behind forward-only aliases + +| | | +|---|---| +| **Status** | Accepted | +| **Date** | 2026-11-11 | +| **Deciders** | v3 architecture review; WP-2.7 implementation | +| **Amends** | [doc 06](../Design/06-Projections-and-Subscriptions.md) §6; [ADR-031](ADR-031-cli-runs-store-commands-globally-and-model-commands-in-the-service.md) decision 6 | + +## Context + +Doc 06 §6 describes blue/green rebuilds: + +- A projection version bump, or `dotnet sourceflow projection rebuild`, builds a new **generation** from position zero. +- The old generation keeps serving reads until the new one has caught up. +- Reads then switch through an alias, and the old generation is dropped after a retention period. + +Several details were left open: + +- the generation naming; +- how a running service learns about a requested rebuild; +- what happens to nodes still running the old code during a rolling deploy; +- how relational (EF Core) read models take part; +- what "replay has no side effects" means for handlers. + +## Decision + +1. **Generation ids.** + - The first build of version *v* is `{name}@{v}`, as before, so existing collections and checkpoints keep their names. + - A rebuild of the same version is `{name}@{v}.{n}`, with *n* starting at 2. + - Generations are ordered by version, then by number (`ReadModelGeneration`). + - Each generation has its own subscription, `projection:{generation}`, with its own checkpoints and leases. +2. **One alias row per projection name** (`collection_aliases`, extended by migration V004). The row holds: + - `target`: the generation serving reads; + - `previous`: the generation the last switch retired; + - `building`: a rebuild that `projection rebuild` requested. + + Every change is a compare-and-set through the `ICollectionAliases` storage port (SCK-73..75), so concurrent nodes switch an alias exactly once. +3. **What each node runs.** Each node runs at most two generations of each async projection: the one serving reads, if it is this code's version, and one being built. The build target is one of these: + - the requested rebuild; + - this code's first generation, when the alias points at an older version; + - this code's first generation, before any alias exists. + + A node whose version is older than the alias target runs nothing for that projection. In a rolling deploy, old nodes keep the old generation current until the switch, then retire it within one poll interval. +4. **Switching forward only.** A node points the alias at the generation it is building once every partition is within `SwitchLagThreshold` events of the log (default 100). The check runs on idle passes and on each alias refresh. + - Reads resolve the alias on every query. The aliases are cached for one poll interval, and a switch made by this node takes effect at once. + - This covers SFQL, domain queries, `at_least` consistency waits, `IReadModelResolver` and the test host. + - `projection switch` can point the alias back at a retained generation (a rollback). Nodes on a newer version then build again. +5. **Retention.** Once `RetainPreviousFor` has passed (default 7 days, checked once per `RetentionInterval`), the node drops the retired generation's data, then clears `previous`: + - documents through `IDocumentAdmin`; + - an EF Core generation's schema through `IProjectionGenerationStore`. + + `projection drop` does the same on demand. It refuses the serving generation and the one being built. +6. **EF Core opts in to a schema per generation.** + - Opt in with `UseEntityFrameworkProjections(configure, (options, schema) => …, generations)`. The context implements `IGenerationSchemaContext` and maps `HasDefaultSchema(Schema)`. Models are cached per schema. + - A generation's schema and tables are created from the EF model on first use. + - Reads resolve the generation with `IReadModelResolver` and open a context with `CreateForGeneration`. + - Without the opt-in, an EF projection keeps one shared schema and does not take part in blue/green switching. +7. **One version of a projection per service.** Two registered projections with the same name fail at startup. A host that carries a new version of a library's projection leaves the old one out with `Projections(p => p.Remove())`. +8. **Rebuilds never re-run side effects.** Process managers and event handlers have their own subscriptions, which no rebuild touches. The `IncludeInReplay` switch in doc 06 §6 is dropped: re-running a handler is a different operation (reset its subscription), not part of a rebuild. + +## Consequences + +- A version bump and a rebuild without a code change behave the same way. Readers see the old generation until the new one is close to the head. There is never an empty or half-built read model, except during the lag window allowed by `SwitchLagThreshold`. +- Inline projections are not rebuilt blue/green; they always write their first generation. To rebuild one, make it async for the rebuild. +- During the overlap, an old-version node reads the new generation's documents with its old document type. Additive document changes are safe; incompatible ones need the old nodes gone before the switch (set `SwitchLagThreshold` to 0 and finish the rollout first). +- Each alias refresh is one small query per poll interval per node. Lag checks read at most `SwitchLagThreshold + 1` log rows per partition, and only while a generation is being built. diff --git a/docs/v3.0.0/engineering/ADRs/ADR-033-final-transport-spi-pull-receivers-and-the-in-memory-reference-broker.md b/docs/v3.0.0/engineering/ADRs/ADR-033-final-transport-spi-pull-receivers-and-the-in-memory-reference-broker.md new file mode 100644 index 00000000..4a3ff2e5 --- /dev/null +++ b/docs/v3.0.0/engineering/ADRs/ADR-033-final-transport-spi-pull-receivers-and-the-in-memory-reference-broker.md @@ -0,0 +1,68 @@ +# ADR-033: The final transport SPI: pull receivers, CESQL filters and the in-memory reference broker + +| | | +|---|---| +| **Status** | Accepted | +| **Date** | 2026-11-11 | +| **Deciders** | v3 architecture review; WP-3.1 implementation | +| **Amends** | [doc 07](../Design/07-Cloud-Transports.md) §2, §7; [ADR-014](ADR-014-transport-spi-and-conformance-kit-parity-required.md) | + +## Context + +Doc 07 §2 sketched a callback-based SPI with a separate sender and provisioner. The core built in M1 uses a pull-based `ITransport`. Here the receive loop, per-key workers, bounded channels and settlement live in the core (`ReceiveEndpoint`, RX-R1..R6). + +WP-3.1 has to freeze the SPI before three provider workstreams start in parallel. It also has to turn the 12-case kit into the planned TCK-01..45. + +## Decision + +1. **Pull, not callbacks.** `ITransportReceiver.ReceiveAsync(max, wait)` stays. + - Every target broker has a native pull: SQS `ReceiveMessage`, Pub/Sub pull, Service Bus `ReceiveMessagesAsync`. + - Keeping the loop in the core keeps backpressure, per-key ordering and shutdown identical on every broker. + - The SPI stays at five types: `ITransport`, `ITransportReceiver`, `ReceivedMessage`, `TransportCapabilities` and `TransportTopology`. +2. **Settlement is complete.** `ReceivedMessage` has `CompleteAsync`, `AbandonAsync(delay)` (native delay), `RenewAsync` (lock, visibility or lease extension) and `DeadLetterAsync(reason)` (the native backstop). + - A late settlement after a lost lock is ignored. + - The receive endpoint renews at half `ReceiveLockDuration` while a handler runs. + - Disposing a receiver releases what it holds unsettled. +3. **Capabilities drive the core.** `TransportCapabilities` keeps the size, attribute, retention and delay limits. It gains: + - `OrderedDelivery`, `NativeDeadLetter`, `SubscriptionFilters`; + - `MaxBatchSize`, `Deduplication` (with its window), `MaxLockDuration`. + + The core uses them to decide: + - client-side filtering when a broker has no native filters (UT-RX-22); + - whether to run the dead-letter ingestor; + - how the TCK judges deduplication. +4. **Errors are typed.** + - `TransportException.IsTransient` (and `RetryAfter` for throttling) drives the error classifier. + - `TransportSendException` reports a partial batch per message: oversized messages are refused before anything is sent for them, and the rest are sent. + - `DestinationNotFoundException` names a missing endpoint or topic. + - `TopologyValidationException.Problems` is the full diff under `Validate`, typed by `TopologyProblemKind`. +5. **The topology carries what brokers need to configure.** `TransportTopology` gains: + - `OrderedEndpoint` and `OrderedTopics`; + - `MaxDeliveries`, the dead-letter threshold: the retry budget (1 + delayed retries) plus two; + - per-topic `Filters`. + + The full topology model and naming conventions remain WP-3.5. `SourceFlowRuntime.Topology()` builds this topology for the host and the CLI. +6. **Subscription filters are CloudEvents SQL.** + - `CloudEventFilter` parses and evaluates CESQL 1.0 over the CloudEvents attributes: operators, `LIKE`, `IN`, `EXISTS` and the common functions. Errors never match. + - Routing compiles `Only()` to `type IN (…)` and ANDs it with `Where(…)`. + - Transports translate `ExactTypes` and `TypePrefixes` natively. Anything else is evaluated client-side with the same evaluator, so results are identical (TCK-28). +7. **The in-memory broker is the reference transport.** It sends messages through the real CloudEvents binary mapping with a 10-attribute budget, the strictest broker's, so the `sfext` overflow runs on every test. It also implements: + - ordered endpoints (one in-flight message per key, head-of-line within a key); + - locks with expiry and renewal; + - a maximum delivery count and a dead-letter queue; + - filtered fan-out, batches and partial failures; + - a provisioning diff; + - faults: outage, throttling, credential expiry, duplicates and dropped acks. + + `StrictDestinations` gives real-broker semantics for unknown destinations. It is off by default, so tests can send to services that start later. +8. **The TCK runs the real core.** + - `SourceFlow.Testing` carries a small generated domain (`TckModule`). Cases 18, 24, 25 and 45 start real services on the transport under test. + - The fixture contract adds `Faults` (null on real cloud; those cases are skipped, never weakened), `InjectDefectAsync` for the `Validate` cases, `QuietPeriod` and `DelayTolerance`. + - Payload protection cases 41–43 cover the transport side: ciphertext and marker are carried byte for byte and never inspected. Decryption and `DecryptionFailed` parking arrive with WP-5.1. + +## Consequences + +- Provider packages (WP-3.2..3.4) implement one small SPI, and must pass the same cases as the in-memory broker (45 at WP-3.1; 49 since WP-C.6 added TCK-46..49). +- Every in-memory test now exercises the CloudEvents wire mapping, so envelope regressions surface everywhere, not only in provider suites. +- Brokers that cannot filter natively still filter correctly, at the cost of receiving and acknowledging unwanted events. +- The broker dead-letter queue is a backstop. The ingestor moves its messages to the store, where `dlq replay` re-sends them. diff --git a/docs/v3.0.0/engineering/ADRs/README.md b/docs/v3.0.0/engineering/ADRs/README.md new file mode 100644 index 00000000..56573873 --- /dev/null +++ b/docs/v3.0.0/engineering/ADRs/README.md @@ -0,0 +1,48 @@ +# SourceFlow.Net v3 — Architecture Decision Records + +One file per decision, in the [MADR](https://adr.github.io/madr/)-style layout: Context → Decision → Alternatives → Consequences → Traces. +Every ADR is **Proposed** until the v3 architecture review. "Traces" lists the [product requirements](../../../product/README.md) and gaps the decision addresses. + +## Rules for this folder + +- One ADR per file, named `ADR-nnn-short-title.md`. Numbers are never reused. +- An accepted ADR is not edited in substance. To change a decision, write a new ADR and mark the old one **Superseded by ADR-nnn**. +- Status values: Proposed → Accepted | Rejected; Accepted → Deprecated | Superseded. + +## Index + +| ADR | Title | Status | +|-----|-------|--------| +| [ADR-001](ADR-001-target-dotnet-10-and-csharp-14.md) | Target .NET 10 and C# 14 only | Proposed | +| [ADR-002](ADR-002-event-sourcing-replaces-command-sourcing.md) | Event sourcing replaces command sourcing | Accepted | +| [ADR-003](ADR-003-aggregates-as-pure-deciders-decide-evolve.md) | Aggregates as pure deciders (decide/evolve) | Proposed | +| [ADR-004](ADR-004-source-generation-instead-of-reflection.md) | Compile-time source generation instead of runtime reflection | Proposed | +| [ADR-005](ADR-005-logical-message-type-names-and-registry.md) | Stable logical message type names, with a registry as allow-list | Proposed | +| [ADR-006](ADR-006-transactional-outbox-and-inbox-for-effectively-once.md) | Transactional outbox and inbox for effectively-once processing | Accepted | +| [ADR-007](ADR-007-single-command-ownership-route-local-xor-remote.md) | Single command ownership: route local XOR remote | Accepted | +| [ADR-008](ADR-008-optimistic-concurrency-with-automatic-re-decide.md) | Optimistic concurrency with automatic re-decide | Proposed | +| [ADR-009](ADR-009-event-store-on-adonet-postgresql-first.md) | Event store on raw ADO.NET; PostgreSQL first | Proposed | +| [ADR-010](ADR-010-commit-ordered-global-position-for-gap-free.md) | Commit-ordered global position for gap-free subscriptions | Proposed | +| [ADR-011](ADR-011-cloudevents-envelope-and-w3c-trace-context.md) | CloudEvents 1.0 envelope and W3C trace context | Proposed | +| [ADR-012](ADR-012-one-middleware-abstraction-for-all-stages.md) | One middleware abstraction for all stages | Proposed | +| [ADR-013](ADR-013-use-platform-libraries-delete-bespoke-equivalents.md) | Use platform libraries; delete bespoke equivalents | Proposed | +| [ADR-014](ADR-014-transport-spi-and-conformance-kit-parity-required.md) | Transport SPI and conformance kit; parity required for GA | Accepted | +| [ADR-015](ADR-015-strongly-typed-caller-assigned-ids-uuidv7-default.md) | Strongly typed, caller-assigned ids (UUIDv7 default) | Accepted | +| [ADR-016](ADR-016-projections-inline-or-async-with-partitioned-fenced.md) | Projections: inline or async, with partitioned, fenced subscriptions | Accepted | +| [ADR-017](ADR-017-provisioning-modes-and-topology-as-data.md) | Provisioning modes and topology as data | Proposed | +| [ADR-018](ADR-018-business-rejections-are-values-not-exceptions.md) | Business rejections are values, not exceptions | Proposed | +| [ADR-019](ADR-019-telemetry-always-on-with-standard-semantic-conventions.md) | Telemetry always on, with standard semantic conventions | Proposed | +| [ADR-020](ADR-020-process-managers-with-durable-state-and-timers.md) | Process managers with durable state and timers replace "Saga" | Proposed | +| [ADR-021](ADR-021-dynamic-consistency-boundaries-dcb-in-3-1.md) | Dynamic consistency boundaries (DCB): schema-ready in 3.0, API in 3.1 | Proposed | +| [ADR-022](ADR-022-conjoined-multi-tenancy-with-row-level-security.md) | Conjoined multi-tenancy with row-level security in 3.0 | Proposed | +| [ADR-023](ADR-023-sfql-query-language-with-cesql-predicates.md) | SFQL: a read-only query language with CESQL-compatible predicates | Accepted | +| [ADR-024](ADR-024-workflow-dsl-compiled-to-process-managers.md) | Workflow DSL (YAML) compiled to process managers | Proposed | +| [ADR-025](ADR-025-studio-react-spa-with-shared-wasm-core.md) | SourceFlow Studio: React SPA with a shared WebAssembly core, hosted locally | Proposed | +| [ADR-026](ADR-026-per-service-query-api-with-sql-syntax-and-injection-proof-compilation.md) | Per-service query API with a SQL syntax and injection-proof compilation | Proposed | +| [ADR-027](ADR-027-single-core-package-with-extensibility-spis-and-categorised-adapters.md) | Single core package with extensibility SPIs, and categorised adapter packages | Accepted | +| [ADR-028](ADR-028-postgresql-payload-columns-and-adapter-refinements.md) | PostgreSQL payload columns are `json`, plus adapter refinements | Accepted | +| [ADR-029](ADR-029-schema-catalog-derived-from-serializer-metadata.md) | The schema catalog is derived at startup from the serializer's source-generated metadata | Accepted | +| [ADR-030](ADR-030-domain-queries-bind-at-startup.md) | Domain queries are checked in two stages: shape at build time, binding at startup | Accepted | +| [ADR-031](ADR-031-cli-runs-store-commands-globally-and-model-commands-in-the-service.md) | The CLI runs store commands as a global tool and model commands inside the service | Accepted | +| [ADR-032](ADR-032-blue-green-read-model-generations-behind-forward-only-aliases.md) | Blue/green read-model generations behind forward-only aliases | Accepted | +| [ADR-033](ADR-033-final-transport-spi-pull-receivers-and-the-in-memory-reference-broker.md) | The final transport SPI: pull receivers, CESQL filters and the in-memory reference broker | Accepted | diff --git a/docs/v3.0.0/engineering/Design/01-Architecture-Overview.md b/docs/v3.0.0/engineering/Design/01-Architecture-Overview.md new file mode 100644 index 00000000..34610761 --- /dev/null +++ b/docs/v3.0.0/engineering/Design/01-Architecture-Overview.md @@ -0,0 +1,256 @@ +# 01 — Architecture Overview + +## 1. Scope and assumptions + +**In scope.** A .NET 10 library for building event-sourced, message-driven services using DDD and CQRS. It covers aggregates, command handling, process managers, projections, an event store, a transactional outbox and inbox, cloud transports, observability, security and test tooling. + +**Out of scope (YAGNI, see §4).** Hosting a broker, a query language, a UI or admin portal, a multi-tenancy framework, and GraphQL or REST endpoints. + +**Assumptions.** Each one is a design input; if it turns out to be wrong, the decision named should be revisited. + +| # | Assumption | If wrong, revisit | +|---|------------|-------------------| +| A1 | Users run on .NET 10 and can adopt C# 14. | [ADR-001](../ADRs/ADR-001-target-dotnet-10-and-csharp-14.md) | +| A2 | The write-side store is a relational database (PostgreSQL first, SQL Server second). Teams that need a dedicated event database can add an adapter later. | [ADR-009](../ADRs/ADR-009-event-store-on-adonet-postgresql-first.md) | +| A3 | A typical service handles 10²–10⁴ commands/s at peak, and aggregate streams are mostly short (fewer than 1,000 events). Long streams use snapshots. | [doc 09](09-Performance-and-Scalability.md) | +| A4 | Cross-service communication is asynchronous messaging. Synchronous RPC is out of scope. | [ADR-007](../ADRs/ADR-007-single-command-ownership-route-local-xor-remote.md) | +| A5 | Teams accept at-least-once delivery from brokers. The library makes processing *effectively once* using the inbox and outbox. | [ADR-006](../ADRs/ADR-006-transactional-outbox-and-inbox-for-effectively-once.md) | +| A6 | v2 users accept a major-version break in return for a migration tool. | [doc 12](12-Migration-Delivery-and-Traceability.md) | + +## 2. Quality goals + +Each quality is a measurable scenario. Targets are validated in M2 to M4 ([doc 09](09-Performance-and-Scalability.md), [doc 11](11-Testing-and-Quality.md)). + +| Quality | Scenario | Target | +|---------|----------|--------| +| **Durability** | The process is killed at any instruction during command handling | No accepted command loses its events or its outbound messages. No message is published without the matching events being committed. | +| **Durability** | The broker is unavailable for 30 minutes | Commands still succeed locally. The outbox buffers messages and drains in order once the broker is back, with no loss. | +| **Correctness** | Two instances handle commands for the same aggregate at the same time | Exactly one append wins for each version. The loser re-decides on fresh state. Stream history always reproduces state. | +| **Correctness** | Subscriptions under concurrent writers | Every committed event is delivered to every subscription partition exactly once in effect, in per-stream order. None is skipped. | +| **Observability** | An operator asks "why is read model X stale?" | The answer comes from standard OpenTelemetry signals (`subscription.lag`, traces linked from command to projection) within 5 minutes, without reading code. | +| **Performance** | Handling an in-process command against the in-memory store | p50 ≤ 20 µs, ≤ 2 KB allocated per command (excluding the user's events) | +| **Performance** | A PostgreSQL append of 1–3 events plus outbox | 1 network round trip. p99 ≤ 10 ms on a same-AZ database | +| **Scalability** | Adding service instances | Command throughput scales close to linearly until the database saturates. Projections scale up to P partitions. | +| **Maintainability** | Adding a transport | Implement the transport SPI (about 6 interfaces) and pass the conformance kit. Core code doesn't change. | +| **Security** | A message arrives with an unregistered `type` | It is rejected before deserialisation and parked as a dead letter. No type is instantiated. | +| **Portability** | Publishing as Native AOT | Core, the PostgreSQL store and every transport are trim- and AOT-safe, with no `RequiresUnreferencedCode` warnings. | + +## 3. Design principles and how they are applied + +| Principle | Concrete application in v3 | +|-----------|----------------------------| +| **S**ingle responsibility | Aggregates only decide and evolve (pure). The `CommandProcessor` only orchestrates load→decide→append. Persistence, transport and serialisation are separate ports. v2's "Saga", which both handled commands and persisted entities, is split. | +| **O**pen/closed | New transports, stores, serialisers, middleware and KMS providers plug in through SPIs. The core is closed to modification. | +| **L**iskov substitution | Every adapter must pass a **conformance kit** (storage and transport), so substitutability is tested, not hoped for. | +| **I**nterface segregation | Small role interfaces: `IEventStore` (streams), `IEventLogReader` (global reads), `IOutbox`, `IInbox`, `ICheckpointStore`, `ILeaseManager`. An adapter implements only the capabilities it supports. | +| **D**ependency inversion | The core depends on ports it defines. Adapters depend on the core, never the other way round. Domain code uses nothing but the attributes and interfaces in the `SourceFlow` namespace of `SourceFlow.Net` (ARCH-04). | +| **DRY** | One middleware abstraction for every stage (v2 had four). One envelope, used by every transport. One retry and dead-letter policy engine. Platform libraries replace custom code: Polly v8 replaces v2's circuit breaker, `Microsoft.Extensions.Compliance.Redaction` replaces v2's masker, and `TimeProvider` is used for time. | +| **KISS** | Aggregates are records with methods; no base class needed. One input queue per service endpoint by default. Sensible defaults let a working service configure only a connection string and a service name. | +| **YAGNI** | See §4. Features are added only where a product requirement or gap calls for them. | +| **Explicit over implicit** | Stable message type names, an explicit `[SourceFlowModule]` registration, explicit routing, explicit consistency mode per projection. No assembly scanning. | +| **Fail fast** | Topology, routing, handler coverage, type registry and options are validated at **startup** (`ValidateOnStart`), and where possible at **compile time** (analyzers). | +| **Pit of success** | The default pipeline includes inbox, outbox, retries, dead-lettering, telemetry and redaction. v2's opt-in "Enhanced" split is gone (GAP-01). | +| **Functional core, imperative shell** | Domain logic is pure and deterministic. I/O lives in the runtime shell. | +| **Ports and adapters (hexagonal)** | The package structure enforces the dependency rule (§5). | +| **Least astonishment** | Ignored options are not allowed: every option is either honoured or rejected by validation (GAP-03). | + +## 4. Deliberately not built (YAGNI register) + +| Not building | Why | Trigger to reconsider | +|--------------|-----|-----------------------| +| An event store on EF Core | The ORM adds per-append overhead and gives no control over ordering or locking SQL. EF Core stays for **read models** only. | Demand from users bound to EF-only database providers | +| A custom circuit breaker or retry engine | Polly v8 via `Microsoft.Extensions.Resilience` is the platform standard. | — | +| A query bus or mediator for reads | Read models are plain stores. A *query language* **is** in scope ([ADR-023](../ADRs/ADR-023-sfql-query-language-with-cesql-predicates.md), [doc 14](14-Query-Side-and-SFQL.md)), but there is no request/response query bus around it. | — | +| ~~General joins in SFQL~~ | **Now in scope** (product request, 2026-11-10; [ADR-026](../ADRs/ADR-026-per-service-query-api-with-sql-syntax-and-injection-proof-compilation.md)): bounded `INNER`/`LEFT` equality joins, grouping and ordering, plus a SQL syntax, behind the per-service query API | — | +| `UNION`, CTEs and window functions in SFQL | Not needed for the requested constructs; more surface to secure | Measured demand (`sfql/1.1`) | +| ~~A saga DSL or state-machine designer~~ | **Trigger met (product request, 2026-11-10).** Now in scope as the separate utility *SourceFlow Studio*: a YAML DSL compiled to process managers, plus a React designer ([doc 15](15-Workflow-DSL-and-Studio.md), [ADR-024](../ADRs/ADR-024-workflow-dsl-compiled-to-process-managers.md), [ADR-025](../ADRs/ADR-025-studio-react-spa-with-shared-wasm-core.md)). Still **no runtime workflow engine** | — | +| A runtime workflow interpreter / engine | DSL workflows are compiled into process managers. One execution model (ADR-024) | — | +| Database-per-tenant and schema-per-tenant | **Conjoined** tenancy with row-level security is in 3.0 ([ADR-022](../ADRs/ADR-022-conjoined-multi-tenancy-with-row-level-security.md)). Separate databases per tenant wait for demand. | Tenants needing physical isolation | +| A claim-check (large payload offload) | Size validation is in 3.0. Offloading is 3.x. | Messages above broker limits in real workloads | +| Archiving cold streams to object storage | Monthly range partitioning of the events table **is** in 3.0 as an opt-in, because the capacity model shows tier M needs it ([doc 09 §5](09-Performance-and-Scalability.md#5-capacity-model)). Detached partitions can be archived with standard database tooling. A built-in archive tier behind `IEventStore` is not needed yet. | Users needing transparent reads of archived streams | +| Snapshots on by default | Most streams are short. Snapshots are a per-aggregate opt-in policy. | `aggregate.load.events` p95 > 200 | + +## 5. Logical architecture + +```mermaid +flowchart TB + subgraph User["User code (pure domain + app)"] + D[Aggregates / Process managers
Projections / Handlers / Messages] + end + subgraph Core["SourceFlow.Net (runtime core)"] + CP[Command processor] --- AS[Aggregate store] + RP[Receive pipeline] --- MW[Middleware pipeline] + SE[Subscription engine] --- PM[Process manager runtime] + OR[Outbox relay] --- SCH[Scheduler] + TR[Type registry + serializer] --- TEL[Telemetry] + TOP[Topology + provisioning] + end + subgraph Ports["Ports (SPI, in core)"] + P1[IEventStore / IEventLogReader / ISnapshotStore] + P2[IOutbox / IInbox / ICheckpointStore / ILeaseManager / IDeadLetterStore] + P3[ITransport: send / publish / receive / provision] + P4[IKeyProvider / IPayloadProtector] + end + subgraph Adapters + PG[(PostgreSQL)]:::a + MS[(SQL Server)]:::a + MEM[(In-memory)]:::a + AWS[[AWS SNS/SQS]]:::a + ASB[[Azure Service Bus]]:::a + GCP[[Google Pub/Sub]]:::a + KMS[AWS KMS / Key Vault / Cloud KMS]:::a + EF[EF Core read models]:::a + end + D --> Core + Core --> Ports + Adapters --> Ports + classDef a fill:#eef,stroke:#88a +``` + +**Dependency rules** ([ADR-027](../ADRs/ADR-027-single-core-package-with-extensibility-spis-and-categorised-adapters.md); enforced by `SourceFlow.Architecture.Tests` with NetArchTest): + +1. **ARCH-01.** `SourceFlow.Net` depends only on the BCL, `Microsoft.Extensions.*`, Polly and `Microsoft.Extensions.Resilience`. It has no cloud SDK, database driver or OpenTelemetry SDK. +2. **ARCH-02.** The core never references an adapter, even through reflection (v2's `UseEFIdempotency` reflection hack is removed). +3. **ARCH-03.** Adapters depend on `SourceFlow.Net` and their own SDK only. They never depend on each other. +4. **ARCH-04.** Domain code references only `SourceFlow.Net`, and uses only the `SourceFlow` (contracts) and `SourceFlow.Workflows` (workflow runtime types) namespaces. This keeps domain assemblies free of infrastructure without a separate abstractions package. + +## 6. Package map + +All packages target `net10.0` only and are versioned together (`3.0.x`). The single exception to `net10.0` is the source generator. It is a compiler plugin, so it must target `netstandard2.0`, and it ships inside `SourceFlow.Net` rather than on its own. Packages are grouped by category, and source projects live under `src///`. + +| Category | Package | Contents | Key dependencies | +|----------|---------|----------|------------------| +| Core | `SourceFlow.Net` | **The single core.** Domain contracts (namespace `SourceFlow`): `ICommand`, `IEvent`, attributes (`[Aggregate]`, `[MessageType]`, `[StronglyTypedId]`, `[SourceFlowModule]`, `[PersonalData]`, `[Queryable]`, `[Tag]`, `[RenamedFrom]`, `[Emits]`, `[Rejects]`), `Decision`, `Reaction`, `Error`, `ConsistencyToken` and id primitives. Runtime: command processor, aggregate store, receive pipeline, middleware, outbox relay, scheduler, subscription engine, process manager runtime, type registry, schema catalog, STJ serializer, telemetry and health checks. Workflow runtime types. In-memory adapters. **Extensibility SPIs** (table below). Bundles the source generator and analyzers (`analyzers/dotnet/cs`). | M.E.DI/Hosting/Options/Logging, Polly/M.E.Resilience, M.E.Compliance.Redaction, System.Diagnostics | +| Storage | `SourceFlow.Storage.PostgreSQL` | Event store, snapshots, outbox, inbox, checkpoints, leases, dead letters, document read-model store, LISTEN/NOTIFY wake-up, SFQL PostgreSQL compiler | Npgsql | +| Storage | `SourceFlow.Storage.SqlServer` | Same capabilities on SQL Server, SFQL SQL Server compiler | Microsoft.Data.SqlClient | +| Storage | `SourceFlow.Storage.EntityFrameworkCore` | Projections that write EF Core read models in the projection transaction | EF Core 10 | +| Cloud | `SourceFlow.Cloud.Aws` | SNS/SQS transport and provisioner, AWS KMS `IKeyProvider`, health checks | AWSSDK.SQS/SNS/KMS | +| Cloud | `SourceFlow.Cloud.Azure` | Service Bus transport and provisioner, Key Vault `IKeyProvider`, health checks | Azure.Messaging.ServiceBus, Azure.Security.KeyVault.Keys | +| Cloud | `SourceFlow.Cloud.Gcp` | Pub/Sub transport and provisioner, Cloud KMS `IKeyProvider`, health checks | Google.Cloud.PubSub.V1, Google.Cloud.Kms.V1 | +| Hosting | `SourceFlow.AspNetCore` | `MapCommand()` (Idempotency-Key, If-Match → expected version, ProblemDetails, ETag, consistency-token header) and the opt-in `MapSourceFlowQuery()` endpoint | ASP.NET Core | +| Tooling | `SourceFlow.Testing` | Given/When/Then specs for aggregates, process managers and projections. Fake transport and store with fault injection. `FakeTimeProvider` integration. Base classes for the conformance kits. | xUnit-agnostic core | +| Tooling | `SourceFlow.Tool` (`dotnet sourceflow`) | CLI: topology export and validate, projection rebuild, dead-letter list/replay/discard, v2 migration, workflow and studio commands | System.CommandLine | +| Workflows | `SourceFlow.Studio` | Workflow DSL semantic core: YAML model, validator, simulator, path enumerator, spec generator, exporters, manifest model. The generator compiles the same sources ([ADR-027 §6](../ADRs/ADR-027-single-core-package-with-extensibility-spis-and-categorised-adapters.md#6-studio-and-the-generator-share-one-dsl-implementation)) | YamlDotNet | +| Workflows | `SourceFlow.Studio.Wasm` + `@sourceflow/studio` (npm) | SourceFlow Studio: the WebAssembly build of the DSL core, and the React designer (separate utility, own release train). The WASM build ships inside the npm package and the tool, not on NuGet | .NET browser-wasm; React 19 | + +**Extensibility SPIs in `SourceFlow.Net`.** Each provider implements one namespace and registers through one `SourceFlowBuilder.Use*` slot. + +| Concern | Namespace | Interfaces | Implemented by | +|---------|-----------|------------|----------------| +| Persistence | `SourceFlow.Storage` | `IEventStore`, `IEventLogReader`, `ISnapshotStore`, `IStorageSession`, `IOutboxStore`, `IInboxStore`, `ICheckpointStore`, `ILeaseManager`, `IDeadLetterStore`, `IDocumentStore` | In-memory (core), `SourceFlow.Storage.*` | +| Cloud / broker | `SourceFlow.Transport` | `ITransport`, `ITransportReceiver`, `ITransportProvisioner`, `TransportCapabilities` | In-memory (core), `SourceFlow.Cloud.*` | +| Security | `SourceFlow.Security` | `IKeyProvider`, `IPayloadProtector`, `IPersonalDataEraser` | Local key provider (core, dev only), `SourceFlow.Cloud.*` (KMS) | +| Querying | `SourceFlow.Query` | `ISqlDialect`, SFQL compiler contract | In-memory interpreter (core), `SourceFlow.Storage.PostgreSQL` / `.SqlServer` | +| Pipeline | `SourceFlow.Pipeline` | `IMessageMiddleware` | User code | +| Telemetry | `SourceFlow.Diagnostics` | `ActivitySource` / `Meter` named `SourceFlow`, semconv constants | Any OpenTelemetry SDK (`AddSource` / `AddMeter`) | + +One core package means a single reference brings the contracts, the runtime and the generator. ARCH-04 keeps domain code infrastructure-free. Each cloud package carries both its transport and its KMS key provider, because a team adopting a cloud uses both. They register separately (`UseAwsTransport()`, `UseAwsKms()`), so mixing clouds still works by referencing two cloud packages. + +## 7. Runtime components + +| Component | Responsibility | Doc | +|-----------|----------------|-----| +| **Type registry** | Maps logical type name ↔ CLR type ↔ JSON type info ↔ schema version and upcasters. It is the allow-list for deserialisation. | 04 | +| **Command router** | Resolves a command to its local handler or its remote endpoint (exactly one). | 04 | +| **Command processor** | Load aggregate → decide → append, all in one storage session. Re-decides on concurrency conflict. | 03, 05 | +| **Aggregate store** | Loads state from snapshot plus tail events, using the generated `Evolve`. Optional state cache. | 05 | +| **Storage session** | The unit of work over one database transaction: append, outbox, inbox, inline projections, process state, checkpoint. | 05 | +| **Outbox relay** | Claims outbox partitions and publishes in order through the transport, deleting after acknowledgement. | 04 | +| **Receive pipeline** | Transport delivery → validate type → decrypt → deserialise → inbox → handler → commit → ack. Retry and park on failure. | 04 | +| **Subscription engine** | Reads the global log in commit order and drives projections and process managers per partition, with fenced leases and checkpoints. | 06 | +| **Process manager runtime** | Event in → load state → react → persist state + outbox commands + timers, in one transaction. | 03 | +| **Scheduler** | Durable timers and delayed messages (outbox rows with `deliver_at`). | 04 | +| **Topology and provisioner** | Builds the topology model from routing. Validates, creates or exports broker resources. | 07 | +| **Telemetry** | One `ActivitySource` and `Meter` named `SourceFlow`. Semantic conventions. Source-generated logging. | 08 | +| **Schema catalog** | Generated JSON Schemas for every message and read-model type. Registered at startup, compatibility-checked in CI, exported as AsyncAPI. | 14 | +| **Query engine + per-service query API** | Request guard → SFQL (pipeline or SQL syntax) parse → bind → policy → plan → compile to parameterised SQL, executed on a read-only connection. Consistency tokens. HTTP API in every service with injection defence | 14 | +| **Workflow compiler** (build time) | `.sfflow.yaml` → validated → generated process manager + timers + operator commands; service manifest emission | 15 | +| **Tenant context** | `ITenantResolver` → ambient tenant → envelope `sftenant` → `SET LOCAL sourceflow.tenant` for RLS | [ADR-022](../ADRs/ADR-022-conjoined-multi-tenancy-with-row-level-security.md) | + +## 8. Key runtime flows + +### 8.1 Local command (the common path) + +```mermaid +sequenceDiagram + autonumber + participant API as Caller (API/handler) + participant CS as ICommandSender + participant MW as Middleware (Send/Handle) + participant CP as CommandProcessor + participant AS as AggregateStore + participant A as Aggregate (pure) + participant SS as StorageSession (1 DB tx) + API->>CS: SendAsync(Deposit) + CS->>MW: pipeline(Handle) + MW->>CP: process + CP->>AS: Load(stream) [snapshot + tail] + AS-->>CP: state, version v + CP->>A: Decide(cmd, state, ctx) + A-->>CP: Decision(events) or Reject(error) + CP->>SS: Append(stream, expected v, events)
+ outbox (mapped integration events)
+ inbox (idempotency key)
+ inline projections + SS-->>CP: Commit OK (new version v+n) + CP-->>API: CommandResult.Accepted(v+n) +``` + +On `ConcurrencyException` at commit, the processor reloads and re-decides, up to `MaxConcurrencyRetries` (default 3) with jittered backoff, then returns `CommandResult.Conflict`. Re-deciding is safe because `Decide` is pure ([ADR-003](../ADRs/ADR-003-aggregates-as-pure-deciders-decide-evolve.md), [ADR-008](../ADRs/ADR-008-optimistic-concurrency-with-automatic-re-decide.md)). + +### 8.2 Async projection and process manager + +```mermaid +sequenceDiagram + participant DB as Event log (commit-ordered) + participant SE as Subscription engine (partition p, holds lease) + participant P as Projection / Process manager + participant SS as StorageSession + DB-->>SE: NOTIFY / poll wake-up + SE->>DB: ReadAll(after checkpoint, partition p, safe horizon) + loop batch + SE->>P: Apply(event) + end + SE->>SS: write read models / PM state + outbox + checkpoint (fenced) + SS-->>SE: commit +``` + +### 8.3 Cross-service command and integration event + +```mermaid +sequenceDiagram + participant A as Service A (handler or PM) + participant OA as Outbox A + participant T as Broker + participant B as Service B receive pipeline + participant IB as Inbox B + A->>OA: Send(ChargeCard) in A's transaction + OA->>T: relay (ordered per partition key) + T->>B: deliver (at-least-once) + B->>IB: seen(messageId)? no + B->>B: CommandProcessor (owner B appends to ITS streams) + B->>IB: record messageId in same tx + B-->>T: ack after commit + Note over B: B's events → B's outbox → integration event topic → subscribers (A, C…) +``` + +Because B handles the command with its own command processor, **the owning service appends, sequences and can replay it** (GAP-19). + +## 9. Hosting model + +- `services.AddSourceFlow(sf => …)` registers everything. Background work runs as `IHostedLifecycleService`s so the ordering is explicit: + 1. **StartingAsync**: validate options, registry, routing and handler coverage. Fail fast. + 2. **StartAsync**: provision or validate topology (according to mode). Start the outbox relay, scheduler, subscription engine and receivers. + 3. **StartedAsync**: report readiness (health check `sourceflow.ready`). + 4. **StoppingAsync**: stop receivers taking new messages. Drain in-flight work within `ShutdownTimeout` (default 25 s). Release leases. Messages not yet acknowledged return to the broker. +> **As built (WP-C.6).** `SourceFlowHost` is an `IHostedLifecycleService`. `StoppingAsync` reports not ready, stops pulling and starts draining (queued messages are abandoned with no delay). `StopAsync` shares one deadline, `ShutdownTimeout` (default 30 s), across the loops, lease release, in-flight handlers (cancelled through their own token when the time is up) and snapshots. Before provisioning, `StartAsync` checks `InboxRetention` against the transport's `MaxRetention` (doc 04 §6). + +- Options are bound with the configuration binding source generator and validated with `[OptionsValidator]` source-generated validators plus `ValidateOnStart()`, so binding and validation are AOT-safe. +- **Roles.** One process can run every role, or a deployment can split them, for example `sf.Roles = SourceFlowRoles.CommandApi | SourceFlowRoles.Workers`. A role that is off doesn't start its hosted services. This lets API pods and worker pods scale independently with the same code. + +## 10. What to revisit as the system grows + +| Signal | Revisit | +|--------|---------| +| The event table is larger than about 1 TB, or index bloat hurts append latency | Archive or tier cold streams (doc 05 §9). Consider a dedicated event database adapter. | +| More than about 30 projections on one database | Separate read-model databases (async only). Raise the partition count. | +| The outbox relay can't keep up (`outbox.age` p95 > 1 s) | Raise outbox partitions and relay concurrency. Batch publishing (SNS/SQS `PublishBatch`, ASB batches). | +| Cross-region active-active demand | Per-region stream ownership, plus a replication design (not in 3.0). | +| Broker limits on message size are hit | Claim-check package (3.x). | diff --git a/docs/v3.0.0/engineering/Design/03-Domain-Programming-Model.md b/docs/v3.0.0/engineering/Design/03-Domain-Programming-Model.md new file mode 100644 index 00000000..ffee1b98 --- /dev/null +++ b/docs/v3.0.0/engineering/Design/03-Domain-Programming-Model.md @@ -0,0 +1,536 @@ +# 03 — Domain Programming Model + +This document defines what application developers write, and what the source generators produce from it. Design drivers: [ADR-002](../ADRs/ADR-002-event-sourcing-replaces-command-sourcing.md), [ADR-003](../ADRs/ADR-003-aggregates-as-pure-deciders-decide-evolve.md), [ADR-004](../ADRs/ADR-004-source-generation-instead-of-reflection.md), [ADR-005](../ADRs/ADR-005-logical-message-type-names-and-registry.md), [ADR-015](../ADRs/ADR-015-strongly-typed-caller-assigned-ids-uuidv7-default.md), [ADR-018](../ADRs/ADR-018-business-rejections-are-values-not-exceptions.md) and [ADR-020](../ADRs/ADR-020-process-managers-with-durable-state-and-timers.md). + +## 1. Building blocks, v2 → v3 + +| v2 concept | v3 concept | Change | +|------------|------------|--------| +| `IEntity` (int `Id`), persisted whole | **Aggregate** state record, rebuilt from its event stream | State comes from events and isn't stored as the source of truth. Ids are strongly typed. | +| `Aggregate` (façade that sends commands) | Removed. Callers use `ICommandSender`. | The façade added no behaviour. | +| `Saga` + `IHandles` (handle, mutate, persist, raise) | **Aggregate `Decide` methods** (pure), or an `ICommandHandler` when dependencies are needed | Persistence and event raising belong to the runtime. | +| `IHandlesWithEvent` (reflection-built event) | `Decision.Accept(new E(...))` | The event is built explicitly and type-checked. | +| (none) | **Process manager** | Durable, cross-aggregate coordination with timers ([ADR-020](../ADRs/ADR-020-process-managers-with-durable-state-and-timers.md)) | +| `View` + `IProjectOn` | **Projection** (document, EF Core or custom), inline or async | Checkpointed, rebuildable, partitionable ([ADR-016](../ADRs/ADR-016-projections-inline-or-async-with-partitioned-fenced.md)) | +| `Command` + `EntityRef` + `Metadata` | `record` implementing `ICommand` with a typed id. Metadata moves to the envelope. | No payload wrapper or mutable metadata. | +| `Event` (payload = whole entity) | `record` implementing `IEvent` that carries only the facts that changed | Events are facts, not entity snapshots. | +| (none) | **Integration event** (`IIntegrationEvent`), the public contract | Keeps internal domain events private. | + +## 2. Messages + +Messages are immutable `sealed record`s with a stable logical name and version ([ADR-005](../ADRs/ADR-005-logical-message-type-names-and-registry.md)). + +```csharp +// Commands target exactly one aggregate type (or none, see §6.2) +[MessageType("bank.account.open", 1)] +public sealed record OpenAccount(AccountId AccountId, string Holder, decimal InitialDeposit) : ICommand; + +[MessageType("bank.account.deposit", 1)] +public sealed record Deposit(AccountId AccountId, decimal Amount) : ICommand; + +[MessageType("bank.account.withdraw", 1)] +public sealed record Withdraw(AccountId AccountId, decimal Amount) : ICommand; + +[MessageType("bank.account.close", 1)] +public sealed record CloseAccount(AccountId AccountId, string Reason) : ICommand; + +// Domain events: internal facts, stored in the stream +[MessageType("bank.account.opened", 1)] +public sealed record AccountOpened(AccountId AccountId, [PersonalData] string Holder, + decimal InitialDeposit, DateTimeOffset OpenedAt) : IEvent; + +[MessageType("bank.account.deposited", 1)] +public sealed record MoneyDeposited(AccountId AccountId, decimal Amount, decimal BalanceAfter) : IEvent; + +[MessageType("bank.account.withdrawn", 1)] +public sealed record MoneyWithdrawn(AccountId AccountId, decimal Amount, decimal BalanceAfter) : IEvent; + +[MessageType("bank.account.closed", 1)] +public sealed record AccountClosed(AccountId AccountId, string Reason, DateTimeOffset ClosedAt) : IEvent; +``` + +**Rules** + +| Rule | Detail | +|------|--------| +| DM-R1 | The name is lowercase, dot-separated, and unique within the deployment's registry. The version starts at 1. | +| DM-R2 | Additive changes (a new optional member) keep the version. Removing, renaming or changing the meaning of a member needs a new version plus an upcaster (§2.1). | +| DM-R3 | A command targets an aggregate by having exactly one member of that aggregate's id type, or by marking one with `[AggregateId]` when there are several (SF0003). | +| DM-R4 | Message metadata (id, correlation, causation, time, tenant, trace) lives in the **envelope**, never in the record. | +| DM-R5 | Members must be serialisable by the System.Text.Json source generator (SF0010). | +| DM-R6 | Query and consistency metadata is declared on members: `[Queryable]` (indexed and filterable in SFQL), `[Tag("account")]` (DCB tag, [ADR-021](../ADRs/ADR-021-dynamic-consistency-boundaries-dcb-in-3-1.md)), `[RenamedFrom("old", Version = n)]` (keeps queries stable across versions). The generator turns these into the schema catalog (doc 14 §2). | + +### 2.1 Upcasting + +```csharp +// v1 had "Name"; v2 splits it. Old events stay stored as v1 and are upcast on read. +[MessageType("bank.account.opened", 2)] +public sealed record AccountOpened(AccountId AccountId, [PersonalData] string GivenName, + [PersonalData] string FamilyName, decimal InitialDeposit, + DateTimeOffset OpenedAt) : IEvent; + +public sealed class AccountOpenedV1ToV2 : IUpcaster +{ + public AccountOpened Upcast(AccountOpenedV1 old) + { + var (given, family) = NameParser.Split(old.Holder); + return new(old.AccountId, given, family, old.InitialDeposit, old.OpenedAt); + } +} +``` + +The old record type is kept, renamed and marked `[Obsolete]`: `[MessageType("bank.account.opened", 1)] sealed record AccountOpenedV1(...)`. The registry chains upcasters (v1→v2→v3) when reading **from storage**. Wire messages from other services are *not* upcast, because integration contracts version through new types instead. + +## 3. Strongly typed ids + +```csharp +[StronglyTypedId] // default backing: Guid (UUIDv7) +public readonly partial record struct AccountId(Guid Value); + +[StronglyTypedId(Backing = IdBacking.String, MaxLength = 64)] +public readonly partial record struct Iban(string Value); +``` + +The generator emits `New()` (using `Guid.CreateVersion7(TimeProvider)`), `Parse`/`TryParse`, `ISpanFormattable`/`IUtf8SpanFormattable`, a JSON converter registered in the generated JSON context, and `ToStreamSegment()`. Default values are rejected when a command is sent ([ADR-015](../ADRs/ADR-015-strongly-typed-caller-assigned-ids-uuidv7-default.md), GAP-20). + +## 4. Aggregates + +```csharp +public enum AccountStatus { None, Open, Closed } + +[Aggregate("bank-account", SnapshotEvery = 0)] // 0 = no snapshots (the default) +public sealed partial record BankAccount : IAggregate +{ + public static BankAccount Initial { get; } = new(); + + public AccountStatus Status { get; init; } + public decimal Balance { get; init; } + + // ---------- Decide: pure, deterministic, no I/O ---------- + public Decision Decide(OpenAccount c, DecisionContext ctx) => Status switch + { + AccountStatus.None when c.InitialDeposit <= 0 => Decision.Reject(AccountErrors.InitialDepositRequired), + AccountStatus.None => Decision.Accept(new AccountOpened(c.AccountId, c.Holder, c.InitialDeposit, ctx.Now)), + _ => Decision.Reject(AccountErrors.AlreadyOpen), + }; + + public Decision Decide(Deposit c, DecisionContext ctx) => this switch + { + { Status: not AccountStatus.Open } => Decision.Reject(AccountErrors.NotOpen), + _ when c.Amount <= 0 => Decision.Reject(AccountErrors.AmountMustBePositive), + _ => Decision.Accept(new MoneyDeposited(c.AccountId, c.Amount, Balance + c.Amount)), + }; + + public Decision Decide(Withdraw c, DecisionContext ctx) => this switch + { + { Status: not AccountStatus.Open } => Decision.Reject(AccountErrors.NotOpen), + _ when c.Amount > Balance => Decision.Reject(AccountErrors.InsufficientFunds), + _ => Decision.Accept(new MoneyWithdrawn(c.AccountId, c.Amount, Balance - c.Amount)), + }; + + public Decision Decide(CloseAccount c, DecisionContext ctx) => Status switch + { + AccountStatus.Closed => Decision.NoOp, // already closed: idempotent, nothing appended + AccountStatus.Open => Decision.Accept(new AccountClosed(c.AccountId, c.Reason, ctx.Now)), + _ => Decision.Reject(AccountErrors.NotOpen), + }; + + // ---------- Evolve: pure state transitions ---------- + BankAccount When(AccountOpened e) => this with { Status = AccountStatus.Open, Balance = e.InitialDeposit }; + BankAccount When(MoneyDeposited e) => this with { Balance = e.BalanceAfter }; + BankAccount When(MoneyWithdrawn e) => this with { Balance = e.BalanceAfter }; + BankAccount When(AccountClosed e) => this with { Status = AccountStatus.Closed }; +} + +public static class AccountErrors +{ + public static readonly Error InitialDepositRequired = new("account.initial_deposit_required", "An initial deposit is required."); + public static readonly Error AlreadyOpen = new("account.already_open", "The account is already open."); + public static readonly Error NotOpen = new("account.not_open", "The account is not open."); + public static readonly Error AmountMustBePositive = new("account.amount_must_be_positive", "Amount must be positive."); + public static readonly Error InsufficientFunds = new("account.insufficient_funds", "Insufficient funds."); +} +``` + +### 4.1 Core types (namespace `SourceFlow` in `SourceFlow.Net`) + +```csharp +public interface IAggregate where TSelf : IAggregate where TId : struct, IStronglyTypedId +{ + static abstract TSelf Initial { get; } +} + +public readonly struct Decision +{ + public static Decision Accept(IEvent @event); + public static Decision Accept(params ReadOnlySpan events); // copied into an array + public static Decision Reject(Error error); + public static Decision NoOp { get; } + public DecisionKind Kind { get; } // Accepted | Rejected | NoOp + public ReadOnlySpan Events { get; } + public Error? Error { get; } +} + +public readonly record struct DecisionContext( + DateTimeOffset Now, // from TimeProvider; fixed for the whole decision + StreamVersion Version, // StreamVersion.None when the stream does not exist + MessageId CommandId, + CorrelationId CorrelationId, + IReadOnlyDictionary Headers) +{ + public bool IsNew => Version == StreamVersion.None; +} + +public sealed record Error(string Code, string Message, IReadOnlyDictionary? Details = null); +``` + +### 4.2 What the generator emits (illustrative) + +```csharp +partial record BankAccount : IAggregateRuntime +{ + public const string AggregateName = "bank-account"; + + // Evolve: unknown events are ignored (tolerant), so streams may carry audit-only events + public BankAccount Evolve(IEvent e) => e switch + { + AccountOpened x => When(x), + MoneyDeposited x => When(x), + MoneyWithdrawn x => When(x), + AccountClosed x => When(x), + _ => this, + }; + + public static Decision Decide(BankAccount s, ICommand c, in DecisionContext ctx) => c switch + { + OpenAccount x => s.Decide(x, ctx), + Deposit x => s.Decide(x, ctx), + Withdraw x => s.Decide(x, ctx), + CloseAccount x => s.Decide(x, ctx), + _ => throw new UnhandledCommandException(c.GetType()), // unreachable: the registry routes only these + }; + + public static AccountId TargetOf(ICommand c) => c switch + { + OpenAccount x => x.AccountId, Deposit x => x.AccountId, Withdraw x => x.AccountId, CloseAccount x => x.AccountId, + _ => throw new UnhandledCommandException(c.GetType()), + }; + + public static StreamId StreamOf(AccountId id) => StreamId.For(AggregateName, id); // "bank-account-0193…" +} +``` + +The pattern-matching `switch` over sealed types compiles to type checks with no reflection or boxing ([ADR-004](../ADRs/ADR-004-source-generation-instead-of-reflection.md)). + +## 5. Command processing + +### 5.1 Sending + +```csharp +public interface ICommandSender +{ + ValueTask SendAsync(TCommand command, SendOptions? options = null, CancellationToken ct = default) + where TCommand : class, ICommand; +} + +public sealed record SendOptions +{ + public string? IdempotencyKey { get; init; } // becomes the MessageId (UUIDv5 of the key); enables the inbox + public StreamVersion? ExpectedVersion { get; init; } // caller-side optimistic check (e.g. from If-Match) + public CorrelationId? CorrelationId { get; init; } + public IReadOnlyDictionary? Headers { get; init; } +} + +public readonly record struct CommandResult(CommandStatus Status, StreamVersion Version, Error? Error, + ConsistencyToken Token) // position + bucket + tenant; read-your-writes (doc 14 §6) +{ + // Status: Accepted | NoOp | Rejected | Conflict | Duplicate | Dispatched (sent to a remote owner) + public CommandResult ThrowIfNotAccepted(); +} +``` + +With `SourceFlow.AspNetCore`, the endpoint below is one line: `app.MapCommand("/accounts/{accountId}/deposits")`. It binds the route and body to the command, maps `Idempotency-Key` → `IdempotencyKey` and `If-Match` → `ExpectedVersion`, returns `ETag` (stream version) and `SourceFlow-Consistency` (token) headers, and turns rejections into RFC 9457 ProblemDetails (422) and conflicts into 409/412. The hand-written equivalent: + +ASP.NET Core usage: + +```csharp +app.MapPost("/accounts/{id}/deposits", async (Guid id, DepositRequest body, HttpRequest http, ICommandSender sender, CancellationToken ct) => +{ + var result = await sender.SendAsync(new Deposit(new AccountId(id), body.Amount), + new SendOptions { IdempotencyKey = http.Headers["Idempotency-Key"] }, ct); + + return result.Status switch + { + CommandStatus.Accepted or CommandStatus.NoOp or CommandStatus.Duplicate + => Results.Ok(new { version = result.Version.Value }), + CommandStatus.Rejected => Results.Problem(result.Error!.Message, statusCode: 422, title: result.Error.Code), + CommandStatus.Conflict => Results.Conflict(), + _ => Results.Accepted(), + }; +}); +``` + +### 5.2 The command processor algorithm + +```text +Process(command, envelope): + route = Router.Resolve(command.Type) // local XOR remote (ADR-007) + if route.IsRemote: + if ambient StorageSession exists: Outbox.Add(envelope) // inside handler / PM transaction + else: Transport.Send(envelope) with resilience pipeline // direct send from API + return Dispatched + + id = Generated.TargetOf(command); reject InvalidCommand if id is default + stream = Generated.StreamOf(id) + for attempt in 0..MaxConcurrencyRetries: + using session = Storage.BeginSession() // 1 DB transaction + if envelope.HasInboxKey and session.Inbox.Seen(consumer, envelope.MessageId): + return Duplicate(previous result stored in inbox row) + (state, version) = AggregateStore.Load(stream) // cache → snapshot → tail + if options.ExpectedVersion is set and != version: return Conflict + ctx = new DecisionContext(time.GetUtcNow(), version, envelope.MessageId, …) + decision = handler?.HandleAsync(...) ?? Generated.Decide(state, command, ctx) + if decision.Rejected: record inbox(result) if keyed; commit; return Rejected + if decision.NoOp: record inbox(result) if keyed; commit; return NoOp + events = Envelope(decision.Events, causation = envelope) // ids, metadata, trace + session.Append(stream, expected = version, events) // first write in tx (doc 05 §5) + session.Outbox.Add(IntegrationMapper.Map(events)) // routed publications + session.Inbox.Record(consumer, envelope.MessageId, result) // if keyed + session.Projections.ApplyInline(events) + try { session.Commit(); AggregateStore.CacheSet(stream, newState, version + n); return Accepted(version + n) } + catch ConcurrencyException: Telemetry.Conflict(); await Backoff(attempt); continue + return Conflict +``` + +Properties: one transaction; one round trip on the PostgreSQL adapter (the stream update, event insert, outbox insert and inbox insert are batched); `Decide` re-runs on fresh state; no side effects before commit. + +### 5.3 Handlers with dependencies + +```csharp +// Only when Decide needs I/O inputs. It must be read-only and safe to re-run (it can run again on a conflict). +public sealed class DepositForeignHandler(IFxRates rates) : ICommandHandler +{ + public async ValueTask HandleAsync(DepositForeign c, BankAccount state, DecisionContext ctx, CancellationToken ct) + { + var rate = await rates.GetRateAsync(c.Currency, "GBP", ctx.Now, ct); + return state.Decide(new Deposit(c.AccountId, decimal.Round(c.Amount * rate, 2)), ctx); + } +} +``` + +Handlers are resolved from a DI **scope** created per message, so their lifetimes are always correct (GAP-08). Aggregates are never DI services. + +### 5.4 Temporal reads (state as of a version or time) + +```csharp +var atMonthEnd = await aggregates.LoadAsync(accountId, AsOf.Time(monthEnd), ct); // fold events with time ≤ monthEnd +var atV10 = await aggregates.LoadAsync(accountId, AsOf.Version(10), ct); +``` + +`IAggregateReader` is part of the **read side**. It is strongly consistent, never writes, and uses snapshots whose version is at or below the bound. SFQL exposes the same capability as `from aggregate … as of …` (doc 14 §5.6). + +## 6. Reacting to events + +### 6.1 Process managers + +```csharp +[StronglyTypedId] public readonly partial record struct TransferId(Guid Value); + +[MessageType("bank.transfer.request", 1)] +public sealed record RequestTransfer(TransferId TransferId, AccountId From, AccountId To, decimal Amount) : ICommand; +// … Transfer is a small aggregate that emits TransferRequested / TransferCompleted / TransferFailed + +[ProcessManager("money-transfer")] +public sealed partial record MoneyTransfer : IProcessManager +{ + public static MoneyTransfer Initial { get; } = new(); + public TransferStage Stage { get; init; } + public AccountId From { get; init; } + public AccountId To { get; init; } + public decimal Amount { get; init; } + + // Correlation: by default the envelope CorrelationId (set from the PM instance on every command it sends). + // Starting events declare it explicitly: + public static TransferId CorrelateBy(TransferRequested e) => e.TransferId; + + public Reaction React(TransferRequested e, ReactionContext ctx) => + Reaction.Send(new Withdraw(e.From, e.Amount)) + .Schedule(new TransferTimedOut(e.TransferId), ctx.Now.AddMinutes(5)) + .AndBecome(this with { Stage = TransferStage.Withdrawing, From = e.From, To = e.To, Amount = e.Amount }); + + public Reaction React(MoneyWithdrawn e, ReactionContext ctx) => Stage switch + { + TransferStage.Withdrawing => Reaction.Send(new Deposit(To, Amount)).AndBecome(this with { Stage = TransferStage.Depositing }), + _ => Reaction.Ignore, + }; + + public Reaction React(MoneyDeposited e, ReactionContext ctx) => Stage switch + { + TransferStage.Depositing => Reaction.Send(new CompleteTransfer(ctx.Id)).AndComplete(), + _ => Reaction.Ignore, + }; + + public Reaction React(CommandRejected r, ReactionContext ctx) => + Reaction.Send(new FailTransfer(ctx.Id, r.Error.Code)).AndComplete(); + + public Reaction React(TransferTimedOut t, ReactionContext ctx) => Stage switch + { + TransferStage.Withdrawing => Reaction.Send(new FailTransfer(ctx.Id, "timeout")).AndComplete(), + TransferStage.Depositing => Reaction.Send(new Deposit(From, Amount)).AndSend(new FailTransfer(ctx.Id, "timeout")).AndComplete(), // compensate + _ => Reaction.Ignore, + }; +} +``` + +**Two ways to author a process manager.** Write the record by hand, as above, or describe the workflow in the YAML DSL and let the generator produce it ([doc 15](15-Workflow-DSL-and-Studio.md), [ADR-024](../ADRs/ADR-024-workflow-dsl-compiled-to-process-managers.md)). Generated workflows add declarative business retries, reverse-order compensation, a pivot and manual intervention, and can be visualised and simulated in SourceFlow Studio. Both run on the same runtime. + +`ReactionContext` carries the strongly typed instance id (`ctx.Id`), the reaction time, the message id and whether the message starts the instance. `Reaction` API (DC-3): static entry points `Reaction.Send(…)`, `Reaction.Become(…)`, `Reaction.Complete()` and `Reaction.Ignore`; chained instance methods `AndSend`, `Schedule`, `AndBecome` and `AndComplete`. C# can't have a static and an instance method with the same signature, so the earlier `.Send(…).Send(…)` shape isn't possible. + +**Runtime semantics** ([ADR-020](../ADRs/ADR-020-process-managers-with-durable-state-and-timers.md)): + +1. The process manager subscribes to every event type it has a `React` for. The source can be local (the subscription engine) or remote (the receive pipeline). +2. For each event, in one transaction: + - load the instance state (or `Initial` if this event starts it); + - call `React`; + - persist the new state with optimistic concurrency; + - add the commands and timers to the outbox; + - record the inbox entry and the checkpoint. +3. `Complete()` marks the instance complete. Later events for it are ignored, and the state is kept for `CompletedRetention` (default 30 days) for diagnostics. +4. **Rejections as inputs.** When a command sent by a process manager is rejected by its owner, the owner sends a `CommandRejected` reply to the correlation (if `ReplyOnReject` is set on the route). This closes the loop for compensation without exceptions ([ADR-018](../ADRs/ADR-018-business-rejections-are-values-not-exceptions.md)). + +### 6.2 Event handlers (side effects) + +```csharp +public sealed class WelcomeEmailHandler(IEmailGateway email) : IEventHandler +{ + public async ValueTask HandleAsync(AccountOpened e, EventContext ctx, CancellationToken ct) + => await email.SendWelcomeAsync(e.AccountId, idempotencyKey: ctx.EventId.ToString(), ct); +} +``` + +Event handlers run on the subscription engine with **at-least-once** semantics. A handler whose side effect is external must be idempotent; `ctx.EventId` is the natural key. A side effect that can be expressed as a command to another service should use `ctx.Session.Send(...)` instead, which goes through the outbox and so becomes effectively-once. + +### 6.3 Projections + +```csharp +public sealed record AccountSummary(AccountId Id, string Holder, decimal Balance, AccountStatus Status, long Version); + +[Projection("account-summary", Version = 1)] // bump Version → blue/green rebuild (doc 06) +public sealed partial class AccountSummaryProjection : IDocumentProjection +{ + // Key defaults to the aggregate id of the source stream; override with KeyOf(e) if needed. + public AccountSummary When(AccountOpened e, AccountSummary? _, EventContext ctx) + => new(e.AccountId, e.Holder, e.InitialDeposit, AccountStatus.Open, ctx.StreamVersion.Value); + + public AccountSummary? When(MoneyDeposited e, AccountSummary? doc, EventContext ctx) + => doc is null ? null : doc with { Balance = e.BalanceAfter, Version = ctx.StreamVersion.Value }; + + public AccountSummary? When(MoneyWithdrawn e, AccountSummary? doc, EventContext ctx) + => doc is null ? null : doc with { Balance = e.BalanceAfter, Version = ctx.StreamVersion.Value }; + + public AccountSummary? When(AccountClosed e, AccountSummary? doc, EventContext ctx) + => doc is null ? null : doc with { Status = AccountStatus.Closed, Version = ctx.StreamVersion.Value }; +} +``` + +An EF Core projection writes relational read models in the projection's transaction: + +```csharp +public sealed class BranchTotalsProjection : IEfProjection +{ + public async ValueTask When(MoneyDeposited e, ReportingDbContext db, EventContext ctx, CancellationToken ct) + => await db.BranchTotals.Where(b => b.AccountId == e.AccountId.Value) + .ExecuteUpdateAsync(s => s.SetProperty(b => b.Total, b => b.Total + e.Amount), ct); +} +``` + +Projection functions are deterministic and contain no I/O except through the store they are given. That makes them replay-safe, so a rebuild can never cause a side effect. + +## 7. Integration events + +Domain events are private to a service. What leaves the service is an explicit, versioned contract: + +```csharp +[MessageType("accounts.account-opened", 1)] +public sealed record AccountOpenedV1(Guid AccountId, DateTimeOffset OpenedAt) : IIntegrationEvent; // no PII by design + +sf.Routing(r => r.Publish() + .As(e => new AccountOpenedV1(e.AccountId.Value, e.OpenedAt)) + .To("accounts.events")); +``` + +The mapping runs **inside the command transaction**, and its output goes to the outbox. Publishing a domain event unchanged needs an explicit `.AsIs()`, and the analyzer warns (SF0013) when that event contains `[PersonalData]`. + +## 8. Composition and host configuration + +```csharp +[SourceFlowModule(typeof(AccountsJsonContext))] // generator fills in handlers, aggregates, PMs, projections, registry (DC-1) +public sealed partial class AccountsModule; + +[JsonSerializable(typeof(OpenAccount))] /* … every message, document and process-state type; SF0010 checks completeness */ +[JsonSourceGenerationOptions(PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase)] +public sealed partial class AccountsJsonContext : JsonSerializerContext; + +var builder = WebApplication.CreateBuilder(args); + +builder.Services.AddSourceFlow(sf => +{ + sf.ServiceName = "accounts"; // envelope 'source', default endpoint, consumer names + sf.AddModule(); + sf.UsePostgreSql(builder.Configuration.GetConnectionString("accounts")!); + sf.UseAmazonSqs(aws => aws.Region = "eu-west-1"); // honoured: becomes the client config (GAP-03) + + sf.Routing(r => + { + r.Command().To("notifications"); // owned by another service + r.Publish().As(AccountContracts.ToV1).To("accounts.events"); + r.Subscribe("payments.events"); // integration events from others + }); + + sf.Projections(p => + { + p.Add().Inline(); // read-your-writes + p.Add().Async(partitions: 4); + }); + + sf.ProcessManagers(pm => pm.Add()); +}); + +builder.Services.AddOpenTelemetry() + .WithTracing(t => t.AddSource(SourceFlowTelemetry.ActivitySourceName).AddOtlpExporter()) + .WithMetrics(m => m.AddMeter(SourceFlowTelemetry.MeterName).AddOtlpExporter()); + +builder.Services.AddHealthChecks().AddSourceFlow(); // readiness, store, transport, lag, outbox age +``` + +The generated module registers **only** what it found at compile time, with no assembly scanning (GAP-16). + +## 9. Analyzers + +| Id | Severity | Rule | +|----|----------|------| +| SF0001 | Error | A type implementing `ICommand`, `IEvent` or `IIntegrationEvent` lacks `[MessageType]`. | +| SF0002 | Error | Duplicate `(name, version)` within the compilation. Cross-assembly duplicates are caught at startup. | +| SF0003 | Error | A command's target id is missing or ambiguous: no member, or several members, of the aggregate's id type. | +| SF0004 | Error | A `When` method has side effects: it calls I/O (`System.IO`, `System.Net`, `System.Data`, EF Core, `Console`), assigns fields, changes a collection reachable from `this` through a method call (`Items.Add`), or has an `async` modifier, including in lambdas and local functions inside it. | +| SF0005 | Warning | An event produced by `Decide` has no `When` in that aggregate. The state ignores it. | +| SF0006 | Warning | A command type has no `Decide` or handler in this compilation, and no route. Startup turns this into an error. | +| SF0007 | Error | `Decide` is `async`, or returns `Task`/`ValueTask`. Use `ICommandHandler` for I/O. | +| SF0008 | Error | An aggregate or process manager is not a `sealed record`, or has `set` accessors (only `init` is allowed). | +| SF0009 | Warning | Non-deterministic API in `Decide`, `When` or `React` (`DateTime.*Now`, `Guid.NewGuid`, `Guid.CreateVersion7`, a generated `Id.New()`, `Random`, `Environment.TickCount`). Use `ctx`: `ctx.Now`, and `ctx.NewId(purpose)` for ids, which derives the id from the command or message id, so a retry creates the same one. | +| SF0010 | Error | A message member type is not supported by the System.Text.Json source generator. | +| SF0011 | Error | `[PersonalData]` is used in an event without a resolvable subject key (doc 10 §4). | +| SF0012 | — | *Not built* (WP-C.17, CR-57). A message without `CorrelateBy` correlates through the envelope's correlation, which replies to the process manager's commands carry; an event that has neither is dropped at runtime, and the specs fail on it (UT-TST-21). | +| SF0013 | Warning | `.AsIs()` publishes an event containing `[PersonalData]`. | +| SF0014 | Error | A command type is both handled locally and routed remotely ([ADR-007](../ADRs/ADR-007-single-command-ownership-route-local-xor-remote.md)). The analyzer catches it when routing uses constant expressions and the aggregate or handler is declared in the same compilation; an aggregate from a referenced assembly is another service's, whose contracts this one uses. Startup validation always catches it. | +| SF0015 | Error | `IQueryService` or `IAggregateReader` used inside `Decide`, `When`, `React` or projection code. CQRS separation (doc 14 Q-R1). | +| SF0016 | Warning | `IQueryService` used in an `ICommandHandler`: the decision depends on eventually consistent reads. | +| SF0017 | Warning | `[Queryable]` on a `[PersonalData]` member. It has no effect, because ciphertext can't be indexed. | +| SF0019 | Warning | Static analysis can't determine the events or rejection codes a `Decide` produces; declare `[Emits(typeof(…))]` / `[Rejects("code")]` so service manifests are exact (doc 15 §3.2) | +| SF0020 | Error | Workflow DSL validation failure (rule WF-V01…V16 named in the message), reported at the `.sfflow.yaml` line (doc 15 §5.4) | +| SF0021 | Error | A workflow `$hook` partial method has no implementation (doc 15 §5.5) | +| SF0018 | Error | A `[DomainQuery]` doesn't bind against the service's own catalog, or its result columns don't match the result record (doc 14 §1.1, Q-B4). | +| SF0022 | Error | A strongly typed id's `Backing` disagrees with the type of its `Value` (CR-30). | +| SF0023 | Error | An upcaster has no public parameterless constructor, so the generated module can't create it (CR-56). | +| SF0024 | Warning | Aggregate state holds a mutable collection (`List`, `Dictionary<,>`, an array…): a `When` that changes it in place changes the previous state too (CR-51). | +| SF0025 | Error | A `Decide` for a command that targets another aggregate (`ICommand`). Startup refuses it too (CR-52). | diff --git a/docs/v3.0.0/engineering/Design/04-Messaging-Pipeline.md b/docs/v3.0.0/engineering/Design/04-Messaging-Pipeline.md new file mode 100644 index 00000000..e4bd3f2a --- /dev/null +++ b/docs/v3.0.0/engineering/Design/04-Messaging-Pipeline.md @@ -0,0 +1,287 @@ +# 04 — Messaging Pipeline and Delivery Semantics + +Design drivers: [ADR-005](../ADRs/ADR-005-logical-message-type-names-and-registry.md), [ADR-006](../ADRs/ADR-006-transactional-outbox-and-inbox-for-effectively-once.md), [ADR-007](../ADRs/ADR-007-single-command-ownership-route-local-xor-remote.md), [ADR-011](../ADRs/ADR-011-cloudevents-envelope-and-w3c-trace-context.md), [ADR-012](../ADRs/ADR-012-one-middleware-abstraction-for-all-stages.md), [ADR-013](../ADRs/ADR-013-use-platform-libraries-delete-bespoke-equivalents.md) and [ADR-018](../ADRs/ADR-018-business-rejections-are-values-not-exceptions.md). Fixes: GAP-01, GAP-09, GAP-10, GAP-11, GAP-19 and NFR-REL-04/06. + +## 1. The envelope + +Every message, in process, in the outbox, on the wire, or in a dead-letter record, travels in one `MessageEnvelope`. + +```csharp +public sealed class MessageEnvelope +{ + public required MessageId MessageId { get; init; } // UUIDv7, logical id; the idempotency key + public required MessageTypeName Type { get; init; } // "bank.account.deposited" + public required int TypeVersion { get; init; } // 1 + public required string Source { get; init; } // "accounts" (service name) + public required DateTimeOffset Time { get; init; } + public CorrelationId CorrelationId { get; init; } // conversation / process id + public MessageId? CausationId { get; init; } // the message that caused this one + public string? Subject { get; init; } // stream id for events; target id for commands + public string? PartitionKey { get; init; } // ordering key (defaults to Subject) + public long? StreamVersion { get; init; } // events only + public string? TenantId { get; init; } // ADR-022; drives RLS and query scoping + public string? Actor { get; init; } // who caused it (IActorAccessor), for audit (doc 10 §1) + public string? TraceParent { get; init; } + public string? TraceState { get; init; } + public string ContentType { get; init; } = "application/json"; + public string? Protection { get; init; } // e.g. "kms:aws:arn:…:key/…" when encrypted + public int? Attempts { get; init; } // attempts so far, on a delayed-retry re-send (§9.2) + public IReadOnlyDictionary Headers { get; init; } = Empty; // user extensions (bounded, §2.3) + public ReadOnlyMemory Body { get; init; } // serialized (and possibly encrypted) payload +} +``` + +### 1.1 CloudEvents mapping ([ADR-011](../ADRs/ADR-011-cloudevents-envelope-and-w3c-trace-context.md)) + +| Envelope | CloudEvents attribute | Notes | +|----------|-----------------------|-------| +| `MessageId` | `id` | | +| `Source` | `source` | `urn:sourceflow:{service}` | +| `Type` + `TypeVersion` | `type` | `bank.account.deposited.v1` | +| — | `specversion` | `1.0` | +| `Subject` | `subject` | | +| `Time` | `time` | RFC 3339 | +| `ContentType` | `datacontenttype` | | +| `CorrelationId` | `sfcorrelationid` | extension | +| `CausationId` | `sfcausationid` | extension | +| `PartitionKey` | `sfpartitionkey` | extension | +| `StreamVersion` | `sfstreamversion` | extension | +| `TenantId` | `sftenant` | extension | +| `Actor` | `sfactor` | extension (travels in `sfext` on SQS, where attributes are limited) | +| `Headers` | `sfheaders` | extension: the user headers, as a JSON object | +| `Protection` | `sfenc` | extension | +| `Attempts` | `sfattempt` | extension; set only on a delayed-retry re-send (§9.2) | +| `TraceParent` / `TraceState` | `traceparent` / `tracestate` | distributed-tracing extension | + +Extensions that don't fit a broker's attribute budget go together in one `sfext` attribute (a JSON object); `id`, `source`, `specversion`, `type`, `time` and `datacontenttype` never do. The version is part of `type`; `dataschema` isn't used. + +Transports use **binary mode**: attributes go in native headers (`ce_` prefix where required) and the body is the data. When a broker's header budget is too small, the transport switches to **structured mode** (a CloudEvents JSON document) and sets `content-type: application/cloudevents+json`. Both modes round-trip losslessly, which the conformance kit checks. + +## 2. Type registry and serialisation + +### 2.1 Registry + +- Built at startup from generated module registrations only ([ADR-004](../ADRs/ADR-004-source-generation-instead-of-reflection.md)). It is frozen into a `FrozenDictionary<(string name, int version), MessageTypeInfo>` and a `FrozenDictionary`. +- `MessageTypeInfo` holds the CLR type, the `JsonTypeInfo` (source-generated), the kind (command, event or integration event), the upcaster chain, any `[PersonalData]` members, and the size limit. +- **Allow-list semantics**: a received or stored envelope whose `(type, version)` isn't registered is never deserialised. It is parked with reason `UnknownMessageType` (GAP-10). +- Startup validation catches duplicate names across modules, events without upcasters for versions older than the latest when those versions are still in the store (opt-in check), and commands with no owner or route. + +### 2.2 Serialiser + +```csharp +public interface IMessageSerializer +{ + string ContentType { get; } + void Serialize(object message, MessageTypeInfo type, IBufferWriter destination); + object Deserialize(ReadOnlySequence source, MessageTypeInfo type); +} +``` + +- The default is `SystemTextJsonMessageSerializer`. It uses the module-declared, source-generated `JsonSerializerContext` (no reflection; completeness checked by SF0010, see DC-1 in ADR-004), camelCase names, strict number handling, and rejects duplicate properties. It writes into a pooled `IBufferWriter` and reads from `ReadOnlySequence`, so large bodies don't need to be contiguous. +- The serialiser is pluggable per content type (for example Protobuf), but only JSON ships in 3.0 (YAGNI). + +### 2.3 Size and header limits + +| Limit | Default | Enforcement | +|-------|---------|-------------| +| Body size | Transport capability (SNS 256 KB, SQS 1 MiB, ASB 256 KB Standard / 100 MB Premium, Pub/Sub 10 MB) minus envelope overhead | Checked **before** the outbox insert, so the command fails with `MessageTooLarge` instead of being parked later. NFR-PERF-07 | +| User headers | 8 entries, 256 bytes each | Validated in the Send stage | + +The transport capability values come from each transport's `TransportCapabilities`, so they aren't hard-coded in the core. + +## 3. Routing + +```csharp +sf.Routing(r => +{ + r.Endpoint("accounts"); // default: ServiceName. Receives commands + subscribed events + r.Command().To("notifications") // remote owner's endpoint + .ReplyOnReject(); // owner replies CommandRejected to the correlation + r.Publish().As(AccountContracts.ToV1).To("accounts.events") + .OrderedBy(e => e.AccountId); // partition key (default: stream id) + r.Subscribe("payments.events", s => s.Only()); // filter on the subscription where supported + r.Subscribe("orders.events", s => s.Filter("type LIKE 'orders.order-%' AND sftenant = 'eu'")); // CESQL (doc 14 §5.1) +}); +``` + +| Rule | Detail | +|------|--------| +| RT-R1 | A command type is **owned** (it has a local `Decide` or handler) or **routed** (`.To(endpoint)`). Never both, never neither ([ADR-007](../ADRs/ADR-007-single-command-ownership-route-local-xor-remote.md), SF0014). | +| RT-R2 | An owner receives remote commands on its endpoint, and they go through the same command processor as local ones. The owner sequences them, logs them and can replay its streams (GAP-19). | +| RT-R3 | Domain events are published **only** through `Publish()` mappings, and therefore only through the outbox. | +| RT-R4 | Each service has **its own subscription** per subscribed topic. Fan-out is to every subscribing service; instances of one service compete (doc 07). Fixes GAP-02 and GAP-13. | +| RT-R5 | Endpoint and topic names are logical. The transport maps them to physical names with a configurable naming convention (prefix, environment, FIFO suffix). | +| RT-R6 | Routing and topology are validated at startup. Under `ProvisioningMode.Validate`, the physical resources are validated too ([ADR-017](../ADRs/ADR-017-provisioning-modes-and-topology-as-data.md)). | + +## 4. Middleware pipeline ([ADR-012](../ADRs/ADR-012-one-middleware-abstraction-for-all-stages.md)) + +```csharp +public interface IMessageMiddleware +{ + ValueTask InvokeAsync(MessageContext context, MessageDelegate next); +} + +public delegate ValueTask MessageDelegate(MessageContext context); + +public sealed class MessageContext +{ + public PipelineStage Stage { get; } // Send | Handle | Receive | Publish | Project + public MessageEnvelope Envelope { get; } + public object? Message { get; set; } // deserialized payload (null until the Deserialize step) + public MessageTypeInfo TypeInfo { get; } + public IServiceProvider Services { get; } // scope for this message + public IStorageSession? Session { get; } // set inside transactional stages + public Activity? Activity { get; } + public CancellationToken CancellationToken { get; } + public HandlingOutcome Outcome { get; set; } // set by the terminal step + public IDictionary Items { get; } // per-message bag for middleware +} +``` + +Registration: `sf.Pipeline(p => p.Use(PipelineStage.Handle | PipelineStage.Receive).For())`. + +Composition: for each `(stage, message type)` the runtime builds the delegate chain once, the first time it is needed, and caches it. Middleware instances are resolved from the per-message scope, unless registered as singletons. + +### 4.1 Built-in middleware order (outermost first) + +| # | Middleware | Stages | Purpose | +|---|------------|--------|---------| +| 1 | `TelemetryMiddleware` | all | Starts the span, records duration and outcome metrics, links to the producer span (doc 08) | +| 2 | `LoggingScopeMiddleware` | all | Log scope with message id, type, correlation and tenant (redacted) | +| 3 | `ErrorClassificationMiddleware` | Receive, Project | Maps exceptions to `Transient`, `Permanent` or `Concurrency` (§9) | +| 4 | `PayloadProtectionMiddleware` | Send/Publish (encrypt), Receive (decrypt) | KMS envelope encryption (doc 10) | +| 5 | `DeserializeMiddleware` | Receive | Registry lookup (allow-list), then upcast and deserialise | +| — | *user middleware* | as registered | | +| 6 | `ValidationMiddleware` *(optional)* | Send, Receive | Runs `IValidator` (a FluentValidation or DataAnnotations adapter) and turns failures into a `Rejected` result | +| 7 | `TransactionMiddleware` | Handle, Receive, Project | Opens the `IStorageSession`. Commits after the terminal step. | +| 8 | `InboxMiddleware` | Receive, Handle when keyed | Duplicate check and record in the same session | +| 9 | Terminal | — | Command processor, event handler, process manager, or projection apply | + +> **As built (WP-C.15, CR-46).** Every stage runs where this section puts it: +> - **Send.** `ICommandSender`: around the outbox write, or around the local processor call. +> - **Handle.** Inside `CommandProcessor`, for commands sent here and commands received from other services alike, so an authorisation middleware sees every command this service decides. A middleware that doesn't call the next step must set `MessageContext.Result`. +> - **Receive.** The receive endpoint's built-ins (telemetry, the log scope, error classification, payload protection) run first. `DeserializeMiddleware` then resolves the type and deserialises, so user middleware sees `MessageContext.Message`. +> - **Publish.** The outbox relay runs it before each broker call. Middleware may change the envelope (`MessageContext.Items["sourceflow.destination"]` names the topic or queue). One that doesn't call the next step drops the message, and the row completes. One that throws fails that row. +> - **Project.** The subscription engine runs it around each applied event, with `MessageContext.Session` set to the subscription's session (`Items["sourceflow.subscription"]` names it). Not calling the next step skips the event. +> - **The log scope** opens around every stage. Receive opens its own in the endpoint. +> - **Publish and Project run only when middleware is registered for them** (`MessagePipeline.Has`), so the relay and the subscriptions pay nothing otherwise. Chains are composed once per stage. +> - **Deviations.** Telemetry stays the Receive built-in: the other stages have their own spans (`send`, the command span, the subscription span). The transaction, inbox and retry steps stay inside the terminal step rather than becoming separate middleware. Filters remain per message (`Func`): evaluating them once at composition would need a type-only filter, an API change left for a later version. + +## 5. Receive pipeline + +```mermaid +flowchart LR + T[Transport receiver
prefetch N] --> C{Partitioned dispatcher
hash(partitionKey) % W} + C --> W1[Worker 1
bounded channel] + C --> W2[Worker 2] + C --> Wn[Worker W] + W1 --> P[Middleware pipeline
Receive stage] + P --> S{Outcome} + S -- Completed/Rejected/Duplicate --> ACK[settle: complete/ack/delete] + S -- Transient --> RETRY[settle: delay / abandon] + S -- Permanent or retries exhausted --> PARK[park to dead letters, then ack] +``` + +| Rule | Detail | +|------|--------| +| RX-R1 | **Ordering.** Messages with the same partition key are handled one at a time, in arrival order, by the same worker. Different keys run in parallel (`MaxConcurrency`, default `Environment.ProcessorCount * 2`). | +| RX-R2 | **Backpressure.** Each worker's channel is bounded (`PrefetchPerWorker`, default 16). The receiver stops pulling when channels are full. | +| RX-R3 | **Settle after commit.** The broker is acknowledged only after the handler transaction commits. A crash before the ack causes redelivery, which the inbox deduplicates. | +| RX-R4 | **Lock renewal.** Transports with message locks or visibility timeouts extend them while a message is in flight (SQS `ChangeMessageVisibility`, ASB lock renewal, Pub/Sub ack-deadline extension). | +| RX-R5 | **One input endpoint, one receiver.** Commands and events arriving on the same endpoint are told apart by envelope `type`, never by competing listeners. Fixes GAP-02. | +| RX-R6 | **Graceful shutdown.** Stop pulling, finish in-flight messages within `ShutdownTimeout`, and abandon the rest so they are redelivered quickly. As built (WP-C.6): draining starts in `StoppingAsync`; queued messages are abandoned with no delay; handlers run under their own token, cancelled only when `ShutdownTimeout` is up. | + +## 6. Inbox + +- The key is `(consumer, message_id)`. `consumer` is `{service}` for command handling, `{service}:{projection|pm|handler name}` for subscribers, and `{service}:local` for keyed local sends. +- It is written in the **same transaction** as the effects. A duplicate shows up as a unique-key violation at insert, or as an early `Seen` check that avoids wasted work. Either way the transaction is rolled back and the message is acknowledged as `Duplicate`. +- **Stored result**: for command consumers the inbox row keeps `(status, version, error_code)`, so a duplicate `SendAsync` with the same idempotency key returns the original `CommandResult`. This is the HTTP `Idempotency-Key` semantics. +- **Retention**: `InboxRetention` (default 14 days) MUST be at least the longest broker redelivery or retention window. This is validated at startup against `TransportCapabilities.MaxRetention`. Cleanup is a batched background delete. + As built (WP-C.6): a shorter retention fails startup when provisioning is `Validate` and logs a warning (event 1405) otherwise, so local development with `CreateIfMissing` is not blocked. + +## 7. Outbox + +- Rows are written by the command processor (integration events, routed commands sent from handlers), by process managers (commands, timers), and by handlers (`ctx.Session.Send/Publish/Schedule`). +- **Partitioning**: `partition = hash(partition_key) mod OutboxPartitions` (default 16). Order is guaranteed **per partition key**. +- **Relay algorithm** (per instance): + +```text +loop: + for each outbox partition p where this instance holds lease(p) (fenced, doc 06 §4): + rows = SELECT … WHERE partition = p AND deliver_at <= now ORDER BY seq LIMIT BatchSize + group rows by destination; publish each group with the transport's batch API (in seq order per key) + on success: DELETE rows (same fencing token) + on transient failure: increment attempts, set next deliver_at with backoff; stop this partition's batch + (a later row with the same key must not overtake a failed one) + on permanent failure (e.g. destination missing): move to dead letters with reason OutboxPublishFailed + wait for wake-up (NOTIFY / in-process signal after commit) or PollInterval (default 1 s, adaptive) +``` + +- **Leases** spread partitions across instances, so relay throughput grows with instance count (up to the number of partitions). + +> **As built (WP-C.6, CR-43).** A claim returns only the head row of each key, so the relay groups a claim's rows by destination and kind and sends each group in one `SendAsync`/`PublishAsync` call; the transport splits it by its batch limits. A partial batch (`TransportSendException`) fails only the rows it names, each classified as a one-message send failure. A drain renews its partition lease every third of `LeaseTtl` (re-acquiring it under the same token); if the lease lapsed meanwhile, the drain stops and whoever holds it now relays the partition. The `send` span stays one per message. +- **Why an outbox table rather than log tailing.** Tailing the event log avoids a second write, but it can only publish *events*. Remote commands, replies and timers would still need a table. Tailing also forces the relay to read every event in order to find the few that are published. One mechanism for every outbound message is simpler (KISS) and lets publication order follow the partition key rather than global commit order. The cost is about one small insert per published message. Measured cost and the alternative are revisited in [doc 09](09-Performance-and-Scalability.md). + +## 8. Scheduler (durable timers and delayed delivery) + +- `Schedule(message, at)` writes an outbox row with `deliver_at = at`. Delivery uses the same relay. Timers addressed to the local service are delivered to its own endpoint (or handled locally when the transport is in-memory). +- Precision is ±`PollInterval`. Timers survive restarts and scale out with the outbox partitions. +- Cancelling a timer: process managers ignore a timeout whose stage no longer matches (idempotent by design). `Reaction.CancelSchedule(id)` deletes the row if it hasn't been sent yet. + +## 9. Failure handling + +### 9.1 Classification + +| Class | Examples | Action | +|-------|----------|--------| +| **Rejected** (handled outcome) | `Decision.Reject`, validation failure | Commit inbox and result, ack, optional `CommandRejected` reply. No retry. | +| **Concurrency** | `ConcurrencyException` after the processor's own retries | Immediate retries, then delayed retries | +| **Transient** | Timeouts, `DbException.IsTransient`, broker throttling, HTTP 5xx/429 | Immediate retries (Polly, default 3, jittered 50–500 ms), then **delayed retries** through the transport (default schedule 10 s, 1 min, 10 min, 1 h) | +| **Permanent** | Unknown type, deserialisation failure, decryption failure, `PermanentException`, `ArgumentException` from user code (configurable) | Park immediately | +| **Exhausted** | A transient failure after every delayed retry | Park | + +The exception→class mapping is configurable through `sf.Errors(e => e.Treat().AsTransient())`. + +> **As built (WP-C.14, CR-39, CR-45).** Every in-process retry goes through a Polly v8 `ResiliencePipeline` (`Polly.Core`), named by `SourceFlowResilience`. Infrastructure timing uses the system clock. +> +> | Pipeline | Used by | Behaviour | +> |---|---|---| +> | `sourceflow.concurrency` | the command processor's re-decide | retries a `ConcurrencyException` `MaxConcurrencyRetries` times, exponential with jitter, 5–50 ms (ADR-008) | +> | `sourceflow.immediate` | receive and subscriptions | retries a transient outcome or failure `ImmediateRetries` times, at once; a permanent failure or a lost lease isn't retried | +> | `sourceflow.outbox` | the outbox relay, one per destination | a circuit breaker: after 20 transient failures in a row within 30 s, the relay leaves that destination alone for 15 s. The rows wait without spending attempts, and a trial call then closes it (F-07) | +> | `sourceflow.ingest` | the broker dead-letter ingestor | retries a failed poll, exponential from 1 s up to `DeadLetterIngestInterval` | +> +> - **Stored retries.** These outlive the process: an outbox row's next attempt, exponential from 2 s with equal jitter up to 5 min; and a stalled subscription's next try, from 1 s doubling up to 5 min. They come from one `Backoff` function. The delayed-retry schedule stays the `DelayedRetries` list. +> - **Customising.** `sf.Resilience(r => r.Configure(SourceFlowResilience.Outbox, b => b.AddTimeout(...)))` adds strategies inside SourceFlow's own. +> - **ARCH-10.** No exponent, jitter or retry `Task.Delay` exists outside the engine. +> - **Deviations.** Immediate retries don't wait (the table's 50–500 ms jitter was never built), as before. The pipelines are built in the core rather than registered through `Microsoft.Extensions.Resilience`, which would add Polly.Extensions and the telemetry packages. + +### 9.2 Delayed retries + +The runtime prefers the broker's native delay: SQS `ChangeMessageVisibility` (up to 12 h), ASB scheduled re-send, Pub/Sub nack with the subscription's retry policy. When the transport lacks a capability, the fallback is an outbox row with `deliver_at` addressed to the same endpoint, carrying an incremented `sfattempt` header. The delay schedule is identical on every transport ([ADR-014](../ADRs/ADR-014-transport-spi-and-conformance-kit-parity-required.md)). + +> **As built (WP-C.6).** +> - A delay up to the transport's `MaxDelay` uses the native delay (`AbandonAsync(delay)`). +> - A longer delay uses the fallback above. The message is queued as received (still protected, same id) as an `OutboxKind.Scheduled` row for this endpoint, with `deliver_at = now + delay` and `sfattempt` set to the attempts so far. Then the original is completed. A crash between the two duplicates it, which the inbox absorbs. The receiver counts attempts as `sfattempt + DeliveryCount`, so the budget and the parked record's `Attempts` span the re-sends. +> - On an ordered endpoint the fallback would let the key's next message overtake the head, so the delay is capped at `MaxDelay`. Startup logs the capped entries (event 1404). +> - **Per-key order on retry.** On an ordered endpoint, when a key's head is abandoned for a delayed retry, the worker releases the key's messages it had already received behind it, unhandled, with the head's delay, so they never become visible before the head. A broker that holds the key back while the head waits (SQS FIFO, Service Bus sessions) would keep them back anyway; one that does not (LocalStack, TCK-46) cannot hand them out first. Messages of other keys are unaffected. + +### 9.3 Dead letters (parking) + +- **One place to look.** Parked messages go to `sf_dead_letters` in the service's own database (doc 05 §7.5), with the full envelope, the exception chain, attempt history and the consumer. +- **The native broker DLQ is a backstop.** Native DLQs are configured with `maxReceiveCount` greater than the runtime's own budget. They only catch messages that crash the process before the runtime can park them. A `DeadLetterIngestor` background service drains native DLQs into `sf_dead_letters`, so operators still have one view (GAP-11). +- **Operations** (CLI `dotnet sourceflow dlq …` and the `IDeadLetterManager` API): list and filter, show, **replay** (re-sends the original envelope to its original endpoint with a new delivery attempt; the message id is kept, so the inbox still protects against duplicates), discard (with a reason, audited), and purge older than a cutoff. +- **Metrics**: `sourceflow.deadletter.parked` (counter, by consumer, type and reason) and `sourceflow.deadletter.count` (gauge). Alert on any increase. + +## 10. Delivery semantics summary + +| Path | Guarantee | Mechanism | +|------|-----------|-----------| +| Local `SendAsync` → aggregate | Atomic. Effectively-once when keyed. | One transaction. Inbox on the idempotency key. | +| Command → remote owner | At-least-once delivery, effectively-once effect, per-key order | Outbox → broker → inbox at the owner | +| Integration event → subscribers | At-least-once delivery, effectively-once effect per subscribing service, per-key order | Outbox → topic → per-service subscription → inbox | +| Event → inline projection | Atomic with the append | Same transaction | +| Event → async projection or process manager (same database) | Exactly-once effect, per-stream order | Checkpoint in the same transaction, fenced leases | +| Event → async projection (other database) | At-least-once; idempotent by stream version | `version` guard in the read model (doc 06 §5) | +| Event → `IEventHandler` with external side effect | At-least-once | The user makes it idempotent with `EventId` | +| Timer | At-least-once at or after `deliver_at` | Outbox and scheduler | diff --git a/docs/v3.0.0/engineering/Design/05-Event-Store-and-Persistence.md b/docs/v3.0.0/engineering/Design/05-Event-Store-and-Persistence.md new file mode 100644 index 00000000..cca3b8a1 --- /dev/null +++ b/docs/v3.0.0/engineering/Design/05-Event-Store-and-Persistence.md @@ -0,0 +1,494 @@ +# 05 — Event Store and Persistence + +Design drivers: [ADR-002](../ADRs/ADR-002-event-sourcing-replaces-command-sourcing.md), [ADR-006](../ADRs/ADR-006-transactional-outbox-and-inbox-for-effectively-once.md), [ADR-008](../ADRs/ADR-008-optimistic-concurrency-with-automatic-re-decide.md), [ADR-009](../ADRs/ADR-009-event-store-on-adonet-postgresql-first.md), [ADR-010](../ADRs/ADR-010-commit-ordered-global-position-for-gap-free.md) and [ADR-016](../ADRs/ADR-016-projections-inline-or-async-with-partitioned-fenced.md). Fixes: GAP-04, GAP-05, GAP-15, GAP-17, CMD-05, EF-06, EF-21 and NFR-PERF-03. + +## 1. Ports + +The core defines small role interfaces (ISP). A storage adapter implements all of them for its database, and the storage conformance kit verifies them ([doc 11](11-Testing-and-Quality.md)). + +```csharp +public interface IEventStore // streams +{ + ValueTask ReadStreamAsync(StreamId stream, StreamVersion fromInclusive, int maxCount, CancellationToken ct); + IAsyncEnumerable ReadStreamBackwardsAsync(StreamId stream, int maxCount, CancellationToken ct); + ValueTask GetStreamInfoAsync(StreamId stream, CancellationToken ct); +} + +public interface IEventLogReader // global, commit-ordered (ADR-010) +{ + ValueTask ReadAsync(GlobalPosition after, BucketRange buckets, int maxCount, CancellationToken ct); + ValueTask GetSafeHorizonAsync(CancellationToken ct); +} + +public interface IStorageSessionFactory { ValueTask BeginAsync(CancellationToken ct); } + +public interface IStorageSession : IAsyncDisposable // one DB transaction = one unit of work +{ + void Append(StreamId stream, string streamType, ExpectedVersion expected, ReadOnlySpan events); + void EnqueueOutbox(ReadOnlySpan messages); + ValueTask InboxSeenAsync(string consumer, MessageId id, CancellationToken ct); + void RecordInbox(string consumer, MessageId id, InboxResult result); + void SaveCheckpoint(string subscription, int partition, GlobalPosition position, FencingToken token); + void SaveProcessState(ProcessKey key, ProcessVersion expected, ReadOnlyMemory state, bool completed); + IDocumentSession Documents { get; } // projection writes in this transaction + DbConnection Connection { get; } // for EF Core / custom projections (same tx) + DbTransaction Transaction { get; } + ValueTask FlushAsync(CancellationToken ct); // sends queued writes now (append first), no commit + ValueTask CommitAsync(CancellationToken ct); // flushes all queued writes in ONE round trip +} + +public interface ISnapshotStore { /* Get / Save (outside the command transaction) */ } +public interface ILeaseManager { /* TryAcquire / Renew / Release → FencingToken */ } +public interface IDeadLetterStore { /* Park / Query / Get / MarkReplayed / Discard / Purge */ } +``` + +**Write-behind session.** `Append`, `EnqueueOutbox`, `RecordInbox`, `SaveCheckpoint` and the document writes are *queued* in memory and sent as **one batch** in `CommitAsync` (`NpgsqlBatch` or one SQL Server command batch). Only operations that need an answer before deciding (`InboxSeenAsync`, loads) go to the server during the session. That gives exactly one round trip for the write side of a typical command. + +### 1.1 Value types + +| Type | Shape | Notes | +|------|-------|-------| +| `StreamId` | `string`, ≤ 200 chars, `{aggregate}-{id}` | Validated at construction | +| `StreamVersion` | `long`. `None = 0`; the first event is 1 | | +| `ExpectedVersion` | `Any`, `NoStream`, `StreamExists`, or `Exact(v)` | | +| `GlobalPosition` | `(ulong Commit, ulong Sequence)`, compared lexicographically | PostgreSQL: `(xid8, seq)`. SQL Server: `(rowversion, 0)` | +| `Bucket` | `ushort` 0–1023 = `xxHash32(tenant_id + '/' + stream_id) & 1023` | Computed by the client at append; fixes the stream→partition mapping and spreads tenants ([ADR-022](../ADRs/ADR-022-conjoined-multi-tenancy-with-row-level-security.md)) | + +## 2. PostgreSQL schema (reference implementation, PostgreSQL 15+) + +```sql +CREATE SCHEMA IF NOT EXISTS sourceflow; + +-- Streams: one row per aggregate instance; the concurrency anchor +CREATE TABLE sourceflow.streams ( + tenant_id text NOT NULL DEFAULT '-', -- ADR-022; '-' = single-tenant default + stream_id text NOT NULL, + stream_type text NOT NULL, + version bigint NOT NULL, + is_deleted boolean NOT NULL DEFAULT false, + is_archived boolean NOT NULL DEFAULT false, -- excluded from loads/rebuilds unless requested (§9) + created_at timestamptz NOT NULL DEFAULT now(), + updated_at timestamptz NOT NULL DEFAULT now(), + PRIMARY KEY (tenant_id, stream_id) +); + +-- Events: append-only +CREATE TABLE sourceflow.events ( + seq bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY, + tx_id xid8 NOT NULL DEFAULT pg_current_xact_id(), + tenant_id text NOT NULL DEFAULT '-', + bucket smallint NOT NULL, -- xxHash32(tenant_id, stream_id) & 1023 + stream_id text NOT NULL, + stream_version bigint NOT NULL, + event_id uuid NOT NULL, + event_type text NOT NULL, + type_version int NOT NULL, + tags text[] NOT NULL DEFAULT '{}', -- DCB-ready (ADR-021) + data json NOT NULL, -- exact payload text (ADR-028) + metadata jsonb NOT NULL, -- envelope attributes: correlation, causation, trace, source, actor + created_at timestamptz NOT NULL, -- decision time (ctx.Now), written explicitly; SFQL 'time' + CONSTRAINT uq_events_stream_version UNIQUE (tenant_id, stream_id, stream_version), + CONSTRAINT uq_events_event_id UNIQUE (event_id) +); +CREATE INDEX ix_events_commit_order ON sourceflow.events (tx_id, seq) INCLUDE (bucket); +-- Read-side indexes used by SFQL (doc 14 §7.2) +CREATE INDEX ix_events_type_time ON sourceflow.events (tenant_id, event_type, created_at); +CREATE INDEX ix_events_correlation ON sourceflow.events ((metadata->>'correlationId')); +CREATE INDEX ix_events_causation ON sourceflow.events ((metadata->>'causationId')); +CREATE INDEX ix_events_tags ON sourceflow.events USING gin (tags); -- created when EnableTags = true +-- + generated partial expression indexes for [Queryable] fields (`dotnet sourceflow db index sync`) +``` + +With `TenantIsolation.RowLevelSecurity` ([ADR-022](../ADRs/ADR-022-conjoined-multi-tenancy-with-row-level-security.md)): + +- Migration V002 creates a `tenant_isolation` policy on `streams`, `events`, `snapshots`, `documents`, `process_instances` and `subject_streams`. Each policy is `USING` and `WITH CHECK (tenant_id = current_setting('sourceflow.tenant', true))`. +- The migrator **enables and forces** row-level security on those tables. Forcing makes the policies apply to the table owner too, so only superusers and `BYPASSRLS` roles skip them. +- Startup verification fails when the database's state differs from the configured isolation. +- Every session runs `set_config('sourceflow.tenant', tenant, true)` at `BeginAsync`, so custom SQL on `session.Connection` is scoped too. `set_config` writes nothing, so ES-R1 still holds. +- Tenant-scoped reads outside a session send the setting in the same batch, which is one implicit transaction. +- With no setting, the application role sees no rows. +- The global log (subscriptions) is read through `SystemConnectionString`, a role with `BYPASSRLS`, because it spans tenants. +- `inbox`, `outbox`, `checkpoints`, `leases` and `dead_letters` hold no tenant payload and are not policy-protected. + +`metadata` is `jsonb` so operators can query by correlation or causation (`metadata->>'correlationId'`) using an optional expression index. `data` is `json`, not `jsonb` ([ADR-028](../ADRs/ADR-028-postgresql-payload-columns-and-adapter-refinements.md)): it keeps the serializer's exact bytes and accepts every valid JSON text (including `\u0000`), while still supporting `->>` and expression indexes for debugging, ad-hoc analysis and SFQL. Fields protected by crypto-shredding are ciphertext strings inside it ([doc 10 §4](10-Security-and-Compliance.md#4-personal-data-in-an-immutable-log-crypto-shredding)). + +## 3. Append + +### 3.1 SQL (exact expected version) + +```sql +WITH s AS ( + UPDATE sourceflow.streams + SET version = version + @count, updated_at = now() + WHERE tenant_id = @tenant AND stream_id = @stream_id AND version = @expected + AND NOT is_deleted AND NOT is_archived + RETURNING version - @count AS base) +INSERT INTO sourceflow.events (tenant_id, bucket, stream_id, stream_version, event_id, event_type, type_version, + tags, data, metadata, created_at) +SELECT @tenant, @bucket, @stream_id, s.base + e.ord, e.id, e.type, e.ver, + ARRAY(SELECT jsonb_array_elements_text(e.tags)), -- per-event tag lists are jagged, so passed as jsonb arrays + e.data, e.meta, @decided_at + FROM s, unnest(@ids::uuid[], @types::text[], @vers::int[], @tags::jsonb[], @datas::jsonb[], @metas::jsonb[]) + WITH ORDINALITY AS e(id, type, ver, tags, data, meta, ord); +``` + +| Expected | Stream statement in the CTE | +|----------|-----------------------------| +| `Exact(v)` | `UPDATE … WHERE version = v` (above) | +| `NoStream` | `INSERT INTO streams … ON CONFLICT (stream_id) DO NOTHING RETURNING 0 AS base` | +| `StreamExists` | `UPDATE … WHERE NOT is_deleted AND NOT is_archived` (no version predicate) | +| `Any` | `INSERT INTO streams … ON CONFLICT DO UPDATE SET version = streams.version + @count WHERE NOT is_deleted AND NOT is_archived` | + +Both take the stream row lock and apply to the committed version they then observe, so every append that reaches the database is still a compare-and-set on an observed version, which §5.3 relies on ([ADR-028](../ADRs/ADR-028-postgresql-payload-columns-and-adapter-refinements.md)). + +**ES-R2: one stream append per session.** A command changes one aggregate (the DDD consistency boundary). The session rejects a second `Append` to a different stream. Bulk operations such as the v2 import use one session per stream. + +**Conflict detection.** The statement affects 0 rows exactly when the stream predicate fails. The session checks the affected-row count and raises `ConcurrencyException`, then rolls back. That also discards every other queued write in the same batch (outbox, inbox, projections). A unique violation on `uq_events_stream_version` is mapped to `ConcurrencyException` as a backstop. **No retries happen in the storage layer.** Re-deciding is the command processor's job ([ADR-008](../ADRs/ADR-008-optimistic-concurrency-with-automatic-re-decide.md)), and the resilience pipeline excludes `ConcurrencyException` (fixes EF-21). + +### 3.2 One round trip + +`CommitAsync` sends one `NpgsqlBatch`. In order, it contains: + +1. `BEGIN` (implicit). +2. The append CTE. +3. The outbox `INSERT … SELECT unnest(…)`. +4. The inbox insert. +5. The document upserts: one multi-row `unnest` upsert when each document is written once. +6. The process-state and checkpoint writes. +7. `SELECT pg_notify(…)`. +8. `COMMIT`. + +The conditional statements assert in SQL (`sf_assert`, SQLSTATE `SF001`), so a failed check aborts the batch before its `COMMIT` ([ADR-028](../ADRs/ADR-028-postgresql-payload-columns-and-adapter-refinements.md)). `Max Auto Prepare` keeps these statements prepared on the server. + +### 3.3 Cost + +The append is O(events appended): one indexed update and n inserts. Unlike v2 (NFR-PERF-03), it never reads the stream history to find the next version. + +## 4. Reading a stream and loading an aggregate + +```text +Load(stream): + if cache has (state, v): start = (state, v) // optional, §8.2 + elif snapshot store has (state, v, hash==current): start = (state, v) + else: start = (Initial, 0) + tail = SELECT … FROM events WHERE stream_id = @s AND stream_version > @v ORDER BY stream_version + state = fold(Evolve, start.state, upcast(deserialize(tail))) + return (state, v + |tail|) +``` + +The tail read uses `uq_events_stream_version` (an index range scan). Deserialisation streams rows from `NpgsqlDataReader` with `GetFieldValue>`-style access into the source-generated JSON reader, with no intermediate strings. + +## 5. Global ordering and the safe horizon + +### 5.1 The problem + +An identity value (`seq`) is assigned at **insert**, but becomes visible at **commit**. Consider two transactions: + +| Time | Tx A | Tx B | Reader with checkpoint = 10 | +|------|------|------|-----------------------------| +| t1 | inserts seq 11 | | | +| t2 | | inserts seq 12, commits | reads `seq > 10` → sees 12, checkpoint = 12 | +| t3 | commits | | reads `seq > 12` → **11 is lost forever** | + +v2 had no global reads. Naive v3 designs, and several event stores, have this bug. + +### 5.2 PostgreSQL solution: order by transaction id, read below `xmin` + +- Every event row records `tx_id = pg_current_xact_id()`. The value is the same for every row in a transaction, and is assigned when the transaction first writes. +- `pg_snapshot_xmin(pg_current_snapshot())` is the smallest transaction id still **in progress**. Every transaction with `tx_id < xmin` has finished (committed or aborted), so no new row with such a `tx_id` can ever appear. +- Readers therefore read: + +```sql +SELECT seq, tx_id, bucket, stream_id, stream_version, event_id, event_type, type_version, data, metadata, created_at + FROM sourceflow.events + WHERE (tx_id, seq) > (@after_tx, @after_seq) + AND tx_id < pg_snapshot_xmin(pg_current_snapshot()) + AND bucket BETWEEN @bucket_lo AND @bucket_hi + ORDER BY tx_id, seq + LIMIT @max; +``` + +The set of rows below the horizon is **final**. The adapter reports the horizon inclusively as `(xmin − 1, max)`: every position at or below `LogBatch.Horizon` is final ([ADR-028](../ADRs/ADR-028-postgresql-payload-columns-and-adapter-refinements.md)). Ordering by `(tx_id, seq)` is total and stable, so a checkpoint `(tx_id, seq)` can never skip a row. The `bucket` filter is answered from the `INCLUDE` column of `ix_events_commit_order`, so partitioned readers scan only the index range and fetch heap rows only for their own buckets. + +### 5.3 Per-stream order equals global order + +**Claim.** For any stream, if append B commits version `k+1` after append A committed version `k`, then `tx_id(A) < tx_id(B)`. Subscriptions therefore see each stream's events in version order. + +**Argument.** +1. Every append is a compare-and-set on an exact version (§3.1). B succeeded with `expected = k`, so B must have *observed* version `k`. That is only possible after A committed. +2. A transaction id is assigned when a transaction first writes (`pg_current_xact_id()` assigns it on first call). **ES-R1: the stream write is the first write in every session.** Inbox and outbox writes are queued after it, and the inbox *check* is a read, which assigns no id. +3. So B's id was assigned after B observed A's commit, and A's id was assigned before A committed. Transaction ids are assigned monotonically, so `tx_id(A) < tx_id(B)`. ∎ + +Without ES-R1, B could take an id early (by writing something else first), wait on A's row lock, and then commit with a *lower* `tx_id` than A, delivering events out of order. The session enforces ES-R1 by construction (queued writes, append flushed first), and a conformance test asserts it by injecting a prior write and expecting `InvalidOperationException`. + +### 5.4 Operational implication + +A long-running *writing* transaction anywhere in the database holds `xmin` back and delays (never corrupts) subscriptions. Read-only transactions don't, because they have no transaction id. `sourceflow.subscription.horizon_age` measures how old the oldest in-progress transaction is, and the health check turns `Degraded` above a threshold (default 30 s). Guidance: keep the event store database for SourceFlow workloads, or at least avoid long write transactions in it. + +### 5.5 SQL Server solution + +```sql +CREATE TABLE sourceflow.Events ( + Seq bigint IDENTITY NOT NULL, + Rv rowversion NOT NULL, + Bucket smallint NOT NULL, + StreamId nvarchar(200) NOT NULL, + StreamVersion bigint NOT NULL, + EventId uniqueidentifier NOT NULL, + EventType varchar(200) NOT NULL, + TypeVersion int NOT NULL, + Data nvarchar(max) NOT NULL, -- 'json' type on SQL Server 2025+ (opt-in) + Metadata nvarchar(max) NOT NULL, + CreatedAt datetime2(7) NOT NULL DEFAULT sysutcdatetime(), + CONSTRAINT PK_Events PRIMARY KEY CLUSTERED (Seq), + CONSTRAINT UQ_Events_Stream UNIQUE (StreamId, StreamVersion), + CONSTRAINT UQ_Events_EventId UNIQUE (EventId)); +CREATE UNIQUE INDEX IX_Events_Rv ON sourceflow.Events (Rv) INCLUDE (Bucket); + +-- Safe read +SELECT TOP (@max) … FROM sourceflow.Events + WHERE Rv > @after AND Rv < MIN_ACTIVE_ROWVERSION() AND Bucket BETWEEN @lo AND @hi + ORDER BY Rv; +``` + +`MIN_ACTIVE_ROWVERSION()` is the lowest rowversion that is still uncommitted, so every row below it is final. The append uses `UPDATE … WITH (ROWLOCK)` on `Streams`, then `INSERT … SELECT` from a table-valued parameter. A zero `@@ROWCOUNT` raises error 50001, which maps to `ConcurrencyException`. ES-R1 applies here too. `READ_COMMITTED_SNAPSHOT ON` is recommended for read concurrency. + +**As built (WP-4.4).** `SourceFlow.Storage.SqlServer` follows this design with these differences: + +- **Engine.** SQL Server 2022 or later, or Azure SQL Database. The SFQL compiler uses `DATE_BUCKET` for `bin()`, which needs 2022. +- **Position.** `GlobalPosition` is `(CAST(rv AS bigint), seq)`. `seq` is the identity key, so rows that share a commit still have a total order. The horizon is `(MIN_ACTIVE_ROWVERSION() - 1, ulong.MaxValue)`. +- **Append.** The rows travel as one JSON parameter read with `OPENJSON`, not as a table-valued parameter. A TVP needs a user-defined table type per schema, and that type cannot be changed while it is in use. A failed version check raises `THROW 50001`. Fenced writes raise `THROW 50002` with a check code. +- **Batches.** A session's writes go as one command batch, split at 2,000 parameters. SQL Server allows at most 2,100. +- **Upserts.** Upserts use `MERGE … WITH (HOLDLOCK)`. Leases use the database clock. + As built (WP-C.7, CR-15): the single-document upsert updates if newer, otherwise inserts, and on a duplicate key (a concurrent writer inserted first) updates again if newer. It takes no key-range locks, which deadlocked two writers of a new document under `MERGE … WITH (HOLDLOCK)` (SCK-80). Batch upserts keep the `MERGE`. +- **Keys.** Key columns are `nvarchar(100/200/400)` with `COLLATE Latin1_General_100_BIN2`, so ids compare ordinally, as on PostgreSQL, whatever the database collation. A primary key over 900 bytes is `NONCLUSTERED`. +- **Notifications.** Notifications are in-process only. Other nodes find new events by polling at `PollInterval`, because SQL Server has no `LISTEN`. +- **Tenancy.** Tenancy is `TenantIsolation.Runtime`: every query filters on `tenant_id`. Row-level security, as on PostgreSQL in WP-2.6, is not provided. +- **Horizon age.** `GetHorizonAgeAsync` reads the oldest active transaction from DMVs, so the login needs `VIEW SERVER STATE`, or `VIEW DATABASE STATE` on Azure SQL. Without it the gauge reports zero. +- **Migrations.** The migrator takes `sp_getapplock` and records checksums in `schema_history`. `Script()` emits the same migration as one transaction, for review or DBA-run deployments. +- **SFQL.** Queries are compiled to one parameterised T-SQL statement on `QueryConnectionString`; for example, use `ApplicationIntent=ReadOnly` for a secondary. `QueryTimeout` is the command timeout. + - **Text.** Text compares with `COLLATE Latin1_General_BIN2`, ordinal like the interpreter. + - **Nulls.** `NULLS FIRST`/`LAST` becomes a `CASE` sort key. + - **Booleans.** A boolean value is a `bit` built from a predicate. + - **Fallback.** A construct SQL Server cannot express the same way falls back to the in-memory interpreter, which returns the same rows. Examples are the text of a decimal and arithmetic between two timestamps. + - **Not yet.** Index sync for `[Queryable]` fields (persisted computed columns plus filtered indexes) is not built yet. + +## 6. Isolation and transactions + +- PostgreSQL uses **Read Committed**, the default. The conditional update provides the compare-and-set, so Serializable isn't needed. +- Every session is one transaction on one connection from `NpgsqlDataSource` (pooled). EF Core projections join it with `DbContext.Database.UseTransaction(session.Transaction)` on the same connection, with no distributed transaction. +- **Inline projections and read models in another database** are rejected at startup: an inline projection needs the same database as the events. Async projections may target any database (doc 06 §5). + +## 7. Supporting tables (PostgreSQL; SQL Server equivalents are analogous) + +### 7.1 Outbox + +```sql +CREATE TABLE sourceflow.outbox ( + seq bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY, + message_id uuid NOT NULL, + partition smallint NOT NULL, -- hash(partition_key) % OutboxPartitions + partition_key text, -- NULL = unordered (e.g. timers) + destination text NOT NULL, -- logical endpoint or topic + kind smallint NOT NULL, -- 1 send, 2 publish, 3 scheduled + attributes jsonb NOT NULL, -- envelope attributes (CloudEvents) + body bytea NOT NULL, + deliver_at timestamptz NOT NULL DEFAULT now(), + attempts int NOT NULL DEFAULT 0, + last_error text, + created_at timestamptz NOT NULL DEFAULT now()); +CREATE INDEX ix_outbox_ready ON sourceflow.outbox (partition, deliver_at, seq); +CREATE INDEX ix_outbox_key ON sourceflow.outbox (partition, partition_key, seq) WHERE partition_key IS NOT NULL; + +-- Relay claim: only the HEAD row per key is eligible (strict per-key order, even across failures). +-- @now is the host's TimeProvider (business time, like timers); leases use the database clock (ADR-028). +SELECT o.* FROM sourceflow.outbox o + WHERE o.partition = @p AND o.deliver_at <= @now + AND (o.partition_key IS NULL OR NOT EXISTS ( + SELECT 1 FROM sourceflow.outbox h + WHERE h.partition = o.partition AND h.partition_key = o.partition_key AND h.seq < o.seq)) + ORDER BY o.seq LIMIT @batch; +``` + +There is no `FOR UPDATE SKIP LOCKED`, because a partition is owned by exactly one relay through a fenced lease (§7.4). That keeps the query simple and preserves order. + +### 7.2 Inbox + +```sql +CREATE TABLE sourceflow.inbox ( + consumer text NOT NULL, + message_id uuid NOT NULL, + processed_at timestamptz NOT NULL DEFAULT now(), + result_status smallint, + result_version bigint, + result_error text, + PRIMARY KEY (consumer, message_id)); +CREATE INDEX ix_inbox_processed_at ON sourceflow.inbox (processed_at); +-- Cleanup: DELETE … WHERE ctid IN (SELECT ctid … WHERE processed_at < now() - @retention LIMIT 5000), looped +``` + +### 7.3 Checkpoints + +```sql +CREATE TABLE sourceflow.checkpoints ( + subscription text NOT NULL, + partition int NOT NULL, + commit_pos xid8 NOT NULL DEFAULT '0', + seq_pos bigint NOT NULL DEFAULT 0, + updated_at timestamptz NOT NULL DEFAULT now(), + PRIMARY KEY (subscription, partition)); + +-- Fenced save: succeeds only while this instance still holds the lease with this token, and locks the lease row +-- (FOR SHARE) until the transaction commits, so a concurrent acquire waits for it (§7.4) +INSERT INTO sourceflow.checkpoints AS c (subscription, partition, commit_pos, seq_pos, updated_at) +SELECT @sub, @p, @tx, @seq, now() FROM sourceflow.leases l + WHERE l.name = @lease AND l.owner = @me AND l.token = @token AND l.expires_at > now() + FOR SHARE OF l +ON CONFLICT (subscription, partition) DO UPDATE + SET commit_pos = excluded.commit_pos, seq_pos = excluded.seq_pos, updated_at = excluded.updated_at; +-- 0 rows ⇒ LeaseLostException ⇒ whole transaction (incl. read-model writes) rolls back +``` + +> **Design change (WP-C.7, CR-14).** The earlier statement checked the lease without locking it. A former owner that passed +> the check and then paused before COMMIT could still commit after its lease expired and a new owner had taken it. Every +> fenced statement now locks the lease row: `FOR SHARE` on PostgreSQL, `WITH (UPDLOCK, HOLDLOCK)` on SQL Server, where +> the fenced outbox statements also run in a transaction of their own. The +> acquire's update waits for that lock, so the new owner reads what the former one committed. SCK-79 checks it on every +> store. + +### 7.4 Leases + +```sql +CREATE TABLE sourceflow.leases ( + name text PRIMARY KEY, -- e.g. 'sub:account-summary:3', 'outbox:7' + owner text, + token bigint NOT NULL DEFAULT 0, -- fencing token, strictly increasing + expires_at timestamptz); + +-- Acquire or renew (database clock only; no reliance on instance clocks) +UPDATE sourceflow.leases + SET owner = @me, expires_at = now() + @ttl, + token = CASE WHEN owner = @me AND expires_at > now() THEN token ELSE token + 1 END + WHERE name = @name AND (owner IS NULL OR owner = @me OR expires_at <= now()) +RETURNING token; +``` + +The TTL defaults to 30 s and is renewed every 10 s. A lost renewal stops work on that partition immediately. Fencing (§7.3) guarantees that a paused former owner cannot commit after a new owner has taken over: its fenced write holds the lease row, so the takeover waits for its commit or rollback. + +### 7.5 Dead letters, process state, snapshots, documents, keys + +```sql +CREATE TABLE sourceflow.dead_letters ( + id uuid PRIMARY KEY, consumer text NOT NULL, source text NOT NULL, -- endpoint / subscription / outbox + message_id uuid NOT NULL, message_type text, attributes jsonb NOT NULL, body bytea NOT NULL, + reason text NOT NULL, error_type text, error_message text, error_detail text, + attempts int NOT NULL, first_failed_at timestamptz NOT NULL, parked_at timestamptz NOT NULL DEFAULT now(), + status smallint NOT NULL DEFAULT 0, -- 0 parked, 1 replayed, 2 discarded + status_changed_at timestamptz, status_note text); +CREATE INDEX ix_dead_letters_status ON sourceflow.dead_letters (status, parked_at); + +CREATE TABLE sourceflow.process_instances ( -- payloads are json (ADR-028) + tenant_id text NOT NULL DEFAULT '-', process_type text, process_id text, version bigint NOT NULL, state json NOT NULL, + completed boolean NOT NULL DEFAULT false, updated_at timestamptz NOT NULL DEFAULT now(), + PRIMARY KEY (tenant_id, process_type, process_id)); + +CREATE TABLE sourceflow.snapshots ( + tenant_id text NOT NULL DEFAULT '-', stream_id text, version bigint NOT NULL, state_type text NOT NULL, + schema_hash text NOT NULL, data json NOT NULL, created_at timestamptz NOT NULL DEFAULT now(), + PRIMARY KEY (tenant_id, stream_id)); + +CREATE TABLE sourceflow.documents ( + tenant_id text NOT NULL DEFAULT '-', collection text, id text, version bigint NOT NULL, data json NOT NULL, + updated_at timestamptz NOT NULL DEFAULT now(), + PRIMARY KEY (tenant_id, collection, id)); + +CREATE TABLE sourceflow.nodes ( -- liveness for lease fair-share (doc 06 §4) + node_id text PRIMARY KEY, roles int NOT NULL, heartbeat_at timestamptz NOT NULL); + +CREATE TABLE sourceflow.collection_aliases ( -- blue/green projection switch (doc 06 §6, ADR-032) + alias text PRIMARY KEY, target text NOT NULL, switched_at timestamptz NOT NULL DEFAULT now(), + previous text NULL, -- retired by the last switch, dropped after RetainPreviousFor + building text NULL); -- requested by `projection rebuild`, cleared by its switch + +CREATE TABLE sourceflow.subject_streams ( -- which streams hold a subject's PII (doc 10 §4) + tenant_id text NOT NULL, subject_id text NOT NULL, stream_id text NOT NULL, + PRIMARY KEY (tenant_id, subject_id, stream_id)); + +-- sourceflow.schemas (event schema catalog) is specified in doc 14 §2.2 + +CREATE TABLE sourceflow.data_keys ( -- crypto-shredding, doc 10 + subject_id text PRIMARY KEY, key_ref text NOT NULL, wrapped_key bytea NOT NULL, + created_at timestamptz NOT NULL DEFAULT now(), shredded_at timestamptz); +``` + +## 8. Snapshots and caching + +### 8.1 Snapshots + +- Each aggregate opts in with `[Aggregate("…", SnapshotEvery = 100, SnapshotVersion = 1)]`. +- After a successful commit that crosses a multiple of `SnapshotEvery`, the state is handed to a bounded background channel and written **outside** the command transaction. A lost snapshot is harmless; it is just a cache. + - The channel holds `SnapshotQueueCapacity` entries (default 1,024). When it is full, the oldest entry is dropped, so commands never wait on snapshot I/O. + - A failed write is dropped too. Both cases count in `sourceflow.snapshot.dropped`. + - The host drains the queue on shutdown, within `ShutdownTimeout`. Without a running host, snapshots are written inline. +- `schema_hash = hash(SnapshotVersion, generated state-shape fingerprint)`. A shape change or an explicit `SnapshotVersion` bump invalidates old snapshots automatically. Bump `SnapshotVersion` when `When` logic changes without the shape changing; the analyzer can't detect that case. +- Guidance: turn snapshots on only when `sourceflow.aggregate.load.events` p95 exceeds about 200 for that aggregate type. + +### 8.2 Aggregate state cache (opt-in) + +- An in-process `MemoryCache` (size-limited) holds `(state, version)` per stream and is set after each commit. +- `CacheMode.ReadTail` (the default when enabled): start from the cached state and read the tail. Usually that is zero rows, from a single index probe. +- `CacheMode.Optimistic`: skip the tail read and rely on the append's version check. A stale entry causes a conflict, an automatic reload, and then success. This is best when partition-keyed routing gives stream affinity to one instance. + - **A rejection or no-op decided on a cached state is confirmed against the tail before it is returned.** It appends nothing, so no version check would otherwise catch a stale state. If newer events exist, the runtime re-decides on fresh state. + - A command with an expected version (`If-Match`) never takes the optimistic shortcut. + - Enable the cache with `SourceFlowOptions.AggregateCache` and size it with `AggregateCacheSize`. Lookups count in `sourceflow.aggregate.cache.hits` with `result` set to hit, miss or stale. +- It is correct by construction, because optimistic concurrency never lets a stale decision commit. + +## 9. Retention, archiving and growth + +| Concern | 3.0 design | Revisit | +|---------|-----------|---------| +| Deleting a stream | Soft delete: `streams.is_deleted` plus a `$deleted` event; further appends are rejected. Hard deletion of event rows is **not** offered, because it breaks projections and audit. | — | +| Right to erasure (GDPR) | Crypto-shredding ([doc 10 §4](10-Security-and-Compliance.md#4-personal-data-in-an-immutable-log-crypto-shredding)) | — | +| Table growth | Default: one table, with autovacuum tuning guidance. **Opt-in `PartitionEvents`** (in 3.0): monthly `RANGE (created_at)` partitions created ahead of time by a maintenance job. Version uniqueness stays enforced by the `streams` compare-and-set, so `uq_events_stream_version` and `uq_events_event_id` become per-partition backstops (they must include the partition key). Each partition has its own `(tx_id, seq)` index, and the safe-horizon read probes them all. Recommended from capacity tier M ([doc 09 §5](09-Performance-and-Scalability.md#5-capacity-model)). | More than about 100 partitions per table: switch to quarterly ranges, or detach and archive | +| Cold streams | **3.0**: `IEventStore.ArchiveStreamAsync(stream)` sets `streams.is_archived`. Archived streams reject appends, are excluded from rebuilds and SFQL by default (`options (include_archived = true)` includes them), and stay loadable. With `PartitionEvents`, old partitions holding only archived streams can be detached. **3.1**: compaction appends a genesis "snapshot event", then archives the prefix (competitive analysis C3). | 3.x: transparent reads from object storage | +| Inbox, outbox, dead letters | Batched background cleanup with configurable retention. Adapters implement `IStoreRetention`, and the relay role runs it every `RetentionInterval` (1 h). Processed inbox rows older than `InboxRetention` (14 days, at least the broker's retention; doc 04 §6) are deleted; redeliveries older than that are no longer detected. Replayed or discarded dead letters older than `DeadLetterRetention` (30 days) are deleted; parked ones are never deleted. Deletes run in batches of `RetentionBatchSize` (5,000) rows per statement. Outbox rows are deleted on delivery. | — | + +**As built (WP-4.5).** The table above is implemented with these specifics. + +- **Archived streams.** Archived streams are left out of read models by every projection subscription, not only by rebuilds. That way a rebuild produces the same documents as the live projection. + - **Lookup.** The subscription asks `IEventStore.GetArchivedStreamsAsync` once per batch and tenant. It is one query, and only for events that some projection handles. + - **SFQL.** `from events` applies the same rule, in the interpreter and in both SQL compilers (a `NOT EXISTS` on `streams`). `options (include_archived = true)` lifts it. `from stream` and `from aggregate` always read archived streams, as loads do. + - **Permanence.** Archiving is permanent. +- **Converting the events table.** `PostgreSqlStorageOptions.PartitionEvents` converts the events table when the migrator runs, inside its transaction. The conversion is not a numbered script, and running it again does nothing. + - **No copy.** No rows are copied. The old table becomes the partition `events_initial`, from MINVALUE to the start of the month after both its newest row and now. Monthly partitions `events_yyyy_MM` follow. + - **Keys.** The primary key is `(seq, created_at)`. `seq` comes from the sequence `events_seq`, because PostgreSQL 15 and 16 reject identity columns on partitioned tables. An application role therefore needs `USAGE` on the sequence. + - **Bookkeeping.** `event_partitions` records each range and when it was detached. +- **Maintenance.** `sf_ensure_event_partitions` creates partitions ahead of time under an advisory lock. + - The migrator creates 3 months ahead. + - A hosted job does the rest: `PartitionMonthsAhead` (default 3) every `PartitionMaintenanceInterval` (default 1 hour), on every node. + - `created_at` comes from the runtime clock. A row past the last partition fails to insert, so the job logs an error (event 2302) when it cannot create partitions. +- **Detaching.** `PostgreSqlStore.DetachEventPartitionAsync`, or `dotnet sourceflow db partitions detach`, detaches a partition that meets both conditions: + - its range has ended; + - every stream with events in it is archived or deleted. + + The detached table keeps its rows for archiving, for example with `pg_dump -t`, and the operator drops it afterwards. Its events then leave stream reads, the global log and queries. +- **Query indexes.** Query-index sync builds the indexes of a partitioned table without `CONCURRENTLY`, because PostgreSQL does not support that on partitioned tables. +- **Commands.** `dotnet sourceflow db migrate --partition-events` converts an existing table. `db partitions list | ensure | detach` manages the partitions. +- **Tests.** SCK-65..68 and SCK-72 cover the partitioned variant, and the whole PostgreSQL suite also runs on it when `SOURCEFLOW_TEST_DATABASE` ends in `-partitioned` (nightly). SCK-69..71 cover the archive rules on every store. + +## 10. Read-model stores + +- **Document store** (`IDocumentSession` / `IDocumentReader`): `jsonb` documents keyed by `(collection, id)`, with `Get`, `GetMany`, and a raw-SQL query escape hatch. Rebuilt collections are versioned (`account-summary@2`) for blue/green switches (doc 06 §6). +- **EF Core** (`SourceFlow.Storage.EntityFrameworkCore`): `IEfProjection` handlers receive a `DbContext` bound to the session's connection and transaction. `SaveChanges` happens before the checkpoint in the same commit. EF Core is **not** used for the event store ([ADR-009](../ADRs/ADR-009-event-store-on-adonet-postgresql-first.md)). + - EF projections are one kind of **session projection** (`ISessionProjection` in the core). The generator emits their `When` dispatch, and their module registers them. A storage package supplies an `IProjectionUnitOfWork` that creates the unit of work on the session and completes it before the commit. For EF Core that registration is `UseEntityFrameworkProjections((o, c) => o.UseNpgsql(c), o => new ReportingDbContext(o))`. A session projection without its unit of work fails at startup. + - **ES-R1 still holds.** Before creating the first unit of work, the runtime calls `IStorageSession.FlushAsync`, which sends the queued append first. EF writes therefore always follow the append, and a conflict surfaces before any EF write. Code that writes through `session.Connection` directly must call `FlushAsync` first. As built (WP-C.7, CR-50), the session enforces it: `Connection` and `Transaction` throw while an append is queued and not yet sent, and after a flush or raw access a new `Append` is refused (SCK-81). + - `IdempotentUpsert.UpsertAsync` applies a change only when the source version is newer than the row's `IVersionedReadModel.Version`, so replays and rebuilds are harmless. + - Tracked changes are saved once, at the end. Set-based statements (`ExecuteUpdateAsync`) run immediately, so a projection should not mix the two on the same rows. +- **Custom**: `IProjection` with `IStorageSession.Connection` for any SQL. +- **No process-global state.** The model and type configuration live in DI-registered options (fixes GAP-17). + +## 11. Schema management + +- Versioned SQL migration scripts are embedded in each storage package and tracked in `sourceflow.schema_history`. A PostgreSQL advisory lock (or `sp_getapplock` on SQL Server) serialises concurrent migrators. +- `AutoMigrate` defaults to `true` in Development and `false` otherwise. Production runs `dotnet sourceflow db migrate` or `db script` (emits SQL for DBAs). +- Least privilege: the runtime role needs `SELECT/INSERT/UPDATE/DELETE` on the SourceFlow tables only. No DDL is needed unless `AutoMigrate` is on. diff --git a/docs/v3.0.0/engineering/Design/06-Projections-and-Subscriptions.md b/docs/v3.0.0/engineering/Design/06-Projections-and-Subscriptions.md new file mode 100644 index 00000000..4e3cd610 --- /dev/null +++ b/docs/v3.0.0/engineering/Design/06-Projections-and-Subscriptions.md @@ -0,0 +1,140 @@ +# 06 — Projections and Subscriptions + +Design drivers: [ADR-010](../ADRs/ADR-010-commit-ordered-global-position-for-gap-free.md), [ADR-016](../ADRs/ADR-016-projections-inline-or-async-with-partitioned-fenced.md) and [ADR-020](../ADRs/ADR-020-process-managers-with-durable-state-and-timers.md). Fixes v2's in-memory, uncheckpointed, non-rebuildable projections (EVT-02..04, DOM-10) and the lost-event risk on crashes. + +## 1. Subscribers and their sources + +| Subscriber | Source | Mode | Default poison policy | +|------------|--------|------|-----------------------| +| Projection (document, EF Core, custom) | Local event log | Inline or async | **Stop** the partition | +| Process manager | Local event log, and/or remote integration events (receive pipeline) | Async | **Park** and continue | +| `IEventHandler` | Local event log, and/or remote integration events | Async | **Park** and continue | +| Integration-event projection (read model built from *other* services' events) | Receive pipeline, `Project` stage | Async | **Stop** | + +Remote events always arrive through the **receive pipeline** (doc 04 §5), deduplicated by the inbox and ordered per partition key. Local events always arrive through the **subscription engine** described here. A subscriber can consume both kinds; both paths end in the same `Project` or `Handle` stage middleware. + +## 2. Subscription engine + +```mermaid +flowchart LR + subgraph Instance + LM[Lease manager] -->|owned partitions| W1[Partition worker
sub=account-summary p=0] + LM --> W2[Partition worker
sub=branch-totals p=2] + N[Wake-up hub
NOTIFY + in-proc signal] --> W1 & W2 + end + W1 -->|ReadAsync after checkpoint, buckets of p| DB[(events)] + W1 -->|apply batch, write models, fenced checkpoint| DB +``` + +**Partition worker loop** + +```text +while lease held: + batch = LogReader.Read(after = checkpoint, buckets = range(p), max = BatchSize) // safe horizon only + if batch empty: await WakeUp or IdleDelay (adaptive 10 ms → 1 s); continue + using session = BeginSession() + subscriber.ApplyBatch(batch, session) // middleware Project stage per event + session.SaveCheckpoint(sub, p, batch.Last.Position, leaseToken) // fenced (doc 05 §7.3) + session.Commit() // read model + checkpoint atomically + on LeaseLost: drop batch, stop worker + on transient error: retry batch with backoff (same batch, same checkpoint) + on poison event: apply poison policy (§7) +``` + +- **Wake-ups.** The PostgreSQL adapter `LISTEN`s on `sourceflow`. After a commit, outside the transaction, it sends one `pg_notify` that covers every commit since the previous one (WP-4.7: a NOTIFY inside the commit serialises every commit on PostgreSQL's notification lock). The SQL Server adapter has no `NOTIFY`, so it polls adaptively. In both, an in-process signal fires after local commits for the lowest latency. Target: event to async projection p95 ≤ 100 ms on PostgreSQL ([doc 09](09-Performance-and-Scalability.md)). +- **Batch size** is adaptive: it starts at 100, grows to `MaxBatchSize` (default 1,000) while catching up, and shrinks when caught up. + +> **As built (WP-C.7, CR-29).** A failing batch is applied again one event at a time (with `ImmediateRetries`) to find the failing event. For process managers and event handlers under the Park policy, a transient failure then holds the partition at that event and retries it on the `DelayedRetries` schedule, as the receive path does; only when that budget is spent, or at once for a permanent error, is the event parked. A projection that chose Park parks at once; Stop keeps its own backoff (§7). A parked event's dead-letter id is derived from the consumer and the event id, so a crash between parking and the checkpoint re-parks the same dead letter (UT-SUB-30). + +## 3. Partitioning + +- Each event carries `bucket = xxHash32(stream_id) & 1023` (doc 05 §1.1). A subscription with `P` partitions (a power of two, 1 to 1024) gives partition `p` the buckets `[p·1024/P, (p+1)·1024/P)`. +- **Per-stream order is preserved**, because a stream always lands in one bucket and so one partition. Order *across* streams is not guaranteed between partitions. Projections that need cross-stream ordering (rare, for example running global totals) use `P = 1`. +- **Changing P** (`dotnet sourceflow projection repartition --partitions 8`): + 1. stop the subscription; + 2. set every new partition's checkpoint to the **minimum** of the old checkpoints; + 3. restart. + + The events between the minimum and each old position are re-applied. That is safe only for **idempotent** projections, so the version guard (§5) is required, and the command refuses to run otherwise. Alternatively, do a blue/green rebuild (§6). + +> **As built (WP-C.9, CR-18).** +> - **`P` is per subscription and stored.** The first node to run a subscription stores its configured count, in `subscription_partitions` (PostgreSQL V009, SQL Server V004, and the in-memory store). +> - **Mismatched nodes refuse it.** A node configured with a different count refuses that subscription (`sourceflow.subscription.partition_mismatch`, log event 4006) and holds none of its leases. During a rolling deploy with a changed count, the nodes still on the stored count keep processing, and each event is handled once (E2E-35). +> - **Configuring `P`.** It comes from `Projections(p => p.Add().Partitions(n))`, or from `SubscriptionPartitions`. That default now applies to subscriptions with no stored count only. +> - **`projection repartition --from --to`** writes the new count with every new partition's checkpoint in one transaction (SCK-82). Nodes pick the new count up after redeploying with it. +> +> **As built (WP-C.11, CR-34).** A new process-manager subscription starts at the head of the log, not the beginning: at startup, a node sets the checkpoints of a process manager that has never run to the safe horizon (SCK-83, log event 4007). Projections and event handlers still start at the beginning. See doc 15 §5.6. + +## 4. Leases, fencing and work distribution + +- Every `(subscription, partition)` and every outbox partition is a lease (doc 05 §7.4). +- Instances heartbeat into `sourceflow.nodes(node_id, heartbeat_at, roles)`. The *fair share* is `ceil(total_leases / live_nodes)`. +- Each instance acquires free or expired leases up to its fair share, and releases leases above it, one per rebalance interval, to avoid thundering herds. +- Every commit carries the lease's **fencing token**, and the checkpoint update fails if the token is stale. A garbage-collection pause or network partition therefore can't cause two instances to commit the same partition. +- Failover time ≈ lease TTL (30 s by default). It is configurable, and the trade-off is between failover speed and renewal traffic. + +## 5. Consistency of async projections + +| Read-model location | Guarantee | How | +|---------------------|-----------|-----| +| Same database as the events | **Exactly-once effect** | Read-model writes and the checkpoint commit in one transaction (fenced) | +| Different database (for example a reporting SQL Server, Elasticsearch) | **At-least-once, idempotent** | The checkpoint is stored in the *target* database when it supports transactions. Otherwise every document or row stores `version` (stream version, or global position for cross-stream models), and writes are guarded with `WHERE version < @incoming` | + +`IDocumentProjection` applies the version guard automatically, and **on read**: before applying an event, it compares the stored document's version with `ctx.StreamVersion` and skips the event when it is already reflected. A write-only guard isn't enough. Re-applying an already-applied event to the *current* document would double-count incremental projections, such as `count += 1` (design correction DC-2, found during the implementation spike). Document reads therefore return `(data, version)`. EF Core and custom projections get `ctx.StreamVersion` and `ctx.Position`, plus a helper (`IdempotentUpsert`). + +> **As built (WP-C.8, CR-31).** A document keyed by its source stream is guarded by the stream version, as above. A document fed by many streams (a total, a cross-stream index) has no stream version to compare, so it records the global position of the last event applied (`StoredDocument.Position`; the `position_commit` and `position_seq` columns, PostgreSQL V008, SQL Server V003). An event at or below that position was applied already and is skipped, so a repartition or a replay that starts at an earlier checkpoint doesn't count it twice (UT-PRJ-13). Every document projection is therefore guarded, and `projection repartition` keeps exempting all of them from `--idempotent`. A deleted cross-stream document loses its position: replaying events from before the delete could recreate it. + +## 6. Rebuilds (blue/green) + +1. Bump the projection version: `[Projection("account-summary", Version = 2)]`. +2. On deploy, the engine starts subscription `account-summary@2` from position zero. It writes to collection `account-summary@2` (documents) or to tables resolved through `ctx.TargetSchema` (EF Core). +3. `account-summary@1` keeps serving reads and keeps updating. +4. Once `@2` lag is below `SwitchLagThreshold` (default 100 events), the engine updates `sourceflow.collection_aliases` (`account-summary → @2`) in one transaction. `IDocumentReader` resolves the alias on every query (cached, invalidated by notification). +5. `@1` is stopped. Its data is dropped after `RetainPreviousFor` (default 7 days), or by `dotnet sourceflow projection drop account-summary@1`. + +The CLI command `projection rebuild ` forces steps 2–5 without a code change (same version, new generation suffix: `account-summary@1.2`). `projection generations` lists the aliases, `projection switch` rolls back to a retained generation, and `--in-place` drops and replays the same generation instead. + +**Details ([ADR-032](../ADRs/ADR-032-blue-green-read-model-generations-behind-forward-only-aliases.md)).** +- The alias only moves forward, by compare-and-set: one node switches it. +- Old-version nodes stop their generation once a newer version serves reads. +- EF Core projections take part when they opt in to a schema per generation (`IGenerationSchemaContext`). Their reads resolve the generation with `IReadModelResolver`. +- A service runs one version of each projection; `Projections(p => p.Remove())` leaves out a module's older one. +- Inline projections always write their first generation. + +**Rebuild speed.** `IDocumentProjection` is *batch-aware*: +1. Collect the document keys touched by the batch. +2. Load them with one `GetMany`. +3. Apply every event in memory. +4. Upsert each changed document **once**. + +For a typical rebuild this cuts database round trips from O(events) to O(batches) ([doc 09](09-Performance-and-Scalability.md)). + +Replay is side-effect free by construction: projections are pure functions of events, and event handlers and process managers are **never** part of a rebuild. They keep their own subscriptions and checkpoints (E2E-08, UT-SUB-28). This closes v2's replay side-effect problem (GAP-06). + +## 7. Errors and poison events + +| Policy | Behaviour | Use for | +|--------|-----------|---------| +| `Stop` | Retry with backoff (1 s to 5 min, capped). The partition halts at the poison event; others continue. Health is `Degraded`, and `subscription.stalled` = 1 for that partition. An operator fixes the code and redeploys, or skips the event (`projection skip --partition p --position …`, which is audited). | Projections, where correctness matters more than freshness | +| `Park` | After the retry budget, the event is copied to dead letters (consumer = subscription), the checkpoint moves past it, and work continues. | Process managers, event handlers | + +v2's silent swallowing is impossible: every failure is retried, stops the partition, or is parked, and each case is visible in metrics (GAP-07, NFR-REL-06). + +## 8. Inline projections + +- They run in the command's transaction, after the append (ES-R1). They use the same `When` code as async projections; the mode is a registration choice. +- They are allowed only when the read model is in the same database as the events (validated at startup). +- A failure fails the command (`CommandResult` failed, nothing appended). Keep inline projections small and fast, because they add directly to write latency. +- An inline projection still has a checkpointed **async shadow** used for rebuilds. The rebuild path is identical for both modes. + +## 9. Observability of subscriptions + +| Signal | Meaning | +|--------|---------| +| `sourceflow.subscription.lag` (gauge, events; tags: subscription, partition) | Events between the checkpoint and the head (estimated from `seq`) | +| `sourceflow.subscription.lag_time` (gauge, seconds) | `now − created_at` of the next unprocessed event. The primary freshness SLO signal | +| `sourceflow.subscription.horizon_age` (gauge, seconds) | Age of the oldest in-progress write transaction holding back the safe horizon | +| `sourceflow.subscription.batch.duration` (histogram) | Apply-and-commit time per batch | +| `sourceflow.subscription.stalled` (gauge 0/1) | The partition is halted by `Stop` | +| `sourceflow.lease.owned` (gauge) | Leases held by this node | +| Span `project {subscription}` | One per batch, with **links** to the producing command spans, taken from each event's `traceparent` (capped at 32 links) | diff --git a/docs/v3.0.0/engineering/Design/07-Cloud-Transports.md b/docs/v3.0.0/engineering/Design/07-Cloud-Transports.md new file mode 100644 index 00000000..dedc0769 --- /dev/null +++ b/docs/v3.0.0/engineering/Design/07-Cloud-Transports.md @@ -0,0 +1,249 @@ +# 07 — Cloud Transports + +Design drivers: [ADR-011](../ADRs/ADR-011-cloudevents-envelope-and-w3c-trace-context.md), [ADR-014](../ADRs/ADR-014-transport-spi-and-conformance-kit-parity-required.md) and [ADR-017](../ADRs/ADR-017-provisioning-modes-and-topology-as-data.md). Fixes: GAP-01, GAP-02, GAP-03, GAP-11, GAP-12, GAP-13, AWS-02/03/05, GCP-04/05/07 and RES-05. + +## 1. Principle: thin transports, smart core + +v2 put retries, idempotency, dead-lettering, encryption and telemetry *inside* each provider's dispatchers and listeners, in two variants (basic and "Enhanced"). That produced divergence and unwired features. In v3 a transport does only what is broker-specific: move bytes and headers, settle messages, and provision resources. Everything else is core middleware (doc 04), written once and identical on every broker. + +## 2. Transport SPI + +> **As built ([ADR-033](../ADRs/ADR-033-final-transport-spi-pull-receivers-and-the-in-memory-reference-broker.md)).** The SPI is pull-based: `ITransport` has `SendAsync`, `PublishAsync`, `CreateReceiverAsync`, `CreateDeadLetterReceiverAsync` and `ProvisionAsync`. `ITransportReceiver.ReceiveAsync(max, wait)` feeds the core's receive loop, and `ReceivedMessage` settles with `CompleteAsync`, `AbandonAsync(delay)`, `RenewAsync` or `DeadLetterAsync(reason)`. +> +> `TransportCapabilities` adds `OrderedDelivery`, `NativeDeadLetter`, `SubscriptionFilters`, `MaxBatchSize`, `Deduplication` and `MaxLockDuration`. Errors are typed: `TransportException.IsTransient`, a per-message `TransportSendException`, and `TopologyValidationException.Problems`. +> +> The callback-based sketch below is the original design input. + +```csharp +public interface ITransport +{ + string Name { get; } // "aws", "azure-servicebus", "gcp-pubsub", "in-memory" + TransportCapabilities Capabilities { get; } + ITransportSender Sender { get; } + ITopologyProvisioner Provisioner { get; } + ITransportReceiver CreateReceiver(EndpointTopology endpoint, ReceiverSettings settings); +} + +public interface ITransportSender +{ + // Batches are per destination and already ordered per partition key by the outbox relay + ValueTask SendAsync(Destination destination, ReadOnlyMemory batch, CancellationToken ct); +} + +public interface ITransportReceiver : IAsyncDisposable +{ + ValueTask StartAsync(ReceiveCallback onMessage, CancellationToken ct); + ValueTask StopAsync(CancellationToken ct); +} + +public delegate ValueTask ReceiveCallback(IReceivedMessage message, CancellationToken ct); + +public interface IReceivedMessage +{ + MessageEnvelope Envelope { get; } // already mapped from native headers (binary or structured mode) + int DeliveryAttempt { get; } + ValueTask CompleteAsync(CancellationToken ct); + ValueTask RetryLaterAsync(TimeSpan delay, CancellationToken ct); // native delay or core fallback + ValueTask DeadLetterAsync(string reason, CancellationToken ct); // native DLQ (backstop path only) + ValueTask RenewAsync(CancellationToken ct); +} + +public sealed record TransportCapabilities( + int MaxMessageBytes, int MaxHeaderCount, bool SupportsOrderedDelivery, bool SupportsNativeDelay, + TimeSpan MaxNativeDelay, bool SupportsNativeDeadLetter, bool SupportsSubscriptionFilters, + bool SupportsBatchSend, TimeSpan MaxRetention); +``` + +That is about six interfaces, which meets the maintainability target in [doc 01](01-Architecture-Overview.md#2-quality-goals). + +## 3. Topology model + +`Routing` (doc 04 §3) compiles to a provider-neutral `Topology`: + +| Element | Meaning | Owned by | +|---------|---------|----------| +| `Endpoint(name, Ordered, MaxDeliveries, Retention, Dlq)` | A service's input queue. It receives commands sent to the service **and** events from topics the service subscribes to. | The owning service | +| `Topic(name, Ordered)` | A publication channel for integration events | The publishing service | +| `Subscription(topic → endpoint, Filter)` | Fan-out: **one per subscribing service**. Instances of that service compete on its endpoint. | The subscribing service | +| `DeadLetter(endpoint)` | The native backstop DLQ | The owning service | + +Physical names come from `INamingConvention`: by default `{environment}-{logical}`, plus provider suffixes (`.fifo`), limited to provider character sets and lengths. They are deterministic, so two services resolve the same topic name. + +Ordered endpoints and topics are opt-in per endpoint or topic (`.Ordered()`). The core always serialises per partition key inside an instance (doc 04 RX-R1). Broker ordering adds ordering *across* instances. + +> **As built (WP-3.5).** The logical model is `TransportTopology` (ADR-033), built by `SourceFlowRuntime.Topology()` from routing: +> - Ordering is declared with `RoutingBuilder.OrderedEndpoint()` and `OrderedTopic(topic)`. A topic's ordering belongs to its publisher, so `OrderedTopic` on a topic the service does not publish fails at startup. +> - Physical names are not pluggable. Each transport's naming is fixed and deterministic (`AwsNaming`, `GcpNaming`, `AzureNaming`) with a `NamePrefix` option for the environment. A custom convention would have to be applied identically by every service and every IaC module, so instead the transports *describe* their names: `ITopologyDescriber.Describe(topology)` returns the `PhysicalTopology` (`AwsTopology`, `GcpTopology`, `AzureTopology`, and the in-memory transport), computed from the options without a broker call. +> - The `DeadLetter(endpoint)` backstop is drained by the `DeadLetterIngestor`, which runs on receiver instances as its own loop. It drains while messages arrive, then checks every `DeadLetterIngestInterval` (30 s by default). Commits do not wake it, because each check is a broker call. After a broker error it recreates its receiver and backs off, from 1 s doubling up to the interval. + +## 4. Provider mappings + +| Concern | AWS (SNS + SQS) | Azure Service Bus | Google Pub/Sub | In-memory | +|---------|-----------------|-------------------|----------------|-----------| +| Endpoint | SQS queue (`.fifo` if ordered) | Queue (sessions on if ordered) | Topic `{svc}` + subscription `{svc}` for commands, plus one subscription per subscribed topic (see Subscription row). **One receiver** pulls from all of them. Pub/Sub has no forwarding, so the endpoint is a set of subscriptions. | `Channel` | +| Topic | SNS topic (FIFO topic if ordered) | Topic | Topic | In-proc fan-out | +| Subscription | SNS→SQS subscription with **`RawMessageDelivery=true`** and a filter policy on `ce_type`. A queue policy allows the topic. | Subscription `{svc}` with `ForwardTo = {svc}` queue and a correlation filter on `type` | Subscription `{svc}.{topic}`, filter `attributes.ce_type` | Subscriber list | +| Ordering | FIFO: `MessageGroupId = partitionKey`. **Validated**: a FIFO queue requires a FIFO topic and vice versa | `SessionId = partitionKey`, session receiver | `enable_message_ordering = true` on the subscription, plus publisher `OrderingKey` | Per-key channel | +| Broker dedup (complementary to the inbox) | FIFO: `MessageDeduplicationId = MessageId` (5 min) | `RequiresDuplicateDetection`, `MessageId` | Optional exactly-once delivery on the subscription | — | +| Native delay | `ChangeMessageVisibility` (≤ 12 h) | Re-send with `ScheduledEnqueueTime` and complete the original | `ModifyAckDeadline` (≤ 600 s), then core fallback | Timer | +| Native DLQ (backstop) | Redrive policy to `{queue}-dlq`, `maxReceiveCount = runtime budget + 2` | Built-in `$DeadLetterQueue`, `MaxDeliveryCount = budget + 2` | `dead_letter_policy → {sub}.dlq`, `max_delivery_attempts = budget + 2` | List | +| Lock renewal | `ChangeMessageVisibility` heartbeat | Processor auto-renew | Streaming pull lease management | — | +| CloudEvents binding | Message attributes (`ce_*`, maximum 10). Overflow extensions go in one `sf_ext` JSON attribute | `ApplicationProperties` (`cloudEvents:*`) | Attributes (`ce-*`) | Object | +| Batch send | `SendMessageBatch` / `PublishBatch` (10) | `ServiceBusMessageBatch` | Publisher batching | — | +| Emulator for CI | LocalStack (pinned image) | Service Bus emulator | Pub/Sub emulator | — | + +> **As built (WP-3.2, AWS).** `SourceFlow.Cloud.Aws` follows the AWS column, with these details fixed by the implementation: +> +> - **Attributes.** CloudEvents attributes travel as String message attributes named `ce_{attribute}` (`ce_type`, `ce_sftenant`, …), and the overflow is `ce_sfext`. +> - **Transport attributes.** Three attributes count against the 10-attribute budget only when used: +> - `sf_body`: `base64` or `empty`, for bodies SQS cannot carry as text; +> - `sf_topic`: the logical topic, on every published event; +> - `sf_reason`: on an explicit dead letter. +> - **Bodies.** A body travels as UTF-8 text when SQS can carry it unchanged (valid UTF-8 and XML characters only); otherwise it travels as base64. Bodies are therefore never transcoded (TCK-42). +> - **Size limits.** `MaxBodyBytes` is 180 KiB, so a base64 body plus its attributes fits the 256 KiB message and batch limit. Larger encoded messages are refused before sending. +> - **Filters.** +> - `ExactTypes` and `TypePrefixes` filters become an SNS filter policy on `ce_type`. +> - Other CESQL filters leave the subscription unfiltered. The receiver evaluates them per topic, using `sf_topic`, and acknowledges non-matching events unseen. +> - So `SubscriptionFilters` is declared true, and results match the reference evaluator (TCK-26..28). +> - **Endpoint resolution.** An endpoint resolves to `{base}` or `{base}.fifo`, whichever exists, so senders do not need to know the owner's ordering. +> - **Topic lookup.** Topics are found with `ListTopics`, because SNS has no lookup by name. This needs describe permission only. +> - **Dead letters.** +> - An explicit `DeadLetterAsync` sends a copy carrying `sf_reason` to the redrive target, then deletes the original. +> - A message redriven by the broker reports `MaxReceiveCountExceeded`. +> - **Broker deduplication.** It is not declared, because standard queues do not deduplicate. FIFO queues still drop a re-sent message id for 5 minutes. +> - **Late settlement.** A settlement after the visibility timeout expired, made with a stale receipt handle, is ignored. +> - **Shutdown.** Disposing a receiver makes its unsettled messages visible again at once. +> - **A failure partway through a receive** (hiding a dead letter, deleting a filtered event) makes every message that receive took and has not settled visible again before the error goes on, and forgets them (WP-C.6, CR-42). + +> **As built (WP-3.3, Google Pub/Sub).** `SourceFlow.Cloud.Gcp` follows the Google Pub/Sub column, with these details fixed by the implementation: +> +> - **Ids.** Topics and subscriptions share one id namespace per project, so ids the transport derives use separators that logical names never contain (`~` and `+` in logical names become `-`): +> - an event topic is `{topic}`; +> - an endpoint is the topic `{endpoint}+in` with the subscription `{endpoint}`; +> - a service's subscription to a topic is `{endpoint}~{topic}` (the doc's `{svc}.{topic}`, made unambiguous, since `.` is common in logical names); +> - the dead-letter topic and its subscription are `{endpoint}+dlq`. +> +> Ids start with a letter and fit 255 characters (long ones keep a readable head and a hash). +> - **Attributes.** CloudEvents attributes travel as `ce-{attribute}` (the CloudEvents Pub/Sub binding). Pub/Sub limits a value to 1,024 bytes, so longer values (a long subject, the user headers) are split into `ce-{attribute}#0`, `#1`, … and joined on receipt. The body is the message data, byte for byte, up to 9 MiB (10 MB per publish request). +> - **Ordering.** The publisher always sets the ordering key to the partition key. The subscription decides: ordered endpoints enable message ordering on every one of their subscriptions, and Validate checks it (GAP-13). A zero-delay abandon on an ordered subscription uses a one-second ack deadline instead of a nack: the emulator redelivers a nacked ordered message after its successor, while an expiring lease keeps the order everywhere. +> - **Receiving.** A receiver uses synchronous pull with immediate return, taking the endpoint's subscriptions in turn, and polls every `PollInterval` while it waits. It does not use streaming pull with automatic lease extension, because a lease must lapse when a process dies holding a message (TCK-22). The receiver sets each message's ack deadline to its lock duration (at most 10 minutes); abandon sets it to the delay (native delay up to 10 minutes); renew extends it. A late ack is ignored by Pub/Sub, so a lapsed lock is detected by the receiver on renew. A failure partway through a pull round returns every message the round leased and has not settled (deadline set to the release value) before the error goes on, and forgets them (WP-C.6, CR-42). +> - **Dead letters.** +> - Every endpoint subscription has a dead-letter policy to `{endpoint}+dlq`. +> - Pub/Sub accepts 5 to 100 deliveries, so the policy holds the clamped value and the label `sf-max-deliveries` holds the topology's limit. The receiver moves a message delivered more often than that to the dead-letter topic itself, with reason `MaxDeliveryAttemptsExceeded`. That also covers projects where the Pub/Sub service agent lacks the publisher grant on the dead-letter topic (the Terraform module grants it, WP-3.5). +> - A message that is not a SourceFlow CloudEvent is moved at once (`MalformedMessage: …`). +> - An explicit `DeadLetterAsync` publishes a copy carrying `sf-reason` and acknowledges the original. +> - **Filters.** `ExactTypes` and `TypePrefixes` become a Pub/Sub filter on `attributes.ce-type` when it fits the 256-byte limit. Other CESQL filters leave the subscription unfiltered and are evaluated by the receiver for that subscription, which acknowledges non-matching events unseen. Pub/Sub filters, like ordering, are immutable: drift is reported, never repaired in place. +> - **Subscriptions.** New subscriptions have a 30-second ack deadline (the default lock, so most pulls need no deadline change), retention from `MessageRetention` (at most 7 days), and no expiry. Validate reports a subscription that expires without receivers. +> - **Broker deduplication.** It is not declared: publishing has no deduplication, and the inbox absorbs duplicates. + +> **As built (WP-3.4, Azure Service Bus).** `SourceFlow.Cloud.Azure` follows the Azure Service Bus column, with these details fixed by the implementation: +> +> - **Names.** An endpoint is the queue `{endpoint}`, a topic is the topic `{topic}`, and a service's subscription on a topic is named after its endpoint (at most 50 characters; long names keep a readable head and a hash). Queues and topics share one name space in a namespace, so Validate names a queue that occupies a topic's name. +> - **Wire.** CloudEvents attributes travel as application properties `cloudEvents:{attribute}` (the AMQP binding), and the body byte for byte up to 192 KiB (256 KiB messages on the standard tier). The broker message id is the envelope id, the session id is the partition key (the message id without one), and the subject is the CloudEvents type. Published events carry `sf-topic`, so the receiver can apply a filter that rules cannot express. +> - **Rules.** `ExactTypes` become one correlation rule per type on `cloudEvents:type`; `TypePrefixes` become SQL `LIKE` rules. Other CESQL filters get a match-all rule and are evaluated by the receiver, which completes non-matching events unseen. +> - **Ordering.** Ordered endpoints have sessions; the publisher always sets the session id. A session receiver works on up to `MaxConcurrentSessions` sessions, accepting the next free one in the background, and takes messages from a session only while none of its messages is unsettled. A key's next message therefore waits for its head on every instance (TCK-15): Service Bus itself would hand out the next message of a session while the head is in flight. +> - **Locks.** The queue's `LockDuration` (an option, 30 seconds by default) bounds how long a dead process holds a message. A receiver that asks for a longer lock keeps the broker lock renewed until its own lock passes; renew renews the broker lock. A late settlement after the lock was lost is ignored. +> - **Settlement failures (WP-C.6, CR-09).** When completing, abandoning or dead-lettering fails, the delivery is forgotten and releases its hold on its session before the error goes on. Its session receiver is closed, so the session lock ends and the broker hands the session (with the message) out again; a message without a session is abandoned, best effort. A failure partway through a receive does the same for what that receive accepted. Session locks are renewed only for sessions with deliveries in flight, so an idle session lapses to another instance even when the receive loop has stopped calling. +> - **Delayed retries.** On a queue without sessions, a delay re-sends a scheduled copy and completes the original. The copy has a broker id of its own (so duplicate detection keeps it) and carries the deliveries so far in `sf-deliveries`, so `DeliveryCount` keeps counting. On a session, the message keeps its place instead: it holds its session (lock renewed) until the delay passes, then it is abandoned. The longest native delay is 1 hour. +> - **Dead letters.** The built-in `$DeadLetterQueue`, with `MaxDeliveryCount` = the topology's limit; explicit dead letters keep their reason. A message that is not a SourceFlow CloudEvent is dead-lettered (`MalformedMessage`); on the dead-letter queue such a message is deferred, so the ingestor moves on and it stays for inspection. +> - **Duplicate detection** is opt-in (`DuplicateDetectionWindow`), and `Deduplication` is declared only then. Within the window, the broker also drops a dead-letter replay, which keeps its message id. +> - **Connections.** `FullyQualifiedNamespace` with a `TokenCredential` (`DefaultAzureCredential` by default); a connection string is for Development and the emulator, and outside Development the host logs a warning. The emulator serves management on a separate endpoint, given as `AdministrationConnectionString`. The receiver of an endpoint learns whether it has sessions from provisioning or from the queue's description, so receivers need the Manage right unless the process provisions. + +### 4.1 How each v2 provider defect is fixed + +| v2 defect | v3 resolution | +|-----------|---------------| +| AWS: events and commands share the first queue without raw delivery, and two listeners compete (GAP-02) | One endpoint, one receiver, raw delivery always set, messages told apart by `ce_type` (RX-R5) | +| AWS: a FIFO queue subscribed to a standard topic | Topology validation rejects the combination at startup | +| AWS: `Region` and `MaxRetries` ignored (GAP-03) | `AwsTransportOptions` builds the SDK client config (§6). Unknown or unused options can't exist. | +| GCP: services compete on the `{topic}-sub` subscription (GAP-13) | The subscription id includes the subscribing service: `{svc}.{topic}` | +| GCP: ordering key set but ordering not enabled (GAP-13) | Ordered topology sets `enable_message_ordering` and publisher ordering; validation checks it | +| No native DLQ configuration (GAP-11) | Every endpoint gets a DLQ backstop, and the ingestor drains it into `sf_dead_letters` | +| Production features opt-in or missing per provider (GAP-01) | Features live in core middleware, so every transport has them | + +## 5. Provisioning ([ADR-017](../ADRs/ADR-017-provisioning-modes-and-topology-as-data.md)) + +| Mode | Behaviour | Required permissions | +|------|-----------|----------------------| +| `CreateIfMissing` (Development default) | Creates missing resources, then validates configuration | Create, describe and subscribe permissions | +| `Validate` (Production default) | Describes resources and checks they exist, ordering compatibility, raw delivery, DLQ attached, subscription filters, encryption, and retention ≥ inbox retention. Startup fails with a full diff report on mismatch. | Describe only | +| `None` | Skips the checks (for emergencies) | — | + +`dotnet sourceflow topology export --format json` writes the topology for IaC. Example: + +```json +{ + "service": "accounts", + "endpoints": [{ "name": "prod-accounts", "ordered": true, "maxDeliveries": 12, "retention": "P14D", "dlq": "prod-accounts-dlq" }], + "topics": [{ "name": "prod-accounts-events", "ordered": true }], + "subscriptions": [{ "topic": "prod-payments-events", "endpoint": "prod-accounts", "filter": { "ce_type": ["payments.payment-settled.v1"] } }] +} +``` + +Reference Terraform and Bicep modules that consume this JSON are published in the repository (`deploy/`). They are maintained with the conformance kit's topology fixtures. + +> **As built (WP-3.5).** +> - **Shared mode behaviour.** Every transport's provisioner derives from `TopologyProvisioner`. It first checks the topology in every mode, `None` included: names present and logical, delivery limit ≥ 1, ordered topics published, filters only on subscribed topics, and filters that parse. Then `None` stops, `CreateIfMissing` creates what is missing, and both `CreateIfMissing` and `Validate` report every difference at once. Existing resources are never changed. +> - **Default mode.** When `SourceFlowBuilder.Provisioning` is left unset, it is `CreateIfMissing` in Development, with the in-memory transport, or without a host environment, and `Validate` in every other environment. +> - **Export.** The library export is `TopologyExport.ToJson(runtime.TopologyDocument())`, and `dotnet sourceflow topology export [--format json|text] [--output file]` writes it. The format is versioned (`schemaVersion: 1`) and deterministic: sorted, with no timestamps. Its JSON Schema is `deploy/topology/topology.schema.json`. Besides the logical topology and the CloudEvents types per topic and endpoint, it lists `resources`: each physical resource with its `kind`, `name`, `logical` owner, `role` and provider `properties` in the provider's units. A resource is marked `owned: false` when it belongs to another stack: subscribed topics belong to their publisher, and remote endpoints to their service. +> - **Modules.** `deploy/topology/terraform/{aws,gcp,azure}` and `deploy/topology/bicep/servicebus.bicep` read the export and compute no names. The Google Cloud module also grants the Pub/Sub service agent the dead-letter permissions, and the AWS module outputs a least-privilege runtime IAM policy. +> - **As built (WP-C.13, CR-24, CR-41).** +> - **Existing queue policies.** On AWS, `CreateIfMissing` merges its statement into a queue's existing policy by its Sid (`sourceflow-sns-to-sqs`). Every other statement, a cross-account grant for example, is kept. +> - **Encryption at rest is checked where the broker's data plane shows it.** The problem kind is `Unencrypted`. +> - AWS: `AwsTransportOptions.RequireEncryption`, with an optional `KmsKeyId`. Validate reports every queue (the endpoint and its dead-letter queue) without SSE (SQS-managed or KMS, or not the configured key), and every topic without a KMS key. `CreateIfMissing` creates them encrypted. +> - Google Cloud: `GcpTransportOptions.KmsKeyName`. Validate reports every topic that isn't encrypted with that CMEK, and `CreateIfMissing` creates topics with it. +> - Azure: amended. Service Bus always encrypts at rest. A customer-managed key is a namespace setting (Premium) that only Azure Resource Manager shows, not the Service Bus client the transport uses, so Validate doesn't check it. Require it with Azure Policy, or in the Bicep/Terraform modules, at deployment. +> - **Azure `$Default` rule.** ARM creates a match-everything rule called `$Default` with every Azure subscription. The export names each subscription's first rule `$Default`, so the modules replace that rule rather than add one beside it. +> - **Tests.** The modules are tested against the fixtures (plan 06 §3.1, IAC-01..04). The Terraform modules applied to LocalStack and the Pub/Sub emulator pass `Validate`. The Azure modules have no emulator for ARM, so they are checked with mock providers and `bicep build`. + +## 6. Options are honoured, always + +Every transport option maps to an SDK setting, and options validation fails startup when a value can't be honoured. This removes the GAP-03 failure class. + +| `AwsTransportOptions` | Maps to | +|-----------------------|---------| +| `Region`, `Profile`, `ServiceUrl` (LocalStack) | `AWSOptions` passed to `CreateServiceClient()` | +| `Credentials` | **Not an option.** The SDK credential chain is used (IAM role, IRSA, SSO). | +| `MaxSdkRetries`, `Timeout` | `ClientConfig.MaxErrorRetry`, `Timeout` | +| `ReceiveWaitTime`, `VisibilityTimeout`, `PrefetchCount` | The receiver's `ReceiveMessageRequest` | + +Azure (`FullyQualifiedNamespace` + `TokenCredential`, i.e. managed identity) and GCP (`ProjectId` + Application Default Credentials, with the emulator detected through `PUBSUB_EMULATOR_HOST`) follow the same rule. Connection strings are accepted only in Development (an analyzer warning, plus a runtime warning in other environments). + +## 7. Transport Conformance Kit (TCK) + +The TCK is an abstract test suite in `SourceFlow.Testing`. Each transport test project subclasses it and supplies a fixture: an emulator, or a real cloud account in nightly runs. **GA requires every mandatory scenario to pass for every transport** ([ADR-014](../ADRs/ADR-014-transport-spi-and-conformance-kit-parity-required.md), Q5). + +| Group | Scenarios (abridged) | +|-------|----------------------| +| Envelope | Binary and structured round-trips; every CloudEvents attribute and extension preserved; header overflow → `sf_ext`; Unicode; maximum-size body accepted; over-size body rejected before send | +| Send and publish | Batch send; partial batch failure reported per message; publish to topic with fan-out to 2 services × 2 instances (each service once, competing within a service) | +| Ordering | Ordered endpoint: 10,000 messages over 100 keys across 3 consumers → per-key order holds; unordered endpoint: no deadlock | +| Settlement | Complete removes the message; abandon/RetryLater redelivers after the delay (±tolerance); renew extends in-flight time; a crash before complete → redelivery | +| Dead-letter | Exceeding max deliveries → message in native DLQ; the ingestor moves it to `sf_dead_letters` with headers intact | +| Filters | A subscription filter delivers only the listed types. **CESQL filters** (the same syntax as SFQL `where`, doc 14) are translated to the native filter where expressible (SNS filter policy, ASB SQL filter, Pub/Sub filter). Otherwise they are evaluated client-side before deserialisation, with identical results on every transport. | +| Provisioning | CreateIfMissing is idempotent; Validate detects missing or misconfigured resources (FIFO mismatch, missing raw delivery, missing DLQ, ordering off) with a precise report | +| Resilience | Broker outage for 60 s → the receiver recovers without a restart; throttling → backoff; credential expiry → refresh | +| Shutdown | Stop drains in-flight messages within the timeout; nothing is acknowledged that wasn't completed | +| End-to-end (with the core) | Command to a remote owner → appended exactly once under duplicate injection; integration event → projection in another service; process manager timeout delivered | + +## 8. Migration bridge from v2 wire formats (optional) + +`sf.UseAmazonSqs(aws => aws.AcceptV2Messages(map => map.Type("MyApp.Commands.CreateAccount, MyApp", "bank.account.open", 1)))` adds a receive-side translator. It reads v2's `CommandType`/`EventType` assembly-qualified-name attributes **through an explicit allow-list mapping**, converts the v2 JSON to the v3 record, and assigns a deterministic `MessageId` (UUIDv5 of the v2 `MessageId`). This lets v2 and v3 services coexist during migration. It is planned for removal in 4.0. + +**As built (WP-5.4).** + +- **Option.** It is an option of the AWS transport: `sf.UseAwsTransport(o => o.AcceptV2Messages(map => map.Type(v2Type, type, version, convert?)))`. It is off by default. +- **Where it runs.** `AwsReceiver` tries it when a message is not a SourceFlow CloudEvent. +- **What it reads.** + - Commands: `CommandType`, `EntityId` and `SequenceNo` attributes on the SQS message. + - Events: an `EventType` attribute, raw on SQS or inside an SNS notification. + - The v2 message id is the SQS message id; for an SNS notification, it is the SNS `MessageId`. +- **Matching.** Types match without assembly version, culture or public key token. +- **Body.** The converter (`Func`) builds the v3 JSON; without one, the v2 `payload` object is used. +- **Envelope.** + - `MessageId` is UUIDv5 of the v2 message id, and the source is `sourceflow-v2`. + - Headers: `sourceflow-v2-type` and `sourceflow-v2-message-id`. +- **Unmapped types.** An unmapped v2 type keeps its normalized name and raw body, and is marked `sourceflow-v2-unmapped`. The receive pipeline parks it as `UnknownMessageType`. +- **Left on the queue.** A mapped message whose body isn't JSON, like any undecodable message, is left for the redrive policy. +- **Core part.** The allow-list and translation (`V2MessageMap`) live in the core's `SourceFlow.Migration`; only the attribute reading (`AwsV2Bridge`) is AWS-specific. +- **Tests.** UT-AWS-31..33 (mocked SQS) and MIG-10..12 on LocalStack. diff --git a/docs/v3.0.0/engineering/Design/08-Observability.md b/docs/v3.0.0/engineering/Design/08-Observability.md new file mode 100644 index 00000000..9748b325 --- /dev/null +++ b/docs/v3.0.0/engineering/Design/08-Observability.md @@ -0,0 +1,167 @@ +# 08 — Observability + +Design driver: [ADR-019](../ADRs/ADR-019-telemetry-always-on-with-standard-semantic-conventions.md). Fixes: OBS-01, OBS-04, CTL-02, CTL-03, GAP-14, NFR-OPS-01/02/05. + +**Goal.** An operator can answer "is it healthy, is it fast, is it fresh, and where did *this* message go?" from standard OpenTelemetry signals, without reading SourceFlow's code. + +## 1. Instrumentation sources + +| Source | Name | Version | +|--------|------|---------| +| `ActivitySource` | `SourceFlow` | package version | +| `Meter` | `SourceFlow` | package version | +| Logger categories | `SourceFlow.*` (for example `SourceFlow.Commands`, `SourceFlow.Subscriptions`, `SourceFlow.Cloud.Aws`) | — | + +Both are **always created** ([ADR-019](../ADRs/ADR-019-telemetry-always-on-with-standard-semantic-conventions.md)). Without a listener, a span start costs one null check and an instrument update is a no-op. The one-line opt-in for users is: + +```csharp +builder.Services.AddOpenTelemetry() + .WithTracing(t => t.AddSource(SourceFlowTelemetry.ActivitySourceName)) // "SourceFlow" + .WithMetrics(m => m.AddMeter(SourceFlowTelemetry.MeterName)); // "SourceFlow" +``` + +The library depends on `System.Diagnostics` only, and there is no separate OpenTelemetry package ([ADR-027 §5](../ADRs/ADR-027-single-core-package-with-extensibility-spis-and-categorised-adapters.md#5-opentelemetry-without-an-extra-package)). Histogram bucket boundaries are declared on the instruments with `InstrumentAdvice` (.NET 9+), so no SDK views are needed. The OpenTelemetry SDK stays the *user's* dependency. + +## 2. Tracing + +### 2.1 Spans + +Spans follow the OpenTelemetry **messaging** semantic conventions at a pinned semconv version. Upgrades are opt-in through `OTEL_SEMCONV_STABILITY_OPT_IN`. + +| Span name | Kind | When | Key attributes | +|-----------|------|------|----------------| +| `send {destination}` | Producer | Outbox relay publishes; direct remote send | `messaging.system`, `messaging.operation.type=send`, `messaging.destination.name`, `messaging.message.id`, `messaging.message.conversation_id` (correlation), `messaging.batch.message_count` | +| `create {message type}` | Producer | A message is *created* (command sent, event appended, integration event enqueued). This is the context stored in the envelope's `traceparent`. | `messaging.operation.type=create`, `sourceflow.message.type` | +| `process {destination}` | Consumer | The receive pipeline handles one message | `messaging.operation.type=process`, `messaging.consumer.group.name` (consumer), `messaging.message.id`, delivery attempt. **Linked** to the `create` span from `traceparent`, and its child when `ParentBasedOnMessage=true`. | +| `handle {command type}` | Internal | Command processor (local or received) | `sourceflow.aggregate.type`, `sourceflow.stream.id`, `sourceflow.expected_version`, `sourceflow.outcome` (accepted, rejected, noop, conflict, duplicate), `sourceflow.concurrency.retries` | +| `sourceflow.eventstore.append` | Client | Session commit | `db.system.name`, `db.operation.name=append`, `sourceflow.events.count`, `sourceflow.outbox.count` | +| `sourceflow.eventstore.load` | Client | Aggregate load | `sourceflow.load.source` (cache, snapshot, events), `sourceflow.load.events` | +| `project {subscription}` | Consumer | One subscription batch | `sourceflow.subscription`, `sourceflow.partition`, `messaging.batch.message_count`, up to 32 **links** to producer contexts | +| `react {process manager}` | Internal | Process manager reaction | `sourceflow.process.id`, `sourceflow.process.completed` | +| `settle {destination}` | Client | Complete, retry or dead-letter | `messaging.operation.type=settle`, `sourceflow.settle.action` | + +**Cardinality rule.** Stream ids, message ids and process ids appear **only** on spans and logs, never as metric tags. + +### 2.2 Propagation + +- The `traceparent` and `tracestate` of the `create` span are stored in the event metadata and the outbox attributes. They are emitted as CloudEvents distributed-tracing attributes on the wire. +- A trace therefore covers: HTTP request → `handle` → `append` → (later) `send` → broker → `process` in service B → `handle` in B → B's `project` batch (link). This gives the end-to-end trace that v2 lacked (CTL-03). +- `Baggage` entries named in `sf.Telemetry.PropagateBaggage` (default: `tenant`) are copied to the envelope and restored on receive. + +### 2.3 Sampling guidance + +The library does not sample. The documentation recommends a parent-based sampler, with a tail-sampling collector that keeps every trace containing `sourceflow.outcome ∈ {conflict, failed}` or a dead-letter settle. + +**As built (WP-4.6).** + +- **Semantic conventions.** The pinned version is 1.27.0 (`SemanticConventions.PinnedVersion`), and it is the telemetry schema URL of the source and the meter. + - `OTEL_SEMCONV_STABILITY_OPT_IN=messaging` selects `SemanticConventions.LatestVersion`. + - `messaging/dup` also emits the deprecated pre-1.26 attribute `messaging.operation`. +- **Parent or link.** `SourceFlowOptions.Telemetry.ParentBasedOnMessage` makes the `process` span a child of the `create` span. Otherwise the span is linked to it. +- **Append span.** The `sourceflow.eventstore.append` span carries `db.operation.name` and `sourceflow.events.count`. `db.system.name` is not set, because the core does not know which store is behind the ports. +- **Not built yet.** The `settle` span and the baggage propagation above (`PropagateBaggage`) are not built; they are follow-ups, and the sections above still describe them as designed. +- **Wiring guide.** See [guides/opentelemetry.md](../../reference/guides/opentelemetry.md). + +## 3. Metrics + +Units follow UCUM. Histogram buckets are set through `InstrumentAdvice`: duration buckets from 0.0005 s to 10 s, and count buckets 1, 2, 5 … 1,000. + +### 3.1 Standard messaging metrics (semconv names) + +| Instrument | Type | Unit | Tags | +|------------|------|------|------| +| `messaging.client.operation.duration` | Histogram | s | `messaging.system`, `messaging.operation.name`, `messaging.destination.name`, `error.type` | +| `messaging.client.sent.messages` | Counter | {message} | `messaging.system`, `messaging.destination.name`, `error.type` | +| `messaging.client.consumed.messages` | Counter | {message} | `messaging.system`, `messaging.destination.name`, `messaging.consumer.group.name` | +| `messaging.process.duration` | Histogram | s | `messaging.system`, `messaging.destination.name`, `messaging.consumer.group.name`, `error.type` | + +> **As built (WP-C.16, CR-47).** +> - **The four standard instruments carry the required attributes.** `messaging.client.operation.duration` is new: the outbox relay records it for each broker call, with `messaging.operation.name` set to `send` or `publish`. `messaging.client.sent.messages` also counts failed sends, with `error.type`. `consumed.messages` and `process.duration` add `messaging.system` and `messaging.destination.name` (the endpoint). +> - **The `process` span** has `messaging.system` and `messaging.destination.name`. +> - **Span names are built only when a listener is attached** (`SourceFlowTelemetry.Start`). The `process` name is composed once per endpoint. +> - **Logical names.** The `handle` span and `sourceflow.command.type` use the logical message name (`bank.account.open`). +> - **Per-tenant tags.** No metric carries a tenant tag, so there is no tenant cardinality to bound (ADR-022). Tenants appear on spans and logs only. + +### 3.2 SourceFlow metrics + +| Instrument | Type | Unit | Tags | Why it exists | +|------------|------|------|------|---------------| +| `sourceflow.command.duration` | Histogram | s | `sourceflow.command.type`, `sourceflow.outcome` | Write latency SLO | +| `sourceflow.eventstore.append.duration` | Histogram | s | `db.system.name` | Database health | +| `sourceflow.eventstore.append.events` | Histogram | {event} | `sourceflow.aggregate.type` | Event volume and shape | +| `sourceflow.eventstore.concurrency_conflicts` | Counter | {conflict} | `sourceflow.aggregate.type` | Hot-stream detection ([ADR-008](../ADRs/ADR-008-optimistic-concurrency-with-automatic-re-decide.md)) | +| `sourceflow.aggregate.load.events` | Histogram | {event} | `sourceflow.aggregate.type`, `sourceflow.load.source` | Snapshot tuning (doc 05 §8) | +| `sourceflow.aggregate.cache.hits` | Counter | {hit} | `sourceflow.aggregate.type`, `result` | Cache effectiveness | +| `sourceflow.snapshot.written` | Counter | {snapshot} | `sourceflow.aggregate.type` | Background snapshot writes (doc 05 §8.1) | +| `sourceflow.snapshot.dropped` | Counter | {snapshot} | `sourceflow.aggregate.type` (failed writes) | Queue overflow or failed writes; harmless, but sustained drops mean the queue or store is too slow | +| `sourceflow.outbox.pending` | Observable gauge | {message} | `partition` | Backlog | +| `sourceflow.outbox.age` | Observable gauge | s | `partition` | **Durability SLO**: oldest undelivered message | +| `sourceflow.outbox.dispatch.duration` | Histogram | s | `messaging.system` | Relay health | +| `sourceflow.inbox.duplicates` | Counter | {message} | `messaging.consumer.group.name` | Redelivery and producer-retry visibility | +| `sourceflow.retry.attempts` | Counter | {attempt} | `stage`, `retry.kind` (immediate, delayed) | Instability signal | +| `sourceflow.deadletter.parked` | Counter | {message} | `consumer`, `reason`, `sourceflow.message.type` | **Alert on any increase** | +| `sourceflow.deadletter.count` | Observable gauge | {message} | `consumer` | Operator backlog | +| `sourceflow.subscription.lag` | Observable gauge | {event} | `subscription`, `partition` | Freshness | +| `sourceflow.subscription.lag_time` | Observable gauge | s | `subscription`, `partition` | **Freshness SLO** | +| `sourceflow.subscription.horizon_age` | Observable gauge | s | — | Long-transaction detector (doc 05 §5.4) | +| `sourceflow.subscription.stalled` | Observable gauge | {partition} | `subscription` | Poison-event stop | +| `sourceflow.subscription.partition_mismatch` | Observable gauge | {subscription} | `subscription` | A subscription this node refuses: its configured partition count differs from the stored one (doc 06 §3) | +| `sourceflow.subscription.batch.duration` | Histogram | s | `subscription` | Projection cost | +| `sourceflow.process.active` | Observable gauge | {instance} | `process.type` | Process-manager load | +| `sourceflow.lease.owned` | Observable gauge | {lease} | `lease.kind` | Work distribution | +| `sourceflow.workflow.transitions` | Counter | {transition} | `workflow`, `version`, `kind` | DSL workflow progress, failures, retries and compensations (doc 15 §7) | +| `sourceflow.workflow.active` | Observable gauge | {instance} | `workflow`, `status` | Instances per status | +| `sourceflow.workflow.manual_intervention` | Counter | {instance} | `workflow` | **Alert on any increase**: a compensation failed or a step needs an operator | + +Each measurement is recorded exactly once, at one well-defined place, and the metric unit tests assert it. That rules out v2's double counting and never-recorded metrics (GAP-14). + +> **As built (WP-4.3).** +> - **Catalogue.** `SourceFlowTelemetry.Catalogue` lists every instrument a host publishes, with its kind, unit, description and the tags it may carry. UT-HC-11 checks it against the instruments a running host creates and the tags it records. The dashboards and alerts are generated from it. +> - **Observable gauges.** These come from one sampler (`SourceFlowMonitor`) that runs on every instance every `MonitorInterval` (15 s). A scrape never queries the store. The store-side readings come from an optional adapter port, `IStoreMonitor`, implemented by the in-memory and PostgreSQL stores; they cover the outbox backlog per partition, parked dead letters per consumer, events after a checkpoint, the horizon age and active process managers. `outbox.age` is measured from when a message became due, so scheduled messages do not count before their time. +> - **Not built yet.** `messaging.client.operation.duration`, and the workflow instruments (the Studio track), are not built yet. `sourceflow.deadletter.replayed` and `.discarded` were added for operator actions. A command that throws records the outcome `failed`. + +## 4. Logging + +- All log statements use **source-generated `[LoggerMessage]`** methods, so the hot path allocates nothing when the level is off. Event ids are grouped in ranges (1000–1999 commands, 2000–2999 store, 3000–3999 transport, 4000–4999 subscriptions, 5000–5999 security). *As built (WP-C.16):* the ids follow these ranges, the host's lifecycle events are 1401–1405, the categories are `SourceFlow.*` type names, and the table in the Observability guide lists every id. +- Logs are structured, with stable property names that match span attributes (`MessageId`, `MessageType`, `CorrelationId`, `StreamId`, `Outcome`). +- Payloads are **never logged by default**. When `LogPayloads = true` is set for debugging, payloads go through `Microsoft.Extensions.Compliance.Redaction`: members marked `[PersonalData]` or classified with a data-classification attribute are redacted by the configured redactor ([ADR-013](../ADRs/ADR-013-use-platform-libraries-delete-bespoke-equivalents.md)). +- Log levels: `Information` for lifecycle (start, stop, provisioning, lease changes); `Debug` per message; `Warning` for retries and conflicts beyond the threshold; `Error` for parks and stalls. + +## 5. Health checks + +`builder.Services.AddHealthChecks().AddSourceFlow()` registers these checks (tags allow liveness and readiness separation): + +| Check | Tag | Healthy | Degraded | Unhealthy | +|-------|-----|---------|----------|-----------| +| `sourceflow.ready` | ready | Startup validation and provisioning done; receivers started | — | Still starting or failed | +| `sourceflow.store` | ready | `SELECT 1` and schema version match | Latency > 250 ms | Unreachable or schema mismatch | +| `sourceflow.transport` | ready | Broker reachable (cheap describe call, cached 30 s) | Throttled | Unreachable | +| `sourceflow.outbox` | — | `outbox.age` < 10 s | < 5 min | ≥ 5 min | +| `sourceflow.subscriptions` | — | Every partition: `lag_time` < 30 s and not stalled | Lag above threshold, or `horizon_age` > 30 s | Any partition stalled > 5 min | +| `sourceflow.leases` | — | Owns its fair share, or there are no leases to own | Under share for > 2 renew intervals | — | + +Liveness should **not** include store or transport checks, so that a dependency outage doesn't cause restart loops. + +> **As built (WP-4.3).** +> - **Registration.** `AddHealthChecks().AddSourceFlow(prefix = "sourceflow")` registers the six checks as `sourceflow.ready`, `.store`, `.transport`, `.outbox`, `.subscriptions` and `.leases`. Ready, store and transport carry the `ready` tag, and every check carries `sourceflow`. Thresholds are `SourceFlowOptions.Health` (`HealthThresholds`), validated at startup. +> - **Store.** The store check probes `IStoreMonitor.ProbeAsync`: on PostgreSQL, `SELECT 1` plus a schema-version check. Without the port it reads the log horizon. +> - **Transport.** The transport check calls `ITransportProbe.ProbeAsync(endpoint)`, which the AWS, Google Cloud, Azure and in-memory transports implement as a describe call on the service's endpoint. The result is cached for 30 s. +> - **Outbox, subscriptions and leases.** These read the monitor's latest sample, and take a fresh one when it is older than two intervals. A stalled partition is unhealthy after five minutes; its `SubscriptionStall.StalledSince` is kept across retries. +> - **Leases.** A node without the Subscriptions role is always healthy here. + +## 6. SLOs and alerting (shipped as guidance plus dashboards) + +| SLO | Indicator | Starting objective | +|-----|-----------|--------------------| +| Write availability | `sourceflow.command.duration` count where `outcome ∉ {failed}` ÷ total | 99.9 % / 30 days | +| Write latency | p99 `sourceflow.command.duration` | < 50 ms | +| Read-model freshness | p99 `sourceflow.subscription.lag_time` | < 5 s | +| Delivery durability | max `sourceflow.outbox.age` | < 60 s | +| Correctness | `sourceflow.deadletter.parked` increase | 0 (page on any) | + +Grafana dashboards (JSON) and Prometheus alert rules are published in `deploy/observability/`. They are generated from the instrument list above, so they can't drift from it. An Aspire dashboard works out of the box through OTLP. + +> **As built (WP-4.3).** +> - **Generator.** `dotnet sourceflow observability export --output deploy/observability` writes `sourceflow-dashboard.json` and `sourceflow-alerts.yaml`. The dashboard has an SLO row and one panel per catalogue instrument. The alert rules cover the five SLOs above, stalled subscriptions and a held horizon. Both use the OpenTelemetry-to-Prometheus names (for example `sourceflow_command_duration_seconds_bucket`). +> - **Drift checks.** A unit test fails when the committed files differ from the generator (UT-HC-15), and CI runs `promtool check rules`. +> - **Bank demo.** The demo exports traces and metrics over OTLP to the Aspire dashboard in `docker-compose.yml` () and maps `/health` (liveness), `/health/ready` and `/health/sourceflow`. diff --git a/docs/v3.0.0/engineering/Design/09-Performance-and-Scalability.md b/docs/v3.0.0/engineering/Design/09-Performance-and-Scalability.md new file mode 100644 index 00000000..5c300c0e --- /dev/null +++ b/docs/v3.0.0/engineering/Design/09-Performance-and-Scalability.md @@ -0,0 +1,127 @@ +# 09 — Performance and Scalability + +Every number in this document is a **target** or an **estimate**, to be validated by the benchmark and load-test programme in §7. Design drivers: [ADR-001](../ADRs/ADR-001-target-dotnet-10-and-csharp-14.md), [ADR-004](../ADRs/ADR-004-source-generation-instead-of-reflection.md), [ADR-008](../ADRs/ADR-008-optimistic-concurrency-with-automatic-re-decide.md), [ADR-009](../ADRs/ADR-009-event-store-on-adonet-postgresql-first.md), [ADR-010](../ADRs/ADR-010-commit-ordered-global-position-for-gap-free.md) and [ADR-016](../ADRs/ADR-016-projections-inline-or-async-with-partitioned-fenced.md). Fixes: NFR-PERF-03, NFR-PERF-04, NFR-PERF-07. + +## 1. Hot-path rules + +| # | Rule | +|---|------| +| HP-1 | No reflection, `Activator`, `MakeGenericMethod` or `Type.GetType` after startup. Every dispatch goes through generated `switch` statements or `FrozenDictionary` lookups ([ADR-004](../ADRs/ADR-004-source-generation-instead-of-reflection.md)). | +| HP-2 | `ValueTask` on every hot async API. No `async void`, no sync-over-async, `ConfigureAwait(false)` in library code. | +| HP-3 | No LINQ, closures or `params object[]` on the hot path. Logging uses `[LoggerMessage]`. | +| HP-4 | Serialisation writes to pooled `IBufferWriter` and reads from `ReadOnlySequence`, with no intermediate `string` for bodies. | +| HP-5 | One database round trip per command write (doc 05 §3.2). At most one more for the load (zero with the optimistic cache). | +| HP-6 | Bounded queues everywhere (`Channel.CreateBounded`). Backpressure, never unbounded buffering. | +| HP-7 | No lock on the hot path. Registries are immutable, and caches are lock-free (`MemoryCache`) or sharded. `System.Threading.Lock` is used only on cold paths. | +| HP-8 | Every allocation of a user-visible object (events, commands) is the user's. The framework aims for a fixed per-message overhead. | + +## 2. Local command: cost budget + +| Step | Allocation target | Notes | +|------|-------------------|-------| +| `SendAsync` + route lookup | 0 B | `FrozenDictionary` | +| Envelope + context | ≤ 400 B | One `MessageEnvelope` and one `MessageContext` | +| Middleware chain | 0 B steady state | Delegates composed once per type and cached | +| Load (in-memory store or cache hit) | ≤ 200 B | Generated `Evolve` switch over the tail | +| `Decide` | User's events only | `Decision` is a struct | +| Serialise events and outbox | Pooled | Source-generated `JsonTypeInfo` into rented buffers | +| Commit (in-memory) | ≤ 300 B | | +| **Total framework overhead** | **≤ 2 KB per command; p50 ≤ 20 µs** (in-memory store, 1 event) | Benchmark `CommandPipelineBench` | + +With PostgreSQL, the dominant cost is two round trips (load and commit), about 1–3 ms within an AZ. Target: append (commit) p99 ≤ 10 ms, end-to-end command p99 ≤ 25 ms at 70 % database CPU. + +## 3. Concurrency model + +```text + ┌──────────── API requests (Kestrel) ─────────────┐ + ▼ ▼ + CommandProcessor (async, per request; no shared mutable state) + │ + Receivers ──► Partitioned dispatcher ──► W workers (bounded channels, per-key order) + Subscription engine ──► one worker per owned (subscription, partition) lease + Outbox relay ──► one worker per owned outbox partition lease + Scheduler ──► part of the outbox relay + Snapshotter ──► single background consumer of a bounded channel (drop-oldest) +``` + +- **Parallelism knobs**: `Receive.MaxConcurrency` (default 2 × cores), `Subscription.Partitions` (per subscription), `Outbox.Partitions` (default 16), and the database connection pool. +- **Hot streams**: optimistic concurrency causes retries when many writers hit one stream. Mitigations, in order: + 1. Route by partition key so that one instance processes a stream's commands serially (RX-R1). + 2. Use `CacheMode.Optimistic` with that affinity, so the load costs nothing. + 3. Redesign the aggregate boundary (the usual root cause). + + `concurrency_conflicts` shows which aggregate types are affected. + +## 4. Database efficiency + +| Operation | Round trips | Statements | +|-----------|-------------|------------| +| Load aggregate (no cache) | 1 | Snapshot `SELECT` + tail `SELECT`, in one batch | +| Commit command | 1 | Append CTE, outbox `INSERT … unnest`, inbox `INSERT`, inline projection upserts, `pg_notify` | +| Subscription batch (N events) | 2 (+1 for document `GetMany`) | Read batch, then one write batch (upserts + fenced checkpoint) | +| Outbox relay batch (N messages) | 2 | Claim `SELECT`, then a `DELETE … WHERE seq = ANY(@ids)` after the broker acknowledges | + +- **Prepared statements**: Npgsql `Max Auto Prepare=20` and stable SQL text per operation. +- **Connection pool sizing**: `Max Pool Size ≥ API concurrency + Receive.MaxConcurrency + owned subscription leases + owned outbox leases + 4`. A startup warning fires if the configured pool is smaller. +- **PgBouncer**: transaction pooling is supported, which needs protocol-level prepared statement support (PgBouncer 1.21+). The `LISTEN` wake-up connection must bypass PgBouncer (`ListenConnectionString`), and falls back to polling if it isn't set. + +## 5. Capacity model + +The estimates assume 1.5 events per command, 0.5 integration events per command, about 600 B event payloads, and about 1.1 KB per event row including indexes and overhead. Average load is taken as 15 % of peak. + +| Tier | Peak commands/s | Event rows/day | Event storage/year | Outbox inserts/s (peak) | Guidance | +|------|-----------------|----------------|--------------------|-------------------------|----------| +| **S** | 100 | ~2 M | ~0.8 TB | 50 | One table, defaults | +| **M** | 1,000 | ~19 M | ~7.7 TB | 500 | Turn on `PartitionEvents` from day 1. Snapshots for long streams. `Outbox.Partitions` 16–32 | +| **L** | 10,000 | ~194 M | ~77 TB | 5,000 | Partitioned events. Database per service (already the rule). Consider an archive tier. Several relay instances. A dedicated subscription node pool | + +**Consequence for the design.** Tier M exceeds the 1 TB comfort zone within weeks. So `PartitionEvents` (monthly range partitions on `created_at`) is an **opt-in schema variant in 3.0**, not a later feature. This updates the YAGNI register in [doc 01](01-Architecture-Overview.md#4-deliberately-not-built-yagni-register) and the growth row in [doc 05 §9](05-Event-Store-and-Persistence.md#9-retention-archiving-and-growth). It is safe because: + +- version uniqueness is enforced by the `streams` compare-and-set, so the event-level unique constraints can become per-partition backstops; +- the safe-horizon query probes the `(tx_id, seq)` index of each partition, and with monthly partitions there are only a few dozen probes; +- old partitions can be detached and archived without touching hot data. + +**Throughput ceiling per database.** A well-provisioned PostgreSQL instance (16 vCPU, NVMe) sustains roughly 10–20k small transactional commits per second with these statement shapes. That is the expected ceiling for tier L, and the M3 load test must confirm it. Beyond it, split services across databases (the bounded-context rule) rather than sharding one service's event store (not in 3.0). + +## 6. Scalability model + +| Scale unit | How it scales | Limit | +|------------|---------------|-------| +| Command API instances | Stateless, behind a load balancer | Database write throughput; contention on hot streams | +| Message receivers | Competing consumers per endpoint, with per-key order | Broker partition, group or session concurrency; database | +| Async projections | Up to `P` partition workers per subscription, spread by leases | `P` (≤ 1024). Read-model database | +| Process managers | Same as projections (subscription partitions) and receivers | As above | +| Outbox relay | Up to `Outbox.Partitions` workers across instances | Broker publish rate | +| Database | Vertical scaling, read replicas for *read models only*, one database per service | Single-primary write throughput | + +The roles feature ([doc 01 §9](01-Architecture-Overview.md#9-hosting-model)) lets API pods (`CommandApi`) and worker pods (`Workers`) scale on different signals: request rate versus `subscription.lag` and `outbox.age`. KEDA can scale workers on the exported lag metric. + +## 7. Benchmark and load-test programme + +| Level | Tool | What it measures | Gate | +|-------|------|------------------|------| +| Micro | BenchmarkDotNet (`[MemoryDiagnoser]`, `[EventPipeProfiler]`) | Envelope mapping, serialiser, `Decide`/`Evolve` dispatch, middleware overhead, type-registry lookup, partitioned dispatcher | CI fails on > 10 % time or any allocation regression against the baseline on `main` | +| Component | BenchmarkDotNet + Testcontainers PostgreSQL | Append (1, 3, 10 events), load (0, 100, 1,000 events, with and without snapshot), subscription batch, outbox relay batch | Nightly. Trend dashboard. 15 % regression = issue | +| System | NBomber (or k6 driving a sample API) + Testcontainers or real cloud | Mixed workload at tiers S and M; soak test 4 h; recovery after broker and database restarts | Before each milestone exit and before RC | +| Startup | `dotnet-counters`, a stopwatch harness, Native AOT publish | Time to `ready` (excluding provisioning) | ≤ 150 ms JIT, ≤ 50 ms AOT for the core | + +### 7.1 Target summary (validated in M2–M4) + +| Scenario | Target | +|----------|--------| +| In-process command overhead | p50 ≤ 20 µs, ≤ 2 KB allocations | +| PostgreSQL commit (1–3 events + outbox) | p99 ≤ 10 ms | +| Commands per instance (4 vCPU, PostgreSQL, distinct streams) | ≥ 5,000/s | +| Event → async projection latency | p95 ≤ 100 ms (PostgreSQL with LISTEN/NOTIFY) | +| Outbox: commit → broker acknowledgement | p95 ≤ 250 ms | +| Projection rebuild, document projection, one partition | ≥ 20,000 events/s | +| Global log read throughput | ≥ 50,000 events/s per reader | + +## 8. Revisit triggers + +| Observation | Action | +|-------------|--------| +| Outbox inserts dominate commit time (> 30 %) at tier L | Prototype a log-tailing relay for integration events only, keeping the outbox for commands and timers | +| `aggregate.load.events` p95 > 200 | Turn on snapshots for that type. Consider the optimistic cache with affinity | +| A projection needs more than 1024-way parallelism | Shard the read model by tenant, or use a dedicated pipeline (beyond 3.0) | +| The database ceiling is reached for one bounded context | Re-examine the bounded context. A dedicated event database adapter (KurrentDB) is a 3.x candidate | diff --git a/docs/v3.0.0/engineering/Design/10-Security-and-Compliance.md b/docs/v3.0.0/engineering/Design/10-Security-and-Compliance.md new file mode 100644 index 00000000..0ebb8fe9 --- /dev/null +++ b/docs/v3.0.0/engineering/Design/10-Security-and-Compliance.md @@ -0,0 +1,191 @@ +# 10 — Security and Compliance + +Design drivers: [ADR-005](../ADRs/ADR-005-logical-message-type-names-and-registry.md), [ADR-013](../ADRs/ADR-013-use-platform-libraries-delete-bespoke-equivalents.md) and [ADR-017](../ADRs/ADR-017-provisioning-modes-and-topology-as-data.md). Fixes: GAP-10, GAP-12, SEC-03/04/06, NFR-SEC-02/03/04. + +## 1. Threat model (STRIDE) + +The assets are domain events (the system of record), command and integration messages in flight, read models, encryption keys, and broker and database credentials. + +| Threat | Vector | Mitigation in v3 | +|--------|--------|------------------| +| **Spoofing** | A forged message written into a service's queue | Broker IAM: only named principals can send or publish (the topology export includes the policies). An optional `sfsig` HMAC envelope signature is a 3.x candidate (YAGNI for 3.0, because broker auth is the boundary). | +| **Tampering** | A message modified in transit or in the broker | TLS to every broker and database. Payload protection uses AES-256-GCM with **associated data** binding `(id, type, source)`, so a ciphertext can't be replayed under another message's header (§3). | +| **Tampering** | Events edited in the database | The runtime role can't `UPDATE` or `DELETE` `events` (separate grants; the migration role owns the DDL). Detection: optional periodic checksum job (3.x). | +| **Repudiation** | "Who caused this change?" | Every event's metadata records `causationId`, `correlationId`, `source` and **`actor`** (from `IActorAccessor`, for example the authenticated user or workload identity). Dead-letter replay and discard are audited with operator identity. | +| **Information disclosure** | PII in the immutable log, logs, traces or broker | Crypto-shredding (§4). Redaction (§5). Integration events are a separate contract without PII (doc 03 §7, SF0013). Optional payload encryption. Payloads are never put in span attributes. | +| **Denial of service** | Oversized or poison messages, retry storms | Size limits before deserialisation. Bounded channels. Retry budgets and parking. Polly circuit breakers on outbound calls. JSON `MaxDepth = 64`. | +| **Tampering / information disclosure** | SQL or script injection through the per-service query API | The API is never a SQL pass-through: allow-list grammar, catalog-only names, every request value bound as a parameter, no dynamic evaluation, safe encoding and headers, read-only role and transaction, RLS, limits and rate limiting ([doc 14 §9.3](14-Query-Side-and-SFQL.md#93-injection-defence), ADR-026) | +| **Elevation of privilege** | A wire message instantiating arbitrary types (v2 GAP-10) | Registry allow-list: only `(type, version)` pairs registered at compile time are deserialisable. No polymorphic `$type` from the wire. Unknown types are parked unread. | +| **Elevation of privilege** | Over-privileged runtime credentials (v2 GAP-12) | `ProvisioningMode.Validate` in Production needs describe-only rights. The runtime database role has DML only on SourceFlow tables. | + +**As built (WP-5.5 security review, [implementation/security-review.md](../implementation/security-review.md)).** + +- **Events in the database.** The append-only runtime role comes from `dotnet sourceflow db script --grants ` (PostgreSQL). + - **Grants.** DML on the SourceFlow tables. `UPDATE`, `DELETE` and `TRUNCATE` are revoked on `events` and every partition, and default privileges keep new partitions append-only. + - **Partitions.** Partition maintenance then runs as the owner (`db partitions ensure`). + - **SQL Server.** The equivalent script is open (O-3). +- **Dead letters.** Replay, discard and skip record the operator: the CLI writes `by @`, and `IDeadLetterManager` writes the `IActorAccessor` actor. +- **Denial of service.** + - **Breakers.** There are no Polly circuit breakers. Outbound calls rely on SDK retries, per-message relay backoff, retry budgets and parking. + - **Body size.** Received bodies are bounded by the broker's limit, not by a per-type limit (3.x candidates O-4 and O-5). + - **Poison messages.** A malformed CloudEvents attribute no longer stops a receiver (F-01, found by fuzzing). + +## 2. Deserialisation hardening + +- **Allow-list.** The registry is frozen at startup from generated registrations ([ADR-005](../ADRs/ADR-005-logical-message-type-names-and-registry.md)). There is no `Type.GetType` on wire input. +- **JSON options.** Source-generated contexts only. `MaxDepth = 64`. Duplicate properties are disallowed. Strict number handling. Unmapped members are ignored for stored events (tolerant reader) and configurable for wire messages. +- **Limits.** Body size is checked against the registry and transport limits before parsing. Header count and size limits apply (doc 04 §2.3). + +**As built (WP-5.5).** + +- **Contracts.** Every parser now rejects malformed input only with its documented exception. The CloudEvents decoders throw `FormatException`; the generated id converters and the personal-data decoder throw `JsonException`. +- **Duplicate attributes.** Structured CloudEvents and the `sfheaders`/`sfext` objects are parsed with duplicate properties disallowed. + +## 3. Payload protection (in transit and at rest in the broker) + +```csharp +sf.Security(s => +{ + s.UseAwsKms(k => k.KeyId = "alias/accounts-messages"); // or UseAzureKeyVault / UseGoogleKms + s.Protect(p => p.Destinations("accounts.events", "payments")); // policy: which destinations are encrypted +}); +``` + +- **Envelope encryption.** A data encryption key (DEK) from `IKeyProvider.GenerateDataKey` is used with AES-256-GCM and a 96-bit random nonce. The associated data is `id|type|source`. The wrapped DEK, nonce and tag travel in the body. The `sfenc` header names the scheme and key reference. +- **DEK caching.** A DEK is reused for at most `MaxMessagesPerKey` (default 10,000) **and** at most `MaxKeyAge` (default 5 min), well inside AES-GCM's safe limit for random nonces. Keys are held in pinned arrays and zeroed when evicted. +- **Decryption** happens in the Receive-stage middleware. Failure is **permanent** and the message is parked with reason `DecryptionFailed`, never retried in a loop. +- **Key rotation** is transparent: the wrapped DEK names its key version, and the KMS handles it. +- **Outbox at rest.** The outbox stores the *protected* body, so pending messages aren't plaintext in the database either. + +**As built (WP-5.1).** + +- **API.** `sf.Security(s => s.UseAwsKms(…) | UseAzureKeyVault(…) | UseGoogleKms(…) | UseKeyProvider(…).Protect(p => p.Protect("accounts.events") | p.ProtectAll()))`. Protection without a key provider fails at startup. +- **Wire format.** + - Body: `version(1) | wrapped DEK length(2) | wrapped DEK | nonce(12) | tag(16) | ciphertext`. + - Header: `sfenc` = `sf-aes256gcm-v1;{provider};{key reference}`. + - Associated data: `id|type|source`. +- **Outbox at rest.** A session decorator holds outbox rows for protected destinations until flush or commit. It then encrypts them and checks the size again, because the wrapped key adds bytes, and writes them in the same transaction. If the key service fails at that point, the command fails and nothing is committed. +- **Receive.** A built-in Receive-stage middleware decrypts the message. + - **Permanent.** A tampered body, a tampered id, type or source, a foreign provider or a refused wrapped key fails with `DecryptionFailedException`. The message is parked as `DecryptionFailed` after one attempt. + - **Transient.** A key service outage (`KeyProviderException` with `IsTransient`) is retried like any transient failure. + - **Required protection.** `RequireOnReceive` parks unprotected messages on protected endpoints as `ProtectionRequired`, so a sender cannot downgrade to plaintext. It is off by default, so protection can be rolled out sender first. +- **Keys in memory.** DEKs live in pinned arrays. + - A replaced DEK is zeroed after the next rotation, and every operation copies the key into its own `AesGcm` instance, so zeroing never races an operation in flight. + - Unwrapped DEKs are cached, `UnwrappedKeyCacheSize` (256), so a receiver makes one key service call per DEK. +- **Providers.** + + | Provider | Generates the DEK | Key reference | Unwraps with | + |----------|-------------------|---------------|--------------| + | AWS KMS | `GenerateDataKey` (AES-256) | the key ARN | `Decrypt` | + | Azure Key Vault | locally, then `wrapKey` (RSA-OAEP-256 by default) | the versioned key id, so DEKs wrapped before a rotation still unwrap | `unwrapKey` | + | Google Cloud KMS | locally, then `Encrypt` | the crypto key; the ciphertext names the version | `Decrypt` | + + Each provider maps throttling and outages as transient, and refusals as permanent. +- **`LocalKeyProvider`.** Holds in-memory master keys with rotation, for tests and development. +- **Tests.** + - **Unit:** UT-SEC-01..20. + - **Providers:** UT-SEC-21..25. AWS KMS runs on LocalStack; Key Vault and Cloud KMS run through fakes of their SDK clients, since neither has an emulator. + - **Real services:** the nightly `real-cloud` job runs `RealKmsTests` when `SOURCEFLOW_KMS_*` is set. + - **End to end:** Accounts to Notifications and Loyalty, protected, in memory and on LocalStack with KMS (TCK-41 and TCK-43 with protection on). + +## 4. Personal data in an immutable log (crypto-shredding) + +An event log can't be edited, yet regulations such as GDPR Art. 17 require erasure. The standard answer is to encrypt personal data with a per-subject key and delete the key to erase it. + +```csharp +[MessageType("bank.account.opened", 2)] +public sealed record AccountOpened( + AccountId AccountId, + [PersonalData(Subject = nameof(CustomerId))] string GivenName, + [PersonalData(Subject = nameof(CustomerId))] string FamilyName, + CustomerId CustomerId, + decimal InitialDeposit, + DateTimeOffset OpenedAt) : IEvent; +``` + +| Step | Behaviour | +|------|-----------| +| Write | The generated serialiser encrypts each `[PersonalData]` member with the subject's DEK (created on first use and stored wrapped by KMS in `data_keys`). The stored JSON is `"givenName": {"$pd": "v1::"}`. | +| Read | DEKs are unwrapped through `IKeyProvider` with a bounded cache, and members are decrypted transparently. | +| Erase | `IPersonalDataEraser.EraseSubjectAsync(customerId)`: (1) marks `data_keys.shredded_at` and destroys the wrapped key; (2) appends a system event `$personal-data.erased {subject}`; (3) deletes snapshots of streams that reference the subject (tracked in `sourceflow.subject_streams`). | +| After erase | The members deserialise to `PersonalData.Erased` (for strings, the constant `"[erased]"`; for other types, the default value plus `IsErased` when the member type is `PersonalData`). Projections receive `$personal-data.erased` and scrub their read models. Built-in document projections do it automatically for members marked `[PersonalData]`. | +| Integration events | They are a separate contract. The SF0013 analyzer discourages PII in them. When it can't be avoided, the receiving service must apply its own retention. | + +The analyzer SF0011 makes sure every `[PersonalData]` member has a resolvable subject key. Aggregates whose *state* holds personal data serialise those members the same way in snapshots. + +**As built (WP-5.2).** + +- **Opt-in.** Encryption is enabled with `sf.Security(s => s.UseKeyProvider(…).EncryptPersonalData())`. Without it, `[PersonalData]` only classifies members for redaction and query policy, and events are stored as they were. +- **Subject.** `[PersonalData(Subject = nameof(CustomerId))]` names the subject member. It is looked up in the member's own object first, then in the enclosing objects. Without `Subject`, the event's stream is the subject, so the aggregate's personal data can be erased by stream id. +- **Write.** + - **Format.** After serialization, each member's JSON value is encrypted with AES-256-GCM under the subject's DEK. Associated data: `subject|path`. Marker: `{"$pd":"v1:{subject (base64url)}:{kind}:{nonce|tag|ciphertext}"}`. + - **Keys.** A subject's DEK is created on first use, wrapped by the key provider, and stored in `data_keys`. + - **Streams.** The streams holding the subject's data are recorded in `subject_streams` before the commit. + - **Snapshots.** Aggregate state is encrypted the same way. + - **Integration events.** An integration event mapped with `.As(…)` is a separate contract. `.AsIs()` publishes the domain event's plaintext, which SF0013 warns about. +- **Read.** The aggregate store (events and snapshots), subscriptions, `IAggregateReader` and the SFQL aggregate fold decrypt markers before deserializing. Unwrapped keys are cached in pinned memory, and an `AesGcm` copy is made per operation. +- **Erase.** `IPersonalDataEraser.EraseSubjectAsync(subject)` runs four steps: + 1. Shreds the key: the wrapped key is destroyed and `shredded_at` is set. + 2. Deletes the snapshots of the subject's streams and evicts them from the aggregate cache. + 3. Scrubs the `[PersonalData]` members of document projections keyed by those streams' aggregates. + 4. Appends `PersonalDataErased` (type `sourceflow.personal-data.erased`) on stream `personal-data-{subject}`. Type names cannot contain `$`. +- **After erase.** Markers read as `"[erased]"` for strings, 0 for numbers, false for booleans, and null otherwise. + - New personal data written for an erased subject is stored as the erased value, and no key is made. + - A marker that was altered, or moved to another member, fails with `DecryptionFailedException`. +- **Analyzers.** + - SF0011 (error): a `Subject` that names no member of the event. + - SF0013 (warning): `.AsIs()` on an event with `[PersonalData]`. Test projects suppress it. + - SF0017 (warning): `[Queryable]` together with `[PersonalData]`. +- **Not decrypted: SFQL event fields.** SFQL `from events` returns personal data fields as stored, so they are ciphertext markers when encryption is on. Read models hold decrypted values and are scrubbed on erasure. +- **Not decrypted: custom read models.** Custom (session) projections must handle `PersonalDataErased` themselves. +- **Tests.** + - **Core:** UT-PII-01..18 and 24, in memory. + - **Storage contract:** UT-PII-19/20 on PostgreSQL and SQL Server (`PersonalDataKeyStoreConformance`). + - **Analyzers:** UT-PII-21..23. + - **End to end:** E2E-29..31 on PostgreSQL, plus the same scenario on SQL Server. + +## 5. Redaction in logs and telemetry + +- `Microsoft.Extensions.Compliance.Redaction` is wired to a SourceFlow taxonomy (`SourceFlowTaxonomy.PersonalData`, `SourceFlowTaxonomy.Secret`). `[PersonalData]` implies the PersonalData classification. +- The default redactor in Production is `ErasingRedactor`, and in Development it is HMAC (correlatable but not reversible). This is configurable. +- Spans and metrics never carry payload values (doc 08 §2.1). Log payloads are off by default (doc 08 §4). + +## 6. Identity and secrets + +| Resource | Recommended identity | Not supported or discouraged | +|----------|----------------------|------------------------------| +| AWS | IAM roles (IRSA, ECS task role) through the SDK credential chain | Access keys in options (no option exists) | +| Azure | `DefaultAzureCredential` / managed identity | Connection strings outside Development (warning) | +| GCP | Application Default Credentials / Workload Identity | Key files in configuration | +| Databases | Managed identity tokens (Entra ID for SQL Server, IAM auth for RDS/Cloud SQL) through `NpgsqlDataSourceBuilder.UsePeriodicPasswordProvider`, or a secret store | Plaintext passwords in `appsettings` | + +## 7. Supply chain and secure development + +- **Builds**: deterministic builds, SourceLink, embedded PDBs, NuGet **author signing**, and a CycloneDX SBOM attached to every release. +- **Scanning**: CodeQL (already in v2 CI), dependency review on PRs, Renovate for updates, and an OpenSSF Scorecard target of ≥ 7. +- **Policy**: the [SECURITY.md](../../../../SECURITY.md) disclosure process carries over. Security fixes are backported to the latest 3.x minor and, for 12 months after 3.0 GA, to v2. +- **Fuzzing**: SharpFuzz harnesses for the envelope parsers (CloudEvents binary and structured), the registry lookup, and the protected-payload decoder run nightly. + +**As built (WP-5.5).** + +- **Builds.** Deterministic CI builds with SourceLink. Symbols ship as `snupkg` rather than embedded PDBs. +- **Release pipeline** (`v3-release.yml`): + - one CycloneDX SBOM per package, attached to each GitHub release; + - NuGet author signing with a timestamp, required for release tags; + - Sigstore provenance attestations; + - nuget.org publishing behind the protected `nuget-release` environment. +- **Scanning.** Dependency review runs in `v3-pr.yml`, Renovate is configured in `renovate.json`, and the OpenSSF Scorecard runs in `v3-scorecard.yml`. +- **Fuzzing.** + - **Targets.** `quality/fuzz/SourceFlow.Fuzz` covers ten targets: the CloudEvents binary and structured parsers, the AWS, Google Cloud and Azure wire decoders with the v2 bridge, the registry lookup, the protected-payload decoder, personal-data markers, and both SFQL parsers with the request guard. + - **Schedule.** Coverage-guided libFuzzer runs weekly for 2 hours per target (`v3-weekly.yml`) rather than nightly. Every PR runs the seeds and 25,000 seeded mutations per target. + - **Results.** Fuzzing found F-01..F-04, which are fixed with regression tests. + +## 8. Compliance mapping + +| Obligation | Mechanism | +|------------|-----------| +| GDPR Art. 17 (erasure) | Crypto-shredding plus read-model scrubbing (§4) | +| GDPR Art. 30 / audit trails | Immutable events with actor, causation and correlation metadata | +| Data minimisation across services | Integration events as explicit contracts without PII (SF0013) | +| Encryption at rest and in transit | TLS, broker-side encryption (SSE-SQS/KMS, ASB, Pub/Sub CMEK) plus SourceFlow payload protection | +| Least privilege | Validate-only provisioning and DML-only runtime database roles | diff --git a/docs/v3.0.0/engineering/Design/11-Testing-and-Quality.md b/docs/v3.0.0/engineering/Design/11-Testing-and-Quality.md new file mode 100644 index 00000000..5d01dcda --- /dev/null +++ b/docs/v3.0.0/engineering/Design/11-Testing-and-Quality.md @@ -0,0 +1,131 @@ +# 11 — Testing and Quality Engineering + +v2's most serious defects were behaviours that unit tests couldn't see: features that weren't wired, options that were ignored, ordering and race windows, and providers that diverged. v3's quality strategy targets exactly those failure classes. It relies on **conformance kits, property-based concurrency tests and fault injection**, not on coverage percentages alone. + +## 1. Test portfolio + +| Layer | Purpose | Tooling | Runs | +|-------|---------|---------|------| +| Domain specs | Aggregates, process managers and projections as pure functions | `SourceFlow.Testing` specs (no DI, no I/O) | Every build | +| Unit | Runtime components in isolation | xUnit v3, Shouldly, `FakeTimeProvider` | Every build | +| Generator and analyzer | Generated code and diagnostics | `Microsoft.CodeAnalysis.Testing`, approved-file snapshots | Every build | +| Storage conformance | Every storage adapter satisfies the port contracts | Abstract suites plus Testcontainers (PostgreSQL 15/16/17, SQL Server 2022/2025) | Every PR (PostgreSQL 17), nightly (full matrix) | +| Transport conformance (TCK) | Every transport satisfies the SPI contract (doc 07 §7) | Abstract suites plus emulators (LocalStack, Service Bus emulator, Pub/Sub emulator) | Every PR (emulators); nightly against real cloud accounts | +| Property-based | Linearisability, gap-freedom, ordering under random interleavings | CsCheck | Every PR (bounded), nightly (long) | +| Fault injection and chaos | Crash consistency, outages, failover | `IFaultInjector` hooks, Toxiproxy, container kill | Nightly and before each milestone | +| Architecture | Dependency rules (doc 01 §5) | NetArchTest | Every build | +| Public API | Detect breaking changes | PublicApiGenerator + approved files | Every PR | +| Performance | Regression gates (doc 09 §7) | BenchmarkDotNet, NBomber | PR (micro), nightly (component), milestone (system) | +| Mutation | Strength of the test suite | Stryker.NET on `SourceFlow.Net` core | Weekly; target mutation score ≥ 70 % | + +## 2. Domain specs (shipped to users) + +```csharp +public class BankAccountSpecs +{ + static readonly AccountId Id = AccountId.New(); + + [Fact] + public void Deposit_increases_balance() => + AggregateSpec.For() + .Given(new AccountOpened(Id, "Ada", 100m, T0)) + .When(new Deposit(Id, 50m)) + .Then(new MoneyDeposited(Id, 50m, 150m)); + + [Fact] + public void Withdraw_more_than_balance_is_rejected() => + AggregateSpec.For() + .Given(new AccountOpened(Id, "Ada", 100m, T0)) + .When(new Withdraw(Id, 500m)) + .ThenRejected(AccountErrors.InsufficientFunds); + + [Fact] + public void Transfer_times_out_and_compensates() => + ProcessManagerSpec.For().WithModule() + .Given(new TransferRequested(TId, From, To, 10m), new MoneyWithdrawn(From, 10m, 90m)) + .WhenTimeAdvances(TimeSpan.FromMinutes(5)) + .When(new TransferTimedOut(TId)) + .ThenSends(new Deposit(From, 10m), new FailTransfer(TId, "timeout")) + .ThenCompleted(); + + [Fact] + public void Summary_tracks_balance() => + ProjectionSpec.For() + .Given(new AccountOpened(Id, "Ada", 100m, T0), new MoneyDeposited(Id, 50m, 150m)) + .ThenDocument(Id, d => d.Balance.ShouldBe(150m)); +} +``` + +The specs run the **generated** `Decide`, `Evolve` and `React` code, so they test exactly what runs in production. + +> **As built (WP-C.11, CR-44).** `ProcessManagerSpec` and `WorkflowSpec` go one step further: each message runs through the process-manager runner over in-memory storage. Correlation uses `TryCorrelate` and the envelope correlation (none for the first message, the instance for later ones, as for replies). A workflow version starts only under the start rules. A completed instance ignores later messages. The state is read back from its JSON after every message. A spec of a workflow version leaves the module's other versions of that workflow out. Commands owned elsewhere go to a stand-in endpoint, because routing is deployment configuration. They also check that each event round-trips through the serialiser and that `Evolve` is deterministic (by applying the events twice). + +## 3. Integration test host + +```csharp +await using var host = await SourceFlowTestHost.StartAsync(sf => +{ + sf.AddModule(); + sf.UseInMemory(); // store + transport, with fault injection +}, time: new FakeTimeProvider(T0)); + +await host.Send(new OpenAccount(Id, "Ada", 100m)); +await host.WaitForIdleAsync(); // drains relays, subscriptions and timers deterministically +host.Documents().Get(Id).Balance.ShouldBe(100m); +host.Outbox.Published().ShouldHaveSingleItem(); +``` + +`WaitForIdleAsync` removes `Task.Delay`-based flakiness: the in-memory adapters expose quiescence counters. The same host can run against Testcontainers PostgreSQL (`sf.UsePostgreSql(container.ConnectionString)`). + +## 4. Storage conformance kit (selected mandatory cases) + +| Area | Cases | +|------|-------| +| Append | `Exact`/`NoStream` success and conflict. The affected-row check rolls back every queued write. ES-R1 (a prior write in the session is rejected). ES-R2 (one stream per session). Unique backstop maps to `ConcurrencyException`. | +| Read | Stream slices and backwards reads. Upcasting on read. A missing stream is `null` (pinned contract; fixes GAP-15). | +| Global log | **Gap-freedom**: 32 concurrent writers with random delays between insert and commit; one reader checkpointing continuously; the reader sees the exact set of committed events, each once (property-based). Per-stream order is preserved. Bucket filtering is correct. | +| Session | Outbox, inbox, documents, process state and checkpoint commit atomically with the append, or not at all (fault injected before and after each statement). | +| Leases | Acquire, renew, expire, steal. **Fencing**: a stale token can't commit (checkpoint and read model rolled back). | +| Outbox | The head-of-key rule holds under failures. `deliver_at` is honoured. Partition assignment is stable. | +| Inbox | Duplicates are detected under concurrent delivery of the same message id to two workers. The stored result is returned. | +| Migrations | Fresh install, upgrade from every previous schema version, concurrent migrators serialised. | + +## 5. Property-based and model-based tests + +- **Linearisable append.** A random schedule of N clients doing load→decide→append against a shared counter aggregate, compared with a sequential model. The final state equals the sum of accepted commands, and no accepted command is lost. +- **Exactly-once effect.** Random message duplication, reordering *across* keys, and crash points in the pipeline. The read model equals the model's projection of the accepted commands. +- **Per-key order.** Random interleavings through the partitioned dispatcher, the outbox relay and the TCK ordered endpoint. Order is checked per key. + +## 6. Fault injection and chaos + +`IFaultInjector` (compiled into Debug builds and the `SourceFlow.Testing` adapters, a no-op in Release) exposes named points: + +`session.beforeCommit`, `session.afterCommitBeforeAck`, `reaction.beforeCommit` (a process manager or event handler reaction, WP-S.13), `relay.afterPublishBeforeDelete`, `subscription.afterApplyBeforeCommit`, `lease.beforeRenew`, `receiver.beforeComplete`. + +Chaos scenarios (nightly, Testcontainers + Toxiproxy): + +| Scenario | Expected | +|----------|----------| +| Kill the process at each injection point, then restart | No lost events or messages. Duplicates are absorbed by the inbox. Projections converge. | +| Broker unavailable for 10 min under load | Commands keep succeeding. `outbox.age` grows, then drains in order after recovery. | +| PostgreSQL failover (primary restart) | Commands fail fast and are retried by callers. Subscriptions and relays resume from checkpoints. No duplicate effects. | +| A paused node (SIGSTOP longer than the lease TTL) | Its leases move to other nodes. On resume, its commits fail on fencing. No double application. | +| A long-running write transaction held for 2 min | Subscriptions pause. `horizon_age` alerts. No events are skipped after release. | + +## 7. CI pipeline + +```text +PR: build (warnings as errors, analyzers, trimming/AOT analysis) → unit + specs + generator snapshots + → architecture + API approval → storage CK (PostgreSQL 17) → TCK (emulators) → micro-benchmarks (gate) +Nightly: full DB matrix → TCK on real AWS/Azure/GCP test accounts → property-based (long) → chaos → component benchmarks +Release: everything above + system load test + SBOM + signing + publish (tag-driven, as in v2 GitVersion flow) +``` + +## 8. Definition of Done (per feature) + +- [ ] Behaviour covered by specs or unit tests, plus the relevant conformance-kit cases. +- [ ] Telemetry: spans, metrics and logs per [doc 08](08-Observability.md), with metric unit tests asserting single recording. +- [ ] Options validated (no ignored options). Analyzer coverage where the rule can be checked statically. +- [ ] Public API approved. XML docs complete. Docs page updated. +- [ ] Trimming and AOT clean. No new allocations on the hot path (benchmark evidence). +- [ ] Failure modes listed and tested (retry, park or stop, with visible signals). diff --git a/docs/v3.0.0/engineering/Design/12-Migration-Delivery-and-Traceability.md b/docs/v3.0.0/engineering/Design/12-Migration-Delivery-and-Traceability.md new file mode 100644 index 00000000..ecc8c1ab --- /dev/null +++ b/docs/v3.0.0/engineering/Design/12-Migration-Delivery-and-Traceability.md @@ -0,0 +1,215 @@ +# 12 — Migration, Delivery Plan and Traceability + +## 1. Compatibility statement + +v3 is a **new major version**. It is neither source- nor binary-compatible with v2, and its storage model differs (events, not commands). Migration is supported by: + +1. a concept and API map (§2); +2. a data migration tool, `dotnet sourceflow migrate v2` (§3); +3. a temporary wire bridge so v2 and v3 services can coexist (§4, doc 07 §8). + +**v2 support policy.** Security and critical fixes for 12 months after 3.0 GA, on the last 2.x minor. No new features. + +## 2. Concept and API map + +| v2 | v3 | Notes | +|----|----|-------| +| `services.UseSourceFlow(assemblies)` | `services.AddSourceFlow(sf => sf.AddModule())` | Compile-time module, no scanning | +| `IEntity { int Id }` | Aggregate `record` + `[StronglyTypedId]` | Ids are assigned by the caller | +| `Aggregate.Send(cmd)` | `ICommandSender.SendAsync(cmd)` | Returns `CommandResult` | +| `Saga` + `IHandles.Handle(entity, cmd)` | Aggregate `Decide(C, ctx)`, or `ICommandHandler` | Pure decision; the runtime persists | +| `IHandlesWithEvent` | `Decision.Accept(new E(...))` | | +| Saga publishing follow-up commands | Process manager `Reaction.Send` | Through the outbox, durable | +| `View` + `IProjectOn` | `IDocumentProjection` / `IEfProjection` | Inline or async, rebuildable | +| `ICommandStore` / `IEntityStore` / `IViewModelStore` | `IEventStore` (+ snapshots) / document store / EF Core read models | | +| `AddSourceFlowEfStores(...)` | `sf.UsePostgreSql(...)` / `sf.UseSqlServer(...)` (+ `SourceFlow.Storage.EntityFrameworkCore` for read models) | | +| `ReplayCommands(id)` | Not needed for state (loading *is* replaying events). `dotnet sourceflow projection rebuild` for read models. | Side-effect free | +| `ICommandDispatchMiddleware`, `ICommandSubscribeMiddleware`, `IEventDispatchMiddleware`, `IEventSubscribeMiddleware` | `IMessageMiddleware` with `PipelineStage` | | +| `UseSourceFlowAws(o, bus, idem)` / `UseSourceFlowGcp(...)` | `sf.UseAmazonSqs(...)` / `sf.UseGooglePubSub(...)` / `sf.UseAzureServiceBus(...)` | Options are honoured | +| `bus.Send.Command(q => q.Queue("x"))` | `r.Command().To("x")` | Remote only ([ADR-007](../ADRs/ADR-007-single-command-ownership-route-local-xor-remote.md)) | +| `bus.Raise.Event(t => t.Topic("x"))` | `r.Publish().As(map).To("x")` | Integration contract | +| `bus.Listen.To.CommandQueue("x")` | `r.Endpoint("x")` (default: service name) | | +| `bus.Subscribe.To.Topic("x")` | `r.Subscribe("x")` | One subscription per service | +| `IdempotencyConfigurationBuilder` / `IIdempotencyService` | Built-in inbox (always on) | | +| `IDeadLetterStore` / `AwsDeadLetterMonitor` | Built-in parking + `dotnet sourceflow dlq …` | | +| `ICircuitBreaker` / `CircuitBreakerOptions` | Polly `ResiliencePipeline` (`sf.Resilience(r => r.Configure(SourceFlowResilience.Outbox, …))`) | As built (WP-C.14): the outbox has a circuit breaker per destination | +| `IMessageEncryption` / `AwsKmsMessageEncryption` | `sf.Security(s => s.UseAwsKms(...))` | | +| `[SensitiveData]` / `SensitiveDataMasker` | `[PersonalData]` + M.E.Compliance.Redaction + crypto-shredding | | +| `AddSourceFlowTelemetry(...)` / `DomainObservabilityOptions` | Always on. `AddSource(SourceFlowTelemetry.ActivitySourceName)` / `AddMeter(SourceFlowTelemetry.MeterName)` on the OTel builders | | + +## 3. Data migration (`dotnet sourceflow migrate v2`) + +v2 stores *commands* and *current entity state*. Re-running v2 commands to derive events would repeat the non-determinism that [ADR-002](../ADRs/ADR-002-event-sourcing-replaces-command-sourcing.md) removes. The migration therefore imports **current state as genesis events** and **archives** the v2 history. + +```csharp +// User-supplied, one per aggregate type (generated scaffold via `dotnet sourceflow migrate v2 scaffold`) +public sealed class BankAccountImport : IV2Import +{ + public AccountId MapId(V2BankAccount e) => AccountIdMap.FromLegacy(e.Id); // deterministic (UUIDv5 of the int id) + public IEnumerable ToEvents(V2BankAccount e, V2ImportContext ctx) => + [ + new AccountImported(MapId(e), e.AccountName, e.Balance, + e.IsClosed ? AccountStatus.Closed : AccountStatus.Open, ctx.ImportedAt) + ]; +} +``` + +| Step | Command | What happens | +|------|---------|--------------| +| 1. Plan | `migrate v2 plan` | Counts entities and commands per type, estimates duration, checks every v2 entity type has an `IV2Import` | +| 2. Freeze or dual-run | — | Stop writes to the bounded context, or run the wire bridge (§4) and import in waves | +| 3. Import | `migrate v2 import --batch 1000` | One session per stream (ES-R2), `ExpectedVersion.NoStream`, so it is idempotent and resumable. Metadata `{migratedFrom: "v2", v2CommandCount, v2LastSequenceNo}` | +| 4. Archive | `migrate v2 archive` | Copies the v2 `CommandRecord` table to `sourceflow_v2_archive.commands` (read-only audit) | +| 5. Rebuild | automatic | Projections build from events. Each needs a `When(…Imported)` handler (generated stub) | +| 6. Verify | `migrate v2 verify` | Compares the rebuilt v3 state with the v2 entity per id using `IV2Import.Compare`, and produces a mismatch report. The exit code gates cut-over. | +| 7. Cut over | — | Switch traffic. The bridge stays until v2 producers are retired. | + +Known limitations: v2 commands lost by GAP-04 or GAP-20 (logged under id 0, or not rebuildable) can't be recovered as history, but the current state *is* migrated. The plan step reports them. + +**As built (WP-5.4).** See also the guide [guides/migrating-from-v2.md](../../reference/guides/migrating-from-v2.md). + +- **API.** `SourceFlow.Migration` in the core: + - **Registration.** `sf.MigrateFromV2(v2 => v2.From(new V2Source(dataSource, V2Dialect.PostgreSql|SqlServer)).Import(…).Ignore(…).NotRebuildable(…))`. + - **Import contract.** `IV2Import` has a third type parameter for the aggregate id, which C# can't infer from the aggregate. Its members: `MapId`, `ToEvents`, `Compare`, and an optional `OwnsCommand` that attributes commands when several v2 entity types share the command table. + - **Row types.** v2 rows are `IV2Entity` records with a static `TableName` and `Read(V2Row)`. `V2Row` converts the column types v2 wrote on each provider. + - **Ids.** `V2Ids.FromLegacy(id, scope?)` is UUIDv5 in a fixed namespace. +- **Reading v2.** The v2 database is read with plain SQL through a `DbDataSource`, on PostgreSQL or SQL Server. No v2 code is referenced. +- **CLI.** `dotnet sourceflow migrate v2 plan|scaffold|import|archive|verify`. + - **Where it runs.** Inside the service, with the registered migration. `plan`, `scaffold` and `archive` also run from the global tool with `--v2-connection`, `--v2-provider`, `--v2-schema`, `--v2-command-table` and `--v2-archive-schema`. + - **Exit codes.** `plan` exits 1 while a v2 table has neither an import nor `Ignore`; `verify` exits 1 on any mismatch. +- **Plan.** + - **Counts.** Commands per type, entity rows, and the commands each import owns. + - **GAP-20.** Commands logged under `EntityId = 0`. + - **GAP-04.** Commands with an empty payload, plus the types declared with `NotRebuildable`. The tool can't load v2 types, so it can't detect a missing parameterless constructor itself. + - **Estimate.** At `EstimatedStreamsPerSecond` (200 by default). +- **Scaffold.** Generates the row type from `INFORMATION_SCHEMA.COLUMNS` and an import stub. A v3 aggregate named like the table is filled in; otherwise the stub has placeholders and a `#warning`. +- **Import.** + - **Ordering.** Keyset pages by v2 id (`--batch`). `--limit` caps a wave. + - **Writes.** One storage session per stream, `ExpectedVersion.NoStream`. An existing stream is skipped, so re-runs resume and repeat nothing. + - **Events.** Deterministic ids (UUIDv5 of tenant, stream and version) and actor `sourceflow-migrate-v2`. + - **Headers.** `migratedFrom`, `v2CommandCount`, `v2LastSequenceNo` and `v2Id` are event headers. + - **Like any append.** Personal data is encrypted, and inline projections apply the events. + - **Not published.** Imported events are not published to integration topics. +- **Archive.** Copies the command table into `sourceflow_v2_archive.commands` in the v2 database, with the same columns and its own primary key. + - **Read-only.** PostgreSQL uses a `BEFORE UPDATE OR DELETE OR TRUNCATE` trigger; SQL Server uses `INSTEAD OF UPDATE, DELETE`. + - **Re-runs** copy only new rows. +- **Verify.** Loads each aggregate through `IAggregateReader` and calls `Compare`. A stream with no events is a mismatch. +- **Tests.** + - **MIG-01..09** run on PostgreSQL and on SQL Server (`tests/Storage/.../Migration`). Each test seeds a v2 database from the v2 `CommandRecord` DDL and the v2 E2E account rows, then imports into the Bank sample's account aggregate. + - **MIG-10..12** are the AWS bridge on LocalStack (`tests/EndToEnd/V2BridgeScenarios.cs`). + - **Unit tests:** UT-MIG-01..06 (core) and UT-AWS-31..33 (the AWS receiver). + +## 4. Coexistence + +- **Strangler by bounded context.** Migrate one service at a time. The v3 service accepts v2 wire messages through the explicit allow-list bridge (doc 07 §8). +- **v3 → v2 direction**: v3 publishes CloudEvents. A v2 consumer can't read them, so publish a v2-shaped integration event (`.As(v2Shape)`, routed to the legacy topic) until the consumer is migrated. +- **As built (WP-5.4).** The v2 → v3 bridge exists for AWS (doc 07 §8), the only v2 cloud provider on `master`. The v2 Azure provider lives on the `azure-cloud` branch (WP-3.R) and has no bridge. + +## 5. Delivery plan + +The milestones run in sequence. Each has exit criteria, and none is complete until its Definition of Done ([doc 11 §8](11-Testing-and-Quality.md#8-definition-of-done-per-feature)) is met. + +| Milestone | Scope | Exit criteria | +|-----------|-------|---------------| +| **M0 Foundations** | New repo layout and `Directory.Build.props` (net10.0, C# 14, AOT/trim analysis, warnings as errors); CI pipelines; benchmark harness; architecture tests; ADR review | ADRs accepted; empty packages build, sign and publish to the feed | +| **M1 Core and programming model** | `SourceFlow.Net` contracts and SPIs, generators and analyzers SF0001–SF0017, type registry, **schema catalog generation** (JSON Schema), STJ serialiser, middleware, command processor (with consistency tokens), tenant context, in-memory store and transport, **SFQL parser, binder and in-memory interpreter**, `SourceFlow.Testing` specs and test host | The bank-account sample runs end to end in memory, including SFQL queries; specs and CESQL TCK pass; public API frozen (approval files) | +| **M2 PostgreSQL and projections** | PostgreSQL adapter (every port, tenant columns, tags, archive flag), migrations, outbox relay, inbox, scheduler, subscription engine (partitions, leases, fencing), document store, EF Core projections, snapshots, cache, **row-level security**, **SFQL PostgreSQL compiler**, `[Queryable]` index sync, temporal reads | Storage conformance kit green (including SFQL cross-provider and tenant-isolation cases); gap-freedom property test green; doc 09 component targets met | +| **M3 Transports** | Transport SPI and TCK first; then AWS SNS/SQS, Google Pub/Sub and Azure Service Bus **in parallel** (three workstreams); provisioning modes; DLQ ingestor; topology export | TCK green on emulators for all three, and nightly against real cloud; cross-service sample (accounts ↔ payments) works on each | +| **M4 Operations** | `dotnet sourceflow` CLI (dlq, projection, topology, db, **query, schema check and export, AsyncAPI**), `SourceFlow.AspNetCore` (`MapCommand`, opt-in `MapSourceFlowQuery`), health checks, dashboards and alerts, SQL Server adapter (+ SFQL compiler), `PartitionEvents`, stream archiving | SQL Server passes the storage CK; chaos suite green; tier-M load test meets the SLOs in doc 08 §6 | +| **M5 Security and migration** | Payload protection (AWS, Azure, GCP KMS), crypto-shredding, redaction wiring, v2 migration tool and wire bridge, fuzzing | Erasure end-to-end test; migration verified on a copy of a v2 sample database; security review signed off | +| **M6 Hardening and GA** | Docs site, samples, companion-book alignment, RC programme with early adopters, performance tuning | RC run in production by at least 2 early adopters for 4 weeks with no Sev-1 issues; every target in doc 09 §7.1 met or formally waived | + +**Release scope is fixed by product sign-off (2026-11-10).** AWS SNS/SQS, Azure Service Bus and Google Pub/Sub are all **GA in 3.0.0** and all release-blocking (Q5, Q6). No transport may slip to 3.1. M3 therefore builds the three transports **in parallel** on the shared SPI and TCK, not one after another, and schedule pressure moves the *date*, not the scope. The remaining scope valve: if M4 slips, the HTTP query endpoint moves to 3.1. The C# and CLI surfaces of SFQL stay in 3.0. + +### 5.0 SourceFlow Studio release train (product doc 07, WQ1) + +The workflow DSL and Studio are a **separate utility on their own release train**: **Studio 1.0**. Work runs in a dedicated lane (F) from M1 exit and is **targeted** to be ready at 3.0.0 GA, but **does not block** 3.0.0. The fixed 3.0.0 scope from the Q5/Q6 sign-off is unchanged. + +| Studio milestone | Scope | Depends on | Exit criteria | +|------------------|-------|------------|---------------| +| **S1 Manifests + DSL core** | Service manifests (static + design-time export), `[Emits]`/`[Rejects]`, SF0019; `SourceFlow.Studio` parser, validator (WF-V01…V16), simulator, path enumerator | v3 M1 (generator, schema catalog, CESQL evaluator) | DSL golden suite green; manifests regenerate with no drift on the Bank sample | +| **S2 Code generation + runtime support** | `WorkflowGenerator`, workflow runtime types (namespace `SourceFlow.Workflows` in `SourceFlow.Net`), operator commands, workflow metrics, CLI `workflow …` | S1, v3 M2 (PostgreSQL process state) | **Differential tests**: simulator ≡ generated process manager on every enumerated path; order-fulfilment E2E green in memory | +| **S3 Studio designer** | WASM core, React SPA (domain map, statechart, swimlane, editor, simulation, path explorer, spec generation), local host `dotnet sourceflow studio` | S1 (S2 for spec generation) | Playwright suite green; accessibility (axe) clean; performance budgets met | +| **S4 Exports + PR diagrams + hardening** | SVG/PNG/Mermaid/BPMN export, static build, `workflow-diff` GitHub Action, docs and samples | S3, v3 M3 (cross-service E2E on cloud transports) | Order fulfilment E2E green on AWS, Azure and Google Cloud; Studio 1.0 RC | +| *Studio 1.1* | Observe mode (live overlay through domain queries) | v3 GA | — | + +### 5.1 Roadmap after 3.0 (from the [competitive analysis](13-Competitive-Analysis.md#5-where-competitors-lead-and-the-response)) + +| Release | Items | +|---------|-------| +| **3.1** | Dynamic consistency boundaries API ([ADR-021](../ADRs/ADR-021-dynamic-consistency-boundaries-dcb-in-3-1.md)); stream compaction; RabbitMQ and Kafka transports (through the TCK); event gateway (subscription → Kafka sink); SFQL `sfql/1.1` (window functions over `events`, if demand is confirmed) | +| **3.x** | Database-per-tenant; KurrentDB storage adapter; open-source "SourceFlow Console" over the CLI and query APIs; claim-check for large payloads; GraphQL adapter over read models | + +## 6. Traceability: v2 gaps → v3 resolution + +| Gap ([doc 06](../../../product/06-Gaps-Risks-and-Open-Questions.md)) | Resolution | Where | +|-----|------------|-------| +| GAP-01 Production pipeline not wired | Features are core middleware, always on, identical on every transport | doc 04 §4, doc 07 §1, [ADR-014](../ADRs/ADR-014-transport-spi-and-conformance-kit-parity-required.md) | +| GAP-02 AWS shared queue, no raw delivery | One endpoint and one receiver per service; raw delivery; FIFO compatibility validated | doc 07 §4.1, RX-R5 | +| GAP-03 Ignored options (Region …) | Options map to SDK config; validation forbids unhonoured options | doc 07 §6 | +| GAP-04 Implicit rebuild contract, silent skips | Event sourcing; logical type names; upcasters; unknown types fail loudly | [ADR-002](../ADRs/ADR-002-event-sourcing-replaces-command-sourcing.md), [ADR-005](../ADRs/ADR-005-logical-message-type-names-and-registry.md), doc 03 §2.1 | +| GAP-05 O(n), racy, non-atomic sequencing | Compare-and-set append; one transaction; re-decide on conflict | [ADR-008](../ADRs/ADR-008-optimistic-concurrency-with-automatic-re-decide.md), doc 05 §3 | +| GAP-06 Replay side effects | Loading is a pure fold; rebuilds exclude handlers and process managers | [ADR-002](../ADRs/ADR-002-event-sourcing-replaces-command-sourcing.md), doc 06 §6 | +| GAP-07 Swallowed event failures | Events are appended with the decision; subscribers retry, stop or park, visibly | doc 06 §7 | +| GAP-08 Captive dependencies | Aggregates aren't DI services; handlers are resolved per message scope | [ADR-003](../ADRs/ADR-003-aggregates-as-pure-deciders-decide-evolve.md), doc 03 §5.3 | +| GAP-09 Per-delivery idempotency key | Inbox keyed on the logical `MessageId` | [ADR-006](../ADRs/ADR-006-transactional-outbox-and-inbox-for-effectively-once.md), doc 04 §6 | +| GAP-10 No type allow-list | Registry allow-list; parked unread | [ADR-005](../ADRs/ADR-005-logical-message-type-names-and-registry.md), doc 10 §2 | +| GAP-11 Incomplete dead-letter story | Parking store, native DLQ backstop and ingestor, CLI replay | doc 04 §9.3 | +| GAP-12 Provisioning can't be switched off | `ProvisioningMode` + topology export | [ADR-017](../ADRs/ADR-017-provisioning-modes-and-topology-as-data.md), doc 07 §5 | +| GAP-13 GCP shared subscriptions, no ordering | `{svc}.{topic}` subscriptions; ordering enabled and validated | doc 07 §4.1 | +| GAP-14 Metric and log inaccuracies | Single-recording rule with tests; semconv names | doc 08 §3 | +| GAP-15 "Not found" semantics unspecified | Pinned in the port contract and the conformance kit | doc 05 §1, doc 11 §4 | +| GAP-16 Assembly-scan fallback rethrows | No assembly scanning (generators) | [ADR-004](../ADRs/ADR-004-source-generation-instead-of-reflection.md) | +| GAP-17 Process-global EF registration | Options in DI; no static state | doc 05 §10 | +| GAP-18 Doc and metadata drift | Dashboards and docs generated from code; API approval; package metadata checked in CI | doc 08 §6, doc 11 §1 | +| GAP-19 Owner doesn't log received commands | Received commands go through the owner's command processor | [ADR-007](../ADRs/ADR-007-single-command-ownership-route-local-xor-remote.md), RT-R2 | +| GAP-20 New entities logged under id 0 | Caller-assigned strongly typed ids; defaults rejected | [ADR-015](../ADRs/ADR-015-strongly-typed-caller-assigned-ids-uuidv7-default.md) | + +## 7. Traceability: product requirement areas → v3 + +| Area | v3 coverage | +|------|-------------| +| DOM (aggregates, sagas, views) | Aggregates, process managers, projections — doc 03 | +| CMD (commands, bus, log, replay) | Command processor and event-sourced streams — doc 03 §5, doc 05 | +| EVT (events) | Domain events vs integration events; durable subscriptions — doc 03 §7, doc 06 | +| STO (store contracts) | Role-segregated ports with pinned semantics — doc 05 §1 | +| REG (registration) | Generated modules — [ADR-004](../ADRs/ADR-004-source-generation-instead-of-reflection.md) | +| EXT (middleware) | One middleware abstraction — [ADR-012](../ADRs/ADR-012-one-middleware-abstraction-for-all-stages.md) | +| OBS / CTL (telemetry, health) | doc 08 | +| PERF | doc 09 | +| EF (persistence) | PostgreSQL and SQL Server stores, EF Core read models — doc 05 | +| BUS (routing, bootstrapping) | Routing, topology, provisioning modes — doc 04 §3, doc 07 | +| IDM, DLQ, RES | Inbox, parking, Polly — doc 04 | +| SEC | doc 10 | +| AWS / GCP (+ Azure) | doc 07, with the TCK as the parity gate | +| NFR (all) | Quality goals in doc 01 §2, verified by doc 11 | +| Query side (new request) | Schema catalog, SFQL, consistency tokens, temporal reads — doc 14, [ADR-023](../ADRs/ADR-023-sfql-query-language-with-cesql-predicates.md) | +| Workflow DSL + visual designer (new request) | Separate utility: DSL compiled to process managers, React Studio, manifests — doc 15, ADR-024, ADR-025, §5.0 | +| Competitive parity (new request) | Tenancy ([ADR-022](../ADRs/ADR-022-conjoined-multi-tenancy-with-row-level-security.md)), DCB readiness ([ADR-021](../ADRs/ADR-021-dynamic-consistency-boundaries-dcb-in-3-1.md)), archiving, `MapCommand`, roadmap — doc 13 | + +## 8. Risk register + +| # | Risk | Likelihood | Impact | Mitigation | +|---|------|------------|--------|------------| +| R1 | v2 users find the event-sourcing shift too large | Medium | High | Migration tool, concept map, companion-book chapter, v2 support window, coexistence bridge | +| R2 | The source-generator learning curve or generator bugs block users | Medium | Medium | Snapshot-tested generators; clear diagnostics; documented "view generated code"; small generated surface | +| R3 | `xid8` horizon stalls caused by long transactions in shared databases | Medium | Medium | `horizon_age` metric and health check; guidance to keep a dedicated database or schema; documented impact (latency only) | +| R4 | Semantic-convention churn in OTel messaging | High | Low | Pinned semconv version with opt-in upgrades ([ADR-019](../ADRs/ADR-019-telemetry-always-on-with-standard-semantic-conventions.md)) | +| R5 | Three release-blocking transports overload M3 | Medium | High | The SPI and TCK land first, so each transport is mechanical. Three parallel workstreams. Emulators in CI from day one. Schedule pressure moves the date, not the scope (Q5/Q6 sign-off) | +| R6 | Outbox write amplification at tier L | Low | Medium | Measured in M2–M4; log-tailing alternative documented (doc 09 §8) | +| R7 | AOT and trimming constraints conflict with user libraries (validators, EF Core) | Medium | Low | AOT is a goal for the core and adapters; EF Core read models are documented as JIT-only where EF requires it | +| R8 | Crypto-shredding complexity (key loss = data loss) | Low | High | KMS-wrapped keys with KMS backup and retention policies; erasure is an explicit, audited API; chaos test for KMS outage (fail closed, retry) | +| R9 | SFQL becomes a large surface to maintain, or queries hurt write performance | Medium | Medium | Small `sfql/1` grammar (no joins), cost guard, read-only role with replica support, golden tests plus CESQL TCK, versioned language | +| R10 | Added scope (tenancy, query engine) stretches M1–M4 | Medium | Medium | The query HTTP endpoint and the GraphQL adapter are explicit slip candidates. Tenancy columns are cheap and must land in M2, because they change keys. | + +## 9. Review checklist for approvers + +- [x] Q1–Q7 answers ([README §3](README.md#3-answers-to-the-open-product-questions)) accepted by product on 2026-11-10 (Q2 with the query-boundary requirement; Q5/Q6 = 3.0.0). +- [ ] [ADR-001](../ADRs/ADR-001-target-dotnet-10-and-csharp-14.md) to [ADR-023](../ADRs/ADR-023-sfql-query-language-with-cesql-predicates.md) accepted or amended. +- [ ] SFQL `sfql/1` grammar and semantics (doc 14) accepted as a public, versioned contract. +- [ ] Workflow DSL `sourceflow.workflow/1` and manifest `manifestVersion: 1` accepted as public contracts (doc 15); Studio release-train decision (WQ1) confirmed. +- [ ] Competitive positioning and licence commitment (doc 13 §6, §8) accepted by leadership. +- [ ] Capacity tiers (doc 09 §5) checked against known v2 user workloads. +- [ ] PostgreSQL 15+ / SQL Server 2022+ minimums acceptable. +- [ ] v2 support window (12 months) accepted. +- [ ] Milestone exit criteria accepted as release gates. diff --git a/docs/v3.0.0/engineering/Design/13-Competitive-Analysis.md b/docs/v3.0.0/engineering/Design/13-Competitive-Analysis.md new file mode 100644 index 00000000..30a4e787 --- /dev/null +++ b/docs/v3.0.0/engineering/Design/13-Competitive-Analysis.md @@ -0,0 +1,186 @@ +# 13 — Competitive Analysis + +**Purpose.** To check that the v3 design follows the practices and standards the mature event-sourcing ecosystem has converged on, to find where competitors are ahead, and to define where SourceFlow.Net v3 can offer a **clear, defensible advantage**. + +**As of** November 2026. Facts marked † were checked against public sources (listed in §9) during this study. Everything else reflects widely documented, long-standing behaviour. Licences and features change quickly, so re-check before using this document externally. + +## 1. Landscape and selection + +| Category | Products studied | Why included | +|----------|------------------|--------------| +| .NET event stores and frameworks | **Marten** (+ its SQL Server sibling **Polecat**†), **Eventuous**, **KurrentDB** (formerly EventStoreDB)† with its .NET client, **Akka.NET Persistence** | Direct competitors for .NET event sourcing | +| .NET messaging frameworks with saga and outbox support | **Wolverine** (pairs with Marten as the "Critter Stack"), **NServiceBus**, **MassTransit** | Competitors for the messaging half of SourceFlow (outbox, inbox, sagas, transports) | +| Cross-platform reference | **Axon Framework 5 + Axon Server** (Java)†, the **DCB** specification community (dcb.events)† | They set new standards that .NET users will ask for | + +Also noted, not profiled: Orleans `JournaledGrain`, Equinox (F#), Cratis Chronicle (.NET, DCB-oriented)†, Emmett (TypeScript), EventSourcingDB. + +## 2. Profiles + +### 2.1 Marten (+ Polecat) — JasperFx, MIT + +- **Model.** PostgreSQL as document database plus event store. Projections can be inline, async (through the *async daemon*) or live. There are single-stream, multi-stream and flat-table projections. `FetchForWriting` gives optimistic concurrency. +- **Strengths.** The most mature .NET option. Very rich projection model. Multi-tenancy (conjoined, and database-per-tenant)†. Stream archiving† and compacting in v8†. Event "skipping" for poison events†. Deep Wolverine integration. Large community. +- **Ordering approach.** The async daemon tracks a *high-water mark* and skips sequence gaps after a time-based staleness threshold†. A public discussion (#4953)† analyses cases where that heuristic can advance past events still being committed. +- **Gaps relative to v3.** PostgreSQL-only (Polecat† covers SQL Server 2025 and .NET 10 as a separate product). Runtime code generation (pre-generation is optional) rather than Roslyn generators. Messaging, outbox and cloud transports need Wolverine. No built-in crypto-shredding (v8 offers masking of protected data by rewriting stored events†, a different trade-off). + +### 2.2 Wolverine — JasperFx, MIT + +- **Model.** A mediator plus message bus with a durable inbox and outbox†. Its "aggregate handler workflow" over Marten writes events from handlers†, and `[WriteAggregate]` spans several streams in one transaction†. Event forwarding goes through the outbox†. Sagas, durable scheduling, HTTP endpoints, and a broad transport set. +- **Strengths.** Excellent developer ergonomics. Transactional outbox and inbox. Many transports. Tight Marten and Polecat integration. +- **Gaps relative to v3.** Handler code generation happens at runtime by default. Cross-transport behavioural parity isn't enforced by a public conformance kit. The full "Critter Stack" means two products to learn. Commercial monitoring (CritterWatch) is separate. + +### 2.3 Eventuous — Apache 2.0 + +- **Model.** Event-sourcing library with aggregates and functional command services. Stores: KurrentDB, PostgreSQL, SQL Server†. Subscriptions with partitioned consumers. A **gateway** that turns private domain events into integration events through producers†. Producers for RabbitMQ, Google Pub/Sub, Kafka and others. +- **Strengths.** Clean design, explicit private-to-public event mapping, OpenTelemetry diagnostics. +- **Gaps relative to v3.** The project states its API isn't yet stable†, and it is pre-1.0 (0.16/0.17 in 2026†). The integration gateway works from subscriptions rather than a transactional outbox. Smaller community. + +### 2.4 KurrentDB (formerly EventStoreDB) — Kurrent License v1† + +- **Model.** A purpose-built event database. Streams, `$all`, catch-up and persistent subscriptions, server-side projections. **Multi-stream appends** with per-stream expected versions arrived in 25.1†. Tiered **archiving** to cloud object storage (licensed)†. **Connectors** (sinks to Kafka, MongoDB, RabbitMQ, Elasticsearch; licensed except HTTP)†. +- **Strengths.** Throughput, built-in global ordering, operational features, a polyglot client ecosystem. +- **Gaps relative to v3.** A separate database to operate. Licence-gated features†. It is not an application framework, so aggregates, outbox and process managers come from elsewhere (for example Eventuous). + +### 2.5 Axon Framework 5 + Axon Server — Apache 2.0 framework, commercial server tiers + +- **Model.** A full CQRS and event-sourcing framework for the JVM. Version 5 introduces **Dynamic Consistency Boundaries (DCB)**†: consistency is decided per operation by querying tagged events instead of fixed aggregate streams. Axon Server 2025.x supports DCB†. +- **Strengths.** It defines the frontier: DCB, mature event processors, upcasting, deadline management, and a distributed command bus. +- **Gaps relative to v3.** JVM only. The server's advanced features are commercial. Version 5 is a significant migration from Axon 4†. + +### 2.6 NServiceBus (Particular, commercial) and MassTransit (v9 commercial†) + +- **Model.** Messaging frameworks with sagas, outbox, recoverability (immediate and delayed retries, error queues) and many transports. Neither is an event store. +- **Strengths.** Battle-tested recoverability and operations tooling (ServicePulse and ServiceInsight for NServiceBus), and large installed bases. +- **Market signal.** MassTransit v9 moved to a commercial licence (announced April 2025, commercial release planned for Q1 2026; v8 stays Apache 2.0)†. Many .NET teams are now re-evaluating open-source alternatives, which is a **window of opportunity** for an open, integrated library. + +### 2.7 Akka.NET Persistence — Apache 2.0 + +- **Model.** Event-sourced persistent actors. Cluster sharding guarantees a **single writer** per entity. `Akka.Persistence.Query` provides projections. +- **Strengths.** No optimistic-concurrency conflicts by design, and high throughput for hot entities. +- **Gaps relative to v3.** The actor model is a steep paradigm shift. Integration events, outbox and cloud transports are left to the user. + +## 3. Feature comparison matrix + +Legend: ● built-in · ◐ partial, through a companion product, or licence-gated · ○ not provided · **v3** = this design (3.0 unless marked). + +| Capability | Marten (+Wolverine) | Eventuous | KurrentDB | Axon 5 | NServiceBus / MassTransit | Akka.NET | **SourceFlow v3** | +|------------|:---:|:---:|:---:|:---:|:---:|:---:|:---:| +| Event-sourced aggregates | ● | ● | ◐ (client only) | ● | ○ | ● (actors) | ● pure deciders | +| Functional decide/evolve as the primary model | ◐ | ● | ○ | ◐ | ○ | ○ | ● | +| Compile-time source generation, Native AOT | ◐ (runtime codegen, pre-gen option) | ○ | ◐ | ○ | ○ | ○ | ● | +| Analyzers enforcing ES discipline (purity, determinism, PII) | ○ | ○ | ○ | ○ | ○ | ○ | ● | +| Stable logical event type names + upcasting | ● | ● | ◐ | ● | ◐ | ● | ● | +| Optimistic concurrency + automatic re-decide | ● (via Wolverine) | ● | ● | ● | — | — (single writer) | ● | +| Multi-stream atomic append / DCB | ● (`[WriteAggregate]`) | ○ | ● (25.1)† | ● (DCB)† | — | ○ | ◐ tags in 3.0 schema; DCB in 3.1 ([ADR-021](../ADRs/ADR-021-dynamic-consistency-boundaries-dcb-in-3-1.md)) | +| Gap-free global ordering, **no timeouts** | ◐ (high-water mark + stale threshold) | ◐ (store-dependent) | ● (native log) | ● | — | ◐ (journal-dependent) | ● commit-ordered (`xid8` / rowversion) | +| Inline + async projections, rebuilds | ● | ● | ◐ | ● | ○ | ◐ | ● blue/green | +| Partitioned projections with **fencing tokens** | ◐ (sharding; leadership by locks) | ◐ | ◐ (persistent subscriptions) | ● | — | ◐ | ● | +| Transactional outbox + inbox | ● (Wolverine) | ◐ | ○ | ● | ● | ○ | ● always on | +| Idempotency key → stored command result (HTTP semantics) | ○ | ○ | ○ | ○ | ○ | ○ | ● | +| Process managers with durable timers | ● (Wolverine sagas, scheduling) | ◐ | ○ | ● (deadlines) | ● | ◐ | ● | +| PostgreSQL **and** SQL Server event store | ◐ (Marten + Polecat, separate products) | ● | — (own database) | ◐ | — | ● | ● one API | +| Cloud transports AWS + Azure + GCP | ● (Wolverine) | ◐ | ◐ (connectors, licensed) | ◐ | ● | ○ | ● | +| Public **transport conformance kit** (behavioural parity) | ○ | ○ | — | — | ◐ (internal) | — | ● | +| CloudEvents-native envelope | ○ | ○ | ○ | ○ | ○ | ○ | ● | +| Provisioning modes (create / **validate-only**) + IaC topology export | ◐ (auto-provision) | ○ | — | ◐ | ◐ (installers) | — | ● | +| OpenTelemetry with **messaging semconv** + lag, outbox-age and horizon metrics | ◐ | ● | ◐ | ◐ | ◐ | ◐ | ● | +| Shipped SLO dashboards and alerts | ○ | ○ | ◐ (UI) | ◐ | ● (ServicePulse, commercial) | ○ | ● Grafana/Prometheus + Aspire | +| Crypto-shredding for GDPR | ○ (masking by rewrite) | ○ | ○ | ◐ (commercial add-on) | ○ | ○ | ● | +| Multi-tenancy | ● (conjoined + database-per-tenant) | ○ | ◐ | ● | ◐ | ○ | ● conjoined + Postgres RLS in 3.0 ([ADR-022](../ADRs/ADR-022-conjoined-multi-tenancy-with-row-level-security.md)); database-per-tenant 3.x | +| Stream archiving / tiered storage | ● (archive, compacting) | ○ | ◐ (licensed)† | ◐ | — | ○ | ◐ partitions + archive flag in 3.0; compaction 3.1 | +| Temporal queries (state as of version or time) | ● | ◐ | ● | ● | — | ◐ | ● (added by this study) | +| Kafka / RabbitMQ transports | ● | ● | ◐ (connectors) | ◐ | ● | ◐ | ◐ 3.1 through the TCK | +| Saga/workflow DSL + **visual designer** across services (success, failure, retry, rollback), simulation, generated tests | ◐ (code-first sagas; commercial CritterWatch for monitoring) | ○ | ○ | ◐ (code-first; commercial tooling) | ◐ (MassTransit state-machine DSL in code; NServiceBus ServiceInsight visualises sagas, commercial) | ○ | ● **SourceFlow Studio** (separate utility; doc 15) | +| Management UI | ◐ (commercial) | ○ | ● | ● | ● (commercial) | ○ | ◐ CLI + dashboards; console in 3.x | +| Licence for **all** core production features | MIT | Apache 2.0 | KLv1 (some features licensed)† | Apache 2.0 + commercial server tiers | Commercial / v9 commercial† | Apache 2.0 | **MIT/Apache, nothing gated** | + +## 4. Industry practices: does v3 conform? + +| Converged practice | Seen in | v3 conformance | +|--------------------|---------|----------------| +| Events are the source of truth; state is a fold | All event-sourcing products | ● [ADR-002](../ADRs/ADR-002-event-sourcing-replaces-command-sourcing.md) | +| Per-stream optimistic concurrency with expected version | Marten, KurrentDB, Eventuous, Axon | ● [ADR-008](../ADRs/ADR-008-optimistic-concurrency-with-automatic-re-decide.md) | +| Stable event type names, separate from CLR types; upcasters | Axon, Marten, Eventuous | ● [ADR-005](../ADRs/ADR-005-logical-message-type-names-and-registry.md) | +| Private domain events vs public integration events | Eventuous (gateway), Axon, DDD guidance | ● doc 03 §7 | +| Transactional outbox and idempotent receivers | Wolverine, NServiceBus, MassTransit | ● [ADR-006](../ADRs/ADR-006-transactional-outbox-and-inbox-for-effectively-once.md) | +| Immediate + delayed retries, then an error queue | NServiceBus, MassTransit, Wolverine | ● doc 04 §9 | +| Checkpointed, rebuildable projections | Marten, Eventuous, Axon | ● doc 06 | +| Snapshots as an optimisation, not truth | All | ● doc 05 §8 | +| Correlation and causation metadata | All | ● doc 04 §1 | +| Multi-tenancy as a first-class concern | Marten, Wolverine, Axon | ● after this study ([ADR-022](../ADRs/ADR-022-conjoined-multi-tenancy-with-row-level-security.md)) | +| Moving beyond fixed aggregates for cross-entity invariants (DCB) | Axon 5†, KurrentDB multi-stream†, Cratis†, EventSourcingDB community | ◐ schema-ready in 3.0, API in 3.1 ([ADR-021](../ADRs/ADR-021-dynamic-consistency-boundaries-dcb-in-3-1.md)) | +| Archiving or tiering cold data | Marten†, KurrentDB† | ◐ partitions + archive flag in 3.0 | + +**Conclusion.** v3 follows every converged practice. Two emerging standards, DCB and first-class tenancy, are added by this study. + +## 5. Where competitors lead, and the response + +| # | Competitor advantage | Response | When | +|---|----------------------|----------|------| +| C1 | Marten and Wolverine: mature multi-tenancy | **Adopt**: conjoined tenancy (tenant column, tenant-scoped streams, PostgreSQL row-level security) in 3.0. Database-per-tenant in 3.x. | 3.0 ([ADR-022](../ADRs/ADR-022-conjoined-multi-tenancy-with-row-level-security.md)) | +| C2 | Axon 5 DCB, KurrentDB multi-stream appends: cross-entity consistency without inflated aggregates | **Adopt in 3.1**: tag-based append conditions. 3.0 adds `tags` to the event schema and a `[Tag]` attribute, so stored events are DCB-ready with no migration. | 3.1 ([ADR-021](../ADRs/ADR-021-dynamic-consistency-boundaries-dcb-in-3-1.md)) | +| C3 | Marten and KurrentDB: archiving and compaction | 3.0: monthly partitions plus a stream `archived` flag (excluded from loads and rebuilds unless asked for). 3.1: compaction (genesis snapshot event + archive the prefix). | 3.0 / 3.1 | +| C4 | Temporal queries ("state as of …") | **Adopt**: `IAggregateReader.LoadAsync(id, AsOf.Version(v) / AsOf.Time(t))`. Cheap, given the store design. | 3.0 | +| C5 | Wolverine.Http: low-ceremony HTTP endpoints | **Adopt** a small `SourceFlow.AspNetCore` package: `app.MapCommand(route)` maps `Idempotency-Key`, `If-Match` → `ExpectedVersion`, `CommandResult` → ProblemDetails or 2xx with `ETag`. | 3.0 | +| C6 | Transport breadth (Wolverine, MassTransit, NServiceBus) | RabbitMQ and Kafka transports through the TCK in 3.1. An event gateway (subscription → Kafka sink) in 3.1. | 3.1 | +| C7 | Management UI (ServicePulse, KurrentDB UI, CritterWatch) | 3.0: CLI plus generated Grafana dashboards, and the Aspire dashboard through OTLP. 3.x: an optional open-source "SourceFlow Console" over the same APIs. | 3.x | +| C8 | Akka.NET: single-writer throughput on hot entities | Partition-key affinity plus the optimistic cache (doc 09 §3) give most of the benefit without actors. Pessimistic per-aggregate locking stays a documented option. | 3.0 (existing) | +| C9 | KurrentDB: purpose-built store throughput | Keep the port open. A KurrentDB storage adapter is a 3.x candidate, which would make SourceFlow the framework layer over KurrentDB as well. | 3.x | +| C10 | Ecosystem maturity and community (Marten, NServiceBus) | Not solvable by design. Answered through the companion book, samples, migration guides from Marten, Eventuous and MassTransit, and an open roadmap. | Ongoing | + +## 6. SourceFlow v3 competitive advantages + +Each claim is backed by a concrete design element, so it can be verified rather than just marketed. + +| # | Advantage | Evidence | Why competitors don't match it today | +|---|-----------|----------|--------------------------------------| +| A1 | **Provably gap-free subscriptions with no timeouts** | Commit-ordered positions (`xid8` horizon on PostgreSQL, `MIN_ACTIVE_ROWVERSION` on SQL Server), with the ordering argument in doc 05 §5 | Sequence-based stores need gap heuristics such as Marten's stale threshold†. KurrentDB solves it with its own database. | +| A2 | **Compile-time and Native-AOT-ready** | Roslyn generators for dispatch, JSON, ids and registration; no reflection on the hot path | Runtime code generation (Wolverine/Marten) or reflection (most others) | +| A3 | **Guard-rails as analyzers** | SF0001–SF0014: purity, determinism, PII leaks, ownership conflicts | No other product found ships event-sourcing discipline analyzers | +| A4 | **One integrated, fully open stack** | Event store, projections, process managers, outbox/inbox and three cloud transports in one coherent API, under a permissive licence with nothing gated | The same scope elsewhere means two products (Marten + Wolverine), a database plus a framework (KurrentDB + Eventuous), or commercial licences (NServiceBus, MassTransit v9†, licensed KurrentDB features†) | +| A5 | **Verified cross-cloud parity** | A public Transport Conformance Kit, CloudEvents envelope, identical retry and dead-letter semantics | Parity elsewhere is best-effort and not publicly verified | +| A6 | **Privacy by design** | Crypto-shredding with per-subject keys, erased-value semantics, automatic read-model scrubbing, PII analyzers | Most rely on DIY approaches or rewriting stored events | +| A7 | **Operations-first** | Validate-only provisioning, topology export for IaC, SLO dashboards generated from the instrument list, lag, outbox-age and horizon metrics, fenced leases | Comparable operations tooling is usually commercial or separate | +| A8 | **HTTP-grade command semantics** | Idempotency keys returning stored results, `If-Match` → expected version, rejections as values → ProblemDetails | Not provided end to end by the products studied | +| A9 | **One API over PostgreSQL and SQL Server** | One storage SPI and one conformance kit | Marten and Polecat are separate products; others are single-database | +| A11 | **Visual, verifiable workflows** | A YAML DSL compiled into ordinary process managers; React designer over the whole business domain; build-time validation of failure, retry and compensation completeness; simulation identical to production (shared WASM core); generated tests per path; PR diagrams | Comparable designers are commercial, code-first, or tied to a separate workflow engine | +| A10 | **Teachable and correct** | Pure deciders, Given/When/Then specs, companion-book alignment | A reference implementation that is both production-grade and pedagogical | + +**Positioning statement.** *SourceFlow.Net is the open, compile-time-verified event-sourcing and messaging framework for .NET 10. It gives you provably correct streams, outbox-backed integration across AWS, Azure and Google Cloud, and privacy and operability built in, in one library on the database you already run.* + +**Primary target segments.** +1. .NET teams on SQL Server or PostgreSQL who want event sourcing without running a second database. +2. Teams leaving commercial messaging frameworks after licence changes. +3. Regulated domains that need crypto-shredding and audit. +4. Multi-cloud or cloud-portable products. + +## 7. Changes applied to the v3 design as a result of this study + +| Change | Documents updated | +|--------|-------------------| +| Conjoined multi-tenancy + row-level security in 3.0 | [ADR-022](../ADRs/ADR-022-conjoined-multi-tenancy-with-row-level-security.md), doc 01 §4, doc 05 §2, doc 12 §5 | +| DCB-ready schema in 3.0 (`tags`), DCB API in 3.1 | [ADR-021](../ADRs/ADR-021-dynamic-consistency-boundaries-dcb-in-3-1.md), doc 05 §2 | +| Stream archive flag (3.0), compaction (3.1) | doc 05 §9 | +| Temporal aggregate reads | doc 03 §5.4 | +| `SourceFlow.AspNetCore` with `MapCommand` | doc 01 §6, doc 03 §5.1, doc 12 §5 | +| 3.1 roadmap: RabbitMQ, Kafka, event gateway, DCB, compaction; 3.x: console, KurrentDB adapter, database-per-tenant | doc 12 §5.1 | + +## 8. Risks from the competitive position + +| Risk | Mitigation | +|------|------------| +| The Critter Stack's momentum and maturity | Differentiate on A1–A9, not on feature count. Publish a Marten → SourceFlow migration guide only after GA. | +| DCB becomes the expected default before 3.1 | The schema is DCB-ready in 3.0, and the 3.1 API is designed now ([ADR-021](../ADRs/ADR-021-dynamic-consistency-boundaries-dcb-in-3-1.md)). | +| Licence shifts in the ecosystem (including ours) | Commit publicly to MIT or Apache for every package. Any future commercial offering covers *services* (support, console hosting), never core features. | + +## 9. Sources (checked during this study) + +- Marten — [Async daemon (high-water mark)](https://martendb.io/events/projections/async-daemon), [Archiving](https://martendb.io/events/archiving), [Releases](https://www.github.com/JasperFx/marten/releases), [v8 stream compacting](https://devbytes.co.in/news/marten-v80-introduces-stream-compacting), [Discussion #4953: daemon progress vs concurrent appends](https://github.com/JasperFx/marten/discussions/4953) +- Wolverine — [Marten outbox](https://wolverine.netlify.app/guide/durability/marten/outbox), [Event sourcing / aggregate handler workflow](https://wolverine.netlify.app/guide/durability/marten/event-sourcing), [Event forwarding](https://wolverine.netlify.app/guide/durability/marten/event-forwarding), [Transactional middleware](https://wolverine.netlify.app/guide/durability/marten/transactional-middleware) +- Polecat — [Introduction](https://polecat.netlify.app/introduction), [Whitepaper](https://jasperfx-polecat.pages.dev/whitepaper) +- Eventuous — [Introduction](https://eventuous-docs.pages.dev/introduction.html), [Eventuous.Postgresql on NuGet](https://packages.nuget.org/packages/Eventuous.Postgresql/), [Eventuous.Subscriptions on NuGet](https://packages.nuget.org/packages/Eventuous.Subscriptions/) +- KurrentDB — [25.0 What's New (rename, licence, archiving, connectors)](https://docs.kurrent.io/server/v25.0/quick-start/whatsnew), [25.1 multi-stream appends](https://kurrent.io/releases/kurrentdb/25-1), [26.0 What's New](https://docs.kurrent.io/server/v26.0/quick-start/whatsnew) +- Axon — [Axon Framework 5.0 release](https://www.axoniq.io/blog/release-of-axon-framework-5-0), [DCB in AF5](https://www.axoniq.io/blog/dcb-in-af-5), [Axon Server 2025.1 with DCB](https://www.axoniq.io/blog/axon-server-future-proof-event-store) +- DCB — [dcb.events](https://dcb.events/), [Python eventsourcing DCB](https://eventsourcing.readthedocs.io/en/stable/topics/dcb.html), [Cratis Chronicle DCB](https://www.cratis.io/chronicle/dynamic-consistency-boundary.md) +- MassTransit — [Announcing MassTransit v9](https://masstransit.io/introduction/v9-announcement), [Analysis by Milan Jovanović](https://milanjovanovic.tech/blog/mediatr-and-masstransit-going-commercial-what-this-means-for-you) +- Comparison context — [Cratis: comparing KurrentDB, Marten and Chronicle](https://www.cratis.io/compare-event-sourcing-dotnet/) diff --git a/docs/v3.0.0/engineering/Design/14-Query-Side-and-SFQL.md b/docs/v3.0.0/engineering/Design/14-Query-Side-and-SFQL.md new file mode 100644 index 00000000..a17ff159 --- /dev/null +++ b/docs/v3.0.0/engineering/Design/14-Query-Side-and-SFQL.md @@ -0,0 +1,774 @@ +# 14 — Query Side: Event Schema Catalog and SFQL + +Design drivers: [ADR-005](../ADRs/ADR-005-logical-message-type-names-and-registry.md), [ADR-016](../ADRs/ADR-016-projections-inline-or-async-with-partitioned-fenced.md), [ADR-022](../ADRs/ADR-022-conjoined-multi-tenancy-with-row-level-security.md) **[ADR-023](../ADRs/ADR-023-sfql-query-language-with-cesql-predicates.md)** and **[ADR-026](../ADRs/ADR-026-per-service-query-api-with-sql-syntax-and-injection-proof-compilation.md)**. This document specifies how the **read side** of CQRS is queried, separately from writes: the event schema catalog that makes events queryable, and SFQL, the query language that runs over it. + +## 1. CQRS separation rules + +| Rule | Detail | +|------|--------| +| Q-R1 | **Writes never read through the query side.** `Decide`, `When` and `React` get state only from their own stream (or DCB query, [ADR-021](../ADRs/ADR-021-dynamic-consistency-boundaries-dcb-in-3-1.md)). Using `IQueryService` inside aggregate, process-manager or projection code is an **error** (analyzer SF0015). Using it in an `ICommandHandler` is a **warning** (SF0016: "decisions based on eventually consistent reads"). | +| Q-R2 | **Queries never write.** SFQL has no data-changing grammar. Execution uses a `QueryDataSource` whose database role has `SELECT` only on `events`, `streams`, `documents`, `schemas` and `collection_aliases`. It can't read `outbox`, `inbox` or `data_keys`. | +| Q-R3 | **Separate resources.** `sf.Query(q => q.ConnectionString = …)` may point at a **read replica**. Query load never competes for the write pool. | +| Q-R4 | **Logical addressing.** Queries name logical event types, schema fields, collections and aggregates, never tables or JSON paths. The physical schema can evolve without breaking queries. | +| Q-R5 | **Consistency is explicit.** Every query states, or defaults to, a consistency level (§6). Read-your-writes uses tokens, not sleeps. | +| Q-R6 | **Every service exposes a query API** (§9) over its own events and read models. It validates syntax and policy before anything runs, supports the basic SQL read constructs (joins, filtering, grouping, ordering, …) through the SQL syntax (§4.2), and is injection-proof by construction (§9.3). | + +### 1.1 Query ownership: the service boundary (Q2) + +Product sign-off on Q2 requires that **querying events is modelled within the owning service's domain and business boundary**. The rules: + +| Rule | Detail | +|------|--------| +| Q-B1 | **One catalog per service.** The schema catalog and SFQL binder see only the event types, read models and aggregates registered by the service's own modules. A query naming another service's event type fails to bind (SFQ0204 *type not owned by this service*). | +| Q-B2 | **No cross-service event-log access.** The read-only query role is granted on the service's own database or schema only. There is no federated query across services. | +| Q-B3 | **Foreign facts become local read models.** To query data that originated elsewhere, the service subscribes to the other service's *integration events* and projects them into **its own** read model, named in its own vocabulary. That read model is then queryable like any other. | +| Q-B4 | **Stable contracts are named domain queries; ad-hoc querying is a permissioned capability.** Inside the service, developers and operators may run ad-hoc SFQL (subject to permissions). Toward other services and UIs, a service publishes **named domain queries**, versioned like integration events: `[DomainQuery("accounts.overdrawn-accounts", 1)]` binds an SFQL text with typed parameters and a typed result record. The per-service query API (§9) also accepts **ad-hoc** queries (pipeline or SQL syntax) for callers holding `sourceflow.query.adhoc`: operators, analysts, BI tools and the service's own UIs. Ad-hoc results aren't a versioned contract; clients that need stability use a named query. | +| Q-B5 | **The vocabulary is the domain's.** Query names, parameters and result fields use the bounded context's ubiquitous language, never storage terms. A named query's result is a read model or projection of events, never raw `data` blobs, unless the query is explicitly an audit query of the service's own log. | +| Q-B6 | **Reporting across services** is a separate bounded context (for example "reporting"). It owns read models built from the integration events it subscribes to, and applies these same rules. | + +```csharp +// A named, versioned domain query: the contract other services and UIs use (Q-B4) +[DomainQuery("accounts.overdrawn-accounts", 1)] +public sealed partial record OverdrawnAccounts(decimal Below) : IDomainQuery +{ + public const string Sfql = """ + from readmodel "account-summary" + | where status = 'Open' and balance < @below + | project accountId = id, holderSegment = segment, balance + | order by balance asc + """; +} +public sealed record OverdrawnAccount(Guid AccountId, string HolderSegment, decimal Balance); + +// In-process: var rows = await queries.ExecuteAsync(new OverdrawnAccounts(Below: 0m), ct); +// HTTP: app.MapDomainQueries(); → GET /queries/accounts.overdrawn-accounts/v1?below=0 +``` + +The generator binds every `[DomainQuery]` at **build time** against the catalog (analyzer SF0018: the query doesn't bind, or its result columns don't match the result record). A broken contract therefore fails compilation, not production. + +```mermaid +flowchart LR + subgraph Write side + CMD[ICommandSender] --> CP[Command processor] --> ES[(events + streams)] + ES --> SE[Subscription engine] --> RM[(read models / documents)] + end + subgraph Read side + API[C# IQueryService / typed builder / CLI / HTTP] --> QE[SFQL engine
parse → bind → policy → plan → compile] + CAT[(Schema catalog)] --> QE + QE -->|read-only role, replica OK| ES + QE --> RM + end + CP -. ConsistencyToken .-> API +``` + +## 2. Event schema catalog + +Queries need to know, statically, which fields every event type has, in every version. The catalog is that knowledge. + +### 2.1 Generation + +For every `[MessageType]`, the source generator emits a **JSON Schema 2020-12** document with SourceFlow extensions: + +```json +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "urn:sourceflow:schema:bank.account.opened:2", + "title": "AccountOpened", + "type": "object", + "properties": { + "accountId": { "type": "string", "format": "uuid", "x-sourceflow-tag": "account" }, + "givenName": { "type": "string", "x-sourceflow-personal-data": { "subject": "customerId" }, + "x-sourceflow-renamed-from": { "1": "holder" } }, + "familyName": { "type": "string", "x-sourceflow-personal-data": { "subject": "customerId" } }, + "customerId": { "type": "string", "format": "uuid", "x-sourceflow-queryable": true }, + "initialDeposit": { "type": "string", "format": "decimal", "x-sourceflow-queryable": true }, + "openedAt": { "type": "string", "format": "date-time" } + }, + "required": ["accountId", "givenName", "familyName", "customerId", "initialDeposit", "openedAt"], + "x-sourceflow": { "type": "bank.account.opened", "version": 2, "kind": "event", "aggregate": "bank-account" } +} +``` + +Attributes on message members drive the extensions: + +| Attribute | Effect on querying | +|-----------|--------------------| +| `[Queryable]` | The field may appear in `where`, `order by` and `summarize by` over the event log. It generates a **partial expression index** (§7.2). | +| `[RenamedFrom("holder", Version = 1)]` | The binder maps the field to its old name when reading rows of that version. | +| `[PersonalData]` | The field can't be filtered, sorted or grouped (it is ciphertext). It is decrypted or masked only in `project` (§8). | +| `[Tag("account")]` | The field becomes a tag ([ADR-021](../ADRs/ADR-021-dynamic-consistency-boundaries-dcb-in-3-1.md)). Tags are always queryable through `has_tag()`. | + +Decimals are serialised as strings (`format: decimal`) so they compare exactly. + +### 2.2 Storage, compatibility and export + +```sql +CREATE TABLE sourceflow.schemas ( + tenant_id text NOT NULL DEFAULT '-', -- '-' = shared (schemas are code, not tenant data) + message_type text NOT NULL, + type_version int NOT NULL, + kind text NOT NULL, -- command | event | integration-event | readmodel + service text NOT NULL, + json_schema jsonb NOT NULL, + fingerprint text NOT NULL, -- SHA-256 of canonical schema + first_seen_at timestamptz NOT NULL DEFAULT now(), + PRIMARY KEY (tenant_id, message_type, type_version)); +``` + +- **Registration.** At startup each service upserts its schemas (idempotent). A *different* fingerprint for an existing `(type, version)` **fails startup**, because a published version is immutable. +- **Compatibility check in CI.** `dotnet sourceflow schema check --baseline schemas.lock.json` enforces these rules: + - adding an optional field is allowed; + - removing, retyping or renaming a field requires a new version plus an upcaster (and `[RenamedFrom]` for renames); + - changes to integration events are always checked against the *published* baseline. +- **Read-model schemas.** Document projections register their document type with `kind = readmodel`, so `readmodel` queries are checked too. +- **Export.** `dotnet sourceflow schema export --format asyncapi` writes an **AsyncAPI 3.0** document: channels are endpoints and topics from the topology, messages are integration-event schemas, and CloudEvents headers are included. Tools that ingest AsyncAPI (for example EventCatalog) can publish it as a browsable event catalog. `--format jsonschema` writes the raw schemas. + +## 3. SFQL overview + +SFQL has **two syntaxes that parse into one AST**. The binder, policy, planner, compilers and security rules are therefore identical for both: + +```text +-- Pipeline syntax (language = "sfql") +from events of "bank.account.deposited" +| where data.amount >= @min and time >= ago(7d) +| project stream, time, amount = data.amount +| order by time desc +| take 100 +``` + +```sql +-- SQL syntax (language = "sql"): a read-only SELECT subset +SELECT e.stream, e.time, e.data.amount AS amount +FROM events."bank.account.deposited" e +WHERE e.data.amount >= @min AND e.time >= ago(7d) +ORDER BY e.time DESC +LIMIT 100 +``` + +- A pipeline query is one **source**, a sequence of **stages** and optional **options**. A SQL query is one `SELECT` with joins, filters, grouping, ordering and limits (§4.2). +- Keywords are case-insensitive. Identifiers are case-sensitive camelCase, matching the JSON. In SQL syntax, `"double quotes"` delimit identifiers and `'single quotes'` delimit strings (the SQL standard). In pipeline syntax, CESQL string rules apply. +- **Values come only from parameters** (`@name`) or literals, and both become bound parameters in generated SQL (§9.3, rule I-3). Caller text is never spliced into SQL. +- Specification identifier: `sfql/1`, covering both syntaxes. A future breaking change is `sfql/2`, selected by `options (language = 'sfql/2')` or the API's `language` field. + +## 4. Grammar (`sfql/1`, EBNF) + +### 4.1 Pipeline syntax + +```ebnf +query = source , { "|" , stage } , [ options ] ; + +source = "from" , ( events_src | stream_src | readmodel_src | aggregate_src | schema_src ) , [ "as" , ident ] ; +events_src = "events" , [ "of" , string , { "," , string } , [ "version" , integer ] ] , [ "upcast" ] ; +stream_src = "stream" , value ; +readmodel_src = "readmodel" , string ; +aggregate_src = "aggregate" , string , "id" , value , [ "as" , "of" , ( "version" | "time" ) , value ] ; +schema_src = "schema" , [ "of" , string ] ; + +stage = where | project | distinct | summarize | order | skip | take | join | lookup ; +where = "where" , expr ; +project = "project" , item , { "," , item } ; +distinct = "distinct" , [ item , { "," , item } ] ; +item = [ ident , "=" ] , expr ; +summarize = "summarize" , agg , { "," , agg } , [ "by" , item , { "," , item } ] ; +agg = [ ident , "=" ] , agg_fn , "(" , [ "distinct" ] , [ expr ] , ")" ; +agg_fn = "count" | "count_distinct" | "sum" | "avg" | "min" | "max" ; +order = "order" , "by" , sort , { "," , sort } ; +sort = expr , [ "asc" | "desc" ] , [ "nulls" , ( "first" | "last" ) ] ; +skip = "skip" , value ; (* read-model-only, §7.4 *) +take = "take" , value ; +join = "join" , [ "kind" , "=" , ( "inner" | "left" ) ] , + ( readmodel_src | events_src | stream_src ) , "as" , ident , "on" , join_cond ; +join_cond = column , "=" , column , { "and" , column , "=" , column } ; +lookup = "lookup" , "readmodel" , string , "on" , "key" , "=" , expr , "as" , ident ; (* sugar: left join on id *) +column = [ ident , "." ] , path ; + +options = "options" , "(" , option , { "," , option } , ")" ; +option = ident , "=" , ( value | ident , "(" , [ value ] , ")" ) ; + +value = literal | parameter ; +parameter = "@" , ident ; + +(* expr: the CloudEvents SQL (CESQL) v1 expression grammar — NOT, AND, OR, XOR, =, !=, <>, <, <=, >, >=, + +, -, *, /, %, LIKE, IN (list), EXISTS, and CESQL built-in functions — extended with: + paths alias.field , data.a.b , data.items[0].sku + parameters @name + literals decimal 12.50m ; duration 7d / 12h / 30m / 15s ; datetime('2026-01-01T00:00:00Z') + predicates x BETWEEN a AND b ; x IS [NOT] NULL ; has_tag('account:…') + conditionals CASE WHEN c THEN a { WHEN … } [ ELSE b ] END + functions now() ; ago(duration) ; bin(timestamp, duration) ; coalesce(a, b, …) ; cast(x as type) ; + lower, upper, trim, length, concat, substring, abs, round, floor, ceiling (allow-list, §9.3 I-5) *) +``` + +### 4.2 SQL syntax (read-only `SELECT` subset) + +```ebnf +sql_query = "select" , [ "distinct" ] , select_list , + "from" , table_ref , { join_clause } , + [ "where" , sql_expr ] , + [ "group" , "by" , sql_expr , { "," , sql_expr } , [ "having" , sql_expr ] ] , + [ "order" , "by" , sql_sort , { "," , sql_sort } ] , + [ "limit" , value , [ "offset" , value ] ] , + [ options ] ; (* exactly one statement: no ';' *) +select_list = "*" | select_item , { "," , select_item } ; +select_item = ( sql_expr | ident , "." , "*" ) , [ [ "as" ] , ident ] ; +table_ref = ( "readmodel" , "." , name + | "events" , [ "." , name ] + | "stream" , "(" , value , ")" ) , [ [ "as" ] , ident ] ; +join_clause = [ "inner" | "left" , [ "outer" ] ] , "join" , table_ref , "on" , join_cond ; +sql_sort = sql_expr , [ "asc" | "desc" ] , [ "nulls" , ( "first" | "last" ) ] ; +name = ident | quoted_ident ; (* readmodel."account-summary", events."bank.account.deposited" *) +sql_expr = expr (* §4.1 expression grammar, plus aggregates below *) + | sql_expr , [ "not" ] , "in" , "(" , subquery , ")" + | [ "not" ] , "exists" , "(" , subquery , ")" ; +subquery = "select" , select_item , "from" , table_ref , [ "where" , expr ] ; (* depth 1, no joins inside *) +aggregate = "count" , "(" , ( "*" | [ "distinct" ] , expr ) , ")" + | ( "sum" | "avg" | "min" | "max" ) , "(" , expr , ")" ; +``` + +There are **no productions** for anything that writes, changes schema, calls procedures, separates statements or carries comments. That makes the grammar itself an allow-list (§9.3, rules I-1 and I-2). + +### 4.3 Supported constructs + +| Construct | Pipeline | SQL syntax | Notes | +|-----------|:--------:|:----------:|-------| +| Projection, aliases, `*` / `alias.*` | ✔ `project` | ✔ | `*` expands to the source's schema fields, never raw storage columns | +| `DISTINCT` | ✔ `distinct` | ✔ | | +| **Filtering**: comparison, `AND`/`OR`/`NOT`, `IN (list)`, `BETWEEN`, `LIKE`, `IS [NOT] NULL`, `EXISTS attr` | ✔ `where` | ✔ `WHERE` | CESQL semantics (§5.5) | +| **Joins**: `INNER`, `LEFT [OUTER]` | ✔ `join` | ✔ | Equality conditions, ≤ 3 joins (G-7…G-9) | +| `RIGHT` / `FULL` / `CROSS` joins | ✗ | ✗ | SFQ0102; rewrite `RIGHT` as `LEFT` | +| **Grouping**: `GROUP BY`, `count`, `count(distinct)`, `sum`, `avg`, `min`, `max`, `HAVING` | ✔ `summarize` + `where` | ✔ | G-1, G-2, G-11 | +| **Ordering**: multiple keys, `ASC`/`DESC`, `NULLS FIRST`/`LAST` | ✔ `order by` | ✔ | Deterministic tiebreak appended (G-6) | +| `LIMIT` / `OFFSET` | ✔ `take` / `skip` | ✔ | `OFFSET` only on read-model-only queries, ≤ 10,000 (§7.4) | +| `CASE`, `CAST`, `COALESCE`, allow-listed scalar functions | ✔ | ✔ | §9.3 I-5 | +| Subqueries in `WHERE`: `IN (SELECT …)`, `EXISTS (SELECT …)` | ✗ (use `join`) | ✔ | Depth 1, ≤ 2 per query, correlated by equality only (G-12) | +| `UNION`, CTEs (`WITH`), window functions | ✗ | ✗ | SFQ0102. Candidates for `sfql/1.1` | +| `INSERT`, `UPDATE`, `DELETE`, `MERGE`, DDL, `EXEC`/`CALL`, `SET`, transactions, `;`, comments | ✗ | ✗ | **Never.** No grammar production (SFQ0102) | + +### 4.4 Composition rules + +| Rule | Detail | +|------|--------| +| G-1 | `where` before `summarize` filters rows. `where` after `summarize` (SQL: `HAVING`) filters groups and may reference aggregate names. | +| G-2 | After `summarize` / `GROUP BY`, only the grouping items and aggregates are in scope. | +| G-3 | `project` / the `SELECT` list sets the output columns. Without it, the source's default columns are returned (§5). | +| G-4 | `join` and `lookup` come before `summarize`. `lookup` is shorthand for `join kind=left … on alias.id = key`. | +| G-5 | `take`/`LIMIT` ≤ `MaxRows` (default 1,000, configurable up to 10,000). Without it, the engine returns pages of `PageSize` (default 100). | +| G-6 | Ordering is made total by appending each source's key (`position` for events, `id` for read models, the grouping keys after `GROUP BY`), so pagination is stable. | +| G-7 | Join conditions are conjunctions of **equalities between columns**. At least one side of each equality must be an **indexed key**: read-model `id` or a `[Queryable]` field; event `id`, `stream`, `aggregatekey`, `sfcorrelationid`, `sfcausationid`, or a `[Queryable]` data field. Otherwise SFQ0405, unless `allow_scan` is given with its permission. | +| G-8 | Joining two `events` sources requires both to be bounded under the SFQ0401 rules (§7.3), otherwise SFQ0406. | +| G-9 | The binder adds `tenant` equality between every joined pair. Join keys can't be personal data (SFQ0301). Every source must belong to this service (Q-B1). | +| G-10 | In multi-source queries, columns are referenced as `alias.field`. An unqualified name that is ambiguous gives SFQ0205. | +| G-11 | Every non-aggregated output expression must appear in the grouping keys (SFQ0206). | +| G-12 | Subqueries: only in `WHERE`, as `IN`/`EXISTS`; depth 1; at most 2 per query; may reference outer columns only through equality. No joins, grouping or ordering inside. | + +## 5. Sources and their attributes + +### 5.1 `events` — the global log + +| Attribute | Type | Meaning | Indexed | +|-----------|------|---------|---------| +| `id` | uuid | Event id | ✔ | +| `type` | string | Logical type, without version | ✔ (with `time`) | +| `typeversion` | integer | Schema version | — | +| `source` | string | Producing service | — | +| `subject`, `stream` | string | Stream id (aliases) | ✔ | +| `aggregatekey` | string | The aggregate-id segment of the stream (join key to read models keyed by aggregate id) | ✔ (via `stream`) | +| `version` | integer | Stream version | ✔ (with `stream`) | +| `position` | position | Global commit-ordered position (opaque, comparable) | ✔ | +| `time` | timestamp | Decision time (`ctx.Now`), also stored as `created_at` | ✔ (with `type`) | +| `sfcorrelationid`, `sfcausationid` | uuid | Correlation and causation | ✔ | +| `tenant`, `sftenant` | string | Tenant (implicitly filtered, §8) | ✔ (leading key) | +| `tags` | string[] | DCB tags | ✔ (GIN) | +| `data` | object | Payload, typed only after `of` narrows the types (§5.4) | `[Queryable]` fields | + +The attribute names deliberately equal **CloudEvents attribute names**. A CESQL filter written for a subscription, such as `type LIKE 'bank.account.%' AND sfcorrelationid = '…'`, runs unchanged as an SFQL `where`. + +Default columns are `position, stream, version, type, typeversion, time, data`. + +### 5.2 `stream ""` + +The events of one stream in version order, with the same attributes as `events`. It is always read at **latest** consistency, which is safe because per-stream order is guaranteed (doc 05 §5.3). + +### 5.3 `readmodel ""` + +The documents of a projection collection, resolved through `collection_aliases` (doc 06 §6). Attributes are the document's schema fields plus `id`, `version` and `updatedAt`. Fields marked `[Queryable]` on the document type get expression indexes. + +### 5.4 Typing of `data` + +| Situation | Behaviour | +|-----------|-----------| +| `events` without `of` | `data` is **opaque**. Only `exists data.x` and `project data` are allowed. Referencing `data.x` in other positions is compile error SFQ0201. This forces narrowing, which is both typed and index-friendly. | +| `events of "t1", "t2"` | `data.x` must exist in at least one listed type, with compatible types (SFQ0202 otherwise). Rows of types without `x` evaluate `data.x` as **missing** (§5.5). | +| Several versions of one type | The binder rewrites `data.x` per version using `[RenamedFrom]`. A field absent from a version is *missing* for rows of that version. | +| `events of "t" version N` | Restricts to one version. Fields are typed exactly from that version's schema. | +| `… upcast` | Rows are fetched with their envelope predicates in SQL, **upcast in process** to the latest version, and their data predicates evaluated in memory. This is correct for structural changes (splits and merges) but costs more, and is flagged by the cost guard (§7). | + +### 5.5 Null and missing semantics (CESQL-aligned) + +- A *missing* field or attribute in a predicate makes that comparison **false**. That matches CESQL, where an absent attribute produces an evaluation error and the expression yields false. `exists data.x` and `x is null` test for it explicitly. +- `is null` is true for missing fields and for explicit JSON `null`. +- Aggregates ignore missing and null values (`count()` counts rows; `count(x)` counts non-null values). +- Type errors that can be detected statically (string compared with number) are **compile errors**. Over opaque or dynamic values, CESQL's implicit casting rules apply. + +### 5.6 `aggregate "" id @id [as of version|time …]` — temporal state + +This source returns **one row**: the aggregate's state, folded in process with its generated `Evolve` from events up to the given version or time (time means `time <=` the bound). It is strongly consistent and reuses snapshots where `snapshot.version ≤ bound`. Columns are the state record's properties. It answers "what did the account look like at month end?" without building a projection. + +### 5.7 `schema [of ""]` + +Catalog introspection. It lists types, versions and fields with their types and attributes (queryable, PII, tags, renamed-from). The CLI uses it for autocompletion. + +### 5.8 Source naming in the SQL syntax + +| Pipeline syntax | SQL syntax | +|-----------------|------------| +| `readmodel "account-summary"` | `readmodel."account-summary"` | +| `events of "bank.account.deposited"` | `events."bank.account.deposited"` (all versions; filter `typeversion` to restrict) | +| `events` | `events` | +| `stream @s` | `stream(@s)` | +| `aggregate … as of …`, `schema` | Pipeline only. Catalog discovery over HTTP is `GET /query/schema` (§9.1) | + +## 6. Consistency semantics + +| Source | Default | Options | +|--------|---------|---------| +| `events` | `horizon`: only events below the safe horizon (doc 05 §5). Results are **monotonic**: a page never later gains earlier rows, so continuation tokens are stable. | `latest`: also includes committed events above the horizon. Fresher, but not monotonic across pages. | +| `stream` | `latest` | — | +| `readmodel` | `eventual`: whatever the projection has applied | `at_least(@token)`: wait until the projection's checkpoint for the token's partition ≥ the token's position, or until `timeout`. Then either fail (`ConsistencyTimeout`) or return with `stale = true` (`on_timeout = 'stale'`). | +| `aggregate … as of` | Strong | — | + +**Consistency tokens.** `CommandResult` carries a `ConsistencyToken` (position, bucket, tenant), serialisable as an opaque string. In HTTP, return it in a header, for example `SourceFlow-Consistency`. A client that just wrote can then query its own write: + +```text +from readmodel "account-summary" | where id = @id +options (consistency = at_least(@token), timeout = 2s) +``` + +Inline projections satisfy any token immediately. With a read replica, the wait checks the **replica's** checkpoint rows. They replicate with the data, so the guarantee holds across replication lag. + +**Joins and consistency.** Each joined source keeps its own consistency: `events` at `horizon` (or `latest`), read models at `eventual` (or `at_least`). `at_least(@token)` waits until **every** read model in the query has passed the token. The response's `consistency.sources[]` reports the level applied to each source. Joining events with a read model that lags can show events whose projection hasn't caught up yet; use `at_least` when that matters. + +## 7. Execution, safety and performance + +### 7.1 Pipeline + +```text +request ─► Request guard (size, characters, limits, rate limit; §9.2) +text ─► Lexer ─► Parser (pipeline or SQL syntax; recursive descent, allow-list grammar) ─► AST + ─► Binder (catalog: names, types, version rewrites, aliases) + ─► Policy (tenant predicate, PII rules, permissions, cost guard) + ─► Planner (push down to SQL vs evaluate in memory: upcast, PII projection, temporal fold) + ─► Compiler (PostgreSQL | SQL Server | in-memory interpreter), parameterised + ─► Executor (read-only connection, statement timeout, streaming reader) + ─► Post-processor (decrypt or mask PII, upcast, shape) ─► IAsyncEnumerable +``` + +Plans are cached by `(normalised text hash, catalog fingerprint, provider)`. The parser has no dependencies and is fuzzed (doc 10 §7). + +> **As built (WP-C.12, CR-21, CR-22, CR-23).** +> - **One fallback rule.** On a store with a SQL engine, that engine runs every `events`, `stream` and `readmodel` query. A construct it can't express is refused with SFQ0410; it isn't run in the interpreter over the whole log. Only what no SQL engine can run (aggregate folds, `schema` rows: `BoundQuery.RequiresInterpreter`) goes to the interpreter. There it is time-boxed to the engine's `QueryTimeout` (`TimeoutException`, HTTP 504) and reads at most `QueryPolicySettings.MaxInterpretedRows` source rows (SFQ0407). PostgreSQL and SQL Server decide `CanExecute` the same way: `RequiresInterpreter`, then a compile probe. A store without an engine (in-memory) runs everything in the interpreter, bounded by `InterpreterTimeout`. +> - **Deviation.** The plan also pushed tenant, type and time filters down to the interpreter's log read. Since a SQL store no longer interprets event queries, the log read stays as it is: only the in-memory store, which has no engine, reads it. +> - **SQL Server text.** `LIKE` has `ESCAPE N'\'`, so `\%`, `\_` and `\\` mean what they mean in the interpreter and PostgreSQL, and `[` is escaped. Text `=`, `<>`, `IN`, join keys, `GROUP BY` and `DISTINCT` compare the byte length too, so T-SQL's trailing-space padding doesn't make `'a'` equal `'a '`. The order of two values that differ only in trailing spaces is still T-SQL's. +> - **Least privilege.** PostgreSQL queries run on `QueryConnectionString` (default `ConnectionString`), in a read-only transaction with the statement timeout. `db script --query-role ` prints the SELECT-only grants. SQL Server queries always use `ApplicationIntent=ReadOnly`: a `QueryConnectionString` without it is refused, and without one the read-intent form of `ConnectionString` is used. `SqlServerSchemaMigrator.QueryGrantsScript` grants SELECT and denies writes. A snapshot transaction is not used: it needs `ALLOW_SNAPSHOT_ISOLATION`, a database setting the migrations don't change. + +### 7.2 Indexes that queries can rely on + +| Index | Supports | +|-------|----------| +| `events (tenant_id, event_type, created_at)` | `of` + time ranges | +| `events (tenant_id, stream_id, stream_version)` (unique) | `stream`, `subject` | +| `events ((metadata->>'correlationId'))` and the causation index | Tracing queries | +| `events USING gin (tags)` | `has_tag` | +| **Generated** partial expression indexes, one per `[Queryable]` event field: `CREATE INDEX … ON events (tenant_id, ((data->>'customerId')::uuid)) WHERE event_type = 'bank.account.opened'` (SQL Server: persisted computed column + filtered index) | Typed `data` predicates | +| Generated expression indexes on `documents` for `[Queryable]` read-model fields | `readmodel` predicates | + +`dotnet sourceflow db index sync` produces or applies these indexes from the catalog, so indexes follow the schema and are never hand-written. + +### 7.3 Cost guard (enforced at policy time) + +| Rule | Error if violated | +|------|-------------------| +| An `events` query must be bounded by at least one of: `of` + a time range ≤ `MaxTimeRange` (default 31 days); `stream`; correlation or causation id; `has_tag`; a position range; a `[Queryable]` equality predicate | SFQ0401 *unbounded scan*. It may be overridden with `options (allow_scan = true)` plus the `sourceflow.query.scan` permission | +| A `data` predicate on a field that isn't `[Queryable]` must be combined with a bounding predicate | SFQ0402 | +| `upcast` queries are limited to `MaxUpcastRows` (default 50,000) examined | SFQ0403 | +| More joins than `MaxJoins` (default 3, cap 5), or subqueries beyond G-12 | SFQ0404 | +| A join condition that isn't an equality on an indexed key on at least one side (G-7) | SFQ0405 (override: `allow_scan` + permission) | +| A join of two `events` sources without bounds on both (G-8) | SFQ0406 | +| Estimated plan cost above `MaxEstimatedCost` (opt-in: PostgreSQL `EXPLAIN (FORMAT JSON)` total cost; SQL Server estimated subtree cost) | SFQ0407 | +| More than `MaxGroups` result groups (default 10,000) | SFQ0408 (at run time) | +| `OFFSET`/`skip` on a query with an `events` or `stream` source, or above `MaxOffset` | SFQ0409 | +| Request limits exceeded (§9.4) | SFQ0103 | +| Statement timeout (`QueryTimeout`, default 5 s, cap 30 s) | `QueryTimeout` | + +`ExplainAsync` (and `dotnet sourceflow query --explain`) shows the bound plan, the generated SQL with parameter placeholders, the indexes used, and the cost-guard decision. + +### 7.4 Pagination + +Results are ordered and keyset-paginated. The continuation token is opaque and contains the last sort key (always ending in the G-6 tiebreak keys), the query hash and the catalog fingerprint. It is rejected if the query text or the schema changed. `OFFSET`/`skip` is accepted **only when every source is a read model**, up to `MaxOffset` (default 10,000). Queries touching the moving event log must use continuation tokens (SFQ0409). + +## 8. Security semantics + +| Concern | Semantics | +|---------|-----------| +| **Tenancy** ([ADR-022](../ADRs/ADR-022-conjoined-multi-tenancy-with-row-level-security.md)) | The binder injects `tenant = ` into every source. `options (tenants = 'all')` needs the `sourceflow.query.cross-tenant` permission. PostgreSQL RLS enforces it again at the database. | +| **Archived streams** ([doc 05 §9](05-Event-Store-and-Persistence.md#9-retention-archiving-and-growth)) | `from events` leaves out events of archived streams. `options (include_archived = true)` includes them and needs no permission. `from stream` and `from aggregate` always read archived streams. | +| **Personal data** (doc 10 §4) | `[PersonalData]` fields can't appear in `where`, `order by`, `summarize` or `lookup` keys (SFQ0301), because they are ciphertext. In `project` they are decrypted in process **only** with the `sourceflow.query.pii` permission. Otherwise they come back redacted. Erased subjects come back as `"[erased]"`. | +| **Permissions** | `sourceflow.query.events`, `.readmodels`, `.aggregates`, `.schema`, `.pii`, `.scan`, `.cross-tenant`, `.adhoc` (ad-hoc API queries), `.validate`, `.explain` (reveals physical schema: operators only). They are evaluated through `IAuthorizationService` policies against the caller's `ClaimsPrincipal`, or the service identity for in-process calls. | +| **Injection** (SQL and script) | Defended in layers, by construction: §9.3 rules I-1…I-8 and S-1…S-6. | +| **Audit** | Every executed query records a span and, optionally, an audit log entry (query hash, principal, tenant, row count). Literal values are logged only if `LogQueryParameters` is on, and are redacted. | + +## 9. Query API (one per service) and other surfaces + +### 9.1 HTTP endpoints + +Every service maps the query API in its host (Q-R6). Mapping **fails closed**: startup fails if no authorization policy is attached. + +```csharp +app.MapSourceFlowQueryApi("/query") // SourceFlow.AspNetCore + .RequireAuthorization("sourceflow-query"); // required; otherwise startup fails (SFQ0504) +app.MapDomainQueries(); // named, versioned contracts (Q-B4) +``` + +| Method and path | Purpose | Permission | +|-----------------|---------|------------| +| `POST /query` | Execute an ad-hoc query in the pipeline (`"language": "sfql"`) or SQL (`"language": "sql"`) syntax | `sourceflow.query.adhoc` + source permissions (§8) | +| `POST /query/validate` | Parse, bind and policy-check **without executing**. Returns diagnostics with positions | `sourceflow.query.validate` | +| `POST /query/explain` | Bound plan, parameterised SQL (placeholders only, no values) and cost estimate | `sourceflow.query.explain` | +| `GET /query/schema` | The service's queryable sources and fields visible to the caller (PII and `[Queryable]` flagged) | `sourceflow.query.schema` | +| `GET /queries`, `GET /queries/{name}/v{n}` | Named domain queries (Q-B4) | Per-query policy | + +The endpoints are described in the service's OpenAPI 3.1 document (ASP.NET Core built-in OpenAPI), including request and response schemas and the error model. + +**Request** + +```json +POST /query +Content-Type: application/json + +{ + "language": "sql", + "query": "SELECT a.id, a.balance, c.segment FROM readmodel.\"account-summary\" a JOIN readmodel.\"customer-profile\" c ON c.id = a.customerId WHERE a.status = @status AND a.balance < @below ORDER BY a.balance LIMIT 50", + "parameters": { "status": "Open", "below": 0 }, + "options": { "consistency": "at_least", "token": "73421", "timeout": "PT2S", "pageSize": 50 }, + "continuation": null +} +``` + +**Response** (`200`, `application/json`; or `application/x-ndjson`, one row per line plus a trailer line carrying `continuation` and `consistency`): + +```json +{ + "columns": [ { "name": "id", "type": "string" }, { "name": "balance", "type": "decimal" }, { "name": "segment", "type": "string" } ], + "rows": [ [ "0193a8…", "-12.50", "retail" ] ], + "continuation": "eyJ…", + "consistency": { "sources": [ { "source": "readmodel.account-summary", "level": "at_least", "stale": false } ] }, + "queryHash": "sha256:9f2c…" +} +``` + +Decimals are returned as strings (exact). Timestamps use RFC 3339 UTC. + +**Errors** are RFC 9457 `application/problem+json`, with diagnostics and positions but **never** an echo of the caller's text (§9.3 S-3): + +```json +{ + "type": "https://sourceflow.net/problems/query-invalid", + "title": "The query is not valid.", + "status": 400, + "diagnostics": [ + { "code": "SFQ0102", "message": "Statement type 'DELETE' is not supported: the query API is read-only.", "line": 1, "column": 1, "length": 6 } + ] +} +``` + +| Status | When | +|--------|------| +| 400 | Syntax, bind or policy diagnostics (SFQ01xx–04xx) | +| 403 | Missing permission (SFQ0501) | +| 409 | Continuation token invalid for this query or schema (SFQ0601) | +| 413 | Request or query too large (SFQ0103) | +| 415 | Content type other than `application/json` | +| 429 | Rate or concurrency limit (SFQ0502/0503), with `Retry-After` | +| 503 | Consistency wait timed out with `on_timeout = 'fail'` (SFQ0602), with `Retry-After` | +| 504 | Statement timeout | + +### 9.2 Request processing + +```text +HTTP request + ├─ Transport guard body ≤ 64 KB · application/json only · JSON depth ≤ 16 · authenticated · rate + concurrency limits + ├─ Text guard valid UTF-8 · NFC normalisation · reject NUL/control chars (except TAB, LF, CR), bidi overrides + │ and isolates (U+202A–U+202E, U+2066–U+2069), zero-width chars outside string literals + │ · length ≤ 16 KB · tokens ≤ 4,000 · nesting depth ≤ 32 (SFQ0103/0104) + ├─ Parse allow-list grammar (§4); one statement; precise error positions (SFQ0101/0102) + ├─ Bind names resolved only against this service's catalog; parameters typed (SFQ02xx) + ├─ Policy tenant · PII · permissions · cost guard · limits (SFQ03xx–05xx) + │ └─ /query/validate stops here and returns diagnostics + ├─ Plan + compile parameterised SQL from catalog identifiers and placeholders only (I-3) + ├─ Execute read-only connection and transaction · statement timeout · RLS tenant · streaming + └─ Serialise System.Text.Json (escaping on) · safe headers (S-2) +``` + +### 9.3 Injection defence + +**SQL injection.** The query API is **not a SQL pass-through**. + +| Rule | Defence | +|------|---------| +| I-1 | **No pass-through.** Caller text is never sent to the database, in whole or in part. It is parsed into an AST by SourceFlow's own grammar, and SQL is generated from the AST. | +| I-2 | **Allow-list grammar.** Only the read-only constructs in §4.3 have productions. `INSERT`/`UPDATE`/`DELETE`/`MERGE`, DDL, `EXEC`/`CALL`, `COPY`, `SET`, `GRANT`, transaction control, `;`, comments (`--`, `/* */`), `INTO`, `UNION` and dynamic SQL are syntax errors (SFQ0102) that name the construct. | +| I-3 | **Only safe tokens reach SQL.** Generated SQL contains only fixed templates; identifiers derived from the **catalog** (table, column and JSON-key names from the service's own schemas, quoted by the provider's quoting function); and **parameter placeholders**. **Every value that came from the request** becomes a typed `DbParameter`: literals in the text, parameters, type and collection names, durations, `LIKE` patterns, `IN` lists, `LIMIT`/`OFFSET`. A property test checks that the SQL text never contains any request literal (QRY-60). | +| I-4 | **Catalog-only name resolution.** Unknown names are bind errors (SFQ0202/0204). `pg_catalog`, `information_schema`, `sys.*`, SourceFlow's internal tables (`outbox`, `inbox`, `data_keys`) and other services' data are unreachable by construction. | +| I-5 | **Function allow-list.** CESQL built-ins plus the SFQL functions in §4.1. No database function can be called directly. | +| I-6 | **Typed parameters.** JSON parameter values are converted to the type the binder expects (SFQ0203 on mismatch). A string parameter is always one value and is never re-parsed as query text. | +| I-7 | **Least privilege (defence in depth).** A read-only role with `SELECT` on query tables only (Q-R2); a read-only transaction (`SET TRANSACTION READ ONLY` on PostgreSQL; `ApplicationIntent=ReadOnly` + snapshot on SQL Server); `statement_timeout`; RLS tenant isolation (ADR-022). Even a compiler defect can't write data or cross tenants. | +| I-8 | **Abuse (SQL denial of service).** Limits (§9.4), the cost guard (§7.3), optional `EXPLAIN` cost ceiling (SFQ0407), rate and concurrency limits. `LIKE` patterns are parameters; the in-memory evaluator uses a linear-time matcher (no backtracking regex, so no ReDoS). | + +**Script injection.** + +| Rule | Defence | +|------|---------| +| S-1 | **No dynamic code evaluation.** Query text, CESQL expressions and parameters are interpreted by a tree-walking evaluator or compiled to parameterised SQL. They are never passed to `eval`, Roslyn scripting, `Expression.Compile`, or database-side scripting (no `EXECUTE`/`sp_executesql` with caller text, no `DO` blocks). | +| S-2 | **Non-executable responses.** Only `application/json`, `application/x-ndjson` or `application/problem+json`, with `X-Content-Type-Options: nosniff`, `Content-Security-Policy: default-src 'none'; frame-ancestors 'none'` and `Cache-Control: no-store`. Never HTML. String values are encoded by System.Text.Json's default encoder, which escapes `<`, `>`, `&`, `'` and `"`, so stored markup such as `" }`, or stored data containing it | Treated as data. Echoed values are JSON-escaped (`", 55m), ("Linus", 300m) }) + { + (await CommandAsync(_client, holder, balance)).EnsureSuccessStatusCode(); + } + + await EventuallyAsync(async () => (await RowsAsync(Summary + " | summarize n = count()"))[0][0].GetInt64() == 4, "four summaries"); + } + + public async ValueTask DisposeAsync() + { + _client.Dispose(); + await _app.DisposeAsync(); + } + + [Fact] + [Trait("Id", "QRY-53")] + [Trait("Covers", "doc 14 9.1;doc 14 5.10")] + public async Task BothSyntaxes_OverHttp_GiveTheSameRows_FromThePostgreSqlEngine() + { + JsonElement[] pipeline = await RowsAsync(Summary + " | where balance >= 100 | project balance, status | order by balance desc"); + JsonElement[] sql = await RowsAsync("SELECT balance, status FROM readmodel.\"account-summary\" WHERE balance >= 100 ORDER BY balance DESC", language: "sql"); + JsonDocument plan = await JsonAsync(await PostAsync("/query/explain", Body(Summary + " | where balance >= 100 | project balance"))); + + pipeline.Select(r => r.GetRawText()).ShouldBe(sql.Select(r => r.GetRawText())); + pipeline.Select(r => decimal.Parse(r[0].ToString(), CultureInfo.InvariantCulture)).ShouldBe([900m, 300m]); // decimals travel as strings + plan.RootElement.GetProperty("engine").GetString().ShouldBe("postgresql"); + } + + [Fact] + [Trait("Id", "QRY-54")] + [Trait("Covers", "doc 14 9.1")] + public async Task Validate_DoesNotExecute() + { + // The documents table's scan counters prove the measurement first: a real query moves them. + long before = await ScansAsync(); + await RowsAsync(Summary + " | project balance"); + await EventuallyAsync(async () => await ScansAsync() > before, "a query scans documents"); + + long quiet = await StableAsync(ScansAsync); + for (int i = 0; i < 5; i++) + { + HttpResponseMessage validated = await PostAsync("/query/validate", Body(Summary + " | where balance > 10 | project balance")); + validated.StatusCode.ShouldBe(HttpStatusCode.OK); + } + + await Task.Delay(TimeSpan.FromMilliseconds(1500), TimeProvider.System, Ct); // statistics are flushed within a second + (await StableAsync(ScansAsync)).ShouldBe(quiet, "validate parses, binds and checks policy without touching the database"); + } + + [Fact] + [Trait("Id", "QRY-55")] + [Trait("Covers", "ADR-026;doc 14 9.1")] + public async Task Explain_ShowsPlaceholdersOnly() + { + const string marker = "zz-literal-7731"; + HttpResponseMessage response = await PostAsync("/query/explain", Body(Summary + $" | where status = 1 and balance > 12.5 and holder = '{marker}' | project balance")); + JsonDocument plan = await JsonAsync(response); + string statement = plan.RootElement.GetProperty("statement").GetString()!; + + response.StatusCode.ShouldBe(HttpStatusCode.OK); + statement.ShouldContain("$1"); + statement.ShouldNotContain(marker); + statement.ShouldNotContain("12.5"); + } + + [Fact] + [Trait("Id", "QRY-56")] + [Trait("Covers", "doc 14 6")] + public async Task ReadYourWrites_TokenFromACommand_IsHonouredByAQuery() + { + // An API-only node: it takes commands but runs no projections, so the read model lags until a worker starts. + string schema = PostgreSqlServer.NewSchema("ryw"); + (WebApplication api, HttpClient client) = await StartAsync(SourceFlowRoles.Api, schema); + await using (api) + { + using (client) + { + HttpResponseMessage opened = await CommandAsync(client, "Barbara", 777m); + opened.EnsureSuccessStatusCode(); + string token = opened.Headers.GetValues(SourceFlowHeaders.Consistency).Single(); + string waiting = Body(Summary + " | where balance = 777 | project balance options (consistency = at_least(@t), timeout = 1s, on_timeout = 'stale')", parameters: new Dictionary { ["t"] = token }); + + JsonDocument stale = await JsonAsync(await PostAsync("/query", waiting, client)); + stale.RootElement.GetProperty("rows").GetArrayLength().ShouldBe(0); + stale.RootElement.GetProperty("consistency").GetProperty("sources")[0].GetProperty("stale").GetBoolean().ShouldBeTrue(); + + // A worker node starts and runs the projection: the same token is then satisfied, and the row is there. + (WebApplication worker, HttpClient workerClient) = await StartAsync(SourceFlowRoles.All, schema); + await using WebApplication _ = worker; + workerClient.Dispose(); + JsonDocument fresh = await JsonAsync(await PostAsync("/query", waiting.Replace("timeout = 1s", "timeout = 10s", StringComparison.Ordinal), client)); + fresh.RootElement.GetProperty("rows").GetArrayLength().ShouldBe(1); + fresh.RootElement.GetProperty("consistency").GetProperty("sources")[0].GetProperty("stale").GetBoolean().ShouldBeFalse(); + } + } + } + + [Fact] + [Trait("Id", "QRY-57")] + [Trait("Id", "QRY-58")] + [Trait("Id", "QRY-59")] + [Trait("Covers", "ADR-026;doc 14 12")] + public async Task InjectionCorpus_OverHttp_IsRejectedOrHarmless_WithNoDatabaseErrorAndNoWrite() + { + string[] statements = + [ + "SELECT * FROM readmodel.\"account-summary\"; DROP TABLE documents", + "SELECT * FROM readmodel.\"account-summary\" WHERE holder = 'a' -- ' OR 1=1", + "SELECT * FROM readmodel.\"account-summary\" /* comment */", + "SELECT usename FROM pg_catalog.pg_user", + "SELECT * FROM information_schema.tables", + "UPDATE readmodel.\"account-summary\" SET balance = 0", + "DELETE FROM readmodel.\"account-summary\"", + "SELECT * FROM readmodel.\"account-summary\" UNION SELECT * FROM readmodel.\"account-summary\"", + "SELECT pg_sleep(10)", + "SELECT * FROM readmodel.\"account-summary\" WHERE holder = 'a‮'", + "SELECT * FROM readmodel.\"account-summary\" WHERE holder = 'a\u0000'", + "SELECT balance FROM readmodel.\"аccount-summary\"", // Cyrillic 'а' + "SELECT * FROM \"" + _schema + "\".outbox", + "' OR '1'='1", + "1; COPY documents TO PROGRAM 'id'", + ]; + string[] values = + [ + "Open' OR '1'='1", "'; DROP TABLE documents; --", "\\'; SELECT pg_sleep(5); --", "%' OR 1=1 OR holder LIKE '%", + "Ada' UNION SELECT usename FROM pg_user --", "", "\">", "Аda", + "1 AND 1=CAST((SELECT version()) AS int)", "${jndi:ldap://x/a}", + ]; + (long Inserts, long Updates, long Deletes) writes = await StableAsync(WritesAsync); + var bodies = new List(); + + foreach (string statement in statements) + { + HttpResponseMessage response = await PostAsync("/query", Body(statement, language: "sql")); + string body = await response.Content.ReadAsStringAsync(Ct); + bodies.Add(body); + response.StatusCode.ShouldBe(HttpStatusCode.BadRequest, statement); + string code = JsonDocument.Parse(body).RootElement.GetProperty("code").GetString()!; + int.Parse(code.AsSpan(3, 2), CultureInfo.InvariantCulture).ShouldBeInRange(1, 2, $"{statement}: {code}"); // syntax or bind + } + + foreach (string value in values) + { + var parameters = new Dictionary { ["v"] = value }; + foreach (string query in new[] { Summary + " | where holder = @v or holder like @v | project balance", Summary + " | where holder = @v | project balance" }) + { + HttpResponseMessage response = await PostAsync("/query", Body(query, parameters: parameters)); + string body = await response.Content.ReadAsStringAsync(Ct); + bodies.Add(body); + response.StatusCode.ShouldBe(HttpStatusCode.OK, value); + (value == "" || JsonDocument.Parse(body).RootElement.GetProperty("rows").GetArrayLength() == 0).ShouldBeTrue(value); + } + } + + // Stored markup comes back as data, escaped in JSON and as text in CSV. + HttpResponseMessage stored = await PostAsync("/query", Body(Summary + " | where balance = 55 | project holder")); + bodies.Add(await stored.Content.ReadAsStringAsync(Ct)); + JsonDocument.Parse(bodies[^1]).RootElement.GetProperty("rows")[0][0].GetString().ShouldBe(""); + + bodies.ShouldAllBe(b => !b.Contains(" StartAsync(SourceFlowRoles roles, string? schema = null, string[]? permissions = null) + { + string[] granted = permissions ?? + [ + QueryPermission.Adhoc, QueryPermission.ReadModels, QueryPermission.Events, QueryPermission.Validate, + QueryPermission.Explain, QueryPermission.Schema, QueryPermission.PersonalData, + ]; + WebApplicationBuilder builder = WebApplication.CreateSlimBuilder(); + builder.WebHost.UseTestServer(); + builder.Logging.AddProvider(new ErrorCapture(_errors)); + builder.Services.AddSourceFlow(sf => + { + sf.ServiceName = "accounts"; + sf.Roles = roles; + sf.AddModule(); + sf.Projections(p => p.Add().Async()); + sf.UsePostgreSql(o => + { + o.DataSource = postgreSql.DataSource; + o.Schema = schema ?? _schema; + o.AutoMigrate = true; + }); + sf.UseInMemoryTransport(); + sf.Configure(o => o.PollInterval = TimeSpan.FromMilliseconds(50)); + }); + builder.Services.AddSourceFlowQueryApi(o => + { + o.RequestsPerMinute = 10_000; + o.Permissions = _ => QueryPermissions.Of(granted); + }); + WebApplication app = builder.Build(); + app.MapCommand("/accounts/{accountId}"); + app.MapSourceFlowQueryApi().AllowAnonymous(); + await app.StartAsync(Ct); + return (app, app.GetTestClient()); + } + + private static Task CommandAsync(HttpClient client, string holder, decimal balance) + { + return client.PostAsync($"/accounts/{AccountId.New()}", new StringContent(JsonSerializer.Serialize(new { holder, initialDeposit = balance }), Encoding.UTF8, "application/json"), Ct); + } + + private Task PostAsync(string path, string body, HttpClient? client = null) + { + return (client ?? _client).PostAsync(path, new StringContent(body, Encoding.UTF8, "application/json"), Ct); + } + + private async Task RowsAsync(string query, string? language = null) + { + HttpResponseMessage response = await PostAsync("/query", Body(query, language: language)); + string body = await response.Content.ReadAsStringAsync(Ct); + response.StatusCode.ShouldBe(HttpStatusCode.OK, body); + return [.. JsonDocument.Parse(body).RootElement.GetProperty("rows").EnumerateArray()]; + } + + private static async Task JsonAsync(HttpResponseMessage response) + { + return JsonDocument.Parse(await response.Content.ReadAsStringAsync(Ct)); + } + + private static string Body(string query, string? language = null, IReadOnlyDictionary? parameters = null) + { + var body = new Dictionary { ["query"] = query }; + if (language is not null) + { + body["language"] = language; + } + + if (parameters is not null) + { + body["parameters"] = parameters; + } + + return JsonSerializer.Serialize(body); + } + + private async Task ScansAsync() + { + await using NpgsqlCommand command = postgreSql.DataSource.CreateCommand( + "SELECT pg_stat_clear_snapshot(); SELECT COALESCE(seq_scan, 0) + COALESCE(idx_scan, 0) FROM pg_stat_user_tables WHERE schemaname = @s AND relname = 'documents'"); + command.Parameters.Add(new NpgsqlParameter("s", _schema)); + await using NpgsqlDataReader reader = await command.ExecuteReaderAsync(Ct); + await reader.NextResultAsync(Ct); + await reader.ReadAsync(Ct); + return reader.GetInt64(0); + } + + private async Task<(long, long, long)> WritesAsync() + { + await using NpgsqlCommand command = postgreSql.DataSource.CreateCommand( + "SELECT pg_stat_clear_snapshot(); SELECT sum(n_tup_ins), sum(n_tup_upd), sum(n_tup_del) FROM pg_stat_user_tables WHERE schemaname = @s AND relname IN ('events', 'streams', 'documents')"); + command.Parameters.Add(new NpgsqlParameter("s", _schema)); + await using NpgsqlDataReader reader = await command.ExecuteReaderAsync(Ct); + await reader.NextResultAsync(Ct); + await reader.ReadAsync(Ct); + return (reader.GetInt64(0), reader.GetInt64(1), reader.GetInt64(2)); + } + + // Statistics reach pg_stat_user_tables up to a second after the transaction: read until two readings agree. + private static async Task StableAsync(Func> read) + { + T last = await read(); + for (int i = 0; i < 20; i++) + { + await Task.Delay(TimeSpan.FromMilliseconds(1200), TimeProvider.System, Ct); + T next = await read(); + if (EqualityComparer.Default.Equals(next, last)) + { + return next; + } + + last = next; + } + + return last; + } + + private static async Task EventuallyAsync(Func> condition, string what) + { + DateTimeOffset deadline = TimeProvider.System.GetUtcNow() + TimeSpan.FromSeconds(30); + while (!await condition()) + { + if (TimeProvider.System.GetUtcNow() > deadline) + { + throw new TimeoutException($"Timed out waiting for: {what}."); + } + + await Task.Delay(TimeSpan.FromMilliseconds(100), TimeProvider.System, Ct); + } + } + + // Records error logs from the database driver and the query API: the corpus must produce none. + private sealed class ErrorCapture(List errors) : ILoggerProvider + { + public ILogger CreateLogger(string categoryName) + { + return new Logger(categoryName, errors); + } + + public void Dispose() + { + } + + private sealed class Logger(string category, List errors) : ILogger + { + public IDisposable? BeginScope(TState state) + where TState : notnull + { + return null; + } + + public bool IsEnabled(LogLevel logLevel) + { + return logLevel >= LogLevel.Error; + } + + public void Log(LogLevel logLevel, EventId eventId, TState state, Exception? exception, Func formatter) + { + if (logLevel >= LogLevel.Error && (exception is PostgresException || category.Contains("Query", StringComparison.Ordinal) || category.StartsWith("Npgsql", StringComparison.Ordinal))) + { + lock (errors) + { + errors.Add($"{category}: {formatter(state, exception)}"); + } + } + } + } + } +} diff --git a/tests/EndToEnd/SourceFlow.EndToEnd.Tests/RebuildScenarios.cs b/tests/EndToEnd/SourceFlow.EndToEnd.Tests/RebuildScenarios.cs new file mode 100644 index 00000000..787bd7cc --- /dev/null +++ b/tests/EndToEnd/SourceFlow.EndToEnd.Tests/RebuildScenarios.cs @@ -0,0 +1,151 @@ +using System.Collections.Concurrent; +using System.Text.Json.Serialization; +using Bank.Accounts; +using Bank.Contracts; +using Microsoft.Extensions.DependencyInjection; +using SourceFlow.Hosting; +using SourceFlow.Messaging; +using SourceFlow.Query; +using SourceFlow.Storage; +using SourceFlow.Storage.InMemory; +using SourceFlow.Testing; + +namespace SourceFlow.EndToEnd.Tests; + +/// Version 2 of the account summary: it also counts the movements (a new field means a rebuild, doc 06 §6). +public sealed record AccountSummaryV2(AccountId Id, string Holder, decimal Balance, [property: Queryable] AccountStatus Status, int Movements, long Version); + +/// The next version of the Bank's account-summary projection. +[Projection("account-summary", Version = 2)] +public sealed partial class AccountSummaryV2Projection : IDocumentProjection +{ + private static AccountSummaryV2 When(AccountOpened e, AccountSummaryV2? current, EventContext ctx) + { + return new AccountSummaryV2(e.AccountId, e.Holder, e.InitialDeposit, AccountStatus.Open, 0, ctx.StreamVersion.Value); + } + + private static AccountSummaryV2? When(MoneyDeposited e, AccountSummaryV2? current, EventContext ctx) + { + return current is null ? null : current with { Balance = e.BalanceAfter, Movements = current.Movements + 1, Version = ctx.StreamVersion.Value }; + } + + private static AccountSummaryV2? When(MoneyWithdrawn e, AccountSummaryV2? current, EventContext ctx) + { + return current is null ? null : current with { Balance = e.BalanceAfter, Movements = current.Movements + 1, Version = ctx.StreamVersion.Value }; + } + + private static AccountSummaryV2? When(AccountClosed e, AccountSummaryV2? current, EventContext ctx) + { + return current is null ? null : current with { Status = AccountStatus.Closed, Version = ctx.StreamVersion.Value }; + } +} + +/// A side effect per opened account; a rebuild must never run it again (GAP-06). +public sealed class WelcomeCounter : IEventHandler +{ + public static ConcurrentDictionary Sent { get; } = new(); + + public ValueTask HandleAsync(AccountOpened @event, EventContext context, CancellationToken cancellationToken) + { + ArgumentNullException.ThrowIfNull(@event); + Sent.AddOrUpdate(@event.AccountId, 1, (_, n) => n + 1); + return ValueTask.CompletedTask; + } +} + +/// The rebuild scenario's module: version 2 of the summary and the side-effect handler. +[SourceFlowModule(typeof(RebuildJsonContext))] +public sealed partial class RebuildTestModule; + +[JsonSerializable(typeof(AccountSummaryV2))] +[JsonSourceGenerationOptions(PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase)] +public sealed partial class RebuildJsonContext : JsonSerializerContext; + +/// E2E-08 and UT-SUB-28: a blue/green rebuild over the Bank sample, in memory (plan 06 §4). +[Trait("Category", "E2E")] +public sealed class RebuildScenarios +{ + private static CancellationToken Ct => TestContext.Current.CancellationToken; + + [Fact] + [Trait("Id", "E2E-08")] + [Trait("Id", "UT-SUB-28")] + [Trait("Covers", "ADR-016;ADR-032;GAP-06;doc 06 6")] + public async Task VersionBump_TheNewGenerationCatchesUp_TheAliasSwitches_AndNoSideEffectRunsAgain() + { + var store = new InMemoryStore(); + AccountId ada = AccountId.New(); + AccountId bob = AccountId.New(); + await using (SourceFlowTestHost v1 = await StartAsync(store, version: 1)) + { + await v1.SendAsync(new OpenAccount(ada, "Ada", 10m), cancellationToken: Ct); + await v1.SendAsync(new Deposit(ada, 5m), cancellationToken: Ct); + await v1.SendAsync(new Withdraw(ada, 3m), cancellationToken: Ct); + await v1.SendAsync(new OpenAccount(bob, "Bob", 1m), cancellationToken: Ct); + await v1.WaitForIdleAsync(); + await AliasAsync(store, v1, "account-summary@1"); + } + + GlobalPosition handlerCheckpoint = await store.GetAsync("handler:WelcomeCounter", 0, Ct); + int outbox = await store.CountAsync(Ct); + + // Deploy version 2: it replays the log into account-summary@2 and takes over reads once caught up. + await using SourceFlowTestHost v2 = await StartAsync(store, version: 2); + await v2.WaitForIdleAsync(); + await AliasAsync(store, v2, "account-summary@2"); + + AccountSummaryV2 summary = (await v2.DocumentAsync(ada.ToStreamSegment())).ShouldNotBeNull(); + summary.ShouldBe(new AccountSummaryV2(ada, "Ada", 12m, AccountStatus.Open, 2, 3)); + IReadOnlyList low = await v2.Services.GetRequiredService().ExecuteAsync(new LowBalanceAccounts(5m), cancellationToken: Ct); + low.ShouldHaveSingleItem().AccountId.ShouldBe(bob); // domain queries read the new generation through the alias + + // No side effects: the handler ran once per account and its checkpoint did not move; nothing was sent. + WelcomeCounter.Sent[ada].ShouldBe(1); + WelcomeCounter.Sent[bob].ShouldBe(1); + (await store.GetAsync("handler:WelcomeCounter", 0, Ct)).ShouldBe(handlerCheckpoint); + (await store.CountAsync(Ct)).ShouldBe(outbox); + CollectionAlias alias = (await store.ListAliasesAsync(Ct)).ShouldHaveSingleItem(); + alias.Previous.ShouldBe("account-summary@1"); + } + + private static Task StartAsync(InMemoryStore store, int version) + { + return SourceFlowTestHost.StartAsync(sf => + { + sf.ServiceName = "accounts"; + sf.AddModule(); + sf.AddModule(); + sf.AddModule(); + sf.Projections(p => + { + if (version == 1) + { + p.Remove(); + p.Add().Async(); + } + else + { + p.Remove(); + p.Add().Async(); + } + }); + sf.Configure(o => o.PollInterval = TimeSpan.FromMilliseconds(20)); + }, store: store); + } + + private static async Task AliasAsync(InMemoryStore store, SourceFlowTestHost host, string target) + { + for (int i = 0; i < 300; i++) + { + if ((await store.ListAliasesAsync(Ct)).FirstOrDefault()?.Target == target) + { + return; + } + + await host.WaitForIdleAsync(); + await Task.Delay(TimeSpan.FromMilliseconds(10), TimeProvider.System, Ct); + } + + throw new TimeoutException($"account-summary did not switch to {target}."); + } +} diff --git a/tests/EndToEnd/SourceFlow.EndToEnd.Tests/RelayLatencyScenarios.cs b/tests/EndToEnd/SourceFlow.EndToEnd.Tests/RelayLatencyScenarios.cs new file mode 100644 index 00000000..fb39208f --- /dev/null +++ b/tests/EndToEnd/SourceFlow.EndToEnd.Tests/RelayLatencyScenarios.cs @@ -0,0 +1,103 @@ +using System.Collections.Concurrent; +using Bank.Accounts; +using Microsoft.Extensions.DependencyInjection; +using SourceFlow.Cloud.Tests.Aws; +using SourceFlow.Cloud.Tests.Azure; +using SourceFlow.Cloud.Tests.Gcp; +using SourceFlow.Messaging; +using SourceFlow.Storage.Tests.PostgreSql; +using SourceFlow.Transport; + +namespace SourceFlow.EndToEnd.Tests; + +/// +/// PERF-07 (plan 06 §8, doc 09 §7.1; WP-4.7): outbox relay latency, from the commit that wrote the outbox row to the +/// broker's acknowledgement of the publish, on PostgreSQL with each emulator. The target is p95 ≤ 250 ms. Commands are +/// sent one at a time (latency, not throughput); the clock starts at the event's time, which is set when the command is +/// decided, just before the commit. +/// +[Collection(PostgreSqlCollection.Name)] +[Trait("Category", "Performance")] +[Trait("Id", "PERF-07")] +[Trait("Requires", "Docker")] +public sealed class RelayLatencyScenarios(PostgreSqlServer postgreSql, LocalStackServer localStack, PubSubEmulatorServer pubSub, ServiceBusEmulatorServer serviceBus) +{ + private const int Warmup = 10; + private const int Measured = 100; + + private Servers Servers => new(postgreSql, localStack, pubSub, serviceBus); + + [Fact] + [Trait("Cloud", "Aws")] + [Trait("Requires", "LocalStack")] + public Task OutboxToBrokerAck_Aws() => MeasureAsync(Broker.Aws); + + [Fact] + [Trait("Cloud", "Gcp")] + [Trait("Requires", "PubSubEmulator")] + public Task OutboxToBrokerAck_Gcp() => MeasureAsync(Broker.Gcp); + + [Fact] + [Trait("Cloud", "Azure")] + [Trait("Requires", "ServiceBusEmulator")] + public Task OutboxToBrokerAck_Azure() => MeasureAsync(Broker.Azure); + + private async Task MeasureAsync(Broker broker) + { + var acks = new ConcurrentDictionary(); + await using CrossServiceSystem system = await CrossServiceSystem.StartAsync(Servers, broker, inner => new TimingTransport(inner, acks)); + ICommandSender commands = system.Accounts.Services.GetRequiredService(); + for (int i = 0; i < Warmup + Measured; i++) + { + int before = acks.Count; + (await commands.SendAsync(new OpenAccount(AccountId.New(), "Ada", 1m), null, TestContext.Current.CancellationToken)).Status.ShouldBe(CommandStatus.Accepted); + DateTimeOffset deadline = TimeProvider.System.GetUtcNow() + TimeSpan.FromSeconds(30); + while (acks.Count == before && TimeProvider.System.GetUtcNow() < deadline) + { + await Task.Delay(TimeSpan.FromMilliseconds(2), TimeProvider.System, TestContext.Current.CancellationToken); + } + } + + double[] latencies = [.. acks.Values.Order().ToArray()]; + latencies.Length.ShouldBe(Warmup + Measured, "every integration event was published"); + double[] measured = [.. acks.OrderBy(a => a.Key.Value).Skip(Warmup).Select(a => a.Value).Order()]; + double p50 = measured[(int)Math.Ceiling(0.50 * measured.Length) - 1]; + double p95 = measured[(int)Math.Ceiling(0.95 * measured.Length) - 1]; + TestContext.Current.TestOutputHelper?.WriteLine($"PERF-07 {broker}: p50 {p50:F1} ms, p95 {p95:F1} ms, max {measured[^1]:F1} ms over {measured.Length} publishes"); + p95.ShouldBeLessThanOrEqualTo(250, $"PERF-07 {broker}: outbox commit to broker acknowledgement p95 (p50 {p50:F1} ms)"); + } + + // Records, per published message, how long after its creation the broker acknowledged it. + private sealed class TimingTransport(ITransport inner, ConcurrentDictionary acks) : ITransport, IAsyncDisposable + { + public string SystemName => inner.SystemName; + + public TransportCapabilities Capabilities => inner.Capabilities; + + public ValueTask SendAsync(string endpoint, IReadOnlyList messages, CancellationToken cancellationToken) => inner.SendAsync(endpoint, messages, cancellationToken); + + public async ValueTask PublishAsync(string topic, IReadOnlyList messages, CancellationToken cancellationToken) + { + await inner.PublishAsync(topic, messages, cancellationToken); + DateTimeOffset acknowledged = TimeProvider.System.GetUtcNow(); + foreach (MessageEnvelope message in messages) + { + acks.TryAdd(message.MessageId, (acknowledged - message.Time).TotalMilliseconds); + } + } + + public ValueTask CreateReceiverAsync(ReceiverOptions options, CancellationToken cancellationToken) => inner.CreateReceiverAsync(options, cancellationToken); + + public ValueTask CreateDeadLetterReceiverAsync(string endpoint, CancellationToken cancellationToken) => inner.CreateDeadLetterReceiverAsync(endpoint, cancellationToken); + + public ValueTask ProvisionAsync(TransportTopology topology, ProvisioningMode mode, CancellationToken cancellationToken) => inner.ProvisionAsync(topology, mode, cancellationToken); + + public async ValueTask DisposeAsync() + { + if (inner is IAsyncDisposable disposable) + { + await disposable.DisposeAsync(); + } + } + } +} diff --git a/tests/EndToEnd/SourceFlow.EndToEnd.Tests/SchemaEvolutionScenarios.cs b/tests/EndToEnd/SourceFlow.EndToEnd.Tests/SchemaEvolutionScenarios.cs new file mode 100644 index 00000000..0f512b74 --- /dev/null +++ b/tests/EndToEnd/SourceFlow.EndToEnd.Tests/SchemaEvolutionScenarios.cs @@ -0,0 +1,97 @@ +#pragma warning disable SF0001 // the messages are registered by hand below, to model two deployments of one service +using System.Text.Json.Serialization.Metadata; +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.Hosting; +using SourceFlow.Hosting; +using SourceFlow.Storage.PostgreSQL; +using SourceFlow.Storage.Tests.PostgreSql; +using SourceFlow.Transport.InMemory; + +namespace SourceFlow.EndToEnd.Tests; + +/// E2E-34 (WP-C.8, CR-17): the rename-and-upcast procedure of doc 03 §2.1 deploys with schema registration enforced. +[Collection(PostgreSqlCollection.Name)] +[Trait("Category", "EndToEnd")] +public sealed class SchemaEvolutionScenarios(PostgreSqlServer postgreSql) +{ + [Fact] + [Trait("Id", "E2E-34")] + [Trait("Covers", "ADR-005;ADR-029 2;doc 03 2.1")] + public async Task RenamingTheClrType_AndAddingAnUpcastVersion_DeploysWithoutASchemaConflict() + { + await postgreSql.EnsureStartedAsync(); + string schema = PostgreSqlServer.NewSchema("evolve"); + + await DeployAsync(schema); // registers v1 (title "MemberJoined") + await DeployAsync(schema); // v1 is now "MemberJoinedV1" and upcasts to v2 + + await using PostgreSqlStore store = await postgreSql.CreateStoreAsync(configure: o => o.Schema = schema); + IReadOnlyList registered = await ((Storage.ISchemaStore)store).ListAsync(TestContext.Current.CancellationToken); + registered.Where(e => e.Type == "e2e.member.joined").Select(e => e.Version).ShouldBe([1, 2]); + } + + // Starts and stops one deployment of the service on the shared schema; a schema conflict fails StartAsync. + private async Task DeployAsync(string schema) + where TModule : ISourceFlowModule + { + HostApplicationBuilder builder = Host.CreateApplicationBuilder(new HostApplicationBuilderSettings { EnvironmentName = Environments.Development, DisableDefaults = true }); + builder.Services.AddSingleton(TimeProvider.System); + builder.Services.AddSourceFlow(sf => + { + sf.ServiceName = "members"; + sf.AddModule(); + sf.UsePostgreSql(o => + { + o.DataSource = postgreSql.DataSource; + o.Schema = schema; + }); + sf.UseTransport(_ => new InMemoryBroker().CreateTransport()); + sf.Configure(o => o.SchemaRegistration = Runtime.SchemaRegistrationMode.Enforce); + }); + + using IHost host = builder.Build(); + await host.StartAsync(TestContext.Current.CancellationToken); + await host.StopAsync(TestContext.Current.CancellationToken); + } + + // Nested, so the generator leaves them out of this assembly's modules; the deployments below register them. + // The first deployment: e2e.member.joined v1 under its original CLR name. + public sealed record MemberJoined(string Name) : IEvent; + + // The next deployment (doc 03 §2.1): the CLR type renamed, a v2 added, and an upcaster from v1. + public sealed record MemberJoinedV1(string Name) : IEvent; + + public sealed record MemberJoinedV2(string Name, string Club) : IEvent; + + public sealed class MemberJoinedUpcaster : IUpcaster + { + public MemberJoinedV2 Upcast(MemberJoinedV1 old) + { + return new MemberJoinedV2(old.Name, "unknown"); + } + } + + private sealed class FirstDeployment : ISourceFlowModule + { + public static string ModuleName => "members"; + + public static void Register(ISourceFlowModuleBuilder builder) + { + builder.AddMessage("e2e.member.joined", 1); + builder.AddJsonTypeInfoResolver(new DefaultJsonTypeInfoResolver()); + } + } + + private sealed class NextDeployment : ISourceFlowModule + { + public static string ModuleName => "members"; + + public static void Register(ISourceFlowModuleBuilder builder) + { + builder.AddMessage("e2e.member.joined", 1); + builder.AddMessage("e2e.member.joined", 2); + builder.AddUpcaster(); + builder.AddJsonTypeInfoResolver(new DefaultJsonTypeInfoResolver()); + } + } +} diff --git a/tests/EndToEnd/SourceFlow.EndToEnd.Tests/SourceFlow.EndToEnd.Tests.csproj b/tests/EndToEnd/SourceFlow.EndToEnd.Tests/SourceFlow.EndToEnd.Tests.csproj new file mode 100644 index 00000000..df1205ae --- /dev/null +++ b/tests/EndToEnd/SourceFlow.EndToEnd.Tests/SourceFlow.EndToEnd.Tests.csproj @@ -0,0 +1,44 @@ + + + + true + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/tests/EndToEnd/SourceFlow.EndToEnd.Tests/TravelBookingScenarios.cs b/tests/EndToEnd/SourceFlow.EndToEnd.Tests/TravelBookingScenarios.cs new file mode 100644 index 00000000..395c1566 --- /dev/null +++ b/tests/EndToEnd/SourceFlow.EndToEnd.Tests/TravelBookingScenarios.cs @@ -0,0 +1,228 @@ +using Bookings; +using Hotels; +using SourceFlow.Cloud.Tests.Aws; +using SourceFlow.Cloud.Tests.Azure; +using SourceFlow.Cloud.Tests.Gcp; +using SourceFlow.Storage.Tests.PostgreSql; +using SourceFlow.Workflows; +using BookingId = Bookings.BookingId; + +namespace SourceFlow.EndToEnd.Tests; + +/// +/// The TravelBooking sample's trip-booking workflow between its two services (TB-E2E-01..06): the booking confirmed, the +/// hotel sold out, the guest not confirming in time, the guest cancelling, a hold released after the point of no return +/// (manual intervention and an operator's abort), and an outage of the Hotels service ridden out by the step's retries. +/// +/// +/// TB-E2E-01 runs on PostgreSQL over every transport; TB-E2E-02..06 on the in-memory store and on PostgreSQL (in-memory +/// broker). The cloud legs move to the real cloud with SOURCEFLOW_REAL_CLOUD (nightly). +/// +[Collection(PostgreSqlCollection.Name)] +[Trait("Category", "EndToEnd")] +[Trait("Category", "Workflow")] +public sealed class TravelBookingScenarios(PostgreSqlServer postgreSql, LocalStackServer localStack, PubSubEmulatorServer pubSub, ServiceBusEmulatorServer serviceBus) +{ + private const string Requested = "bookings.booking-requested.v1"; + private const string GuestConfirmed = "bookings.guest-confirmed.v1"; + private const string GuestCancelled = "bookings.guest-cancelled.v1"; + private const string Confirmed = "bookings.booking-confirmed.v1"; + private const string Declined = "bookings.booking-declined.v1"; + private const string Registered = "hotels.hotel-registered.v1"; + private const string Held = "hotels.room-reserved.v1"; + private const string Released = "hotels.room-released.v1"; + private const string Reserved = "hotels.reservation-confirmed.v1"; + + // The Bookings clock only has to pass a timer's due time; a second more avoids an edge. + private static readonly TimeSpan Second = TimeSpan.FromSeconds(1); + + private Servers Servers => new(postgreSql, localStack, pubSub, serviceBus); + + // ================================================================ TB-E2E-01: the booking is confirmed + + [Fact] + [Trait("Id", "TB-E2E-01")] + [Trait("Requires", "Docker")] + public Task Booking_IsConfirmed_InMemoryBroker() => ConfirmedAsync(Broker.InMemory); + + [Fact] + [Trait("Id", "TB-E2E-01")] + [Trait("Cloud", "Aws")] + [Trait("Requires", "LocalStack")] + public Task Booking_IsConfirmed_Aws() => ConfirmedAsync(Broker.Aws); + + [Fact] + [Trait("Id", "TB-E2E-01")] + [Trait("Cloud", "Gcp")] + [Trait("Requires", "PubSubEmulator")] + public Task Booking_IsConfirmed_Gcp() => ConfirmedAsync(Broker.Gcp); + + [Fact] + [Trait("Id", "TB-E2E-01")] + [Trait("Cloud", "Azure")] + [Trait("Requires", "ServiceBusEmulator")] + public Task Booking_IsConfirmed_Azure() => ConfirmedAsync(Broker.Azure); + + // ================================================================ TB-E2E-02..06 on both stores + + [Fact] + [Trait("Id", "TB-E2E-02")] + public Task SoldOut_DeclinesTheBooking_InMemory() => SoldOutAsync(Store.InMemory); + + [Fact] + [Trait("Id", "TB-E2E-02")] + [Trait("Requires", "Docker")] + public Task SoldOut_DeclinesTheBooking_PostgreSql() => SoldOutAsync(Store.PostgreSql); + + [Fact] + [Trait("Id", "TB-E2E-03")] + public Task GuestTooLate_ReleasesTheRoom_InMemory() => GuestTooLateAsync(Store.InMemory); + + [Fact] + [Trait("Id", "TB-E2E-03")] + [Trait("Requires", "Docker")] + public Task GuestTooLate_ReleasesTheRoom_PostgreSql() => GuestTooLateAsync(Store.PostgreSql); + + [Fact] + [Trait("Id", "TB-E2E-04")] + public Task GuestCancels_ReleasesTheRoom_InMemory() => GuestCancelsAsync(Store.InMemory); + + [Fact] + [Trait("Id", "TB-E2E-04")] + [Trait("Requires", "Docker")] + public Task GuestCancels_ReleasesTheRoom_PostgreSql() => GuestCancelsAsync(Store.PostgreSql); + + [Fact] + [Trait("Id", "TB-E2E-05")] + public Task HoldLostAfterThePivot_NeedsAnOperator_InMemory() => HoldLostAsync(Store.InMemory); + + [Fact] + [Trait("Id", "TB-E2E-05")] + [Trait("Requires", "Docker")] + public Task HoldLostAfterThePivot_NeedsAnOperator_PostgreSql() => HoldLostAsync(Store.PostgreSql); + + [Fact] + [Trait("Id", "TB-E2E-06")] + public Task HotelsOutage_IsRiddenOutByRetries_InMemory() => HotelsOutageAsync(Store.InMemory); + + [Fact] + [Trait("Id", "TB-E2E-06")] + [Trait("Requires", "Docker")] + public Task HotelsOutage_IsRiddenOutByRetries_PostgreSql() => HotelsOutageAsync(Store.PostgreSql); + + // ================================================================ scenarios + + // Hold the room, the guest confirms, the hotel confirms: the booking is confirmed and the room is booked. + private async Task ConfirmedAsync(Broker broker) + { + await using TravelBookingSystem system = await TravelBookingSystem.StartAsync(Servers, Store.PostgreSql, broker); + HotelId hotel = await system.RegisterHotelAsync(rooms: 1); + BookingId booking = await system.RequestAsync(hotel); + + await system.WaitAsync(booking, s => s.Step == "await-guest", "the room to be held and the workflow to wait for the guest"); + await system.WaitForRoomsAsync(hotel, held: 1, confirmed: 0); + await system.GuestAsync(new ConfirmByGuest(booking)); + + WorkflowInstanceSummary done = await system.WaitAsync(booking, s => s.Status == "Completed", "the booking to be confirmed"); + done.PendingCompensations.ShouldBe(1, "hold-room pushed its compensation, which never ran"); + await system.WaitForBookingEventsAsync(booking, Requested, GuestConfirmed, Confirmed); + await system.WaitForRoomsAsync(hotel, held: 0, confirmed: 1); + (await system.HotelEventsAsync(hotel)).ShouldBe([Registered, Held, Reserved]); + } + + // The only room is held by the first booking: the second is rejected by the hotel, and declined without undoing anything. + private async Task SoldOutAsync(Store store) + { + await using TravelBookingSystem system = await TravelBookingSystem.StartAsync(Servers, store, Broker.InMemory); + HotelId hotel = await system.RegisterHotelAsync(rooms: 1); + BookingId first = await system.RequestAsync(hotel); + await system.WaitAsync(first, s => s.Step == "await-guest", "the first booking to hold the room"); + + BookingId second = await system.RequestAsync(hotel); + + WorkflowInstanceSummary declined = await system.WaitAsync(second, s => s.Status == "Compensated", "the second booking to be declined"); + declined.FailureCode.ShouldBe(HotelErrors.SoldOut); + await system.WaitForBookingEventsAsync(second, Requested, Declined); + await system.WaitForRoomsAsync(hotel, held: 1, confirmed: 0); + (await system.SummaryAsync(first))!.Status.ShouldBe("Running", "the first booking still waits for its guest"); + } + + // The guest doesn't confirm within 15 minutes: the hold is released (compensation) and the booking declined. + private async Task GuestTooLateAsync(Store store) + { + await using TravelBookingSystem system = await TravelBookingSystem.StartAsync(Servers, store, Broker.InMemory); + HotelId hotel = await system.RegisterHotelAsync(rooms: 1); + BookingId booking = await system.RequestAsync(hotel); + await system.WaitAsync(booking, s => s.Step == "await-guest", "the room to be held"); + + system.Advance(TimeSpan.FromMinutes(15) + Second); + + await system.WaitAsync(booking, s => s.Status == "Compensated", "the lapsed hold to be undone"); + await system.WaitForBookingEventsAsync(booking, Requested, Declined); + await system.WaitForRoomsAsync(hotel, held: 0, confirmed: 0); + (await system.HotelEventsAsync(hotel)).ShouldBe([Registered, Held, Released]); + } + + // The guest cancels: a failure event of the await-guest step. The hold is released; the booking stays cancelled. + private async Task GuestCancelsAsync(Store store) + { + await using TravelBookingSystem system = await TravelBookingSystem.StartAsync(Servers, store, Broker.InMemory); + HotelId hotel = await system.RegisterHotelAsync(rooms: 1); + BookingId booking = await system.RequestAsync(hotel); + await system.WaitAsync(booking, s => s.Step == "await-guest", "the room to be held"); + + await system.GuestAsync(new CancelByGuest(booking)); + + await system.WaitAsync(booking, s => s.Status == "Compensated", "the cancelled booking's hold to be released"); + await system.WaitForRoomsAsync(hotel, held: 0, confirmed: 0); + (await system.BookingEventsAsync(booking)).ShouldBe([Requested, GuestCancelled], "a cancelled booking is not declined as well"); + } + + // Hotel staff release the hold after the guest confirmed: the confirmation is past the point of no return, so the + // rejection stops the instance for an operator, who aborts it after rebooking the guest by other means. + private async Task HoldLostAsync(Store store) + { + await using TravelBookingSystem system = await TravelBookingSystem.StartAsync(Servers, store, Broker.InMemory); + HotelId hotel = await system.RegisterHotelAsync(rooms: 1); + BookingId booking = await system.RequestAsync(hotel); + await system.WaitAsync(booking, s => s.Step == "await-guest", "the room to be held"); + await system.StaffAsync(new ReleaseRoom(hotel, new Hotels.BookingId(booking.Value))); + await system.WaitForRoomsAsync(hotel, held: 0, confirmed: 0); + + await system.GuestAsync(new ConfirmByGuest(booking)); + + WorkflowInstanceSummary manual = await system.WaitAsync(booking, s => s.Status == "ManualIntervention", "the instance to need an operator"); + manual.FailureCode.ShouldBe(HotelErrors.HoldLost); + (await system.BookingEventsAsync(booking)).ShouldBe([Requested, GuestConfirmed], "the booking stays open for the operator"); + + (int code, string output, string error) = await system.CliAsync("workflow", "show", TravelBookingSystem.Workflow, booking.ToString()); + code.ShouldBe(0, error); + output.ShouldContain("ManualIntervention"); + + (code, _, error) = await system.CliAsync("workflow", "abort", TravelBookingSystem.Workflow, booking.ToString(), "--reason", "rebooked by phone"); + code.ShouldBe(0, error); + (await system.WaitAsync(booking, s => s.Status == "Aborted", "the operator's abort")).Status.ShouldBe("Aborted"); + } + + // Hotels loses what it receives for a while: the hold request times out and is sent again; once Hotels is back, the + // retry succeeds and the booking completes. + private async Task HotelsOutageAsync(Store store) + { + await using TravelBookingSystem system = await TravelBookingSystem.StartAsync(Servers, store, Broker.InMemory); + HotelId hotel = await system.RegisterHotelAsync(rooms: 1); + system.Outage(); + + BookingId booking = await system.RequestAsync(hotel); + await system.WaitAsync(booking, s => s.Step == "hold-room", "the hold to be requested while Hotels is down"); + await Task.Delay(TimeSpan.FromMilliseconds(500), TimeProvider.System, TestContext.Current.CancellationToken); // the request is lost + system.Outage(down: false); + system.Advance(TimeSpan.FromMinutes(1) + Second); // the step times out and sends the hold again + + await system.WaitAsync(booking, s => s.Step == "await-guest", "the retried hold to succeed"); + (await TravelBookingSystem.ParkedAsync(system.Hotels)).ShouldContain("hotels.reserve-room.v1", "the first request was lost to the outage"); + (await system.HotelEventsAsync(hotel)).ShouldBe([Registered, Held], "the retry held the room once"); + await system.GuestAsync(new ConfirmByGuest(booking)); + await system.WaitAsync(booking, s => s.Status == "Completed", "the booking to be confirmed"); + await system.WaitForRoomsAsync(hotel, held: 0, confirmed: 1); + } +} diff --git a/tests/EndToEnd/SourceFlow.EndToEnd.Tests/TravelBookingSystem.cs b/tests/EndToEnd/SourceFlow.EndToEnd.Tests/TravelBookingSystem.cs new file mode 100644 index 00000000..0f70e008 --- /dev/null +++ b/tests/EndToEnd/SourceFlow.EndToEnd.Tests/TravelBookingSystem.cs @@ -0,0 +1,299 @@ +using System.Collections.Concurrent; +using Bookings; +using Hotels; +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.Hosting; +using SourceFlow.Hosting; +using SourceFlow.Messaging; +using SourceFlow.Pipeline; +using SourceFlow.Runtime; +using SourceFlow.Storage; +using SourceFlow.Storage.InMemory; +using SourceFlow.Storage.PostgreSQL; +using SourceFlow.Storage.Tests.PostgreSql; +using SourceFlow.Tool; +using SourceFlow.Workflows; +using BookingId = Bookings.BookingId; + +namespace SourceFlow.EndToEnd.Tests; + +/// +/// The TravelBooking sample as its two services (samples/TravelBooking): Bookings, which owns the trip-booking workflow, +/// and Hotels, each with its own store (an in-memory store or a PostgreSQL schema) and its own transport client on one +/// broker, configured exactly as the sample's hosts configure them (AddBookingsService, AddHotelsService). +/// +/// +/// Bookings runs on (real time plus an offset the test moves forward), so the workflow's timers fall due +/// at once. takes Hotels' message handling down: what it receives meanwhile is parked, and the +/// workflow only sees time pass. +/// +internal sealed class TravelBookingSystem : IAsyncDisposable +{ + public const string Workflow = "trip-booking@1"; + + private readonly List _hosts = []; + private readonly Servers _servers; + private readonly Store _store; + private readonly BrokerConnection _connection; + private readonly Dictionary _schemas = []; + private readonly Dictionary _memory = []; + private readonly ConcurrentDictionary _outages = new(StringComparer.Ordinal); + + private TravelBookingSystem(Servers servers, Store store, Broker broker) + { + _servers = servers; + _store = store; + _connection = new BrokerConnection(servers, broker, "tb"); + foreach (string service in (string[])[BookingsService.Name, HotelsService.Name]) + { + _schemas[service] = PostgreSqlServer.NewSchema("tb_" + service); + _memory[service] = new InMemoryStore(service == BookingsService.Name ? Clock : TimeProvider.System); + } + } + + /// The Bookings service's clock. + public ShiftingClock Clock { get; } = new(); + + public IHost Bookings { get; private set; } = null!; + + public IHost Hotels { get; private set; } = null!; + + public static async Task StartAsync(Servers servers, Store store, Broker broker) + { + if (store == Store.PostgreSql) + { + await servers.PostgreSql.EnsureStartedAsync(); + } + + await BrokerConnection.EnsureStartedAsync(servers, broker); + var system = new TravelBookingSystem(servers, store, broker); + try + { + // The owner of the commands first: its endpoint exists before the workflow sends to it. + system.Hotels = await system.StartServiceAsync(HotelsService.Name, sf => sf.AddHotelsService()); + system.Bookings = await system.StartServiceAsync(BookingsService.Name, sf => sf.AddBookingsService()); + return system; + } + catch + { + await system.DisposeAsync(); + throw; + } + } + + /// Takes Hotels' message handling down (true) or back up (false). + public void Outage(bool down = true) + { + _outages[HotelsService.Name] = down; + } + + // ================================================================ commands + + /// Registers a hotel with its rooms. + public async Task RegisterHotelAsync(int rooms, string name = "Seaview") + { + var hotel = HotelId.New(); + (await Send(Hotels, new RegisterHotel(hotel, name, rooms))).Status.ShouldBe(CommandStatus.Accepted); + return hotel; + } + + /// A guest requests a booking, which starts its trip-booking workflow. + public async Task RequestAsync(HotelId hotel, int nights = 2) + { + var booking = BookingId.New(); + (await Send(Bookings, new RequestBooking(booking, hotel.Value, "Ada Lovelace", nights))).Status.ShouldBe(CommandStatus.Accepted); + return booking; + } + + /// Sends a command to the Bookings service (the guest). + public async Task GuestAsync(ICommand command) + { + (await Send(Bookings, command)).Status.ShouldBe(CommandStatus.Accepted); + } + + /// Sends a command to the Hotels service (hotel staff). + public async Task StaffAsync(ICommand command) + { + (await Send(Hotels, command)).Status.ShouldBe(CommandStatus.Accepted); + } + + /// Runs the SourceFlow CLI in the Bookings service (the operator's view). + public async Task<(int Code, string Output, string Error)> CliAsync(params string[] args) + { + var output = new StringWriter(); + var error = new StringWriter(); + int code = await SourceFlowCli.RunAsync(args, Bookings.Services, output, error, Ct); + return (code, output.ToString(), error.ToString()); + } + + // ================================================================ reads + + /// The workflow-instances read model's row for a booking, or null before the workflow started. + public async Task SummaryAsync(BookingId booking) + { + StoredDocument? document = await Runtime(Bookings).Storage.Documents.GetAsync( + MessageEnvelope.DefaultTenant, WorkflowInstanceSummary.Collection, WorkflowInstanceSummary.DocumentId(Workflow, booking.ToString()), Ct); + return document is null ? null : WorkflowRuntime.DeserializeSummary(document.Data.Span); + } + + /// Waits until the booking's instance satisfies . + public async Task WaitAsync(BookingId booking, Func condition, string what) + { + WorkflowInstanceSummary? last = null; + await EventuallyAsync(async () => (last = await SummaryAsync(booking)) is { } summary && condition(summary), what, + () => last is null ? "no instance" : $"{last.Status} at {last.Step} (attempt {last.Attempt}, failure {last.FailureCode ?? "none"})"); + return last!; + } + + /// Waits until the booking's events in the Bookings service are . + public Task WaitForBookingEventsAsync(BookingId booking, params string[] expected) + { + IReadOnlyList last = []; + return EventuallyAsync(async () => (last = await BookingEventsAsync(booking)).SequenceEqual(expected), + "booking events " + string.Join(", ", expected), () => string.Join(", ", last)); + } + + /// Waits until the hotel's rooms read model shows and . + public Task WaitForRoomsAsync(HotelId hotel, int held, int confirmed) + { + HotelRooms? last = null; + return EventuallyAsync(async () => (last = await RoomsAsync(hotel)) is { } rooms && rooms.Held == held && rooms.Confirmed == confirmed, + $"{held} held and {confirmed} confirmed", () => last is null ? "no document" : $"{last.Held} held, {last.Confirmed} confirmed"); + } + + /// The events of a booking's stream in the Bookings service, by CloudEvents type. + public Task> BookingEventsAsync(BookingId booking) => EventTypesAsync(Bookings, StreamId.For(Booking.AggregateName, booking.ToStreamSegment())); + + /// The events of a hotel's stream in the Hotels service, by CloudEvents type. + public Task> HotelEventsAsync(HotelId hotel) => EventTypesAsync(Hotels, StreamId.For(Hotel.AggregateName, hotel.ToStreamSegment())); + + /// A hotel's rooms read model. + public async Task RoomsAsync(HotelId hotel) + { + // The generation serving reads (blue/green read models, doc 06 §6). + ReadModelGeneration generation = await Hotels.Services.GetRequiredService().ResolveAsync("hotel-rooms", Ct); + StoredDocument? document = await Runtime(Hotels).Storage.Documents.GetAsync(MessageEnvelope.DefaultTenant, generation.Collection, hotel.ToStreamSegment(), Ct); + return document is null ? null : (HotelRooms?)System.Text.Json.JsonSerializer.Deserialize(document.Data.Span, Runtime(Hotels).Model.JsonTypeInfoFor(typeof(HotelRooms))); + } + + /// The CloudEvents types a service parked (dead letters). + public static async Task> ParkedAsync(IHost service) + { + IReadOnlyList parked = await service.Services.GetRequiredService().ListAsync(new DeadLetterQuery(), Ct); + return [.. parked.Select(d => CloudEvents.FormatType(d.Envelope.Type, d.Envelope.TypeVersion))]; + } + + /// Moves the Bookings service's clock forward, so the timers due by then fire. + public void Advance(TimeSpan by) + { + Clock.Advance(by); + } + + /// What each service parked, for a failure message. + public async Task DiagnoseAsync() + { + var text = new System.Text.StringBuilder(); + foreach (IHost host in _hosts) + { + IReadOnlyList parked = await host.Services.GetRequiredService().ListAsync(new DeadLetterQuery(), CancellationToken.None); + text.Append(System.Globalization.CultureInfo.InvariantCulture, $"[{Runtime(host).ServiceName}: {parked.Count} dead letter(s)] "); + } + + return text.ToString(); + } + + public async ValueTask DisposeAsync() + { + foreach (IHost host in Enumerable.Reverse(_hosts).ToList()) + { + using var deadline = new CancellationTokenSource(TimeSpan.FromSeconds(30)); + await host.StopAsync(deadline.Token); + host.Dispose(); + } + + _hosts.Clear(); + await _connection.DisposeAsync(); + } + + private static CancellationToken Ct => TestContext.Current.CancellationToken; + + private static SourceFlowRuntime Runtime(IHost host) => host.Services.GetRequiredService(); + + private static ValueTask Send(IHost host, ICommand command) => host.Services.GetRequiredService().SendAsync(command, null, Ct); + + private static async Task> EventTypesAsync(IHost service, StreamId stream) + { + SourceFlowRuntime runtime = Runtime(service); + StreamSlice slice = await runtime.Storage.Events.ReadStreamAsync(runtime.Options.DefaultTenant, stream, new StreamVersion(1), int.MaxValue, Ct); + return [.. slice.Events.Select(e => CloudEvents.FormatType(e.Type, e.TypeVersion))]; + } + + private async Task EventuallyAsync(Func> condition, string what, Func state) + { + DateTimeOffset deadline = TimeProvider.System.GetUtcNow() + TimeSpan.FromSeconds(60); + while (!await condition()) + { + if (TimeProvider.System.GetUtcNow() > deadline) + { + throw new TimeoutException($"Timed out waiting for: {what}. Last seen: {state()}. {await DiagnoseAsync()}"); + } + + await Task.Delay(TimeSpan.FromMilliseconds(100), TimeProvider.System, Ct); + } + } + + private async Task StartServiceAsync(string service, Func add) + { + HostApplicationBuilder builder = Host.CreateApplicationBuilder(new HostApplicationBuilderSettings { EnvironmentName = Environments.Development, DisableDefaults = true }); + builder.Services.AddSingleton(service == BookingsService.Name ? Clock : TimeProvider.System); + builder.Services.AddSourceFlow(sf => + { + add(sf); + if (_store == Store.PostgreSql) + { + sf.UsePostgreSql(o => + { + o.DataSource = _servers.PostgreSql.DataSource; + o.Schema = _schemas[service]; + }); + } + else + { + sf.UseInMemoryStorage(_memory[service]); + } + + sf.UseTransport(_ => _connection.CreateTransport()); + sf.UseMiddleware(_ => new OutageMiddleware(this, service), PipelineStage.Receive); + sf.Configure(o => + { + o.NodeId = service + "-1"; + o.PollInterval = TimeSpan.FromMilliseconds(50); + o.DeadLetterIngestInterval = TimeSpan.FromSeconds(1); + o.ReceiveLockDuration = TimeSpan.FromSeconds(2); + }); + }); + + IHost host = builder.Build(); + try + { + await host.StartAsync(Ct); + } + catch + { + host.Dispose(); + throw; + } + + _hosts.Add(host); + return host; + } + + /// Fails what a service receives while it is down (parked at once: an outage, not a bug). + private sealed class OutageMiddleware(TravelBookingSystem system, string service) : IMessageMiddleware + { + public ValueTask InvokeAsync(MessageContext context, MessageDelegate next) + { + return system._outages.GetValueOrDefault(service) ? throw new PermanentException($"{service} is down.") : next(context); + } + } +} diff --git a/tests/EndToEnd/SourceFlow.EndToEnd.Tests/V2BridgeScenarios.cs b/tests/EndToEnd/SourceFlow.EndToEnd.Tests/V2BridgeScenarios.cs new file mode 100644 index 00000000..7a846a25 --- /dev/null +++ b/tests/EndToEnd/SourceFlow.EndToEnd.Tests/V2BridgeScenarios.cs @@ -0,0 +1,217 @@ +using System.Text.Json.Nodes; +using Amazon.Runtime; +using Amazon.SimpleNotificationService; +using Amazon.SQS; +using Amazon.SQS.Model; +using Bank.Accounts; +using Bank.Contracts; +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.Hosting; +using SourceFlow.Cloud.Aws; +using SourceFlow.Cloud.Tests.Aws; +using SourceFlow.Hosting; +using SourceFlow.Migration; +using SourceFlow.Query; +using SourceFlow.Runtime; +using SourceFlow.Storage; +using SourceFlow.Storage.PostgreSQL; +using SourceFlow.Storage.Tests.PostgreSql; + +namespace SourceFlow.EndToEnd.Tests; + +/// +/// MIG-10..12 (plan 06 §6, WP-5.4): the v2 wire bridge on LocalStack. A v2 SourceFlow.Cloud.AWS producer sends commands +/// to the v3 Accounts service's queue in the v2 shape (a CommandType attribute and a camelCase +/// Command<TPayload> body). With AcceptV2Messages, a mapped type is decided with a deterministic id and +/// an unmapped one is parked; without it, v2 messages are neither handled nor parked. +/// +[Collection(PostgreSqlCollection.Name)] +[Trait("Category", "EndToEnd")] +[Trait("Cloud", "Aws")] +[Trait("Requires", "LocalStack")] +public sealed class V2BridgeScenarios(PostgreSqlServer postgreSql, LocalStackServer localStack) : IAsyncLifetime +{ + private const string CreateAccount = "SourceFlow.Core.Tests.E2E.Commands.CreateAccount, SourceFlow.Core.Tests, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null"; + private const string ActivateAccount = "SourceFlow.Core.Tests.E2E.Commands.ActivateAccount, SourceFlow.Core.Tests, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null"; + + private readonly string _prefix = "v2b" + Guid.CreateVersion7().ToString("N")[^8..] + "-"; + private readonly List _hosts = []; + private AmazonSQSClient _sqs = null!; + + private static CancellationToken Ct => TestContext.Current.CancellationToken; + + public async ValueTask InitializeAsync() + { + await postgreSql.EnsureStartedAsync(); + await localStack.EnsureStartedAsync(); + _sqs = new AmazonSQSClient(new BasicAWSCredentials("test", "test"), new AmazonSQSConfig { ServiceURL = localStack.Endpoint.ToString(), AuthenticationRegion = LocalStackServer.Region }); + } + + public async ValueTask DisposeAsync() + { + foreach (IHost host in _hosts) + { + await host.StopAsync(CancellationToken.None); + host.Dispose(); + } + + try + { + foreach (string url in (await _sqs.ListQueuesAsync(new ListQueuesRequest { QueueNamePrefix = _prefix })).QueueUrls ?? []) + { + await _sqs.DeleteQueueAsync(url); + } + } + catch (AmazonServiceException) + { + // Best effort: LocalStack is discarded with the run. + } + + _sqs.Dispose(); + } + + [Fact] + [Trait("Id", "MIG-10")] + [Trait("Id", "MIG-11")] + [Trait("Covers", "doc 07 8;doc 12 4")] + public async Task MappedV2Command_IsDecidedWithADeterministicId_AndAnUnmappedOneIsParked() + { + IHost accounts = await StartAccountsAsync("accounts", bridge: true); + string queue = await QueueUrlAsync("accounts"); + + // MIG-10: v2 CreateAccount for entity 7 becomes bank.account.open for the mapped v3 id. + string sent = await SendV2Async(queue, CreateAccount, 7, """{"metadata":{"sequenceNo":1},"name":"CreateAccount","payload":{"id":7,"initialAmount":100,"accountName":"Ada"},"entity":{"id":7,"isNew":false}}"""); + AccountId id = V2Ids.FromLegacy(7); + IAggregateReader reader = accounts.Services.GetRequiredService(); + await EventuallyAsync(async () => (await reader.LoadAsync(id, cancellationToken: Ct)).Version == new StreamVersion(1), "the v2 command to be decided"); + (await reader.LoadAsync(id, cancellationToken: Ct)).State.Balance.ShouldBe(100m); + + SourceFlowRuntime runtime = accounts.Services.GetRequiredService(); + StoredEvent opened = (await runtime.Storage.Events.ReadStreamAsync(runtime.Options.DefaultTenant, StreamId.For(BankAccount.AggregateName, id), new StreamVersion(1), 1, Ct)).Events.Single(); + opened.Metadata.CausationId.ShouldBe(V2MessageMap.MessageIdOf(sent)); // the command's id: UUIDv5 of the v2 message id + opened.Metadata.Source.ShouldBe("accounts"); + + // MIG-11: a v2 type that isn't on the allow-list is parked, with its v2 name and body. + await SendV2Async(queue, ActivateAccount, 7, """{"name":"ActivateAccount","payload":{"id":7},"entity":{"id":7}}"""); + IDeadLetterManager deadLetters = accounts.Services.GetRequiredService(); + await EventuallyAsync(async () => (await deadLetters.ListAsync(new DeadLetterQuery(), Ct)).Count == 1, "the unmapped v2 command to be parked"); + DeadLetter parked = (await deadLetters.ListAsync(new DeadLetterQuery(), Ct)).Single(); + parked.Reason.ShouldBe("UnknownMessageType"); + parked.Envelope.Type.ShouldBe("SourceFlow.Core.Tests.E2E.Commands.ActivateAccount, SourceFlow.Core.Tests"); + parked.Envelope.Headers[V2MessageMap.UnmappedHeader].ShouldBe("true"); + parked.Envelope.Headers[V2MessageMap.V2TypeHeader].ShouldBe(ActivateAccount); + } + + [Fact] + [Trait("Id", "MIG-12")] + [Trait("Covers", "doc 07 8")] + public async Task WithoutAcceptV2Messages_V2MessagesAreNeitherHandledNorParked() + { + IHost accounts = await StartAccountsAsync("accounts", bridge: false); + string queue = await QueueUrlAsync("accounts"); + await SendV2Async(queue, CreateAccount, 8, """{"name":"CreateAccount","payload":{"id":8,"initialAmount":5,"accountName":"Bob"},"entity":{"id":8}}"""); + + // A v3 command sent after it is handled, so the receiver has seen the v2 message by then. + ICommandSender commands = accounts.Services.GetRequiredService(); + var probe = AccountId.New(); + (await commands.SendAsync(new OpenAccount(probe, "Probe", 1m), null, Ct)).Status.ShouldBe(CommandStatus.Accepted); + await Task.Delay(TimeSpan.FromSeconds(3), TimeProvider.System, Ct); + + IAggregateReader reader = accounts.Services.GetRequiredService(); + (await reader.LoadAsync(V2Ids.FromLegacy(8), cancellationToken: Ct)).Version.ShouldBe(StreamVersion.None); + (await accounts.Services.GetRequiredService().ListAsync(new DeadLetterQuery(), Ct)).ShouldBeEmpty(); + GetQueueAttributesResponse attributes = await _sqs.GetQueueAttributesAsync(queue, ["ApproximateNumberOfMessages", "ApproximateNumberOfMessagesNotVisible"], Ct); + (attributes.ApproximateNumberOfMessages + attributes.ApproximateNumberOfMessagesNotVisible).ShouldBe(1); // left for the redrive policy + } + + private async Task StartAccountsAsync(string service, bool bridge) + { + HostApplicationBuilder builder = Host.CreateApplicationBuilder(new HostApplicationBuilderSettings { EnvironmentName = Environments.Development, DisableDefaults = true }); + builder.Services.AddSourceFlow(sf => + { + sf.ServiceName = service; + sf.AddModule(); + sf.AddModule(); + sf.UsePostgreSql(o => + { + o.DataSource = postgreSql.DataSource; + o.Schema = PostgreSqlServer.NewSchema("v2bridge"); + }); + var options = new AwsTransportOptions { NamePrefix = _prefix, ReceiveWaitTime = TimeSpan.FromSeconds(1) }; + if (bridge) + { + // The allow-list: v2 CreateAccount → bank.account.open, its payload converted to the v3 record. + options.AcceptV2Messages(map => map.Type("SourceFlow.Core.Tests.E2E.Commands.CreateAccount, SourceFlow.Core.Tests", "bank.account.open", 1, v2 => new JsonObject + { + ["accountId"] = V2Ids.FromLegacy(v2.EntityId ?? v2.Payload!["id"]!.GetValue()).ToString(), + ["holder"] = v2.Payload!["accountName"]!.GetValue(), + ["initialDeposit"] = v2.Payload!["initialAmount"]!.GetValue(), + })); + } + + sf.UseTransport(_ => new AwsTransport( + new AmazonSQSClient(new BasicAWSCredentials("test", "test"), new AmazonSQSConfig { ServiceURL = localStack.Endpoint.ToString(), AuthenticationRegion = LocalStackServer.Region }), + new AmazonSimpleNotificationServiceClient(new BasicAWSCredentials("test", "test"), new AmazonSimpleNotificationServiceConfig { ServiceURL = localStack.Endpoint.ToString(), AuthenticationRegion = LocalStackServer.Region }), + options)); + sf.Configure(o => o.PollInterval = TimeSpan.FromMilliseconds(50)); + }); + + IHost host = builder.Build(); + _hosts.Add(host); + await host.StartAsync(Ct); + return host; + } + + private async Task QueueUrlAsync(string endpoint) + { + foreach (bool ordered in new[] { false, true }) + { + try + { + return (await _sqs.GetQueueUrlAsync(AwsNaming.Queue(_prefix, endpoint, ordered), Ct)).QueueUrl; + } + catch (QueueDoesNotExistException) + { + } + } + + throw new InvalidOperationException($"The '{endpoint}' queue was not provisioned."); + } + + // A v2 AwsSqsCommandDispatcher send: CommandType (assembly-qualified), EntityId and SequenceNo as String attributes. + private async Task SendV2Async(string queue, string commandType, int entityId, string body) + { + var request = new SendMessageRequest + { + QueueUrl = queue, + MessageBody = body, + MessageAttributes = new Dictionary + { + ["CommandType"] = new() { DataType = "String", StringValue = commandType }, + ["EntityId"] = new() { DataType = "String", StringValue = entityId.ToString(System.Globalization.CultureInfo.InvariantCulture) }, + ["SequenceNo"] = new() { DataType = "String", StringValue = "1" }, + }, + }; + if (queue.EndsWith(".fifo", StringComparison.Ordinal)) + { + request.MessageGroupId = entityId.ToString(System.Globalization.CultureInfo.InvariantCulture); + request.MessageDeduplicationId = Guid.CreateVersion7().ToString("N"); + } + + return (await _sqs.SendMessageAsync(request, Ct)).MessageId; + } + + private static async Task EventuallyAsync(Func> condition, string what) + { + DateTimeOffset deadline = TimeProvider.System.GetUtcNow() + TimeSpan.FromSeconds(60); + while (!await condition()) + { + if (TimeProvider.System.GetUtcNow() > deadline) + { + throw new TimeoutException($"Timed out waiting for {what}."); + } + + await Task.Delay(TimeSpan.FromMilliseconds(200), TimeProvider.System, Ct); + } + } +} diff --git a/tests/Fixtures/Bank/Bank.Accounts/AccountSummary.cs b/tests/Fixtures/Bank/Bank.Accounts/AccountSummary.cs new file mode 100644 index 00000000..ad8fa59a --- /dev/null +++ b/tests/Fixtures/Bank/Bank.Accounts/AccountSummary.cs @@ -0,0 +1,85 @@ +using System.Text.Json.Serialization; +using Bank.Contracts; +using SourceFlow; + +namespace Bank.Accounts; + +/// The account summary read model (ported from the v2 AccountView). +public sealed record AccountSummary(AccountId Id, string Holder, decimal Balance, [property: Queryable] AccountStatus Status, long Version); + +/// Maintains documents. +[Projection("account-summary")] +public sealed partial class AccountSummaryProjection : IDocumentProjection +{ + private static AccountSummary When(AccountOpened e, AccountSummary? current, EventContext ctx) + { + return new AccountSummary(e.AccountId, e.Holder, e.InitialDeposit, AccountStatus.Open, ctx.StreamVersion.Value); + } + + private static AccountSummary? When(MoneyDeposited e, AccountSummary? current, EventContext ctx) + { + return current is null ? null : current with { Balance = e.BalanceAfter, Version = ctx.StreamVersion.Value }; + } + + private static AccountSummary? When(MoneyWithdrawn e, AccountSummary? current, EventContext ctx) + { + return current is null ? null : current with { Balance = e.BalanceAfter, Version = ctx.StreamVersion.Value }; + } + + private static AccountSummary? When(AccountClosed e, AccountSummary? current, EventContext ctx) + { + return current is null ? null : current with { Status = AccountStatus.Closed, Version = ctx.StreamVersion.Value }; + } +} + +/// +/// Accounts below a balance: a named, versioned domain query (doc 14 Q-B4), the stable contract other services and UIs +/// use instead of ad-hoc queries. +/// +/// The balance threshold. +[DomainQuery("accounts.low-balance", 1)] +public sealed partial record LowBalanceAccounts(decimal Below) : IDomainQuery +{ + /// The query text. + public const string Sfql = """ + from readmodel "account-summary" + | where status = 1 and balance < @below + | project accountId = id, holder, balance + | order by balance + """; +} + +/// A row of . +/// The account. +/// The holder. +/// The balance. +public sealed record LowBalanceAccount(AccountId AccountId, string Holder, decimal Balance); + +/// Maps domain events to the public contract (doc 03 §7). +public static class AccountContracts +{ + /// Maps to . + public static AccountOpenedV1 ToV1(AccountOpened e) + { + ArgumentNullException.ThrowIfNull(e); + return new AccountOpenedV1(e.AccountId.Value, e.OpenedAt); + } +} + +/// The Accounts module: the generator registers everything in this assembly. +[SourceFlowModule(typeof(AccountsJsonContext))] +public sealed partial class AccountsModule; + +/// Source-generated JSON metadata for every message, document and state type (DC-1). +[JsonSerializable(typeof(OpenAccount))] +[JsonSerializable(typeof(Deposit))] +[JsonSerializable(typeof(Withdraw))] +[JsonSerializable(typeof(CloseAccount))] +[JsonSerializable(typeof(AccountOpened))] +[JsonSerializable(typeof(MoneyDeposited))] +[JsonSerializable(typeof(MoneyWithdrawn))] +[JsonSerializable(typeof(AccountClosed))] +[JsonSerializable(typeof(AccountSummary))] +[JsonSerializable(typeof(BankAccount))] +[JsonSourceGenerationOptions(PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase)] +public sealed partial class AccountsJsonContext : JsonSerializerContext; diff --git a/tests/Fixtures/Bank/Bank.Accounts/Bank.Accounts.csproj b/tests/Fixtures/Bank/Bank.Accounts/Bank.Accounts.csproj new file mode 100644 index 00000000..1ba0f777 --- /dev/null +++ b/tests/Fixtures/Bank/Bank.Accounts/Bank.Accounts.csproj @@ -0,0 +1,7 @@ + + + + + + + diff --git a/tests/Fixtures/Bank/Bank.Accounts/BankAccount.cs b/tests/Fixtures/Bank/Bank.Accounts/BankAccount.cs new file mode 100644 index 00000000..f9a3d8c6 --- /dev/null +++ b/tests/Fixtures/Bank/Bank.Accounts/BankAccount.cs @@ -0,0 +1,150 @@ +using SourceFlow; + +namespace Bank.Accounts; + +/// The account id (UUIDv7). +[StronglyTypedId] +public readonly partial record struct AccountId(Guid Value); + +/// The account lifecycle (ported from the v2 E2E BankAccount entity). +public enum AccountStatus +{ + /// Not opened yet. + None = 0, + + /// Open for deposits and withdrawals. + Open = 1, + + /// Closed; no further changes. + Closed = 2, +} + +/// Opens an account with an initial deposit. +[MessageType("bank.account.open", 1)] +public sealed record OpenAccount(AccountId AccountId, string Holder, decimal InitialDeposit) : ICommand; + +/// Deposits money. +[MessageType("bank.account.deposit", 1)] +public sealed record Deposit(AccountId AccountId, decimal Amount) : ICommand; + +/// Withdraws money. +[MessageType("bank.account.withdraw", 1)] +public sealed record Withdraw(AccountId AccountId, decimal Amount) : ICommand; + +/// Closes the account. +[MessageType("bank.account.close", 1)] +public sealed record CloseAccount(AccountId AccountId, string Reason) : ICommand; + +/// The account was opened. +[MessageType("bank.account.opened", 1)] +public sealed record AccountOpened(AccountId AccountId, [property: PersonalData] string Holder, decimal InitialDeposit, DateTimeOffset OpenedAt) : IEvent; + +/// Money was deposited. +[MessageType("bank.account.deposited", 1)] +public sealed record MoneyDeposited([property: Queryable] AccountId AccountId, decimal Amount, decimal BalanceAfter) : IEvent; + +/// Money was withdrawn. +[MessageType("bank.account.withdrawn", 1)] +public sealed record MoneyWithdrawn(AccountId AccountId, decimal Amount, decimal BalanceAfter) : IEvent; + +/// The account was closed. +[MessageType("bank.account.closed", 1)] +public sealed record AccountClosed(AccountId AccountId, string Reason, DateTimeOffset ClosedAt) : IEvent; + +/// The bank account aggregate: pure deciders (ADR-003). +[Aggregate("bank-account")] +public sealed partial record BankAccount : IAggregate +{ + /// The state before the first event. + public static BankAccount Initial { get; } = new(); + + /// The lifecycle status. + public AccountStatus Status { get; init; } + + /// The current balance. + public decimal Balance { get; init; } + + /// Opens the account. + public Decision Decide(OpenAccount c, DecisionContext ctx) + { + return Status switch + { + AccountStatus.None when c.InitialDeposit <= 0 => Decision.Reject(AccountErrors.InitialDepositRequired), + AccountStatus.None => Decision.Accept(new AccountOpened(c.AccountId, c.Holder, c.InitialDeposit, ctx.Now)), + _ => Decision.Reject(AccountErrors.AlreadyOpen), + }; + } + + /// Deposits money. + public Decision Decide(Deposit c, DecisionContext ctx) + { + return this switch + { + { Status: not AccountStatus.Open } => Decision.Reject(AccountErrors.NotOpen), + _ when c.Amount <= 0 => Decision.Reject(AccountErrors.AmountMustBePositive), + _ => Decision.Accept(new MoneyDeposited(c.AccountId, c.Amount, Balance + c.Amount)), + }; + } + + /// Withdraws money. + public Decision Decide(Withdraw c, DecisionContext ctx) + { + return this switch + { + { Status: not AccountStatus.Open } => Decision.Reject(AccountErrors.NotOpen), + _ when c.Amount <= 0 => Decision.Reject(AccountErrors.AmountMustBePositive), + _ when c.Amount > Balance => Decision.Reject(AccountErrors.InsufficientFunds), + _ => Decision.Accept(new MoneyWithdrawn(c.AccountId, c.Amount, Balance - c.Amount)), + }; + } + + /// Closes the account; closing a closed account is a no-op. + public Decision Decide(CloseAccount c, DecisionContext ctx) + { + return Status switch + { + AccountStatus.Closed => Decision.NoOp, + AccountStatus.Open => Decision.Accept(new AccountClosed(c.AccountId, c.Reason, ctx.Now)), + _ => Decision.Reject(AccountErrors.NotOpen), + }; + } + + private BankAccount When(AccountOpened e) + { + return this with { Status = AccountStatus.Open, Balance = e.InitialDeposit }; + } + + private BankAccount When(MoneyDeposited e) + { + return this with { Balance = e.BalanceAfter }; + } + + private BankAccount When(MoneyWithdrawn e) + { + return this with { Balance = e.BalanceAfter }; + } + + private BankAccount When(AccountClosed e) + { + return this with { Status = AccountStatus.Closed }; + } +} + +/// Business errors of the account aggregate. +public static class AccountErrors +{ + /// An initial deposit is required. + public static readonly Error InitialDepositRequired = new("account.initial_deposit_required", "An initial deposit is required."); + + /// The account is already open. + public static readonly Error AlreadyOpen = new("account.already_open", "The account is already open."); + + /// The account is not open. + public static readonly Error NotOpen = new("account.not_open", "The account is not open."); + + /// The amount must be positive. + public static readonly Error AmountMustBePositive = new("account.amount_must_be_positive", "Amount must be positive."); + + /// The balance is too low. + public static readonly Error InsufficientFunds = new("account.insufficient_funds", "Insufficient funds."); +} diff --git a/tests/Fixtures/Bank/Bank.AotCheck/Bank.AotCheck.csproj b/tests/Fixtures/Bank/Bank.AotCheck/Bank.AotCheck.csproj new file mode 100644 index 00000000..3ce27498 --- /dev/null +++ b/tests/Fixtures/Bank/Bank.AotCheck/Bank.AotCheck.csproj @@ -0,0 +1,23 @@ + + + + false + true + + true + + + + + + + + + + diff --git a/tests/Fixtures/Bank/Bank.AotCheck/Program.cs b/tests/Fixtures/Bank/Bank.AotCheck/Program.cs new file mode 100644 index 00000000..bbec6927 --- /dev/null +++ b/tests/Fixtures/Bank/Bank.AotCheck/Program.cs @@ -0,0 +1,41 @@ +using Bank.Accounts; +using Bank.Contracts; +using Bank.Notifications; +using Bank.Transfers; +using Microsoft.AspNetCore.Diagnostics.HealthChecks; +using SourceFlow.AspNetCore; +using SourceFlow.Hosting; +using SourceFlow.Query; +using SourceFlow.Storage.PostgreSQL; + +// The AOT check (ARCH-06): a service built from the AOT-marked packages (core, PostgreSQL, ASP.NET Core) and the Bank +// domain, published with PublishAot and warnings as errors in CI. It is never run. +WebApplicationBuilder builder = WebApplication.CreateSlimBuilder(args); +string connectionString = builder.Configuration.GetConnectionString("SourceFlow") ?? "Host=localhost"; + +builder.Services.AddSourceFlow(sf => +{ + sf.ServiceName = "bank"; + sf.AddModule(); + sf.AddModule(); + sf.AddModule(); + sf.AddModule(); + sf.Routing(r => + { + r.Publish().As(AccountContracts.ToV1).To("accounts.events"); + r.Subscribe("accounts.events"); + }); + sf.UsePostgreSql(connectionString); + sf.UseInMemoryTransport(); +}); +builder.Services.AddHealthChecks().AddSourceFlow(); +builder.Services.AddSourceFlowQueryApi(o => o.Permissions = _ => QueryPermissions.Of([QueryPermission.ReadModels, QueryPermission.Validate])); + +WebApplication app = builder.Build(); +app.MapHealthChecks("/health/ready", new HealthCheckOptions { Predicate = c => c.Tags.Contains(SourceFlowHealthChecks.ReadyTag) }); +app.MapCommand("/accounts/{accountId}"); +app.MapCommand("/accounts/{accountId}/deposits"); +app.MapCommand("/transfers/{transferId}"); +app.MapSourceFlowQueryApi().RequireAuthorization(); +app.MapDomainQueries().RequireAuthorization(); +app.Run(); diff --git a/tests/Fixtures/Bank/Bank.Contracts/AccountContracts.cs b/tests/Fixtures/Bank/Bank.Contracts/AccountContracts.cs new file mode 100644 index 00000000..53f797d2 --- /dev/null +++ b/tests/Fixtures/Bank/Bank.Contracts/AccountContracts.cs @@ -0,0 +1,17 @@ +using System.Text.Json.Serialization; +using SourceFlow; + +namespace Bank.Contracts; + +/// Published by Accounts when an account is opened (no PII by design, doc 03 §7). +[MessageType("accounts.account-opened", 1)] +public sealed record AccountOpenedV1(Guid AccountId, DateTimeOffset OpenedAt) : IIntegrationEvent; + +/// The contracts module: registers the integration events for every service that uses them. +[SourceFlowModule(typeof(ContractsJsonContext))] +public sealed partial class ContractsModule; + +/// JSON metadata for the contracts (DC-1). +[JsonSerializable(typeof(AccountOpenedV1))] +[JsonSourceGenerationOptions(PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase)] +public sealed partial class ContractsJsonContext : JsonSerializerContext; diff --git a/tests/Fixtures/Bank/Bank.Contracts/Bank.Contracts.csproj b/tests/Fixtures/Bank/Bank.Contracts/Bank.Contracts.csproj new file mode 100644 index 00000000..852f7152 --- /dev/null +++ b/tests/Fixtures/Bank/Bank.Contracts/Bank.Contracts.csproj @@ -0,0 +1,6 @@ + + + + + + diff --git a/tests/Fixtures/Bank/Bank.Notifications/Bank.Notifications.csproj b/tests/Fixtures/Bank/Bank.Notifications/Bank.Notifications.csproj new file mode 100644 index 00000000..33bc94e5 --- /dev/null +++ b/tests/Fixtures/Bank/Bank.Notifications/Bank.Notifications.csproj @@ -0,0 +1,7 @@ + + + + + + + diff --git a/tests/Fixtures/Bank/Bank.Notifications/Notifications.cs b/tests/Fixtures/Bank/Bank.Notifications/Notifications.cs new file mode 100644 index 00000000..d2023844 --- /dev/null +++ b/tests/Fixtures/Bank/Bank.Notifications/Notifications.cs @@ -0,0 +1,111 @@ +using System.Text.Json.Serialization; +using Bank.Contracts; +using SourceFlow; + +namespace Bank.Notifications; + +/// The customer id in the Notifications service (the account id from the integration event). +[StronglyTypedId] +public readonly partial record struct CustomerId(Guid Value); + +/// Sends the welcome message to a new customer (idempotent). +[MessageType("notifications.welcome.send", 1)] +public sealed record SendWelcome(CustomerId CustomerId, DateTimeOffset OpenedAt) : ICommand; + +/// The welcome message was sent. +[MessageType("notifications.welcome.sent", 1)] +public sealed record WelcomeSent(CustomerId CustomerId, DateTimeOffset At) : IEvent; + +/// +/// Sends the customer a statement for a period. Notifications owns this command; other services (Accounts) route it here +/// (ADR-007), so it is a public contract of this service. +/// +[MessageType("notifications.statement.request", 1)] +public sealed record RequestStatement(CustomerId CustomerId, string Period) : ICommand; + +/// A statement was sent. +[MessageType("notifications.statement.sent", 1)] +public sealed record StatementSent(CustomerId CustomerId, string Period, DateTimeOffset At) : IEvent; + +/// The notifications a customer received. +[Aggregate("customer-inbox")] +public sealed partial record CustomerInbox : IAggregate +{ + /// The initial state. + public static CustomerInbox Initial { get; } = new(); + + /// True once the welcome message was sent. + public bool Welcomed { get; init; } + + /// How many statements were sent. + public int StatementsSent { get; init; } + + /// Sends the welcome message once. + public Decision Decide(SendWelcome c, DecisionContext ctx) + { + return Welcomed ? Decision.NoOp : Decision.Accept(new WelcomeSent(c.CustomerId, ctx.Now)); + } + + /// Sends a statement every time one is requested: a repeated request is a new statement, a redelivered one is not (the inbox). + public Decision Decide(RequestStatement c, DecisionContext ctx) + { + ArgumentNullException.ThrowIfNull(c); + return Decision.Accept(new StatementSent(c.CustomerId, c.Period, ctx.Now)); + } + + private CustomerInbox When(WelcomeSent e) + { + return this with { Welcomed = true }; + } + + private CustomerInbox When(StatementSent e) + { + return this with { StatementsSent = StatementsSent + 1 }; + } +} + +/// Reacts to the Accounts integration event (received through the service's own subscription, RT-R4). +public sealed class AccountOpenedHandler(ICommandSender commands) : IEventHandler +{ + /// + public async ValueTask HandleAsync(AccountOpenedV1 @event, EventContext context, CancellationToken cancellationToken) + { + ArgumentNullException.ThrowIfNull(@event); + await commands.SendAsync( + new SendWelcome(new CustomerId(@event.AccountId), @event.OpenedAt), + new SendOptions { IdempotencyKey = "welcome:" + context.EventId }, + cancellationToken).ConfigureAwait(false); + } +} + +/// +/// The Notifications commands other services send (), without the aggregate that decides +/// them: a sender registers this module and routes the command to the notifications endpoint. +/// +public sealed class NotificationsCommandsModule : ISourceFlowModule +{ + /// + public static string ModuleName => nameof(NotificationsCommandsModule); + + /// + public static void Register(ISourceFlowModuleBuilder builder) + { + ArgumentNullException.ThrowIfNull(builder); + builder.AddMessage("notifications.statement.request", 1); + builder.AddJsonTypeInfoResolver(NotificationsJsonContext.Default); + builder.AddJsonConverter(new CustomerId.SourceFlowJsonConverter()); // ids travel as strings, as the owner reads them + } +} + +/// The Notifications module. +[SourceFlowModule(typeof(NotificationsJsonContext))] +public sealed partial class NotificationsModule; + +/// JSON metadata for the Notifications module (DC-1). +[JsonSerializable(typeof(SendWelcome))] +[JsonSerializable(typeof(WelcomeSent))] +[JsonSerializable(typeof(RequestStatement))] +[JsonSerializable(typeof(StatementSent))] +[JsonSerializable(typeof(CustomerInbox))] +[JsonSourceGenerationOptions(PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase)] +public sealed partial class NotificationsJsonContext : JsonSerializerContext; diff --git a/tests/Fixtures/Bank/Bank.Transfers/Bank.Transfers.csproj b/tests/Fixtures/Bank/Bank.Transfers/Bank.Transfers.csproj new file mode 100644 index 00000000..a6ce0636 --- /dev/null +++ b/tests/Fixtures/Bank/Bank.Transfers/Bank.Transfers.csproj @@ -0,0 +1,7 @@ + + + + + + + diff --git a/tests/Fixtures/Bank/Bank.Transfers/Transfers.cs b/tests/Fixtures/Bank/Bank.Transfers/Transfers.cs new file mode 100644 index 00000000..53d2dce5 --- /dev/null +++ b/tests/Fixtures/Bank/Bank.Transfers/Transfers.cs @@ -0,0 +1,209 @@ +using System.Text.Json.Serialization; +using Bank.Accounts; +using SourceFlow; + +namespace Bank.Transfers; + +/// The transfer id. +[StronglyTypedId] +public readonly partial record struct TransferId(Guid Value); + +/// Requests a transfer between two accounts. +[MessageType("bank.transfer.request", 1)] +public sealed record RequestTransfer(TransferId TransferId, AccountId From, AccountId To, decimal Amount) : ICommand; + +/// Marks a transfer completed (sent by the process manager). +[MessageType("bank.transfer.complete", 1)] +public sealed record CompleteTransfer(TransferId TransferId) : ICommand; + +/// Marks a transfer failed (sent by the process manager). +[MessageType("bank.transfer.fail", 1)] +public sealed record FailTransfer(TransferId TransferId, string Reason) : ICommand; + +/// A transfer was requested. +[MessageType("bank.transfer.requested", 1)] +public sealed record TransferRequested(TransferId TransferId, AccountId From, AccountId To, decimal Amount) : IEvent; + +/// A transfer completed. +[MessageType("bank.transfer.completed", 1)] +public sealed record TransferCompleted(TransferId TransferId) : IEvent; + +/// A transfer failed. +[MessageType("bank.transfer.failed", 1)] +public sealed record TransferFailed(TransferId TransferId, string Reason) : IEvent; + +/// The transfer did not finish in time. +[MessageType("bank.transfer.timed-out", 1)] +public sealed record TransferTimedOut(TransferId TransferId) : ITimeout; + +/// The lifecycle of a transfer. +public enum TransferStatus +{ + /// Not requested. + None = 0, + + /// In progress. + Requested = 1, + + /// Completed. + Completed = 2, + + /// Failed. + Failed = 3, +} + +/// The transfer aggregate: records the request and the outcome. +[Aggregate("bank-transfer")] +public sealed partial record Transfer : IAggregate +{ + /// The initial state. + public static Transfer Initial { get; } = new(); + + /// The status. + public TransferStatus Status { get; init; } + + /// Requests the transfer. + public Decision Decide(RequestTransfer c, DecisionContext ctx) + { + return this switch + { + { Status: not TransferStatus.None } => Decision.NoOp, + _ when c.Amount <= 0 => Decision.Reject(new Error("transfer.amount_must_be_positive", "Amount must be positive.")), + _ when c.From == c.To => Decision.Reject(new Error("transfer.same_account", "Cannot transfer to the same account.")), + _ => Decision.Accept(new TransferRequested(c.TransferId, c.From, c.To, c.Amount)), + }; + } + + /// Completes the transfer. + public Decision Decide(CompleteTransfer c, DecisionContext ctx) + { + return Status == TransferStatus.Requested ? Decision.Accept(new TransferCompleted(c.TransferId)) : Decision.NoOp; + } + + /// Fails the transfer. + public Decision Decide(FailTransfer c, DecisionContext ctx) + { + return Status == TransferStatus.Requested ? Decision.Accept(new TransferFailed(c.TransferId, c.Reason)) : Decision.NoOp; + } + + private Transfer When(TransferRequested e) + { + return this with { Status = TransferStatus.Requested }; + } + + private Transfer When(TransferCompleted e) + { + return this with { Status = TransferStatus.Completed }; + } + + private Transfer When(TransferFailed e) + { + return this with { Status = TransferStatus.Failed }; + } +} + +/// The stage of a money transfer. +public enum TransferStage +{ + /// Not started. + None = 0, + + /// Waiting for the withdrawal. + Withdrawing = 1, + + /// Waiting for the deposit. + Depositing = 2, +} + +/// Coordinates a transfer across two accounts with a timeout and compensation (doc 03 §6.1). +[ProcessManager("money-transfer")] +public sealed partial record MoneyTransfer : IProcessManager +{ + /// How long a transfer may take. + public static readonly TimeSpan Timeout = TimeSpan.FromMinutes(5); + + /// The initial state. + public static MoneyTransfer Initial { get; } = new(); + + /// The stage. + public TransferStage Stage { get; init; } + + /// The source account. + public AccountId From { get; init; } + + /// The target account. + public AccountId To { get; init; } + + /// The amount. + public decimal Amount { get; init; } + + /// Starting events correlate by the transfer id. + public static TransferId CorrelateBy(TransferRequested e) + { + ArgumentNullException.ThrowIfNull(e); + return e.TransferId; + } + + /// Starts: withdraw from the source and arm the timeout. + public Reaction React(TransferRequested e, ReactionContext ctx) + { + ArgumentNullException.ThrowIfNull(e); + return Reaction.Send(new Withdraw(e.From, e.Amount)) + .Schedule(new TransferTimedOut(e.TransferId), ctx.Now + Timeout) + .AndBecome(this with { Stage = TransferStage.Withdrawing, From = e.From, To = e.To, Amount = e.Amount }); + } + + /// The withdrawal happened: deposit to the target. + public Reaction React(MoneyWithdrawn e, ReactionContext ctx) + { + return Stage == TransferStage.Withdrawing + ? Reaction.Send(new Deposit(To, Amount)).AndBecome(this with { Stage = TransferStage.Depositing }) + : Reaction.Ignore; + } + + /// The deposit happened: complete. + public Reaction React(MoneyDeposited e, ReactionContext ctx) + { + return Stage == TransferStage.Depositing + ? Reaction.Send(new CompleteTransfer(ctx.Id)).AndComplete() + : Reaction.Ignore; + } + + /// The source account rejected the withdrawal (for example insufficient funds): fail now (ADR-018). + public Reaction React(CommandRejected r, ReactionContext ctx) + { + ArgumentNullException.ThrowIfNull(r); + return Stage == TransferStage.Withdrawing + ? Reaction.Send(new FailTransfer(ctx.Id, r.Error.Code)).AndComplete() + : Reaction.Ignore; + } + + /// The timeout fired: fail, compensating a withdrawal that already happened. + public Reaction React(TransferTimedOut e, ReactionContext ctx) + { + return Stage switch + { + TransferStage.Withdrawing => Reaction.Send(new FailTransfer(ctx.Id, "timeout")).AndComplete(), + TransferStage.Depositing => Reaction.Send(new Deposit(From, Amount)).AndSend(new FailTransfer(ctx.Id, "timeout")).AndComplete(), + _ => Reaction.Ignore, + }; + } +} + +/// The Transfers module. +[SourceFlowModule(typeof(TransfersJsonContext))] +public sealed partial class TransfersModule; + +/// JSON metadata for the Transfers module (DC-1). +[JsonSerializable(typeof(RequestTransfer))] +[JsonSerializable(typeof(CompleteTransfer))] +[JsonSerializable(typeof(FailTransfer))] +[JsonSerializable(typeof(TransferRequested))] +[JsonSerializable(typeof(TransferCompleted))] +[JsonSerializable(typeof(TransferFailed))] +[JsonSerializable(typeof(TransferTimedOut))] +[JsonSerializable(typeof(MoneyTransfer))] +[JsonSerializable(typeof(CommandRejected))] +[JsonSerializable(typeof(Transfer))] +[JsonSourceGenerationOptions(PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase)] +public sealed partial class TransfersJsonContext : JsonSerializerContext; diff --git a/tests/Fixtures/Cloud.AotCheck/Cloud.AotCheck.csproj b/tests/Fixtures/Cloud.AotCheck/Cloud.AotCheck.csproj new file mode 100644 index 00000000..59894193 --- /dev/null +++ b/tests/Fixtures/Cloud.AotCheck/Cloud.AotCheck.csproj @@ -0,0 +1,19 @@ + + + + false + true + + true + + + + + + diff --git a/tests/Fixtures/Cloud.AotCheck/Program.cs b/tests/Fixtures/Cloud.AotCheck/Program.cs new file mode 100644 index 00000000..989e1045 --- /dev/null +++ b/tests/Fixtures/Cloud.AotCheck/Program.cs @@ -0,0 +1,23 @@ +using SourceFlow.Cloud.Aws; +using SourceFlow.Cloud.Azure; +using SourceFlow.Hosting; + +// The cloud AOT check (ARCH-06): a service on each AOT-marked cloud transport (AWS, Azure), published with PublishAot and +// warnings as errors in CI. A service has one transport, so the argument picks it; the AOT compiler analyses both. It is +// never run. The GCP adapter is not AOT-marked (plan 09 IR-08). +WebApplicationBuilder builder = WebApplication.CreateSlimBuilder(args); +string cloud = args.Length > 0 ? args[0] : "aws"; + +builder.Services.AddSourceFlow(sf => +{ + sf.ServiceName = "aot-check"; + sf.Routing(r => r.Subscribe("aot.events")); + sf.UseInMemoryStorage(); + _ = cloud switch + { + "azure" => sf.UseAzureTransport(o => o.FullyQualifiedNamespace = "aot-check.servicebus.windows.net"), + _ => sf.UseAwsTransport(o => o.Region = "eu-west-1"), + }; +}); + +builder.Build().Run(); diff --git a/tests/Fixtures/Directory.Build.props b/tests/Fixtures/Directory.Build.props new file mode 100644 index 00000000..e1364674 --- /dev/null +++ b/tests/Fixtures/Directory.Build.props @@ -0,0 +1,14 @@ + + + + + false + true + true + true + + diff --git a/tests/Fuzz/SourceFlow.Fuzz.Tests/FuzzTargetTests.cs b/tests/Fuzz/SourceFlow.Fuzz.Tests/FuzzTargetTests.cs new file mode 100644 index 00000000..e590fe70 --- /dev/null +++ b/tests/Fuzz/SourceFlow.Fuzz.Tests/FuzzTargetTests.cs @@ -0,0 +1,57 @@ +using SourceFlow.Messaging; + +namespace SourceFlow.Fuzz.Tests; + +/// +/// UT-FUZZ-10..19 (WP-5.5, doc 10 §7): each fuzz target accepts its seeds and survives a bounded, seeded mutation run +/// (repeatable: a finding names its input). Coverage-guided runs with the 2-hour budget per target are libFuzzer in the +/// weekly workflow. +/// +[Trait("Category", "Unit")] +public sealed class FuzzTargetTests +{ + private const int Iterations = 25_000; + + // UT-FUZZ-10..19, in this order. + public static TheoryData Targets { get; } = + [ + "cloudevents-binary", "cloudevents-structured", "aws-wire", "gcp-wire", "azure-wire", + "registry", "protected-payload", "personal-data", "sfql", "sql", + ]; + + [Theory] + [MemberData(nameof(Targets))] + [Trait("Id", "UT-FUZZ-10")] + [Trait("Id", "UT-FUZZ-11")] + [Trait("Id", "UT-FUZZ-12")] + [Trait("Id", "UT-FUZZ-13")] + [Trait("Id", "UT-FUZZ-14")] + [Trait("Id", "UT-FUZZ-15")] + [Trait("Id", "UT-FUZZ-16")] + [Trait("Id", "UT-FUZZ-17")] + [Trait("Id", "UT-FUZZ-18")] + [Trait("Id", "UT-FUZZ-19")] + [Trait("Covers", "doc 10 7")] + public void Target_SurvivesASeededMutationRun(string target) + { + FuzzTargets.Seeds(target).ShouldNotBeEmpty(); + + FuzzFinding? finding = new Mutator(target, seed: 20261113).Run(Iterations, TimeSpan.FromSeconds(60)); + + finding.ShouldBeNull(finding?.ToString()); + } + + [Fact] + [Trait("Id", "UT-FUZZ-20")] + [Trait("Covers", "doc 10 7")] + public void EveryTargetIsCovered_AndItsSeedsAreValidInput() + { + Targets.Select(t => t.Data).Order().ShouldBe(FuzzTargets.All.Keys.Order()); + + // Seeds built by the real encoders decode without being rejected (the mutations start from valid input). + foreach (byte[] seed in FuzzTargets.Seeds("cloudevents-structured")) + { + Should.NotThrow(() => CloudEvents.FromStructured(seed)); + } + } +} diff --git a/tests/Fuzz/SourceFlow.Fuzz.Tests/SourceFlow.Fuzz.Tests.csproj b/tests/Fuzz/SourceFlow.Fuzz.Tests/SourceFlow.Fuzz.Tests.csproj new file mode 100644 index 00000000..257860ea --- /dev/null +++ b/tests/Fuzz/SourceFlow.Fuzz.Tests/SourceFlow.Fuzz.Tests.csproj @@ -0,0 +1,7 @@ + + + + + + diff --git a/tests/Golden/.gitattributes b/tests/Golden/.gitattributes new file mode 100644 index 00000000..9eab79d3 --- /dev/null +++ b/tests/Golden/.gitattributes @@ -0,0 +1,2 @@ +# Golden workflow fixtures are compared byte for byte (round trip, WP-S.10): keep LF everywhere. +* text eol=lf diff --git a/tests/Golden/cases/01-order-fulfilment/expected.bpmn b/tests/Golden/cases/01-order-fulfilment/expected.bpmn new file mode 100644 index 00000000..d0caff72 --- /dev/null +++ b/tests/Golden/cases/01-order-fulfilment/expected.bpmn @@ -0,0 +1,180 @@ + + + + + + + + + + + + + + + + + + + + Reserve stock, take payment, ship. + + Flow_2 + + + + Flow_18 + + + Flow_5 + Flow_6 + Flow_9 + Flow_10 + Flow_11 + Flow_15 + Flow_1 + + + + Flow_1 + + + An operator resumes, retries or aborts the instance. + Flow_16 + Flow_20 + Flow_22 + + + Flow_2 + Flow_3 + + + + + + await inventory.stock-released.v1; retry 5× (exponential, initial PT30S, cap PT10M); timeout PT15M, then manual intervention + + + Flow_3 + Flow_4 + + + Flow_5 + + + + retry 2× (fixed, initial PT0S) + Flow_6 + + PT5M + + + + Flow_4 + Flow_7 + + + + + + await payments.refunded.v1; retry 5× (exponential, initial PT1M); timeout PT30M, then manual intervention + + + Flow_7 + Flow_8 + + + retry 3× (fixed, initial PT10M) + Flow_9 + + + + Flow_10 + + + + retry 2× (fixed, initial PT0S) + Flow_11 + + PT2M + + + + Flow_8 + Flow_12 + Flow_skip_review_large_order + + + Flow_12 + Flow_14 + + + Flow_15 + + + + Flow_16 + + P1D + + + + Pivot: the point of no return. + Flow_skip_review_large_order + Flow_14 + Flow_21 + Flow_17 + + + Flow_17 + Flow_18 + + + Flow_19 + + + + retry 3× (exponential, initial PT5M) + Flow_20 + + PT1H + + + + Flow_19 + Flow_21 + + + Flow_22 + + P2D + + + + + + + + + + + + + + + $data.amount > 5000 + + + + + + + + + + + + + + + diff --git a/tests/Golden/cases/01-order-fulfilment/expected.diagnostics.json b/tests/Golden/cases/01-order-fulfilment/expected.diagnostics.json new file mode 100644 index 00000000..fe51488c --- /dev/null +++ b/tests/Golden/cases/01-order-fulfilment/expected.diagnostics.json @@ -0,0 +1 @@ +[] diff --git a/tests/Golden/cases/01-order-fulfilment/expected.graph.json b/tests/Golden/cases/01-order-fulfilment/expected.graph.json new file mode 100644 index 00000000..bdfb71e9 --- /dev/null +++ b/tests/Golden/cases/01-order-fulfilment/expected.graph.json @@ -0,0 +1,316 @@ +{ + "nodes": [ + { + "id": "start", + "kind": "start", + "label": "orders.order-placed.v1", + "compensable": false + }, + { + "id": "reserve-stock", + "kind": "step", + "label": "reserve-stock", + "sends": "inventory.reserve-stock.v1", + "awaits": "inventory.stock-reserved.v1", + "timeout": "PT5M", + "compensable": true + }, + { + "id": "charge-payment", + "kind": "step", + "label": "charge-payment", + "sends": "payments.charge.v1", + "awaits": "payments.payment-captured.v1", + "timeout": "PT2M", + "compensable": true + }, + { + "id": "review-large-order", + "kind": "step", + "label": "review-large-order", + "awaits": "orders.order-approved.v1", + "when": "$data.amount > 5000", + "timeout": "P1D", + "compensable": false + }, + { + "id": "create-shipment", + "kind": "pivot", + "label": "create-shipment", + "sends": "shipping.create-shipment.v1", + "awaits": "shipping.shipment-created.v1", + "timeout": "PT1H", + "compensable": false + }, + { + "id": "await-address-fix", + "kind": "step", + "label": "await-address-fix", + "awaits": "orders.address-corrected.v1", + "timeout": "P2D", + "compensable": false + }, + { + "id": "Completed", + "kind": "terminal", + "label": "Completed", + "compensable": false + }, + { + "id": "Compensating", + "kind": "compensating", + "label": "Compensating", + "compensable": false + }, + { + "id": "undo:charge-payment", + "kind": "compensation", + "label": "⟲ 1 charge-payment", + "sends": "payments.refund.v1", + "awaits": "payments.refunded.v1", + "parent": "Compensating", + "compensable": false, + "order": 1 + }, + { + "id": "undo:reserve-stock", + "kind": "compensation", + "label": "⟲ 2 reserve-stock", + "sends": "inventory.release-stock.v1", + "awaits": "inventory.stock-released.v1", + "parent": "Compensating", + "compensable": false, + "order": 2 + }, + { + "id": "Compensated", + "kind": "terminal", + "label": "Compensated", + "compensable": false + }, + { + "id": "ManualIntervention", + "kind": "manual", + "label": "✋ Manual intervention", + "compensable": false + } + ], + "edges": [ + { + "id": "start->reserve-stock:start:0", + "source": "start", + "target": "reserve-stock", + "kind": "start", + "label": "▶ orders.order-placed.v1", + "description": "orders.order-placed.v1 starts the workflow at reserve-stock" + }, + { + "id": "reserve-stock->charge-payment:success:0", + "source": "reserve-stock", + "target": "charge-payment", + "kind": "success", + "label": "✓ inventory.stock-reserved.v1", + "description": "Success: inventory.stock-reserved.v1 moves from reserve-stock to charge-payment" + }, + { + "id": "reserve-stock->Compensating:failure:0", + "source": "reserve-stock", + "target": "Compensating", + "kind": "failure", + "label": "✕ inventory.out_of_stock", + "description": "Failure: inventory.out_of_stock at reserve-stock leads to Compensating" + }, + { + "id": "reserve-stock->reserve-stock:retry:0", + "source": "reserve-stock", + "target": "reserve-stock", + "kind": "retry", + "label": "↻ 2× on timeout", + "description": "Retry: reserve-stock is retried 2× when it times out" + }, + { + "id": "reserve-stock->Compensating:timeout:0", + "source": "reserve-stock", + "target": "Compensating", + "kind": "timeout", + "label": "⏱ PT5M", + "description": "Timeout: after PT5M reserve-stock leads to Compensating" + }, + { + "id": "charge-payment->review-large-order:success:0", + "source": "charge-payment", + "target": "review-large-order", + "kind": "success", + "label": "✓ payments.payment-captured.v1", + "description": "Success: payments.payment-captured.v1 moves from charge-payment to review-large-order" + }, + { + "id": "charge-payment->charge-payment:retry:0", + "source": "charge-payment", + "target": "charge-payment", + "kind": "retry", + "label": "↻ 3× every PT10M on payments.declined", + "description": "Retry: charge-payment is retried 3× every PT10M on payments.declined" + }, + { + "id": "charge-payment->Compensating:failure:0", + "source": "charge-payment", + "target": "Compensating", + "kind": "failure", + "label": "✕ payments.declined", + "description": "Failure: payments.declined at charge-payment leads to Compensating" + }, + { + "id": "charge-payment->Compensating:failure:1", + "source": "charge-payment", + "target": "Compensating", + "kind": "failure", + "label": "✕ payments.fraud_suspected", + "description": "Failure: payments.fraud_suspected at charge-payment leads to Compensating" + }, + { + "id": "charge-payment->charge-payment:retry:1", + "source": "charge-payment", + "target": "charge-payment", + "kind": "retry", + "label": "↻ 2× on timeout", + "description": "Retry: charge-payment is retried 2× when it times out" + }, + { + "id": "charge-payment->Compensating:timeout:0", + "source": "charge-payment", + "target": "Compensating", + "kind": "timeout", + "label": "⏱ PT2M", + "description": "Timeout: after PT2M charge-payment leads to Compensating" + }, + { + "id": "review-large-order->create-shipment:success:0", + "source": "review-large-order", + "target": "create-shipment", + "kind": "success", + "label": "✓ orders.order-approved.v1", + "description": "Success: orders.order-approved.v1 moves from review-large-order to create-shipment" + }, + { + "id": "review-large-order->create-shipment:skip:0", + "source": "review-large-order", + "target": "create-shipment", + "kind": "skip", + "label": "⤼ unless $data.amount > 5000", + "description": "review-large-order is skipped to create-shipment unless $data.amount > 5000" + }, + { + "id": "review-large-order->Compensating:failure:0", + "source": "review-large-order", + "target": "Compensating", + "kind": "failure", + "label": "✕ orders.order-rejected-by-review.v1", + "description": "Failure: orders.order-rejected-by-review.v1 at review-large-order leads to Compensating" + }, + { + "id": "review-large-order->ManualIntervention:timeout:0", + "source": "review-large-order", + "target": "ManualIntervention", + "kind": "timeout", + "label": "⏱ P1D", + "description": "Timeout: after P1D review-large-order leads to ManualIntervention" + }, + { + "id": "create-shipment->Completed:success:0", + "source": "create-shipment", + "target": "Completed", + "kind": "success", + "label": "✓ shipping.shipment-created.v1", + "description": "Success: shipping.shipment-created.v1 moves from create-shipment to Completed" + }, + { + "id": "create-shipment->await-address-fix:failure:0", + "source": "create-shipment", + "target": "await-address-fix", + "kind": "failure", + "label": "✕ shipping.address_invalid", + "description": "Failure: shipping.address_invalid at create-shipment leads to await-address-fix" + }, + { + "id": "create-shipment->create-shipment:retry:0", + "source": "create-shipment", + "target": "create-shipment", + "kind": "retry", + "label": "↻ 3× exponential from PT5M on timeout", + "description": "Retry: create-shipment is retried 3× exponential from PT5M when it times out" + }, + { + "id": "create-shipment->ManualIntervention:timeout:0", + "source": "create-shipment", + "target": "ManualIntervention", + "kind": "timeout", + "label": "⏱ PT1H", + "description": "Timeout: after PT1H create-shipment leads to ManualIntervention" + }, + { + "id": "await-address-fix->create-shipment:success:0", + "source": "await-address-fix", + "target": "create-shipment", + "kind": "success", + "label": "✓ orders.address-corrected.v1", + "description": "Success: orders.address-corrected.v1 moves from await-address-fix to create-shipment" + }, + { + "id": "await-address-fix->ManualIntervention:timeout:0", + "source": "await-address-fix", + "target": "ManualIntervention", + "kind": "timeout", + "label": "⏱ P2D", + "description": "Timeout: after P2D await-address-fix leads to ManualIntervention" + }, + { + "id": "Compensating->undo:charge-payment:compensation:0", + "source": "Compensating", + "target": "undo:charge-payment", + "kind": "compensation", + "label": "⟲ most recent first", + "description": "Compensation starts with charge-payment, the most recent completed step" + }, + { + "id": "undo:charge-payment->undo:charge-payment:retry:0", + "source": "undo:charge-payment", + "target": "undo:charge-payment", + "kind": "retry", + "label": "↻ 5× exponential from PT1M", + "description": "Retry: the compensation of charge-payment is retried 5× exponential from PT1M" + }, + { + "id": "undo:charge-payment->undo:reserve-stock:compensation:0", + "source": "undo:charge-payment", + "target": "undo:reserve-stock", + "kind": "compensation", + "label": "⟲ payments.refunded.v1", + "description": "Compensation: charge-payment is undone (payments.refunded.v1), then undo:reserve-stock" + }, + { + "id": "undo:reserve-stock->undo:reserve-stock:retry:0", + "source": "undo:reserve-stock", + "target": "undo:reserve-stock", + "kind": "retry", + "label": "↻ 5× exponential from PT30S", + "description": "Retry: the compensation of reserve-stock is retried 5× exponential from PT30S" + }, + { + "id": "undo:reserve-stock->Compensated:compensation:0", + "source": "undo:reserve-stock", + "target": "Compensated", + "kind": "compensation", + "label": "⟲ inventory.stock-released.v1", + "description": "Compensation: reserve-stock is undone (inventory.stock-released.v1), then Compensated" + }, + { + "id": "Compensating->ManualIntervention:manual:0", + "source": "Compensating", + "target": "ManualIntervention", + "kind": "manual", + "label": "✋ a compensation failed", + "description": "Manual: a compensation that keeps failing needs an operator" + } + ] +} diff --git a/tests/Golden/cases/01-order-fulfilment/expected.mmd b/tests/Golden/cases/01-order-fulfilment/expected.mmd new file mode 100644 index 00000000..1f6b5443 --- /dev/null +++ b/tests/Golden/cases/01-order-fulfilment/expected.mmd @@ -0,0 +1,57 @@ +--- +title: order-fulfilment@1 (orders) +--- +stateDiagram-v2 + state "Compensating" as Compensating + state "Manual intervention" as ManualIntervention + state "reserve-stock" as reserve_stock + reserve_stock : send inventory.reserve-stock.v1 + reserve_stock : await inventory.stock-reserved.v1 + state "charge-payment" as charge_payment + charge_payment : send payments.charge.v1 + charge_payment : await payments.payment-captured.v1 + state "review-large-order" as review_large_order + review_large_order : await orders.order-approved.v1 + state "create-shipment" as create_shipment + create_shipment : ◆ pivot + create_shipment : send shipping.create-shipment.v1 + create_shipment : await shipping.shipment-created.v1 + state "await-address-fix" as await_address_fix + await_address_fix : await orders.address-corrected.v1 + [*] --> reserve_stock : orders.order-placed.v1 + reserve_stock --> charge_payment : ✓ inventory.stock-reserved.v1 + reserve_stock --> Compensating : ✕ inventory.out_of_stock + reserve_stock --> reserve_stock : ↻ 2× on timeout + reserve_stock --> Compensating : ⏱ PT5M + charge_payment --> review_large_order : ✓ payments.payment-captured.v1 + charge_payment --> charge_payment : ↻ 3× every PT10M on payments.declined + charge_payment --> Compensating : ✕ payments.declined + charge_payment --> Compensating : ✕ payments.fraud_suspected + charge_payment --> charge_payment : ↻ 2× on timeout + charge_payment --> Compensating : ⏱ PT2M + review_large_order --> create_shipment : ✓ orders.order-approved.v1 + review_large_order --> create_shipment : skip unless $data.amount > 5000 + review_large_order --> Compensating : ✕ orders.order-rejected-by-review.v1 + review_large_order --> ManualIntervention : ⏱ P1D + create_shipment --> Completed : ✓ shipping.shipment-created.v1 + create_shipment --> await_address_fix : ✕ shipping.address_invalid + create_shipment --> create_shipment : ↻ 3× exponential from PT5M on timeout + create_shipment --> ManualIntervention : ⏱ PT1H + await_address_fix --> create_shipment : ✓ orders.address-corrected.v1 + await_address_fix --> ManualIntervention : ⏱ P2D + state Compensating { + state "⟲ 1 charge-payment" as undo_charge_payment + undo_charge_payment : send payments.refund.v1 + undo_charge_payment --> undo_charge_payment : ↻ 5× exponential from PT1M + state "⟲ 2 reserve-stock" as undo_reserve_stock + undo_reserve_stock : send inventory.release-stock.v1 + undo_reserve_stock --> undo_reserve_stock : ↻ 5× exponential from PT30S + [*] --> undo_charge_payment : most recent first + undo_charge_payment --> undo_reserve_stock : ✓ payments.refunded.v1 + undo_reserve_stock --> [*] : ✓ inventory.stock-released.v1 + } + Compensating --> Compensated : ⟲ all undone + Compensating --> ManualIntervention : ✋ a compensation failed + Completed --> [*] + Compensated --> [*] + ManualIntervention --> [*] : ✋ operator resumes or aborts diff --git a/tests/Golden/cases/01-order-fulfilment/expected.paths.txt b/tests/Golden/cases/01-order-fulfilment/expected.paths.txt new file mode 100644 index 00000000..341bd5c9 --- /dev/null +++ b/tests/Golden/cases/01-order-fulfilment/expected.paths.txt @@ -0,0 +1,439 @@ +P01 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: success ⇒ Completed +P02 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P03 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P04 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P05 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P06 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P07 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P08 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P09 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P10 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P11 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P12 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P13 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P14 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P15 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P16 reserve-stock: success → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P17 reserve-stock: success → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P18 reserve-stock: success → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P19 reserve-stock: success → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P20 reserve-stock: success → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P21 reserve-stock: success → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P22 reserve-stock: success → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout (retries exhausted) ⇒ ManualIntervention +P23 reserve-stock: success → charge-payment: success → review-large-order: timeout ⇒ ManualIntervention +P24 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: success ⇒ Completed +P25 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P26 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P27 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P28 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P29 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P30 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P31 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P32 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P33 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P34 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P35 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P36 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P37 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P38 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P39 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: success ⇒ Completed +P40 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P41 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P42 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P43 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P44 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P45 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P46 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P47 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P48 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P49 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P50 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P51 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P52 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P53 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P54 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P55 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P56 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P57 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P58 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P59 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P60 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout (retries exhausted) ⇒ ManualIntervention +P61 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: timeout ⇒ ManualIntervention +P62 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: success ⇒ Completed +P63 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P64 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P65 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P66 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P67 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P68 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P69 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P70 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P71 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P72 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P73 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P74 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P75 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P76 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P77 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensated ⇒ Compensated +P78 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P79 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P80 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: success ⇒ Completed +P81 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P82 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P83 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P84 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P85 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P86 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P87 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P88 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P89 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P90 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P91 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P92 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P93 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P94 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P95 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P96 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P97 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P98 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P99 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P100 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P101 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout (retries exhausted) ⇒ ManualIntervention +P102 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: timeout ⇒ ManualIntervention +P103 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: success ⇒ Completed +P104 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P105 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P106 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P107 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P108 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P109 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P110 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P111 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P112 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P113 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P114 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P115 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P116 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P117 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P118 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensated ⇒ Compensated +P119 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P120 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P121 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: timeout → charge-payment: timeout (retries exhausted) → reserve-stock: compensated ⇒ Compensated +P122 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: timeout → charge-payment: timeout (retries exhausted) → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P123 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: timeout → charge-payment: timeout (retries exhausted) → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P124 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined (retries exhausted) → reserve-stock: compensated ⇒ Compensated +P125 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined (retries exhausted) → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P126 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined (retries exhausted) → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P127 reserve-stock: success → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensated ⇒ Compensated +P128 reserve-stock: success → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P129 reserve-stock: success → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P130 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: success ⇒ Completed +P131 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P132 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P133 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P134 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P135 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P136 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P137 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P138 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P139 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P140 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P141 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P142 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P143 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P144 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P145 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P146 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P147 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P148 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P149 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P150 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P151 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout (retries exhausted) ⇒ ManualIntervention +P152 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: timeout ⇒ ManualIntervention +P153 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: success ⇒ Completed +P154 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P155 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P156 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P157 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P158 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P159 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P160 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P161 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P162 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P163 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P164 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P165 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P166 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P167 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P168 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: success ⇒ Completed +P169 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P170 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P171 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P172 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P173 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P174 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P175 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P176 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P177 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P178 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P179 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P180 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P181 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P182 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P183 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P184 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P185 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P186 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P187 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P188 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P189 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout (retries exhausted) ⇒ ManualIntervention +P190 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: timeout ⇒ ManualIntervention +P191 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: success ⇒ Completed +P192 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P193 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P194 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P195 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P196 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P197 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P198 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P199 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P200 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P201 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P202 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P203 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P204 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P205 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P206 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensated ⇒ Compensated +P207 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P208 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P209 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined (retries exhausted) → reserve-stock: compensated ⇒ Compensated +P210 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined (retries exhausted) → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P211 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined (retries exhausted) → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P212 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensated ⇒ Compensated +P213 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P214 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P215 reserve-stock: success → charge-payment: timeout → charge-payment: timeout → charge-payment: timeout (retries exhausted) → reserve-stock: compensated ⇒ Compensated +P216 reserve-stock: success → charge-payment: timeout → charge-payment: timeout → charge-payment: timeout (retries exhausted) → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P217 reserve-stock: success → charge-payment: timeout → charge-payment: timeout → charge-payment: timeout (retries exhausted) → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P218 reserve-stock: rejected inventory.out_of_stock ⇒ Compensated +P219 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: success ⇒ Completed +P220 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P221 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P222 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P223 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P224 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P225 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P226 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P227 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P228 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P229 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P230 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P231 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P232 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P233 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P234 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P235 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P236 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P237 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P238 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P239 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P240 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout (retries exhausted) ⇒ ManualIntervention +P241 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: timeout ⇒ ManualIntervention +P242 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: success ⇒ Completed +P243 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P244 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P245 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P246 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P247 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P248 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P249 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P250 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P251 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P252 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P253 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P254 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P255 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P256 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P257 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: success ⇒ Completed +P258 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P259 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P260 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P261 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P262 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P263 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P264 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P265 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P266 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P267 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P268 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P269 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P270 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P271 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P272 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P273 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P274 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P275 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P276 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P277 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P278 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout (retries exhausted) ⇒ ManualIntervention +P279 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: timeout ⇒ ManualIntervention +P280 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: success ⇒ Completed +P281 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P282 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P283 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P284 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P285 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P286 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P287 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P288 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P289 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P290 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P291 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P292 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P293 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P294 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P295 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensated ⇒ Compensated +P296 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P297 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P298 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: success ⇒ Completed +P299 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P300 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P301 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P302 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P303 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P304 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P305 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P306 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P307 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P308 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P309 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P310 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P311 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P312 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P313 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P314 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P315 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P316 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P317 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P318 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P319 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout (retries exhausted) ⇒ ManualIntervention +P320 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: timeout ⇒ ManualIntervention +P321 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: success ⇒ Completed +P322 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P323 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P324 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P325 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P326 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P327 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P328 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P329 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P330 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P331 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P332 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P333 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P334 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P335 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P336 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensated ⇒ Compensated +P337 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P338 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P339 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: timeout → charge-payment: timeout (retries exhausted) → reserve-stock: compensated ⇒ Compensated +P340 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: timeout → charge-payment: timeout (retries exhausted) → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P341 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: timeout → charge-payment: timeout (retries exhausted) → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P342 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined (retries exhausted) → reserve-stock: compensated ⇒ Compensated +P343 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined (retries exhausted) → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P344 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined (retries exhausted) → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P345 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensated ⇒ Compensated +P346 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P347 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P348 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: success ⇒ Completed +P349 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P350 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P351 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P352 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P353 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P354 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P355 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P356 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P357 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P358 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P359 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P360 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P361 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P362 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P363 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P364 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P365 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P366 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P367 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P368 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P369 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout (retries exhausted) ⇒ ManualIntervention +P370 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: timeout ⇒ ManualIntervention +P371 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: success ⇒ Completed +P372 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P373 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P374 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P375 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P376 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P377 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P378 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P379 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P380 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P381 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P382 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P383 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P384 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P385 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P386 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: success ⇒ Completed +P387 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P388 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P389 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P390 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P391 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P392 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P393 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P394 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P395 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P396 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P397 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P398 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P399 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P400 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P401 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P402 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P403 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P404 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P405 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P406 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P407 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout (retries exhausted) ⇒ ManualIntervention +P408 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: timeout ⇒ ManualIntervention +P409 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: success ⇒ Completed +P410 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P411 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P412 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P413 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P414 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P415 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P416 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P417 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P418 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P419 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P420 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P421 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P422 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P423 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P424 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensated ⇒ Compensated +P425 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P426 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P427 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined (retries exhausted) → reserve-stock: compensated ⇒ Compensated +P428 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined (retries exhausted) → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P429 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined (retries exhausted) → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P430 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensated ⇒ Compensated +P431 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P432 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P433 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: timeout → charge-payment: timeout (retries exhausted) → reserve-stock: compensated ⇒ Compensated +P434 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: timeout → charge-payment: timeout (retries exhausted) → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P435 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: timeout → charge-payment: timeout (retries exhausted) → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P436 reserve-stock: timeout → reserve-stock: rejected inventory.out_of_stock ⇒ Compensated +P437 reserve-stock: timeout → reserve-stock: timeout → reserve-stock: timeout (retries exhausted) ⇒ Compensated + +edges: 25, uncovered: none diff --git a/tests/Golden/cases/01-order-fulfilment/expected.specs.cs b/tests/Golden/cases/01-order-fulfilment/expected.specs.cs new file mode 100644 index 00000000..2793db79 --- /dev/null +++ b/tests/Golden/cases/01-order-fulfilment/expected.specs.cs @@ -0,0 +1,137 @@ +// +// Generated by SourceFlow Studio from order-fulfilment@1 (sha256:fce7254988d2015b). +// One test per path; regenerate after changing the workflow (edits are overwritten). +// +#nullable enable +using SourceFlow.Testing; +using SourceFlow.Workflows; +using Xunit; + +namespace Orders.Tests; + +public sealed class OrderFulfilmentV1PathTests +{ + /// P04 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed + [Fact] + public void P04_Completed() + { + var spec = WorkflowSpec.For(); + spec.Start("orders.order-placed.v1", """{"orderId":"bdcbea6c-2dc6-58e2-8f01-846c12116012","total":5001,"lines":[],"customerEmail":"sample-customerEmail","priority":false}""") + .ThenSends("inventory.reserve-stock.v1"); + spec.Succeed("inventory.stock-reserved.v1", """{"orderId":"bdcbea6c-2dc6-58e2-8f01-846c12116012"}""") + .ThenSends("payments.charge.v1"); + spec.Succeed("payments.payment-captured.v1", """{"paymentId":"4c2c1c1b-efe8-55fa-ba4c-a3259738ac48","orderId":"bdcbea6c-2dc6-58e2-8f01-846c12116012","amount":100,"cardHolder":"sample-cardHolder"}""") + .ThenSends(); + spec.Succeed("orders.order-approved.v1", """{"orderId":"bdcbea6c-2dc6-58e2-8f01-846c12116012"}""") + .ThenSends("shipping.create-shipment.v1"); + spec.Reject("shipping.address_invalid") + .ThenSends(); + spec.Succeed("orders.address-corrected.v1", """{"orderId":"bdcbea6c-2dc6-58e2-8f01-846c12116012"}""") + .ThenSends("shipping.create-shipment.v1"); + spec.FireTimer() + .ThenSends(); + spec.FireTimer() + .ThenSends("shipping.create-shipment.v1"); + spec.Succeed("shipping.shipment-created.v1", """{"orderId":"bdcbea6c-2dc6-58e2-8f01-846c12116012","shipmentId":"50f39b5b-0cc0-5554-9fa8-b1598bb338ea"}""") + .ThenSends("orders.mark-fulfilled.v1"); + spec.ThenStatus(WorkflowStatus.Completed); + } + + /// P23 reserve-stock: success → charge-payment: success → review-large-order: timeout ⇒ ManualIntervention + [Fact] + public void P23_ManualIntervention() + { + var spec = WorkflowSpec.For(); + spec.Start("orders.order-placed.v1", """{"orderId":"bdcbea6c-2dc6-58e2-8f01-846c12116012","total":5001,"lines":[],"customerEmail":"sample-customerEmail","priority":false}""") + .ThenSends("inventory.reserve-stock.v1"); + spec.Succeed("inventory.stock-reserved.v1", """{"orderId":"bdcbea6c-2dc6-58e2-8f01-846c12116012"}""") + .ThenSends("payments.charge.v1"); + spec.Succeed("payments.payment-captured.v1", """{"paymentId":"4c2c1c1b-efe8-55fa-ba4c-a3259738ac48","orderId":"bdcbea6c-2dc6-58e2-8f01-846c12116012","amount":100,"cardHolder":"sample-cardHolder"}""") + .ThenSends(); + spec.FireTimer() + .ThenSends(); + spec.ThenStatus(WorkflowStatus.ManualIntervention); + } + + /// P30 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention + [Fact] + public void P30_ManualIntervention() + { + var spec = WorkflowSpec.For(); + spec.Start("orders.order-placed.v1", """{"orderId":"bdcbea6c-2dc6-58e2-8f01-846c12116012","total":100,"lines":[],"customerEmail":"sample-customerEmail","priority":false}""") + .ThenSends("inventory.reserve-stock.v1"); + spec.Succeed("inventory.stock-reserved.v1", """{"orderId":"bdcbea6c-2dc6-58e2-8f01-846c12116012"}""") + .ThenSends("payments.charge.v1"); + spec.Succeed("payments.payment-captured.v1", """{"paymentId":"4c2c1c1b-efe8-55fa-ba4c-a3259738ac48","orderId":"bdcbea6c-2dc6-58e2-8f01-846c12116012","amount":100,"cardHolder":"sample-cardHolder"}""") + .ThenSends("shipping.create-shipment.v1"); + spec.Reject("shipping.address_invalid") + .ThenSends(); + spec.FireTimer() + .ThenSends(); + spec.ThenStatus(WorkflowStatus.ManualIntervention); + } + + /// P127 reserve-stock: success → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensated ⇒ Compensated + [Fact] + public void P127_Compensated() + { + var spec = WorkflowSpec.For(); + spec.Start("orders.order-placed.v1", """{"orderId":"bdcbea6c-2dc6-58e2-8f01-846c12116012","total":100,"lines":[],"customerEmail":"sample-customerEmail","priority":false}""") + .ThenSends("inventory.reserve-stock.v1"); + spec.Succeed("inventory.stock-reserved.v1", """{"orderId":"bdcbea6c-2dc6-58e2-8f01-846c12116012"}""") + .ThenSends("payments.charge.v1"); + spec.Reject("payments.fraud_suspected") + .ThenSends("inventory.release-stock.v1"); + spec.Succeed("inventory.stock-released.v1", """{"orderId":"bdcbea6c-2dc6-58e2-8f01-846c12116012"}""") + .ThenSends("orders.cancel-order.v1"); + spec.ThenStatus(WorkflowStatus.Compensated); + } + + /// P218 reserve-stock: rejected inventory.out_of_stock ⇒ Compensated + [Fact] + public void P218_Compensated() + { + var spec = WorkflowSpec.For(); + spec.Start("orders.order-placed.v1", """{"orderId":"bdcbea6c-2dc6-58e2-8f01-846c12116012","total":100,"lines":[],"customerEmail":"sample-customerEmail","priority":false}""") + .ThenSends("inventory.reserve-stock.v1"); + spec.Reject("inventory.out_of_stock") + .ThenSends("orders.cancel-order.v1"); + spec.ThenStatus(WorkflowStatus.Compensated); + } + + /// P317 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated + [Fact] + public void P317_Compensated() + { + var spec = WorkflowSpec.For(); + spec.Start("orders.order-placed.v1", """{"orderId":"bdcbea6c-2dc6-58e2-8f01-846c12116012","total":5001,"lines":[],"customerEmail":"sample-customerEmail","priority":false}""") + .ThenSends("inventory.reserve-stock.v1"); + spec.FireTimer() + .ThenSends("inventory.reserve-stock.v1"); + spec.Succeed("inventory.stock-reserved.v1", """{"orderId":"bdcbea6c-2dc6-58e2-8f01-846c12116012"}""") + .ThenSends("payments.charge.v1"); + spec.Reject("payments.declined") + .ThenSends(); + spec.FireTimer() + .ThenSends("payments.charge.v1"); + spec.FireTimer() + .ThenSends("payments.charge.v1"); + spec.Succeed("payments.payment-captured.v1", """{"paymentId":"4c2c1c1b-efe8-55fa-ba4c-a3259738ac48","orderId":"bdcbea6c-2dc6-58e2-8f01-846c12116012","amount":100,"cardHolder":"sample-cardHolder"}""") + .ThenSends(); + spec.Fail("orders.order-rejected-by-review.v1", """{"orderId":"bdcbea6c-2dc6-58e2-8f01-846c12116012","reason":"sample-reason"}""") + .ThenSends("payments.refund.v1"); + spec.FireTimer() + .ThenSends(); + spec.FireTimer() + .ThenSends("payments.refund.v1"); + spec.Succeed("payments.refunded.v1", """{"paymentId":"4ca63db0-c8d1-537e-9e50-fa380e457a58","orderId":"bdcbea6c-2dc6-58e2-8f01-846c12116012"}""") + .ThenSends("inventory.release-stock.v1"); + spec.FireTimer() + .ThenSends(); + spec.FireTimer() + .ThenSends("inventory.release-stock.v1"); + spec.Succeed("inventory.stock-released.v1", """{"orderId":"bdcbea6c-2dc6-58e2-8f01-846c12116012"}""") + .ThenSends("orders.cancel-order.v1"); + spec.ThenStatus(WorkflowStatus.Compensated); + } +} diff --git a/tests/Golden/cases/01-order-fulfilment/workflow.sfflow.yaml b/tests/Golden/cases/01-order-fulfilment/workflow.sfflow.yaml new file mode 100644 index 00000000..7fd7d7b9 --- /dev/null +++ b/tests/Golden/cases/01-order-fulfilment/workflow.sfflow.yaml @@ -0,0 +1,77 @@ +sourceflow.workflow: 1 +name: order-fulfilment +version: 1 +owner: orders # generated into the orders service +description: Reserve stock, take payment, ship. + +start: + on: orders.order-placed.v1 # local domain event of the owner + correlate: data.orderId # instance id +data: # instance data, typed from schemas + orderId: { from: start.data.orderId } + amount: { from: start.data.total } + lines: { from: start.data.lines } + +steps: + - id: reserve-stock + send: { command: inventory.reserve-stock.v1, map: { orderId: $data.orderId, lines: $data.lines } } + await: + success: inventory.stock-reserved.v1 + failure: + - rejected: inventory.out_of_stock + then: fail # compensate completed steps (none yet), then Compensated + timeout: { after: PT5M, retry: { max: 2 }, then: fail } + compensate: + send: { command: inventory.release-stock.v1, map: { orderId: $data.orderId } } + await: { success: inventory.stock-released.v1 } + retry: { max: 5, backoff: exponential, initial: PT30S, cap: PT10M } + timeout: { after: PT15M } + + - id: charge-payment + send: { command: payments.charge.v1, map: { orderId: $data.orderId, amount: $data.amount } } + await: + success: + on: payments.payment-captured.v1 + capture: { paymentId: event.data.paymentId } + failure: + - rejected: payments.declined + retry: { max: 3, backoff: fixed, initial: PT10M } # business retry + then: fail + - rejected: payments.fraud_suspected + then: fail + timeout: { after: PT2M, retry: { max: 2 }, then: fail } + compensate: + send: { command: payments.refund.v1, map: { paymentId: $data.paymentId, amount: $data.amount } } + await: { success: payments.refunded.v1 } + retry: { max: 5, backoff: exponential, initial: PT1M } + timeout: { after: PT30M } + + - id: review-large-order + when: "$data.amount > 5000" # CESQL guard; skipped when false + await: + success: orders.order-approved.v1 + failure: + - on: orders.order-rejected-by-review.v1 + then: fail + timeout: { after: P1D, then: manual } + + - id: create-shipment + pivot: true # point of no return + send: { command: shipping.create-shipment.v1, map: { orderId: $data.orderId, lines: $data.lines } } + await: + success: shipping.shipment-created.v1 + failure: + - rejected: shipping.address_invalid + then: { goto: await-address-fix } # forward recovery after pivot + timeout: { after: PT1H, retry: { max: 3, backoff: exponential, initial: PT5M }, then: manual } + next: complete + + - id: await-address-fix + await: { success: orders.address-corrected.v1 } + timeout: { after: P2D, then: manual } + next: create-shipment + +on: + completed: { send: { command: orders.mark-fulfilled.v1, map: { orderId: $data.orderId } } } + compensated: { send: { command: orders.cancel-order.v1, map: { orderId: $data.orderId, reason: $failure.code } } } + manual: { alert: true } # metric + structured log + dead-letter-style record diff --git a/tests/Golden/cases/02-minimal/expected.bpmn b/tests/Golden/cases/02-minimal/expected.bpmn new file mode 100644 index 00000000..06a2ea2a --- /dev/null +++ b/tests/Golden/cases/02-minimal/expected.bpmn @@ -0,0 +1,45 @@ + + + + + + + + Flow_2 + + + + Flow_4 + + + Flow_1 + + + + Flow_1 + + + An operator resumes, retries or aborts the instance. + Flow_5 + + + Flow_2 + Flow_3 + + + Flow_3 + Flow_4 + + + Flow_5 + + PT1H + + + + + + + + + diff --git a/tests/Golden/cases/02-minimal/expected.diagnostics.json b/tests/Golden/cases/02-minimal/expected.diagnostics.json new file mode 100644 index 00000000..fe51488c --- /dev/null +++ b/tests/Golden/cases/02-minimal/expected.diagnostics.json @@ -0,0 +1 @@ +[] diff --git a/tests/Golden/cases/02-minimal/expected.graph.json b/tests/Golden/cases/02-minimal/expected.graph.json new file mode 100644 index 00000000..4255c639 --- /dev/null +++ b/tests/Golden/cases/02-minimal/expected.graph.json @@ -0,0 +1,77 @@ +{ + "nodes": [ + { + "id": "start", + "kind": "start", + "label": "orders.order-placed.v1", + "compensable": false + }, + { + "id": "approve", + "kind": "step", + "label": "approve", + "sends": "orders.approve-order.v1", + "awaits": "orders.order-approved.v1", + "timeout": "PT1H", + "compensable": false + }, + { + "id": "Completed", + "kind": "terminal", + "label": "Completed", + "compensable": false + }, + { + "id": "Compensating", + "kind": "compensating", + "label": "Compensating", + "compensable": false + }, + { + "id": "Compensated", + "kind": "terminal", + "label": "Compensated", + "compensable": false + }, + { + "id": "ManualIntervention", + "kind": "manual", + "label": "✋ Manual intervention", + "compensable": false + } + ], + "edges": [ + { + "id": "start->approve:start:0", + "source": "start", + "target": "approve", + "kind": "start", + "label": "▶ orders.order-placed.v1", + "description": "orders.order-placed.v1 starts the workflow at approve" + }, + { + "id": "approve->Completed:success:0", + "source": "approve", + "target": "Completed", + "kind": "success", + "label": "✓ orders.order-approved.v1", + "description": "Success: orders.order-approved.v1 moves from approve to Completed" + }, + { + "id": "approve->ManualIntervention:timeout:0", + "source": "approve", + "target": "ManualIntervention", + "kind": "timeout", + "label": "⏱ PT1H", + "description": "Timeout: after PT1H approve leads to ManualIntervention" + }, + { + "id": "Compensating->Compensated:compensation:0", + "source": "Compensating", + "target": "Compensated", + "kind": "compensation", + "label": "⟲ nothing to undo", + "description": "Compensation: nothing to undo, the workflow is compensated" + } + ] +} diff --git a/tests/Golden/cases/02-minimal/expected.mmd b/tests/Golden/cases/02-minimal/expected.mmd new file mode 100644 index 00000000..45420079 --- /dev/null +++ b/tests/Golden/cases/02-minimal/expected.mmd @@ -0,0 +1,16 @@ +--- +title: approve-order@1 (orders) +--- +stateDiagram-v2 + state "Compensating" as Compensating + state "Manual intervention" as ManualIntervention + state "approve" as approve + approve : send orders.approve-order.v1 + approve : await orders.order-approved.v1 + [*] --> approve : orders.order-placed.v1 + approve --> Completed : ✓ orders.order-approved.v1 + approve --> ManualIntervention : ⏱ PT1H + Compensating --> Compensated : nothing to undo + Completed --> [*] + Compensated --> [*] + ManualIntervention --> [*] : ✋ operator resumes or aborts diff --git a/tests/Golden/cases/02-minimal/expected.paths.txt b/tests/Golden/cases/02-minimal/expected.paths.txt new file mode 100644 index 00000000..8844a878 --- /dev/null +++ b/tests/Golden/cases/02-minimal/expected.paths.txt @@ -0,0 +1,4 @@ +P01 approve: success ⇒ Completed +P02 approve: timeout ⇒ ManualIntervention + +edges: 2, uncovered: none diff --git a/tests/Golden/cases/02-minimal/workflow.sfflow.yaml b/tests/Golden/cases/02-minimal/workflow.sfflow.yaml new file mode 100644 index 00000000..ef9e812e --- /dev/null +++ b/tests/Golden/cases/02-minimal/workflow.sfflow.yaml @@ -0,0 +1,12 @@ +sourceflow.workflow: 1 +name: approve-order +version: 1 +owner: orders +start: { on: orders.order-placed.v1, correlate: data.orderId } +data: + orderId: { from: start.data.orderId } +steps: + - id: approve + send: { command: orders.approve-order.v1, map: { orderId: $data.orderId } } + await: { success: orders.order-approved.v1 } + timeout: { after: PT1H, then: manual } diff --git a/tests/Golden/cases/03-s01-invalid-yaml/expected.diagnostics.json b/tests/Golden/cases/03-s01-invalid-yaml/expected.diagnostics.json new file mode 100644 index 00000000..4a14876e --- /dev/null +++ b/tests/Golden/cases/03-s01-invalid-yaml/expected.diagnostics.json @@ -0,0 +1,9 @@ +[ + { + "id": "WF-S01", + "severity": "error", + "line": 10, + "column": 4, + "message": "Invalid YAML: While parsing a block collection, did not find expected '-' indicator." + } +] diff --git a/tests/Golden/cases/03-s01-invalid-yaml/workflow.sfflow.yaml b/tests/Golden/cases/03-s01-invalid-yaml/workflow.sfflow.yaml new file mode 100644 index 00000000..d0e0f07b --- /dev/null +++ b/tests/Golden/cases/03-s01-invalid-yaml/workflow.sfflow.yaml @@ -0,0 +1,13 @@ +sourceflow.workflow: 1 +name: approve-order +version: 1 +owner: orders +start: { on: orders.order-placed.v1, correlate: data.orderId } +data: + orderId: { from: start.data.orderId } +steps: + - id: approve + bad: indentation + send: { command: orders.approve-order.v1, map: { orderId: $data.orderId } } + await: { success: orders.order-approved.v1 } + timeout: { after: PT1H, then: manual } diff --git a/tests/Golden/cases/04-s02-unknown-keys/expected.diagnostics.json b/tests/Golden/cases/04-s02-unknown-keys/expected.diagnostics.json new file mode 100644 index 00000000..cdd12bba --- /dev/null +++ b/tests/Golden/cases/04-s02-unknown-keys/expected.diagnostics.json @@ -0,0 +1,16 @@ +[ + { + "id": "WF-S02", + "severity": "error", + "line": 5, + "column": 1, + "message": "Unknown key 'colour' in workflow; expected sourceflow.workflow, name, version, owner, description, start, data, steps, on." + }, + { + "id": "WF-S02", + "severity": "error", + "line": 14, + "column": 5, + "message": "Unknown key 'retries' in step; expected id, send, await, timeout, compensate, pivot, when, next." + } +] diff --git a/tests/Golden/cases/04-s02-unknown-keys/workflow.sfflow.yaml b/tests/Golden/cases/04-s02-unknown-keys/workflow.sfflow.yaml new file mode 100644 index 00000000..e1076674 --- /dev/null +++ b/tests/Golden/cases/04-s02-unknown-keys/workflow.sfflow.yaml @@ -0,0 +1,14 @@ +sourceflow.workflow: 1 +name: approve-order +version: 1 +owner: orders +colour: blue +start: { on: orders.order-placed.v1, correlate: data.orderId } +data: + orderId: { from: start.data.orderId } +steps: + - id: approve + send: { command: orders.approve-order.v1, map: { orderId: $data.orderId } } + await: { success: orders.order-approved.v1 } + timeout: { after: PT1H, then: manual } + retries: 3 diff --git a/tests/Golden/cases/05-s03-shape/expected.diagnostics.json b/tests/Golden/cases/05-s03-shape/expected.diagnostics.json new file mode 100644 index 00000000..a2ddca7a --- /dev/null +++ b/tests/Golden/cases/05-s03-shape/expected.diagnostics.json @@ -0,0 +1,23 @@ +[ + { + "id": "WF-S03", + "severity": "error", + "line": 1, + "column": 1, + "message": "'workflow' needs 'owner'." + }, + { + "id": "WF-S03", + "severity": "error", + "line": 3, + "column": 10, + "message": "'version' is a whole number." + }, + { + "id": "WF-S03", + "severity": "error", + "line": 11, + "column": 35, + "message": "'then' is fail, manual, complete or { goto: }." + } +] diff --git a/tests/Golden/cases/05-s03-shape/workflow.sfflow.yaml b/tests/Golden/cases/05-s03-shape/workflow.sfflow.yaml new file mode 100644 index 00000000..b4c6d4b3 --- /dev/null +++ b/tests/Golden/cases/05-s03-shape/workflow.sfflow.yaml @@ -0,0 +1,11 @@ +sourceflow.workflow: 1 +name: approve-order +version: one +start: { on: orders.order-placed.v1, correlate: data.orderId } +data: + orderId: { from: start.data.orderId } +steps: + - id: approve + send: { command: orders.approve-order.v1, map: { orderId: $data.orderId } } + await: { success: orders.order-approved.v1 } + timeout: { after: PT1H, then: later } diff --git a/tests/Golden/cases/06-s04-schema-version/expected.diagnostics.json b/tests/Golden/cases/06-s04-schema-version/expected.diagnostics.json new file mode 100644 index 00000000..f822adf1 --- /dev/null +++ b/tests/Golden/cases/06-s04-schema-version/expected.diagnostics.json @@ -0,0 +1,9 @@ +[ + { + "id": "WF-S04", + "severity": "error", + "line": 1, + "column": 22, + "message": "This workflow uses sourceflow.workflow 2; this version of SourceFlow reads version 1. Update SourceFlow Studio and the SourceFlow.Net package." + } +] diff --git a/tests/Golden/cases/06-s04-schema-version/workflow.sfflow.yaml b/tests/Golden/cases/06-s04-schema-version/workflow.sfflow.yaml new file mode 100644 index 00000000..e1a5a4f4 --- /dev/null +++ b/tests/Golden/cases/06-s04-schema-version/workflow.sfflow.yaml @@ -0,0 +1,12 @@ +sourceflow.workflow: 2 +name: approve-order +version: 1 +owner: orders +start: { on: orders.order-placed.v1, correlate: data.orderId } +data: + orderId: { from: start.data.orderId } +steps: + - id: approve + send: { command: orders.approve-order.v1, map: { orderId: $data.orderId } } + await: { success: orders.order-approved.v1 } + timeout: { after: PT1H, then: manual } diff --git a/tests/Golden/cases/07-s05-duration/expected.diagnostics.json b/tests/Golden/cases/07-s05-duration/expected.diagnostics.json new file mode 100644 index 00000000..a4381cd3 --- /dev/null +++ b/tests/Golden/cases/07-s05-duration/expected.diagnostics.json @@ -0,0 +1,16 @@ +[ + { + "id": "WF-S05", + "severity": "error", + "line": 12, + "column": 23, + "message": "'5 minutes' is not an ISO-8601 duration such as PT30S, PT5M, PT1H or P1D (years and months are not supported)." + }, + { + "id": "WF-S05", + "severity": "error", + "line": 12, + "column": 74, + "message": "'P1M' is not an ISO-8601 duration such as PT30S, PT5M, PT1H or P1D (years and months are not supported)." + } +] diff --git a/tests/Golden/cases/07-s05-duration/workflow.sfflow.yaml b/tests/Golden/cases/07-s05-duration/workflow.sfflow.yaml new file mode 100644 index 00000000..aef63eb2 --- /dev/null +++ b/tests/Golden/cases/07-s05-duration/workflow.sfflow.yaml @@ -0,0 +1,12 @@ +sourceflow.workflow: 1 +name: approve-order +version: 1 +owner: orders +start: { on: orders.order-placed.v1, correlate: data.orderId } +data: + orderId: { from: start.data.orderId } +steps: + - id: approve + send: { command: orders.approve-order.v1, map: { orderId: $data.orderId } } + await: { success: orders.order-approved.v1 } + timeout: { after: 5 minutes, then: manual, retry: { max: 2, initial: P1M } } diff --git a/tests/Golden/cases/08-s06-format/expected.diagnostics.json b/tests/Golden/cases/08-s06-format/expected.diagnostics.json new file mode 100644 index 00000000..4d34ce99 --- /dev/null +++ b/tests/Golden/cases/08-s06-format/expected.diagnostics.json @@ -0,0 +1,30 @@ +[ + { + "id": "WF-S06", + "severity": "error", + "line": 2, + "column": 7, + "message": "'ApproveOrder' is not a kebab-case name such as 'order-fulfilment'." + }, + { + "id": "WF-S06", + "severity": "error", + "line": 9, + "column": 9, + "message": "'Approve_Order' is not a kebab-case step id such as 'charge-payment'." + }, + { + "id": "WF-S06", + "severity": "error", + "line": 10, + "column": 22, + "message": "'orders.approve-order' is not a command type such as 'payments.charge.v1'." + }, + { + "id": "WF-V01", + "severity": "error", + "line": 10, + "column": 22, + "message": "orders.approve-order (send.command) is not a message type of the workspace." + } +] diff --git a/tests/Golden/cases/08-s06-format/workflow.sfflow.yaml b/tests/Golden/cases/08-s06-format/workflow.sfflow.yaml new file mode 100644 index 00000000..537b0373 --- /dev/null +++ b/tests/Golden/cases/08-s06-format/workflow.sfflow.yaml @@ -0,0 +1,12 @@ +sourceflow.workflow: 1 +name: ApproveOrder +version: 1 +owner: orders +start: { on: orders.order-placed.v1, correlate: data.orderId } +data: + orderId: { from: start.data.orderId } +steps: + - id: Approve_Order + send: { command: orders.approve-order, map: { orderId: $data.orderId } } + await: { success: orders.order-approved.v1 } + timeout: { after: PT1H, then: manual } diff --git a/tests/Golden/cases/09-v01-unknown-type/expected.diagnostics.json b/tests/Golden/cases/09-v01-unknown-type/expected.diagnostics.json new file mode 100644 index 00000000..4f088584 --- /dev/null +++ b/tests/Golden/cases/09-v01-unknown-type/expected.diagnostics.json @@ -0,0 +1,16 @@ +[ + { + "id": "WF-V01", + "severity": "error", + "line": 10, + "column": 22, + "message": "orders.approve-the-order.v1 (send.command) is not a message type of the workspace." + }, + { + "id": "WF-V01", + "severity": "error", + "line": 11, + "column": 23, + "message": "orders.reject-order.v1 is a command, but await.success needs an event." + } +] diff --git a/tests/Golden/cases/09-v01-unknown-type/workflow.sfflow.yaml b/tests/Golden/cases/09-v01-unknown-type/workflow.sfflow.yaml new file mode 100644 index 00000000..44132f46 --- /dev/null +++ b/tests/Golden/cases/09-v01-unknown-type/workflow.sfflow.yaml @@ -0,0 +1,12 @@ +sourceflow.workflow: 1 +name: approve-order +version: 1 +owner: orders +start: { on: orders.order-placed.v1, correlate: data.orderId } +data: + orderId: { from: start.data.orderId } +steps: + - id: approve + send: { command: orders.approve-the-order.v1, map: { orderId: $data.orderId } } + await: { success: orders.reject-order.v1 } + timeout: { after: PT1H, then: manual } diff --git a/tests/Golden/cases/10-v02-command-owner/expected.diagnostics.json b/tests/Golden/cases/10-v02-command-owner/expected.diagnostics.json new file mode 100644 index 00000000..9b163b10 --- /dev/null +++ b/tests/Golden/cases/10-v02-command-owner/expected.diagnostics.json @@ -0,0 +1,30 @@ +[ + { + "id": "WF-V02", + "severity": "error", + "line": 14, + "column": 22, + "message": "legacy.adjust.v1 is owned by orders and shipping; a command has exactly one owner (ADR-007)." + }, + { + "id": "WF-V02", + "severity": "error", + "line": 18, + "column": 22, + "message": "No service of the workspace owns billing.invoice.v1." + }, + { + "id": "WF-V02", + "severity": "error", + "line": 22, + "column": 22, + "message": "orders doesn't route payments.void.v1 to its owner payments; add routing.Command<…>().To(\"payments\")." + }, + { + "id": "WF-V03", + "severity": "error", + "line": 23, + "column": 23, + "message": "orders never receives payments.voided.v1 (step 'void'): it is not a domain event of orders and no service publishes it." + } +] diff --git a/tests/Golden/cases/10-v02-command-owner/workflow.sfflow.yaml b/tests/Golden/cases/10-v02-command-owner/workflow.sfflow.yaml new file mode 100644 index 00000000..cfbbed58 --- /dev/null +++ b/tests/Golden/cases/10-v02-command-owner/workflow.sfflow.yaml @@ -0,0 +1,25 @@ +sourceflow.workflow: 1 +name: approve-order +version: 1 +owner: orders +start: { on: orders.order-placed.v1, correlate: data.orderId } +data: + orderId: { from: start.data.orderId } +steps: + - id: approve + send: { command: orders.approve-order.v1, map: { orderId: $data.orderId } } + await: { success: orders.order-approved.v1 } + timeout: { after: PT1H, then: manual } + - id: adjust + send: { command: legacy.adjust.v1, map: { orderId: $data.orderId } } + await: { success: orders.order-approved.v1 } + timeout: { after: PT1H, then: manual } + - id: invoice + send: { command: billing.invoice.v1, map: { orderId: $data.orderId } } + await: { success: orders.order-approved.v1 } + timeout: { after: PT1H, then: manual } + - id: void + send: { command: payments.void.v1, map: { paymentId: $data.orderId } } + await: { success: payments.voided.v1 } + timeout: { after: PT1H, then: manual } + compensate: { none: true, reason: nothing to undo } diff --git a/tests/Golden/cases/11-v03-unreachable-event/expected.diagnostics.json b/tests/Golden/cases/11-v03-unreachable-event/expected.diagnostics.json new file mode 100644 index 00000000..8a0ca86f --- /dev/null +++ b/tests/Golden/cases/11-v03-unreachable-event/expected.diagnostics.json @@ -0,0 +1,16 @@ +[ + { + "id": "WF-V03", + "severity": "error", + "line": 19, + "column": 16, + "message": "inventory.reserve-stock.v1 doesn't produce payments.refunded.v1 (step 'reserve-stock'); it produces inventory.stock-reserved.v1." + }, + { + "id": "WF-V03", + "severity": "error", + "line": 70, + "column": 23, + "message": "orders never receives inventory.audited.v1 (step 'await-address-fix'): it is published to inventory.events, which orders doesn't subscribe to (or filters out)." + } +] diff --git a/tests/Golden/cases/11-v03-unreachable-event/workflow.sfflow.yaml b/tests/Golden/cases/11-v03-unreachable-event/workflow.sfflow.yaml new file mode 100644 index 00000000..c4020639 --- /dev/null +++ b/tests/Golden/cases/11-v03-unreachable-event/workflow.sfflow.yaml @@ -0,0 +1,77 @@ +sourceflow.workflow: 1 +name: order-fulfilment +version: 1 +owner: orders # generated into the orders service +description: Reserve stock, take payment, ship. + +start: + on: orders.order-placed.v1 # local domain event of the owner + correlate: data.orderId # instance id +data: # instance data, typed from schemas + orderId: { from: start.data.orderId } + amount: { from: start.data.total } + lines: { from: start.data.lines } + +steps: + - id: reserve-stock + send: { command: inventory.reserve-stock.v1, map: { orderId: $data.orderId, lines: $data.lines } } + await: + success: payments.refunded.v1 + failure: + - rejected: inventory.out_of_stock + then: fail # compensate completed steps (none yet), then Compensated + timeout: { after: PT5M, retry: { max: 2 }, then: fail } + compensate: + send: { command: inventory.release-stock.v1, map: { orderId: $data.orderId } } + await: { success: inventory.stock-released.v1 } + retry: { max: 5, backoff: exponential, initial: PT30S, cap: PT10M } + timeout: { after: PT15M } + + - id: charge-payment + send: { command: payments.charge.v1, map: { orderId: $data.orderId, amount: $data.amount } } + await: + success: + on: payments.payment-captured.v1 + capture: { paymentId: event.data.paymentId } + failure: + - rejected: payments.declined + retry: { max: 3, backoff: fixed, initial: PT10M } # business retry + then: fail + - rejected: payments.fraud_suspected + then: fail + timeout: { after: PT2M, retry: { max: 2 }, then: fail } + compensate: + send: { command: payments.refund.v1, map: { paymentId: $data.paymentId, amount: $data.amount } } + await: { success: payments.refunded.v1 } + retry: { max: 5, backoff: exponential, initial: PT1M } + timeout: { after: PT30M } + + - id: review-large-order + when: "$data.amount > 5000" # CESQL guard; skipped when false + await: + success: orders.order-approved.v1 + failure: + - on: orders.order-rejected-by-review.v1 + then: fail + timeout: { after: P1D, then: manual } + + - id: create-shipment + pivot: true # point of no return + send: { command: shipping.create-shipment.v1, map: { orderId: $data.orderId, lines: $data.lines } } + await: + success: shipping.shipment-created.v1 + failure: + - rejected: shipping.address_invalid + then: { goto: await-address-fix } # forward recovery after pivot + timeout: { after: PT1H, retry: { max: 3, backoff: exponential, initial: PT5M }, then: manual } + next: complete + + - id: await-address-fix + await: { success: inventory.audited.v1 } + timeout: { after: P2D, then: manual } + next: create-shipment + +on: + completed: { send: { command: orders.mark-fulfilled.v1, map: { orderId: $data.orderId } } } + compensated: { send: { command: orders.cancel-order.v1, map: { orderId: $data.orderId, reason: $failure.code } } } + manual: { alert: true } # metric + structured log + dead-letter-style record diff --git a/tests/Golden/cases/12-v04-correlation/expected.diagnostics.json b/tests/Golden/cases/12-v04-correlation/expected.diagnostics.json new file mode 100644 index 00000000..9b0bbacc --- /dev/null +++ b/tests/Golden/cases/12-v04-correlation/expected.diagnostics.json @@ -0,0 +1,16 @@ +[ + { + "id": "WF-V04", + "severity": "error", + "line": 5, + "column": 49, + "message": "'start.correlate' reads 'customerId', which orders.order-placed.v1 doesn't have." + }, + { + "id": "WF-V04", + "severity": "error", + "line": 14, + "column": 23, + "message": "Step 'audit' awaits orders.audit-noted.v1 without sending a command, so it must carry the instance key 'customerId'; it doesn't." + } +] diff --git a/tests/Golden/cases/12-v04-correlation/workflow.sfflow.yaml b/tests/Golden/cases/12-v04-correlation/workflow.sfflow.yaml new file mode 100644 index 00000000..4904dde6 --- /dev/null +++ b/tests/Golden/cases/12-v04-correlation/workflow.sfflow.yaml @@ -0,0 +1,15 @@ +sourceflow.workflow: 1 +name: approve-order +version: 1 +owner: orders +start: { on: orders.order-placed.v1, correlate: data.customerId } +data: + orderId: { from: start.data.orderId } +steps: + - id: approve + send: { command: orders.approve-order.v1, map: { orderId: $data.orderId } } + await: { success: orders.order-approved.v1 } + timeout: { after: PT1H, then: manual } + - id: audit + await: { success: orders.audit-noted.v1 } + timeout: { after: PT1H, then: manual } diff --git a/tests/Golden/cases/13-v05-unreachable-step/expected.diagnostics.json b/tests/Golden/cases/13-v05-unreachable-step/expected.diagnostics.json new file mode 100644 index 00000000..77d522c6 --- /dev/null +++ b/tests/Golden/cases/13-v05-unreachable-step/expected.diagnostics.json @@ -0,0 +1,9 @@ +[ + { + "id": "WF-V05", + "severity": "error", + "line": 14, + "column": 5, + "message": "Step 'orphan' is never reached." + } +] diff --git a/tests/Golden/cases/13-v05-unreachable-step/workflow.sfflow.yaml b/tests/Golden/cases/13-v05-unreachable-step/workflow.sfflow.yaml new file mode 100644 index 00000000..b57a2e31 --- /dev/null +++ b/tests/Golden/cases/13-v05-unreachable-step/workflow.sfflow.yaml @@ -0,0 +1,17 @@ +sourceflow.workflow: 1 +name: approve-order +version: 1 +owner: orders +start: { on: orders.order-placed.v1, correlate: data.orderId } +data: + orderId: { from: start.data.orderId } +steps: + - id: approve + send: { command: orders.approve-order.v1, map: { orderId: $data.orderId } } + await: { success: orders.order-approved.v1 } + timeout: { after: PT1H, then: manual } + next: complete + - id: orphan + send: { command: orders.mark-fulfilled.v1, map: { orderId: $data.orderId } } + await: { success: orders.order-fulfilled.v1 } + timeout: { after: PT1H, then: manual } diff --git a/tests/Golden/cases/14-v05-never-completes/expected.diagnostics.json b/tests/Golden/cases/14-v05-never-completes/expected.diagnostics.json new file mode 100644 index 00000000..d6238152 --- /dev/null +++ b/tests/Golden/cases/14-v05-never-completes/expected.diagnostics.json @@ -0,0 +1,9 @@ +[ + { + "id": "WF-V05", + "severity": "error", + "line": 9, + "column": 3, + "message": "No path reaches Completed." + } +] diff --git a/tests/Golden/cases/14-v05-never-completes/workflow.sfflow.yaml b/tests/Golden/cases/14-v05-never-completes/workflow.sfflow.yaml new file mode 100644 index 00000000..07c2aaf1 --- /dev/null +++ b/tests/Golden/cases/14-v05-never-completes/workflow.sfflow.yaml @@ -0,0 +1,13 @@ +sourceflow.workflow: 1 +name: approve-order +version: 1 +owner: orders +start: { on: orders.order-placed.v1, correlate: data.orderId } +data: + orderId: { from: start.data.orderId } +steps: + - id: approve + send: { command: orders.approve-order.v1, map: { orderId: $data.orderId } } + await: { success: orders.order-approved.v1 } + timeout: { after: PT1H, then: manual } + next: approve diff --git a/tests/Golden/cases/15-v06-timeouts/expected.diagnostics.json b/tests/Golden/cases/15-v06-timeouts/expected.diagnostics.json new file mode 100644 index 00000000..bdb1754b --- /dev/null +++ b/tests/Golden/cases/15-v06-timeouts/expected.diagnostics.json @@ -0,0 +1,23 @@ +[ + { + "id": "WF-V06", + "severity": "error", + "line": 16, + "column": 5, + "message": "Step 'reserve-stock' waits without a timeout; add 'timeout: { after: PT…, then: … }', or 'timeout: { none: true, reason: … }'." + }, + { + "id": "WF-V06", + "severity": "error", + "line": 43, + "column": 7, + "message": "The compensation of 'charge-payment' waits without a timeout; add 'timeout: { after: PT… }'." + }, + { + "id": "WF-V06", + "severity": "error", + "line": 54, + "column": 14, + "message": "'timeout: none' on step 'review-large-order' needs a 'reason'." + } +] diff --git a/tests/Golden/cases/15-v06-timeouts/workflow.sfflow.yaml b/tests/Golden/cases/15-v06-timeouts/workflow.sfflow.yaml new file mode 100644 index 00000000..354249ac --- /dev/null +++ b/tests/Golden/cases/15-v06-timeouts/workflow.sfflow.yaml @@ -0,0 +1,75 @@ +sourceflow.workflow: 1 +name: order-fulfilment +version: 1 +owner: orders # generated into the orders service +description: Reserve stock, take payment, ship. + +start: + on: orders.order-placed.v1 # local domain event of the owner + correlate: data.orderId # instance id +data: # instance data, typed from schemas + orderId: { from: start.data.orderId } + amount: { from: start.data.total } + lines: { from: start.data.lines } + +steps: + - id: reserve-stock + send: { command: inventory.reserve-stock.v1, map: { orderId: $data.orderId, lines: $data.lines } } + await: + success: inventory.stock-reserved.v1 + failure: + - rejected: inventory.out_of_stock + then: fail # compensate completed steps (none yet), then Compensated + compensate: + send: { command: inventory.release-stock.v1, map: { orderId: $data.orderId } } + await: { success: inventory.stock-released.v1 } + retry: { max: 5, backoff: exponential, initial: PT30S, cap: PT10M } + timeout: { after: PT15M } + + - id: charge-payment + send: { command: payments.charge.v1, map: { orderId: $data.orderId, amount: $data.amount } } + await: + success: + on: payments.payment-captured.v1 + capture: { paymentId: event.data.paymentId } + failure: + - rejected: payments.declined + retry: { max: 3, backoff: fixed, initial: PT10M } # business retry + then: fail + - rejected: payments.fraud_suspected + then: fail + timeout: { after: PT2M, retry: { max: 2 }, then: fail } + compensate: + send: { command: payments.refund.v1, map: { paymentId: $data.paymentId, amount: $data.amount } } + await: { success: payments.refunded.v1 } + retry: { max: 5, backoff: exponential, initial: PT1M } + + - id: review-large-order + when: "$data.amount > 5000" # CESQL guard; skipped when false + await: + success: orders.order-approved.v1 + failure: + - on: orders.order-rejected-by-review.v1 + then: fail + timeout: { none: true } + + - id: create-shipment + pivot: true # point of no return + send: { command: shipping.create-shipment.v1, map: { orderId: $data.orderId, lines: $data.lines } } + await: + success: shipping.shipment-created.v1 + failure: + - rejected: shipping.address_invalid + then: { goto: await-address-fix } # forward recovery after pivot + timeout: { after: PT1H, retry: { max: 3, backoff: exponential, initial: PT5M }, then: manual } + next: complete + + - id: await-address-fix + await: { success: orders.address-corrected.v1 } + timeout: { after: P2D, then: manual } + next: create-shipment + +on: + completed: { send: { command: orders.mark-fulfilled.v1, map: { orderId: $data.orderId } } } + compensated: { send: { command: orders.cancel-order.v1, map: { orderId: $data.orderId, reason: $failure.code } } } + manual: { alert: true } # metric + structured log + dead-letter-style record diff --git a/tests/Golden/cases/16-v07-pivot/expected.diagnostics.json b/tests/Golden/cases/16-v07-pivot/expected.diagnostics.json new file mode 100644 index 00000000..18843e2a --- /dev/null +++ b/tests/Golden/cases/16-v07-pivot/expected.diagnostics.json @@ -0,0 +1,37 @@ +[ + { + "id": "WF-V07", + "severity": "error", + "line": 64, + "column": 11, + "message": "Step 'create-shipment' is at or after the pivot, so a failure can't 'fail' (no compensation after the point of no return); use manual, complete or goto." + }, + { + "id": "WF-V07", + "severity": "error", + "line": 68, + "column": 7, + "message": "Step 'create-shipment' is at or after the pivot, so it can't be compensated; recover forward instead." + }, + { + "id": "WF-V05", + "severity": "error", + "line": 72, + "column": 5, + "message": "Step 'await-address-fix' is never reached." + }, + { + "id": "WF-V07", + "severity": "error", + "line": 74, + "column": 34, + "message": "Step 'await-address-fix' is at or after the pivot, so its timeout can't 'fail' (no compensation after the point of no return); use manual or goto." + }, + { + "id": "WF-V07", + "severity": "error", + "line": 75, + "column": 12, + "message": "A workflow has one pivot; 'create-shipment' is already the pivot." + } +] diff --git a/tests/Golden/cases/16-v07-pivot/workflow.sfflow.yaml b/tests/Golden/cases/16-v07-pivot/workflow.sfflow.yaml new file mode 100644 index 00000000..188192b5 --- /dev/null +++ b/tests/Golden/cases/16-v07-pivot/workflow.sfflow.yaml @@ -0,0 +1,81 @@ +sourceflow.workflow: 1 +name: order-fulfilment +version: 1 +owner: orders # generated into the orders service +description: Reserve stock, take payment, ship. + +start: + on: orders.order-placed.v1 # local domain event of the owner + correlate: data.orderId # instance id +data: # instance data, typed from schemas + orderId: { from: start.data.orderId } + amount: { from: start.data.total } + lines: { from: start.data.lines } + +steps: + - id: reserve-stock + send: { command: inventory.reserve-stock.v1, map: { orderId: $data.orderId, lines: $data.lines } } + await: + success: inventory.stock-reserved.v1 + failure: + - rejected: inventory.out_of_stock + then: fail # compensate completed steps (none yet), then Compensated + timeout: { after: PT5M, retry: { max: 2 }, then: fail } + compensate: + send: { command: inventory.release-stock.v1, map: { orderId: $data.orderId } } + await: { success: inventory.stock-released.v1 } + retry: { max: 5, backoff: exponential, initial: PT30S, cap: PT10M } + timeout: { after: PT15M } + + - id: charge-payment + send: { command: payments.charge.v1, map: { orderId: $data.orderId, amount: $data.amount } } + await: + success: + on: payments.payment-captured.v1 + capture: { paymentId: event.data.paymentId } + failure: + - rejected: payments.declined + retry: { max: 3, backoff: fixed, initial: PT10M } # business retry + then: fail + - rejected: payments.fraud_suspected + then: fail + timeout: { after: PT2M, retry: { max: 2 }, then: fail } + compensate: + send: { command: payments.refund.v1, map: { paymentId: $data.paymentId, amount: $data.amount } } + await: { success: payments.refunded.v1 } + retry: { max: 5, backoff: exponential, initial: PT1M } + timeout: { after: PT30M } + + - id: review-large-order + when: "$data.amount > 5000" # CESQL guard; skipped when false + await: + success: orders.order-approved.v1 + failure: + - on: orders.order-rejected-by-review.v1 + then: fail + timeout: { after: P1D, then: manual } + + - id: create-shipment + pivot: true # point of no return + send: { command: shipping.create-shipment.v1, map: { orderId: $data.orderId, lines: $data.lines } } + await: + success: shipping.shipment-created.v1 + failure: + - rejected: shipping.address_invalid + timeout: { after: PT1H, retry: { max: 3, backoff: exponential, initial: PT5M }, then: manual } + next: complete + compensate: + send: { command: orders.cancel-order.v1, map: { orderId: $data.orderId, reason: undo } } + await: { success: orders.order-cancelled.v1 } + timeout: { after: PT1M } + + - id: await-address-fix + await: { success: orders.address-corrected.v1 } + timeout: { after: P2D, then: fail } + pivot: true + next: create-shipment + +on: + completed: { send: { command: orders.mark-fulfilled.v1, map: { orderId: $data.orderId } } } + compensated: { send: { command: orders.cancel-order.v1, map: { orderId: $data.orderId, reason: $failure.code } } } + manual: { alert: true } # metric + structured log + dead-letter-style record diff --git a/tests/Golden/cases/17-v08-rejections/expected.diagnostics.json b/tests/Golden/cases/17-v08-rejections/expected.diagnostics.json new file mode 100644 index 00000000..7558a842 --- /dev/null +++ b/tests/Golden/cases/17-v08-rejections/expected.diagnostics.json @@ -0,0 +1,30 @@ +[ + { + "id": "WF-V08", + "severity": "error", + "line": 34, + "column": 21, + "message": "inventory.release-stock.v1 never rejects with 'inventory.out_of_stock'." + }, + { + "id": "WF-V08", + "severity": "error", + "line": 34, + "column": 21, + "message": "orders doesn't receive rejections of inventory.release-stock.v1; add .ReplyOnReject() to its route." + }, + { + "id": "WF-V08", + "severity": "error", + "line": 49, + "column": 21, + "message": "payments.charge.v1 never rejects with 'payments.fraud' (it rejects with payments.declined, payments.fraud_suspected)." + }, + { + "id": "WF-V08", + "severity": "error", + "line": 82, + "column": 21, + "message": "'rejected: orders.empty' needs a command; step 'await-address-fix' sends none." + } +] diff --git a/tests/Golden/cases/17-v08-rejections/workflow.sfflow.yaml b/tests/Golden/cases/17-v08-rejections/workflow.sfflow.yaml new file mode 100644 index 00000000..0c92145e --- /dev/null +++ b/tests/Golden/cases/17-v08-rejections/workflow.sfflow.yaml @@ -0,0 +1,90 @@ +sourceflow.workflow: 1 +name: order-fulfilment +version: 1 +owner: orders # generated into the orders service +description: Reserve stock, take payment, ship. + +start: + on: orders.order-placed.v1 # local domain event of the owner + correlate: data.orderId # instance id +data: # instance data, typed from schemas + orderId: { from: start.data.orderId } + amount: { from: start.data.total } + lines: { from: start.data.lines } + +steps: + - id: reserve-stock + send: { command: inventory.reserve-stock.v1, map: { orderId: $data.orderId, lines: $data.lines } } + await: + success: inventory.stock-reserved.v1 + failure: + - rejected: inventory.out_of_stock + then: fail # compensate completed steps (none yet), then Compensated + timeout: { after: PT5M, retry: { max: 2 }, then: fail } + compensate: + send: { command: inventory.release-stock.v1, map: { orderId: $data.orderId } } + await: { success: inventory.stock-released.v1 } + retry: { max: 5, backoff: exponential, initial: PT30S, cap: PT10M } + timeout: { after: PT15M } + - id: release-early + send: { command: inventory.release-stock.v1, map: { orderId: $data.orderId } } + await: + success: inventory.stock-released.v1 + failure: + - rejected: inventory.out_of_stock + then: manual + timeout: { after: PT5M, then: manual } + compensate: { none: true, reason: releasing is its own undo } + + - id: charge-payment + send: { command: payments.charge.v1, map: { orderId: $data.orderId, amount: $data.amount } } + await: + success: + on: payments.payment-captured.v1 + capture: { paymentId: event.data.paymentId } + failure: + - rejected: payments.declined + retry: { max: 3, backoff: fixed, initial: PT10M } # business retry + then: fail + - rejected: payments.fraud + then: fail + timeout: { after: PT2M, retry: { max: 2 }, then: fail } + compensate: + send: { command: payments.refund.v1, map: { paymentId: $data.paymentId, amount: $data.amount } } + await: { success: payments.refunded.v1 } + retry: { max: 5, backoff: exponential, initial: PT1M } + timeout: { after: PT30M } + + - id: review-large-order + when: "$data.amount > 5000" # CESQL guard; skipped when false + await: + success: orders.order-approved.v1 + failure: + - on: orders.order-rejected-by-review.v1 + then: fail + timeout: { after: P1D, then: manual } + + - id: create-shipment + pivot: true # point of no return + send: { command: shipping.create-shipment.v1, map: { orderId: $data.orderId, lines: $data.lines } } + await: + success: shipping.shipment-created.v1 + failure: + - rejected: shipping.address_invalid + then: { goto: await-address-fix } # forward recovery after pivot + timeout: { after: PT1H, retry: { max: 3, backoff: exponential, initial: PT5M }, then: manual } + next: complete + + - id: await-address-fix + await: + success: orders.address-corrected.v1 + failure: + - rejected: orders.empty + then: manual + timeout: { after: P2D, then: manual } + next: create-shipment + +on: + completed: { send: { command: orders.mark-fulfilled.v1, map: { orderId: $data.orderId } } } + compensated: { send: { command: orders.cancel-order.v1, map: { orderId: $data.orderId, reason: $failure.code } } } + manual: { alert: true } # metric + structured log + dead-letter-style record diff --git a/tests/Golden/cases/18-v09-compensation/expected.bpmn b/tests/Golden/cases/18-v09-compensation/expected.bpmn new file mode 100644 index 00000000..21caa068 --- /dev/null +++ b/tests/Golden/cases/18-v09-compensation/expected.bpmn @@ -0,0 +1,164 @@ + + + + + + + + + + + + + + + + + + Reserve stock, take payment, ship. + + Flow_2 + + + + Flow_18 + + + Flow_5 + Flow_6 + Flow_9 + Flow_10 + Flow_11 + Flow_15 + Flow_1 + + + + Flow_1 + + + An operator resumes, retries or aborts the instance. + Flow_16 + Flow_20 + Flow_22 + + + Flow_2 + Flow_3 + + + Flow_3 + Flow_4 + + + Flow_5 + + + + retry 2× (fixed, initial PT0S) + Flow_6 + + PT5M + + + + Flow_4 + Flow_7 + + + Flow_7 + Flow_8 + + + retry 3× (fixed, initial PT10M) + Flow_9 + + + + Flow_10 + + + + retry 2× (fixed, initial PT0S) + Flow_11 + + PT2M + + + + Flow_8 + Flow_12 + Flow_skip_review_large_order + + + Flow_12 + Flow_14 + + + Flow_15 + + + + Flow_16 + + P1D + + + + Pivot: the point of no return. + Flow_skip_review_large_order + Flow_14 + Flow_21 + Flow_17 + + + Flow_17 + Flow_18 + + + Flow_19 + + + + retry 3× (exponential, initial PT5M) + Flow_20 + + PT1H + + + + Flow_19 + Flow_21 + + + Flow_22 + + P2D + + + + + + + + + + + + + + + $data.amount > 5000 + + + + + + + + + + + + + diff --git a/tests/Golden/cases/18-v09-compensation/expected.diagnostics.json b/tests/Golden/cases/18-v09-compensation/expected.diagnostics.json new file mode 100644 index 00000000..38922def --- /dev/null +++ b/tests/Golden/cases/18-v09-compensation/expected.diagnostics.json @@ -0,0 +1,16 @@ +[ + { + "id": "WF-V09", + "severity": "warning", + "line": 24, + "column": 17, + "message": "'compensate: none' needs a 'reason'." + }, + { + "id": "WF-V09", + "severity": "warning", + "line": 26, + "column": 5, + "message": "Step 'charge-payment' changes state in payments before the pivot but has no compensation; add 'compensate', or 'compensate: { none: true, reason: … }'." + } +] diff --git a/tests/Golden/cases/18-v09-compensation/expected.graph.json b/tests/Golden/cases/18-v09-compensation/expected.graph.json new file mode 100644 index 00000000..b44dafd1 --- /dev/null +++ b/tests/Golden/cases/18-v09-compensation/expected.graph.json @@ -0,0 +1,256 @@ +{ + "nodes": [ + { + "id": "start", + "kind": "start", + "label": "orders.order-placed.v1", + "compensable": false + }, + { + "id": "reserve-stock", + "kind": "step", + "label": "reserve-stock", + "sends": "inventory.reserve-stock.v1", + "awaits": "inventory.stock-reserved.v1", + "timeout": "PT5M", + "compensable": false + }, + { + "id": "charge-payment", + "kind": "step", + "label": "charge-payment", + "sends": "payments.charge.v1", + "awaits": "payments.payment-captured.v1", + "timeout": "PT2M", + "compensable": false + }, + { + "id": "review-large-order", + "kind": "step", + "label": "review-large-order", + "awaits": "orders.order-approved.v1", + "when": "$data.amount > 5000", + "timeout": "P1D", + "compensable": false + }, + { + "id": "create-shipment", + "kind": "pivot", + "label": "create-shipment", + "sends": "shipping.create-shipment.v1", + "awaits": "shipping.shipment-created.v1", + "timeout": "PT1H", + "compensable": false + }, + { + "id": "await-address-fix", + "kind": "step", + "label": "await-address-fix", + "awaits": "orders.address-corrected.v1", + "timeout": "P2D", + "compensable": false + }, + { + "id": "Completed", + "kind": "terminal", + "label": "Completed", + "compensable": false + }, + { + "id": "Compensating", + "kind": "compensating", + "label": "Compensating", + "compensable": false + }, + { + "id": "Compensated", + "kind": "terminal", + "label": "Compensated", + "compensable": false + }, + { + "id": "ManualIntervention", + "kind": "manual", + "label": "✋ Manual intervention", + "compensable": false + } + ], + "edges": [ + { + "id": "start->reserve-stock:start:0", + "source": "start", + "target": "reserve-stock", + "kind": "start", + "label": "▶ orders.order-placed.v1", + "description": "orders.order-placed.v1 starts the workflow at reserve-stock" + }, + { + "id": "reserve-stock->charge-payment:success:0", + "source": "reserve-stock", + "target": "charge-payment", + "kind": "success", + "label": "✓ inventory.stock-reserved.v1", + "description": "Success: inventory.stock-reserved.v1 moves from reserve-stock to charge-payment" + }, + { + "id": "reserve-stock->Compensating:failure:0", + "source": "reserve-stock", + "target": "Compensating", + "kind": "failure", + "label": "✕ inventory.out_of_stock", + "description": "Failure: inventory.out_of_stock at reserve-stock leads to Compensating" + }, + { + "id": "reserve-stock->reserve-stock:retry:0", + "source": "reserve-stock", + "target": "reserve-stock", + "kind": "retry", + "label": "↻ 2× on timeout", + "description": "Retry: reserve-stock is retried 2× when it times out" + }, + { + "id": "reserve-stock->Compensating:timeout:0", + "source": "reserve-stock", + "target": "Compensating", + "kind": "timeout", + "label": "⏱ PT5M", + "description": "Timeout: after PT5M reserve-stock leads to Compensating" + }, + { + "id": "charge-payment->review-large-order:success:0", + "source": "charge-payment", + "target": "review-large-order", + "kind": "success", + "label": "✓ payments.payment-captured.v1", + "description": "Success: payments.payment-captured.v1 moves from charge-payment to review-large-order" + }, + { + "id": "charge-payment->charge-payment:retry:0", + "source": "charge-payment", + "target": "charge-payment", + "kind": "retry", + "label": "↻ 3× every PT10M on payments.declined", + "description": "Retry: charge-payment is retried 3× every PT10M on payments.declined" + }, + { + "id": "charge-payment->Compensating:failure:0", + "source": "charge-payment", + "target": "Compensating", + "kind": "failure", + "label": "✕ payments.declined", + "description": "Failure: payments.declined at charge-payment leads to Compensating" + }, + { + "id": "charge-payment->Compensating:failure:1", + "source": "charge-payment", + "target": "Compensating", + "kind": "failure", + "label": "✕ payments.fraud_suspected", + "description": "Failure: payments.fraud_suspected at charge-payment leads to Compensating" + }, + { + "id": "charge-payment->charge-payment:retry:1", + "source": "charge-payment", + "target": "charge-payment", + "kind": "retry", + "label": "↻ 2× on timeout", + "description": "Retry: charge-payment is retried 2× when it times out" + }, + { + "id": "charge-payment->Compensating:timeout:0", + "source": "charge-payment", + "target": "Compensating", + "kind": "timeout", + "label": "⏱ PT2M", + "description": "Timeout: after PT2M charge-payment leads to Compensating" + }, + { + "id": "review-large-order->create-shipment:success:0", + "source": "review-large-order", + "target": "create-shipment", + "kind": "success", + "label": "✓ orders.order-approved.v1", + "description": "Success: orders.order-approved.v1 moves from review-large-order to create-shipment" + }, + { + "id": "review-large-order->create-shipment:skip:0", + "source": "review-large-order", + "target": "create-shipment", + "kind": "skip", + "label": "⤼ unless $data.amount > 5000", + "description": "review-large-order is skipped to create-shipment unless $data.amount > 5000" + }, + { + "id": "review-large-order->Compensating:failure:0", + "source": "review-large-order", + "target": "Compensating", + "kind": "failure", + "label": "✕ orders.order-rejected-by-review.v1", + "description": "Failure: orders.order-rejected-by-review.v1 at review-large-order leads to Compensating" + }, + { + "id": "review-large-order->ManualIntervention:timeout:0", + "source": "review-large-order", + "target": "ManualIntervention", + "kind": "timeout", + "label": "⏱ P1D", + "description": "Timeout: after P1D review-large-order leads to ManualIntervention" + }, + { + "id": "create-shipment->Completed:success:0", + "source": "create-shipment", + "target": "Completed", + "kind": "success", + "label": "✓ shipping.shipment-created.v1", + "description": "Success: shipping.shipment-created.v1 moves from create-shipment to Completed" + }, + { + "id": "create-shipment->await-address-fix:failure:0", + "source": "create-shipment", + "target": "await-address-fix", + "kind": "failure", + "label": "✕ shipping.address_invalid", + "description": "Failure: shipping.address_invalid at create-shipment leads to await-address-fix" + }, + { + "id": "create-shipment->create-shipment:retry:0", + "source": "create-shipment", + "target": "create-shipment", + "kind": "retry", + "label": "↻ 3× exponential from PT5M on timeout", + "description": "Retry: create-shipment is retried 3× exponential from PT5M when it times out" + }, + { + "id": "create-shipment->ManualIntervention:timeout:0", + "source": "create-shipment", + "target": "ManualIntervention", + "kind": "timeout", + "label": "⏱ PT1H", + "description": "Timeout: after PT1H create-shipment leads to ManualIntervention" + }, + { + "id": "await-address-fix->create-shipment:success:0", + "source": "await-address-fix", + "target": "create-shipment", + "kind": "success", + "label": "✓ orders.address-corrected.v1", + "description": "Success: orders.address-corrected.v1 moves from await-address-fix to create-shipment" + }, + { + "id": "await-address-fix->ManualIntervention:timeout:0", + "source": "await-address-fix", + "target": "ManualIntervention", + "kind": "timeout", + "label": "⏱ P2D", + "description": "Timeout: after P2D await-address-fix leads to ManualIntervention" + }, + { + "id": "Compensating->Compensated:compensation:0", + "source": "Compensating", + "target": "Compensated", + "kind": "compensation", + "label": "⟲ nothing to undo", + "description": "Compensation: nothing to undo, the workflow is compensated" + } + ] +} diff --git a/tests/Golden/cases/18-v09-compensation/expected.mmd b/tests/Golden/cases/18-v09-compensation/expected.mmd new file mode 100644 index 00000000..33fdf397 --- /dev/null +++ b/tests/Golden/cases/18-v09-compensation/expected.mmd @@ -0,0 +1,45 @@ +--- +title: order-fulfilment@1 (orders) +--- +stateDiagram-v2 + state "Compensating" as Compensating + state "Manual intervention" as ManualIntervention + state "reserve-stock" as reserve_stock + reserve_stock : send inventory.reserve-stock.v1 + reserve_stock : await inventory.stock-reserved.v1 + state "charge-payment" as charge_payment + charge_payment : send payments.charge.v1 + charge_payment : await payments.payment-captured.v1 + state "review-large-order" as review_large_order + review_large_order : await orders.order-approved.v1 + state "create-shipment" as create_shipment + create_shipment : ◆ pivot + create_shipment : send shipping.create-shipment.v1 + create_shipment : await shipping.shipment-created.v1 + state "await-address-fix" as await_address_fix + await_address_fix : await orders.address-corrected.v1 + [*] --> reserve_stock : orders.order-placed.v1 + reserve_stock --> charge_payment : ✓ inventory.stock-reserved.v1 + reserve_stock --> Compensating : ✕ inventory.out_of_stock + reserve_stock --> reserve_stock : ↻ 2× on timeout + reserve_stock --> Compensating : ⏱ PT5M + charge_payment --> review_large_order : ✓ payments.payment-captured.v1 + charge_payment --> charge_payment : ↻ 3× every PT10M on payments.declined + charge_payment --> Compensating : ✕ payments.declined + charge_payment --> Compensating : ✕ payments.fraud_suspected + charge_payment --> charge_payment : ↻ 2× on timeout + charge_payment --> Compensating : ⏱ PT2M + review_large_order --> create_shipment : ✓ orders.order-approved.v1 + review_large_order --> create_shipment : skip unless $data.amount > 5000 + review_large_order --> Compensating : ✕ orders.order-rejected-by-review.v1 + review_large_order --> ManualIntervention : ⏱ P1D + create_shipment --> Completed : ✓ shipping.shipment-created.v1 + create_shipment --> await_address_fix : ✕ shipping.address_invalid + create_shipment --> create_shipment : ↻ 3× exponential from PT5M on timeout + create_shipment --> ManualIntervention : ⏱ PT1H + await_address_fix --> create_shipment : ✓ orders.address-corrected.v1 + await_address_fix --> ManualIntervention : ⏱ P2D + Compensating --> Compensated : nothing to undo + Completed --> [*] + Compensated --> [*] + ManualIntervention --> [*] : ✋ operator resumes or aborts diff --git a/tests/Golden/cases/18-v09-compensation/expected.paths.txt b/tests/Golden/cases/18-v09-compensation/expected.paths.txt new file mode 100644 index 00000000..ff9571b0 --- /dev/null +++ b/tests/Golden/cases/18-v09-compensation/expected.paths.txt @@ -0,0 +1,343 @@ +P01 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: success ⇒ Completed +P02 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P03 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P04 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P05 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P06 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P07 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P08 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P09 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P10 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P11 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P12 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P13 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P14 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P15 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P16 reserve-stock: success → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 ⇒ Compensated +P17 reserve-stock: success → charge-payment: success → review-large-order: timeout ⇒ ManualIntervention +P18 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: success ⇒ Completed +P19 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P20 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P21 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P22 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P23 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P24 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P25 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P26 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P27 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P28 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P29 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P30 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P31 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P32 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P33 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: success ⇒ Completed +P34 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P35 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P36 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P37 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P38 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P39 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P40 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P41 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P42 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P43 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P44 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P45 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P46 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P47 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P48 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 ⇒ Compensated +P49 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: timeout ⇒ ManualIntervention +P50 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: success ⇒ Completed +P51 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P52 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P53 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P54 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P55 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P56 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P57 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P58 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P59 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P60 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P61 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P62 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P63 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P64 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P65 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.fraud_suspected ⇒ Compensated +P66 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: success ⇒ Completed +P67 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P68 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P69 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P70 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P71 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P72 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P73 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P74 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P75 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P76 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P77 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P78 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P79 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P80 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P81 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 ⇒ Compensated +P82 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: timeout ⇒ ManualIntervention +P83 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: success ⇒ Completed +P84 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P85 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P86 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P87 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P88 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P89 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P90 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P91 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P92 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P93 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P94 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P95 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P96 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P97 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P98 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: rejected payments.fraud_suspected ⇒ Compensated +P99 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: timeout → charge-payment: timeout (retries exhausted) ⇒ Compensated +P100 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined (retries exhausted) ⇒ Compensated +P101 reserve-stock: success → charge-payment: rejected payments.fraud_suspected ⇒ Compensated +P102 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: success ⇒ Completed +P103 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P104 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P105 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P106 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P107 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P108 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P109 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P110 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P111 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P112 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P113 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P114 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P115 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P116 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P117 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 ⇒ Compensated +P118 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: timeout ⇒ ManualIntervention +P119 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: success ⇒ Completed +P120 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P121 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P122 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P123 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P124 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P125 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P126 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P127 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P128 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P129 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P130 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P131 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P132 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P133 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P134 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: success ⇒ Completed +P135 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P136 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P137 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P138 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P139 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P140 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P141 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P142 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P143 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P144 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P145 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P146 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P147 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P148 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P149 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 ⇒ Compensated +P150 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: timeout ⇒ ManualIntervention +P151 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: success ⇒ Completed +P152 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P153 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P154 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P155 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P156 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P157 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P158 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P159 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P160 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P161 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P162 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P163 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P164 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P165 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P166 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.fraud_suspected ⇒ Compensated +P167 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined (retries exhausted) ⇒ Compensated +P168 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.fraud_suspected ⇒ Compensated +P169 reserve-stock: success → charge-payment: timeout → charge-payment: timeout → charge-payment: timeout (retries exhausted) ⇒ Compensated +P170 reserve-stock: rejected inventory.out_of_stock ⇒ Compensated +P171 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: success ⇒ Completed +P172 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P173 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P174 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P175 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P176 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P177 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P178 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P179 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P180 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P181 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P182 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P183 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P184 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P185 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P186 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 ⇒ Compensated +P187 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: timeout ⇒ ManualIntervention +P188 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: success ⇒ Completed +P189 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P190 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P191 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P192 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P193 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P194 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P195 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P196 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P197 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P198 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P199 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P200 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P201 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P202 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P203 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: success ⇒ Completed +P204 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P205 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P206 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P207 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P208 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P209 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P210 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P211 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P212 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P213 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P214 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P215 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P216 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P217 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P218 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 ⇒ Compensated +P219 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: timeout ⇒ ManualIntervention +P220 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: success ⇒ Completed +P221 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P222 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P223 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P224 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P225 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P226 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P227 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P228 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P229 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P230 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P231 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P232 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P233 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P234 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P235 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.fraud_suspected ⇒ Compensated +P236 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: success ⇒ Completed +P237 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P238 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P239 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P240 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P241 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P242 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P243 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P244 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P245 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P246 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P247 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P248 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P249 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P250 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P251 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 ⇒ Compensated +P252 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: timeout ⇒ ManualIntervention +P253 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: success ⇒ Completed +P254 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P255 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P256 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P257 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P258 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P259 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P260 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P261 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P262 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P263 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P264 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P265 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P266 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P267 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P268 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: rejected payments.fraud_suspected ⇒ Compensated +P269 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: timeout → charge-payment: timeout (retries exhausted) ⇒ Compensated +P270 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined (retries exhausted) ⇒ Compensated +P271 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.fraud_suspected ⇒ Compensated +P272 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: success ⇒ Completed +P273 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P274 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P275 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P276 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P277 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P278 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P279 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P280 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P281 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P282 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P283 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P284 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P285 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P286 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P287 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 ⇒ Compensated +P288 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: timeout ⇒ ManualIntervention +P289 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: success ⇒ Completed +P290 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P291 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P292 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P293 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P294 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P295 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P296 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P297 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P298 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P299 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P300 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P301 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P302 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P303 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P304 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: success ⇒ Completed +P305 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P306 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P307 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P308 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P309 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P310 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P311 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P312 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P313 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P314 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P315 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P316 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P317 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P318 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P319 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 ⇒ Compensated +P320 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: timeout ⇒ ManualIntervention +P321 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: success ⇒ Completed +P322 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P323 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P324 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P325 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P326 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P327 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P328 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P329 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P330 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P331 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P332 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P333 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P334 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P335 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P336 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.fraud_suspected ⇒ Compensated +P337 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined (retries exhausted) ⇒ Compensated +P338 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.fraud_suspected ⇒ Compensated +P339 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: timeout → charge-payment: timeout (retries exhausted) ⇒ Compensated +P340 reserve-stock: timeout → reserve-stock: rejected inventory.out_of_stock ⇒ Compensated +P341 reserve-stock: timeout → reserve-stock: timeout → reserve-stock: timeout (retries exhausted) ⇒ Compensated + +edges: 19, uncovered: none diff --git a/tests/Golden/cases/18-v09-compensation/workflow.sfflow.yaml b/tests/Golden/cases/18-v09-compensation/workflow.sfflow.yaml new file mode 100644 index 00000000..ac674553 --- /dev/null +++ b/tests/Golden/cases/18-v09-compensation/workflow.sfflow.yaml @@ -0,0 +1,68 @@ +sourceflow.workflow: 1 +name: order-fulfilment +version: 1 +owner: orders # generated into the orders service +description: Reserve stock, take payment, ship. + +start: + on: orders.order-placed.v1 # local domain event of the owner + correlate: data.orderId # instance id +data: # instance data, typed from schemas + orderId: { from: start.data.orderId } + amount: { from: start.data.total } + lines: { from: start.data.lines } + +steps: + - id: reserve-stock + send: { command: inventory.reserve-stock.v1, map: { orderId: $data.orderId, lines: $data.lines } } + await: + success: inventory.stock-reserved.v1 + failure: + - rejected: inventory.out_of_stock + then: fail # compensate completed steps (none yet), then Compensated + timeout: { after: PT5M, retry: { max: 2 }, then: fail } + compensate: none + + - id: charge-payment + send: { command: payments.charge.v1, map: { orderId: $data.orderId, amount: $data.amount } } + await: + success: + on: payments.payment-captured.v1 + capture: { paymentId: event.data.paymentId } + failure: + - rejected: payments.declined + retry: { max: 3, backoff: fixed, initial: PT10M } # business retry + then: fail + - rejected: payments.fraud_suspected + then: fail + timeout: { after: PT2M, retry: { max: 2 }, then: fail } + + - id: review-large-order + when: "$data.amount > 5000" # CESQL guard; skipped when false + await: + success: orders.order-approved.v1 + failure: + - on: orders.order-rejected-by-review.v1 + then: fail + timeout: { after: P1D, then: manual } + + - id: create-shipment + pivot: true # point of no return + send: { command: shipping.create-shipment.v1, map: { orderId: $data.orderId, lines: $data.lines } } + await: + success: shipping.shipment-created.v1 + failure: + - rejected: shipping.address_invalid + then: { goto: await-address-fix } # forward recovery after pivot + timeout: { after: PT1H, retry: { max: 3, backoff: exponential, initial: PT5M }, then: manual } + next: complete + + - id: await-address-fix + await: { success: orders.address-corrected.v1 } + timeout: { after: P2D, then: manual } + next: create-shipment + +on: + completed: { send: { command: orders.mark-fulfilled.v1, map: { orderId: $data.orderId } } } + compensated: { send: { command: orders.cancel-order.v1, map: { orderId: $data.orderId, reason: $failure.code } } } + manual: { alert: true } # metric + structured log + dead-letter-style record diff --git a/tests/Golden/cases/19-v10-retries/expected.diagnostics.json b/tests/Golden/cases/19-v10-retries/expected.diagnostics.json new file mode 100644 index 00000000..922c3c15 --- /dev/null +++ b/tests/Golden/cases/19-v10-retries/expected.diagnostics.json @@ -0,0 +1,30 @@ +[ + { + "id": "WF-V10", + "severity": "error", + "line": 27, + "column": 21, + "message": "'max' is between 1 and 20 (it is 0); retries are bounded." + }, + { + "id": "WF-V10", + "severity": "error", + "line": 27, + "column": 67, + "message": "'cap' is shorter than 'initial'." + }, + { + "id": "WF-V10", + "severity": "error", + "line": 38, + "column": 25, + "message": "'max' is between 1 and 20 (it is 25); retries are bounded." + }, + { + "id": "WF-V10", + "severity": "error", + "line": 46, + "column": 14, + "message": "Exponential backoff needs an 'initial' delay longer than zero." + } +] diff --git a/tests/Golden/cases/19-v10-retries/workflow.sfflow.yaml b/tests/Golden/cases/19-v10-retries/workflow.sfflow.yaml new file mode 100644 index 00000000..b02a737c --- /dev/null +++ b/tests/Golden/cases/19-v10-retries/workflow.sfflow.yaml @@ -0,0 +1,77 @@ +sourceflow.workflow: 1 +name: order-fulfilment +version: 1 +owner: orders # generated into the orders service +description: Reserve stock, take payment, ship. + +start: + on: orders.order-placed.v1 # local domain event of the owner + correlate: data.orderId # instance id +data: # instance data, typed from schemas + orderId: { from: start.data.orderId } + amount: { from: start.data.total } + lines: { from: start.data.lines } + +steps: + - id: reserve-stock + send: { command: inventory.reserve-stock.v1, map: { orderId: $data.orderId, lines: $data.lines } } + await: + success: inventory.stock-reserved.v1 + failure: + - rejected: inventory.out_of_stock + then: fail # compensate completed steps (none yet), then Compensated + timeout: { after: PT5M, retry: { max: 2 }, then: fail } + compensate: + send: { command: inventory.release-stock.v1, map: { orderId: $data.orderId } } + await: { success: inventory.stock-released.v1 } + retry: { max: 0, backoff: exponential, initial: PT30S, cap: PT10S } + timeout: { after: PT15M } + + - id: charge-payment + send: { command: payments.charge.v1, map: { orderId: $data.orderId, amount: $data.amount } } + await: + success: + on: payments.payment-captured.v1 + capture: { paymentId: event.data.paymentId } + failure: + - rejected: payments.declined + retry: { max: 25, backoff: fixed, initial: PT10M } # business retry + then: fail + - rejected: payments.fraud_suspected + then: fail + timeout: { after: PT2M, retry: { max: 2 }, then: fail } + compensate: + send: { command: payments.refund.v1, map: { paymentId: $data.paymentId, amount: $data.amount } } + await: { success: payments.refunded.v1 } + retry: { max: 5, backoff: exponential } + timeout: { after: PT30M } + + - id: review-large-order + when: "$data.amount > 5000" # CESQL guard; skipped when false + await: + success: orders.order-approved.v1 + failure: + - on: orders.order-rejected-by-review.v1 + then: fail + timeout: { after: P1D, then: manual } + + - id: create-shipment + pivot: true # point of no return + send: { command: shipping.create-shipment.v1, map: { orderId: $data.orderId, lines: $data.lines } } + await: + success: shipping.shipment-created.v1 + failure: + - rejected: shipping.address_invalid + then: { goto: await-address-fix } # forward recovery after pivot + timeout: { after: PT1H, retry: { max: 3, backoff: exponential, initial: PT5M }, then: manual } + next: complete + + - id: await-address-fix + await: { success: orders.address-corrected.v1 } + timeout: { after: P2D, then: manual } + next: create-shipment + +on: + completed: { send: { command: orders.mark-fulfilled.v1, map: { orderId: $data.orderId } } } + compensated: { send: { command: orders.cancel-order.v1, map: { orderId: $data.orderId, reason: $failure.code } } } + manual: { alert: true } # metric + structured log + dead-letter-style record diff --git a/tests/Golden/cases/20-v11-goto/expected.diagnostics.json b/tests/Golden/cases/20-v11-goto/expected.diagnostics.json new file mode 100644 index 00000000..fa33eddc --- /dev/null +++ b/tests/Golden/cases/20-v11-goto/expected.diagnostics.json @@ -0,0 +1,23 @@ +[ + { + "id": "WF-V11", + "severity": "error", + "line": 65, + "column": 17, + "message": "'goto: fix-address' names no step." + }, + { + "id": "WF-V05", + "severity": "error", + "line": 69, + "column": 5, + "message": "Step 'await-address-fix' is never reached." + }, + { + "id": "WF-V11", + "severity": "error", + "line": 72, + "column": 11, + "message": "'next: ship-again' names no step." + } +] diff --git a/tests/Golden/cases/20-v11-goto/workflow.sfflow.yaml b/tests/Golden/cases/20-v11-goto/workflow.sfflow.yaml new file mode 100644 index 00000000..8788daff --- /dev/null +++ b/tests/Golden/cases/20-v11-goto/workflow.sfflow.yaml @@ -0,0 +1,77 @@ +sourceflow.workflow: 1 +name: order-fulfilment +version: 1 +owner: orders # generated into the orders service +description: Reserve stock, take payment, ship. + +start: + on: orders.order-placed.v1 # local domain event of the owner + correlate: data.orderId # instance id +data: # instance data, typed from schemas + orderId: { from: start.data.orderId } + amount: { from: start.data.total } + lines: { from: start.data.lines } + +steps: + - id: reserve-stock + send: { command: inventory.reserve-stock.v1, map: { orderId: $data.orderId, lines: $data.lines } } + await: + success: inventory.stock-reserved.v1 + failure: + - rejected: inventory.out_of_stock + then: fail # compensate completed steps (none yet), then Compensated + timeout: { after: PT5M, retry: { max: 2 }, then: fail } + compensate: + send: { command: inventory.release-stock.v1, map: { orderId: $data.orderId } } + await: { success: inventory.stock-released.v1 } + retry: { max: 5, backoff: exponential, initial: PT30S, cap: PT10M } + timeout: { after: PT15M } + + - id: charge-payment + send: { command: payments.charge.v1, map: { orderId: $data.orderId, amount: $data.amount } } + await: + success: + on: payments.payment-captured.v1 + capture: { paymentId: event.data.paymentId } + failure: + - rejected: payments.declined + retry: { max: 3, backoff: fixed, initial: PT10M } # business retry + then: fail + - rejected: payments.fraud_suspected + then: fail + timeout: { after: PT2M, retry: { max: 2 }, then: fail } + compensate: + send: { command: payments.refund.v1, map: { paymentId: $data.paymentId, amount: $data.amount } } + await: { success: payments.refunded.v1 } + retry: { max: 5, backoff: exponential, initial: PT1M } + timeout: { after: PT30M } + + - id: review-large-order + when: "$data.amount > 5000" # CESQL guard; skipped when false + await: + success: orders.order-approved.v1 + failure: + - on: orders.order-rejected-by-review.v1 + then: fail + timeout: { after: P1D, then: manual } + + - id: create-shipment + pivot: true # point of no return + send: { command: shipping.create-shipment.v1, map: { orderId: $data.orderId, lines: $data.lines } } + await: + success: shipping.shipment-created.v1 + failure: + - rejected: shipping.address_invalid + then: { goto: fix-address } # forward recovery after pivot + timeout: { after: PT1H, retry: { max: 3, backoff: exponential, initial: PT5M }, then: manual } + next: complete + + - id: await-address-fix + await: { success: orders.address-corrected.v1 } + timeout: { after: P2D, then: manual } + next: ship-again + +on: + completed: { send: { command: orders.mark-fulfilled.v1, map: { orderId: $data.orderId } } } + compensated: { send: { command: orders.cancel-order.v1, map: { orderId: $data.orderId, reason: $failure.code } } } + manual: { alert: true } # metric + structured log + dead-letter-style record diff --git a/tests/Golden/cases/21-v12-map/expected.diagnostics.json b/tests/Golden/cases/21-v12-map/expected.diagnostics.json new file mode 100644 index 00000000..e97929b9 --- /dev/null +++ b/tests/Golden/cases/21-v12-map/expected.diagnostics.json @@ -0,0 +1,44 @@ +[ + { + "id": "WF-V12", + "severity": "error", + "line": 31, + "column": 82, + "message": "'amount' of payments.charge.v1 is number; the mapped value is string." + }, + { + "id": "WF-V12", + "severity": "error", + "line": 31, + "column": 90, + "message": "payments.charge.v1 has no field 'currency'." + }, + { + "id": "WF-V12", + "severity": "error", + "line": 60, + "column": 68, + "message": "'event.data.orderId' reads an event, which is only the start event in the first step; capture the value into data and use $data." + }, + { + "id": "WF-V12", + "severity": "error", + "line": 60, + "column": 95, + "message": "There is no data field 'items'; declare it in 'data' or capture it." + }, + { + "id": "WF-V12", + "severity": "error", + "line": 75, + "column": 77, + "message": "'$failure.code' is only available in on.compensated." + }, + { + "id": "WF-V12", + "severity": "error", + "line": 76, + "column": 66, + "message": "orders.cancel-order.v1 needs 'reason'; map it." + } +] diff --git a/tests/Golden/cases/21-v12-map/workflow.sfflow.yaml b/tests/Golden/cases/21-v12-map/workflow.sfflow.yaml new file mode 100644 index 00000000..98d187bc --- /dev/null +++ b/tests/Golden/cases/21-v12-map/workflow.sfflow.yaml @@ -0,0 +1,77 @@ +sourceflow.workflow: 1 +name: order-fulfilment +version: 1 +owner: orders # generated into the orders service +description: Reserve stock, take payment, ship. + +start: + on: orders.order-placed.v1 # local domain event of the owner + correlate: data.orderId # instance id +data: # instance data, typed from schemas + orderId: { from: start.data.orderId } + amount: { from: start.data.total } + lines: { from: start.data.lines } + +steps: + - id: reserve-stock + send: { command: inventory.reserve-stock.v1, map: { orderId: $data.orderId, lines: $data.lines } } + await: + success: inventory.stock-reserved.v1 + failure: + - rejected: inventory.out_of_stock + then: fail # compensate completed steps (none yet), then Compensated + timeout: { after: PT5M, retry: { max: 2 }, then: fail } + compensate: + send: { command: inventory.release-stock.v1, map: { orderId: $data.orderId } } + await: { success: inventory.stock-released.v1 } + retry: { max: 5, backoff: exponential, initial: PT30S, cap: PT10M } + timeout: { after: PT15M } + + - id: charge-payment + send: { command: payments.charge.v1, map: { orderId: $data.orderId, amount: 'lots', currency: EUR } } + await: + success: + on: payments.payment-captured.v1 + capture: { paymentId: event.data.paymentId } + failure: + - rejected: payments.declined + retry: { max: 3, backoff: fixed, initial: PT10M } # business retry + then: fail + - rejected: payments.fraud_suspected + then: fail + timeout: { after: PT2M, retry: { max: 2 }, then: fail } + compensate: + send: { command: payments.refund.v1, map: { paymentId: $data.paymentId, amount: $data.amount } } + await: { success: payments.refunded.v1 } + retry: { max: 5, backoff: exponential, initial: PT1M } + timeout: { after: PT30M } + + - id: review-large-order + when: "$data.amount > 5000" # CESQL guard; skipped when false + await: + success: orders.order-approved.v1 + failure: + - on: orders.order-rejected-by-review.v1 + then: fail + timeout: { after: P1D, then: manual } + + - id: create-shipment + pivot: true # point of no return + send: { command: shipping.create-shipment.v1, map: { orderId: event.data.orderId, lines: $data.items, note: null } } + await: + success: shipping.shipment-created.v1 + failure: + - rejected: shipping.address_invalid + then: { goto: await-address-fix } # forward recovery after pivot + timeout: { after: PT1H, retry: { max: 3, backoff: exponential, initial: PT5M }, then: manual } + next: complete + + - id: await-address-fix + await: { success: orders.address-corrected.v1 } + timeout: { after: P2D, then: manual } + next: create-shipment + +on: + completed: { send: { command: orders.mark-fulfilled.v1, map: { orderId: $failure.code } } } + compensated: { send: { command: orders.cancel-order.v1, map: { orderId: $data.orderId } } } + manual: { alert: true } # metric + structured log + dead-letter-style record diff --git a/tests/Golden/cases/22-v13-guards/expected.diagnostics.json b/tests/Golden/cases/22-v13-guards/expected.diagnostics.json new file mode 100644 index 00000000..66ea5b35 --- /dev/null +++ b/tests/Golden/cases/22-v13-guards/expected.diagnostics.json @@ -0,0 +1,23 @@ +[ + { + "id": "WF-V13", + "severity": "error", + "line": 10, + "column": 9, + "message": "The guard 'event.data.priority = true AND (event.data.total >' doesn't parse: the guard ends early (at character 51)." + }, + { + "id": "WF-V13", + "severity": "error", + "line": 20, + "column": 57, + "message": "The guard 'event.data.sku = 'x' OR $data.unknown' doesn't bind: 'event.data.sku' is not in scope here ($data.* and event.data.* of inventory.stock-reserved.v1)." + }, + { + "id": "WF-V13", + "severity": "error", + "line": 51, + "column": 11, + "message": "The guard '$data.amount > 'big'' doesn't bind: '>' compares a number with text." + } +] diff --git a/tests/Golden/cases/22-v13-guards/workflow.sfflow.yaml b/tests/Golden/cases/22-v13-guards/workflow.sfflow.yaml new file mode 100644 index 00000000..a7ef2f9f --- /dev/null +++ b/tests/Golden/cases/22-v13-guards/workflow.sfflow.yaml @@ -0,0 +1,78 @@ +sourceflow.workflow: 1 +name: order-fulfilment +version: 1 +owner: orders # generated into the orders service +description: Reserve stock, take payment, ship. + +start: + on: orders.order-placed.v1 # local domain event of the owner + correlate: data.orderId # instance id + when: "event.data.priority = true AND (event.data.total >" +data: # instance data, typed from schemas + orderId: { from: start.data.orderId } + amount: { from: start.data.total } + lines: { from: start.data.lines } + +steps: + - id: reserve-stock + send: { command: inventory.reserve-stock.v1, map: { orderId: $data.orderId, lines: $data.lines } } + await: + success: { on: inventory.stock-reserved.v1, when: "event.data.sku = 'x' OR $data.unknown" } + failure: + - rejected: inventory.out_of_stock + then: fail # compensate completed steps (none yet), then Compensated + timeout: { after: PT5M, retry: { max: 2 }, then: fail } + compensate: + send: { command: inventory.release-stock.v1, map: { orderId: $data.orderId } } + await: { success: inventory.stock-released.v1 } + retry: { max: 5, backoff: exponential, initial: PT30S, cap: PT10M } + timeout: { after: PT15M } + + - id: charge-payment + send: { command: payments.charge.v1, map: { orderId: $data.orderId, amount: $data.amount } } + await: + success: + on: payments.payment-captured.v1 + capture: { paymentId: event.data.paymentId } + failure: + - rejected: payments.declined + retry: { max: 3, backoff: fixed, initial: PT10M } # business retry + then: fail + - rejected: payments.fraud_suspected + then: fail + timeout: { after: PT2M, retry: { max: 2 }, then: fail } + compensate: + send: { command: payments.refund.v1, map: { paymentId: $data.paymentId, amount: $data.amount } } + await: { success: payments.refunded.v1 } + retry: { max: 5, backoff: exponential, initial: PT1M } + timeout: { after: PT30M } + + - id: review-large-order + when: "$data.amount > 'big'" # CESQL guard; skipped when false + await: + success: orders.order-approved.v1 + failure: + - on: orders.order-rejected-by-review.v1 + then: fail + timeout: { after: P1D, then: manual } + + - id: create-shipment + pivot: true # point of no return + send: { command: shipping.create-shipment.v1, map: { orderId: $data.orderId, lines: $data.lines } } + await: + success: shipping.shipment-created.v1 + failure: + - rejected: shipping.address_invalid + then: { goto: await-address-fix } # forward recovery after pivot + timeout: { after: PT1H, retry: { max: 3, backoff: exponential, initial: PT5M }, then: manual } + next: complete + + - id: await-address-fix + await: { success: orders.address-corrected.v1 } + timeout: { after: P2D, then: manual } + next: create-shipment + +on: + completed: { send: { command: orders.mark-fulfilled.v1, map: { orderId: $data.orderId } } } + compensated: { send: { command: orders.cancel-order.v1, map: { orderId: $data.orderId, reason: $failure.code } } } + manual: { alert: true } # metric + structured log + dead-letter-style record diff --git a/tests/Golden/cases/23-v14-personal-data/expected.bpmn b/tests/Golden/cases/23-v14-personal-data/expected.bpmn new file mode 100644 index 00000000..d0caff72 --- /dev/null +++ b/tests/Golden/cases/23-v14-personal-data/expected.bpmn @@ -0,0 +1,180 @@ + + + + + + + + + + + + + + + + + + + + Reserve stock, take payment, ship. + + Flow_2 + + + + Flow_18 + + + Flow_5 + Flow_6 + Flow_9 + Flow_10 + Flow_11 + Flow_15 + Flow_1 + + + + Flow_1 + + + An operator resumes, retries or aborts the instance. + Flow_16 + Flow_20 + Flow_22 + + + Flow_2 + Flow_3 + + + + + + await inventory.stock-released.v1; retry 5× (exponential, initial PT30S, cap PT10M); timeout PT15M, then manual intervention + + + Flow_3 + Flow_4 + + + Flow_5 + + + + retry 2× (fixed, initial PT0S) + Flow_6 + + PT5M + + + + Flow_4 + Flow_7 + + + + + + await payments.refunded.v1; retry 5× (exponential, initial PT1M); timeout PT30M, then manual intervention + + + Flow_7 + Flow_8 + + + retry 3× (fixed, initial PT10M) + Flow_9 + + + + Flow_10 + + + + retry 2× (fixed, initial PT0S) + Flow_11 + + PT2M + + + + Flow_8 + Flow_12 + Flow_skip_review_large_order + + + Flow_12 + Flow_14 + + + Flow_15 + + + + Flow_16 + + P1D + + + + Pivot: the point of no return. + Flow_skip_review_large_order + Flow_14 + Flow_21 + Flow_17 + + + Flow_17 + Flow_18 + + + Flow_19 + + + + retry 3× (exponential, initial PT5M) + Flow_20 + + PT1H + + + + Flow_19 + Flow_21 + + + Flow_22 + + P2D + + + + + + + + + + + + + + + $data.amount > 5000 + + + + + + + + + + + + + + + diff --git a/tests/Golden/cases/23-v14-personal-data/expected.diagnostics.json b/tests/Golden/cases/23-v14-personal-data/expected.diagnostics.json new file mode 100644 index 00000000..8532ae3e --- /dev/null +++ b/tests/Golden/cases/23-v14-personal-data/expected.diagnostics.json @@ -0,0 +1,16 @@ +[ + { + "id": "WF-V14", + "severity": "warning", + "line": 14, + "column": 3, + "message": "Data field 'email' copies personal data (orders.order-placed.v1.customerEmail); mark it 'personal: true', or don't keep it." + }, + { + "id": "WF-V14", + "severity": "warning", + "line": 37, + "column": 53, + "message": "The capture 'holder' copies personal data (payments.payment-captured.v1.cardHolder); declare it in 'data' with 'personal: true'." + } +] diff --git a/tests/Golden/cases/23-v14-personal-data/expected.graph.json b/tests/Golden/cases/23-v14-personal-data/expected.graph.json new file mode 100644 index 00000000..bdfb71e9 --- /dev/null +++ b/tests/Golden/cases/23-v14-personal-data/expected.graph.json @@ -0,0 +1,316 @@ +{ + "nodes": [ + { + "id": "start", + "kind": "start", + "label": "orders.order-placed.v1", + "compensable": false + }, + { + "id": "reserve-stock", + "kind": "step", + "label": "reserve-stock", + "sends": "inventory.reserve-stock.v1", + "awaits": "inventory.stock-reserved.v1", + "timeout": "PT5M", + "compensable": true + }, + { + "id": "charge-payment", + "kind": "step", + "label": "charge-payment", + "sends": "payments.charge.v1", + "awaits": "payments.payment-captured.v1", + "timeout": "PT2M", + "compensable": true + }, + { + "id": "review-large-order", + "kind": "step", + "label": "review-large-order", + "awaits": "orders.order-approved.v1", + "when": "$data.amount > 5000", + "timeout": "P1D", + "compensable": false + }, + { + "id": "create-shipment", + "kind": "pivot", + "label": "create-shipment", + "sends": "shipping.create-shipment.v1", + "awaits": "shipping.shipment-created.v1", + "timeout": "PT1H", + "compensable": false + }, + { + "id": "await-address-fix", + "kind": "step", + "label": "await-address-fix", + "awaits": "orders.address-corrected.v1", + "timeout": "P2D", + "compensable": false + }, + { + "id": "Completed", + "kind": "terminal", + "label": "Completed", + "compensable": false + }, + { + "id": "Compensating", + "kind": "compensating", + "label": "Compensating", + "compensable": false + }, + { + "id": "undo:charge-payment", + "kind": "compensation", + "label": "⟲ 1 charge-payment", + "sends": "payments.refund.v1", + "awaits": "payments.refunded.v1", + "parent": "Compensating", + "compensable": false, + "order": 1 + }, + { + "id": "undo:reserve-stock", + "kind": "compensation", + "label": "⟲ 2 reserve-stock", + "sends": "inventory.release-stock.v1", + "awaits": "inventory.stock-released.v1", + "parent": "Compensating", + "compensable": false, + "order": 2 + }, + { + "id": "Compensated", + "kind": "terminal", + "label": "Compensated", + "compensable": false + }, + { + "id": "ManualIntervention", + "kind": "manual", + "label": "✋ Manual intervention", + "compensable": false + } + ], + "edges": [ + { + "id": "start->reserve-stock:start:0", + "source": "start", + "target": "reserve-stock", + "kind": "start", + "label": "▶ orders.order-placed.v1", + "description": "orders.order-placed.v1 starts the workflow at reserve-stock" + }, + { + "id": "reserve-stock->charge-payment:success:0", + "source": "reserve-stock", + "target": "charge-payment", + "kind": "success", + "label": "✓ inventory.stock-reserved.v1", + "description": "Success: inventory.stock-reserved.v1 moves from reserve-stock to charge-payment" + }, + { + "id": "reserve-stock->Compensating:failure:0", + "source": "reserve-stock", + "target": "Compensating", + "kind": "failure", + "label": "✕ inventory.out_of_stock", + "description": "Failure: inventory.out_of_stock at reserve-stock leads to Compensating" + }, + { + "id": "reserve-stock->reserve-stock:retry:0", + "source": "reserve-stock", + "target": "reserve-stock", + "kind": "retry", + "label": "↻ 2× on timeout", + "description": "Retry: reserve-stock is retried 2× when it times out" + }, + { + "id": "reserve-stock->Compensating:timeout:0", + "source": "reserve-stock", + "target": "Compensating", + "kind": "timeout", + "label": "⏱ PT5M", + "description": "Timeout: after PT5M reserve-stock leads to Compensating" + }, + { + "id": "charge-payment->review-large-order:success:0", + "source": "charge-payment", + "target": "review-large-order", + "kind": "success", + "label": "✓ payments.payment-captured.v1", + "description": "Success: payments.payment-captured.v1 moves from charge-payment to review-large-order" + }, + { + "id": "charge-payment->charge-payment:retry:0", + "source": "charge-payment", + "target": "charge-payment", + "kind": "retry", + "label": "↻ 3× every PT10M on payments.declined", + "description": "Retry: charge-payment is retried 3× every PT10M on payments.declined" + }, + { + "id": "charge-payment->Compensating:failure:0", + "source": "charge-payment", + "target": "Compensating", + "kind": "failure", + "label": "✕ payments.declined", + "description": "Failure: payments.declined at charge-payment leads to Compensating" + }, + { + "id": "charge-payment->Compensating:failure:1", + "source": "charge-payment", + "target": "Compensating", + "kind": "failure", + "label": "✕ payments.fraud_suspected", + "description": "Failure: payments.fraud_suspected at charge-payment leads to Compensating" + }, + { + "id": "charge-payment->charge-payment:retry:1", + "source": "charge-payment", + "target": "charge-payment", + "kind": "retry", + "label": "↻ 2× on timeout", + "description": "Retry: charge-payment is retried 2× when it times out" + }, + { + "id": "charge-payment->Compensating:timeout:0", + "source": "charge-payment", + "target": "Compensating", + "kind": "timeout", + "label": "⏱ PT2M", + "description": "Timeout: after PT2M charge-payment leads to Compensating" + }, + { + "id": "review-large-order->create-shipment:success:0", + "source": "review-large-order", + "target": "create-shipment", + "kind": "success", + "label": "✓ orders.order-approved.v1", + "description": "Success: orders.order-approved.v1 moves from review-large-order to create-shipment" + }, + { + "id": "review-large-order->create-shipment:skip:0", + "source": "review-large-order", + "target": "create-shipment", + "kind": "skip", + "label": "⤼ unless $data.amount > 5000", + "description": "review-large-order is skipped to create-shipment unless $data.amount > 5000" + }, + { + "id": "review-large-order->Compensating:failure:0", + "source": "review-large-order", + "target": "Compensating", + "kind": "failure", + "label": "✕ orders.order-rejected-by-review.v1", + "description": "Failure: orders.order-rejected-by-review.v1 at review-large-order leads to Compensating" + }, + { + "id": "review-large-order->ManualIntervention:timeout:0", + "source": "review-large-order", + "target": "ManualIntervention", + "kind": "timeout", + "label": "⏱ P1D", + "description": "Timeout: after P1D review-large-order leads to ManualIntervention" + }, + { + "id": "create-shipment->Completed:success:0", + "source": "create-shipment", + "target": "Completed", + "kind": "success", + "label": "✓ shipping.shipment-created.v1", + "description": "Success: shipping.shipment-created.v1 moves from create-shipment to Completed" + }, + { + "id": "create-shipment->await-address-fix:failure:0", + "source": "create-shipment", + "target": "await-address-fix", + "kind": "failure", + "label": "✕ shipping.address_invalid", + "description": "Failure: shipping.address_invalid at create-shipment leads to await-address-fix" + }, + { + "id": "create-shipment->create-shipment:retry:0", + "source": "create-shipment", + "target": "create-shipment", + "kind": "retry", + "label": "↻ 3× exponential from PT5M on timeout", + "description": "Retry: create-shipment is retried 3× exponential from PT5M when it times out" + }, + { + "id": "create-shipment->ManualIntervention:timeout:0", + "source": "create-shipment", + "target": "ManualIntervention", + "kind": "timeout", + "label": "⏱ PT1H", + "description": "Timeout: after PT1H create-shipment leads to ManualIntervention" + }, + { + "id": "await-address-fix->create-shipment:success:0", + "source": "await-address-fix", + "target": "create-shipment", + "kind": "success", + "label": "✓ orders.address-corrected.v1", + "description": "Success: orders.address-corrected.v1 moves from await-address-fix to create-shipment" + }, + { + "id": "await-address-fix->ManualIntervention:timeout:0", + "source": "await-address-fix", + "target": "ManualIntervention", + "kind": "timeout", + "label": "⏱ P2D", + "description": "Timeout: after P2D await-address-fix leads to ManualIntervention" + }, + { + "id": "Compensating->undo:charge-payment:compensation:0", + "source": "Compensating", + "target": "undo:charge-payment", + "kind": "compensation", + "label": "⟲ most recent first", + "description": "Compensation starts with charge-payment, the most recent completed step" + }, + { + "id": "undo:charge-payment->undo:charge-payment:retry:0", + "source": "undo:charge-payment", + "target": "undo:charge-payment", + "kind": "retry", + "label": "↻ 5× exponential from PT1M", + "description": "Retry: the compensation of charge-payment is retried 5× exponential from PT1M" + }, + { + "id": "undo:charge-payment->undo:reserve-stock:compensation:0", + "source": "undo:charge-payment", + "target": "undo:reserve-stock", + "kind": "compensation", + "label": "⟲ payments.refunded.v1", + "description": "Compensation: charge-payment is undone (payments.refunded.v1), then undo:reserve-stock" + }, + { + "id": "undo:reserve-stock->undo:reserve-stock:retry:0", + "source": "undo:reserve-stock", + "target": "undo:reserve-stock", + "kind": "retry", + "label": "↻ 5× exponential from PT30S", + "description": "Retry: the compensation of reserve-stock is retried 5× exponential from PT30S" + }, + { + "id": "undo:reserve-stock->Compensated:compensation:0", + "source": "undo:reserve-stock", + "target": "Compensated", + "kind": "compensation", + "label": "⟲ inventory.stock-released.v1", + "description": "Compensation: reserve-stock is undone (inventory.stock-released.v1), then Compensated" + }, + { + "id": "Compensating->ManualIntervention:manual:0", + "source": "Compensating", + "target": "ManualIntervention", + "kind": "manual", + "label": "✋ a compensation failed", + "description": "Manual: a compensation that keeps failing needs an operator" + } + ] +} diff --git a/tests/Golden/cases/23-v14-personal-data/expected.mmd b/tests/Golden/cases/23-v14-personal-data/expected.mmd new file mode 100644 index 00000000..1f6b5443 --- /dev/null +++ b/tests/Golden/cases/23-v14-personal-data/expected.mmd @@ -0,0 +1,57 @@ +--- +title: order-fulfilment@1 (orders) +--- +stateDiagram-v2 + state "Compensating" as Compensating + state "Manual intervention" as ManualIntervention + state "reserve-stock" as reserve_stock + reserve_stock : send inventory.reserve-stock.v1 + reserve_stock : await inventory.stock-reserved.v1 + state "charge-payment" as charge_payment + charge_payment : send payments.charge.v1 + charge_payment : await payments.payment-captured.v1 + state "review-large-order" as review_large_order + review_large_order : await orders.order-approved.v1 + state "create-shipment" as create_shipment + create_shipment : ◆ pivot + create_shipment : send shipping.create-shipment.v1 + create_shipment : await shipping.shipment-created.v1 + state "await-address-fix" as await_address_fix + await_address_fix : await orders.address-corrected.v1 + [*] --> reserve_stock : orders.order-placed.v1 + reserve_stock --> charge_payment : ✓ inventory.stock-reserved.v1 + reserve_stock --> Compensating : ✕ inventory.out_of_stock + reserve_stock --> reserve_stock : ↻ 2× on timeout + reserve_stock --> Compensating : ⏱ PT5M + charge_payment --> review_large_order : ✓ payments.payment-captured.v1 + charge_payment --> charge_payment : ↻ 3× every PT10M on payments.declined + charge_payment --> Compensating : ✕ payments.declined + charge_payment --> Compensating : ✕ payments.fraud_suspected + charge_payment --> charge_payment : ↻ 2× on timeout + charge_payment --> Compensating : ⏱ PT2M + review_large_order --> create_shipment : ✓ orders.order-approved.v1 + review_large_order --> create_shipment : skip unless $data.amount > 5000 + review_large_order --> Compensating : ✕ orders.order-rejected-by-review.v1 + review_large_order --> ManualIntervention : ⏱ P1D + create_shipment --> Completed : ✓ shipping.shipment-created.v1 + create_shipment --> await_address_fix : ✕ shipping.address_invalid + create_shipment --> create_shipment : ↻ 3× exponential from PT5M on timeout + create_shipment --> ManualIntervention : ⏱ PT1H + await_address_fix --> create_shipment : ✓ orders.address-corrected.v1 + await_address_fix --> ManualIntervention : ⏱ P2D + state Compensating { + state "⟲ 1 charge-payment" as undo_charge_payment + undo_charge_payment : send payments.refund.v1 + undo_charge_payment --> undo_charge_payment : ↻ 5× exponential from PT1M + state "⟲ 2 reserve-stock" as undo_reserve_stock + undo_reserve_stock : send inventory.release-stock.v1 + undo_reserve_stock --> undo_reserve_stock : ↻ 5× exponential from PT30S + [*] --> undo_charge_payment : most recent first + undo_charge_payment --> undo_reserve_stock : ✓ payments.refunded.v1 + undo_reserve_stock --> [*] : ✓ inventory.stock-released.v1 + } + Compensating --> Compensated : ⟲ all undone + Compensating --> ManualIntervention : ✋ a compensation failed + Completed --> [*] + Compensated --> [*] + ManualIntervention --> [*] : ✋ operator resumes or aborts diff --git a/tests/Golden/cases/23-v14-personal-data/expected.paths.txt b/tests/Golden/cases/23-v14-personal-data/expected.paths.txt new file mode 100644 index 00000000..341bd5c9 --- /dev/null +++ b/tests/Golden/cases/23-v14-personal-data/expected.paths.txt @@ -0,0 +1,439 @@ +P01 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: success ⇒ Completed +P02 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P03 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P04 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P05 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P06 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P07 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P08 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P09 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P10 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P11 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P12 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P13 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P14 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P15 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P16 reserve-stock: success → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P17 reserve-stock: success → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P18 reserve-stock: success → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P19 reserve-stock: success → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P20 reserve-stock: success → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P21 reserve-stock: success → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P22 reserve-stock: success → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout (retries exhausted) ⇒ ManualIntervention +P23 reserve-stock: success → charge-payment: success → review-large-order: timeout ⇒ ManualIntervention +P24 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: success ⇒ Completed +P25 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P26 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P27 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P28 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P29 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P30 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P31 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P32 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P33 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P34 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P35 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P36 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P37 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P38 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P39 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: success ⇒ Completed +P40 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P41 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P42 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P43 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P44 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P45 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P46 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P47 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P48 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P49 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P50 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P51 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P52 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P53 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P54 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P55 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P56 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P57 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P58 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P59 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P60 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout (retries exhausted) ⇒ ManualIntervention +P61 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: timeout ⇒ ManualIntervention +P62 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: success ⇒ Completed +P63 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P64 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P65 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P66 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P67 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P68 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P69 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P70 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P71 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P72 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P73 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P74 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P75 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P76 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P77 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensated ⇒ Compensated +P78 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P79 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P80 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: success ⇒ Completed +P81 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P82 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P83 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P84 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P85 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P86 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P87 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P88 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P89 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P90 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P91 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P92 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P93 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P94 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P95 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P96 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P97 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P98 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P99 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P100 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P101 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout (retries exhausted) ⇒ ManualIntervention +P102 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: timeout ⇒ ManualIntervention +P103 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: success ⇒ Completed +P104 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P105 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P106 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P107 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P108 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P109 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P110 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P111 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P112 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P113 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P114 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P115 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P116 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P117 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P118 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensated ⇒ Compensated +P119 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P120 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P121 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: timeout → charge-payment: timeout (retries exhausted) → reserve-stock: compensated ⇒ Compensated +P122 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: timeout → charge-payment: timeout (retries exhausted) → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P123 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: timeout → charge-payment: timeout (retries exhausted) → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P124 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined (retries exhausted) → reserve-stock: compensated ⇒ Compensated +P125 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined (retries exhausted) → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P126 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined (retries exhausted) → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P127 reserve-stock: success → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensated ⇒ Compensated +P128 reserve-stock: success → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P129 reserve-stock: success → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P130 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: success ⇒ Completed +P131 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P132 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P133 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P134 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P135 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P136 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P137 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P138 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P139 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P140 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P141 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P142 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P143 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P144 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P145 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P146 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P147 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P148 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P149 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P150 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P151 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout (retries exhausted) ⇒ ManualIntervention +P152 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: timeout ⇒ ManualIntervention +P153 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: success ⇒ Completed +P154 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P155 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P156 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P157 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P158 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P159 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P160 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P161 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P162 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P163 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P164 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P165 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P166 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P167 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P168 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: success ⇒ Completed +P169 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P170 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P171 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P172 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P173 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P174 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P175 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P176 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P177 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P178 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P179 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P180 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P181 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P182 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P183 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P184 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P185 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P186 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P187 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P188 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P189 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout (retries exhausted) ⇒ ManualIntervention +P190 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: timeout ⇒ ManualIntervention +P191 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: success ⇒ Completed +P192 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P193 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P194 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P195 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P196 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P197 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P198 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P199 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P200 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P201 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P202 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P203 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P204 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P205 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P206 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensated ⇒ Compensated +P207 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P208 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P209 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined (retries exhausted) → reserve-stock: compensated ⇒ Compensated +P210 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined (retries exhausted) → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P211 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined (retries exhausted) → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P212 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensated ⇒ Compensated +P213 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P214 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P215 reserve-stock: success → charge-payment: timeout → charge-payment: timeout → charge-payment: timeout (retries exhausted) → reserve-stock: compensated ⇒ Compensated +P216 reserve-stock: success → charge-payment: timeout → charge-payment: timeout → charge-payment: timeout (retries exhausted) → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P217 reserve-stock: success → charge-payment: timeout → charge-payment: timeout → charge-payment: timeout (retries exhausted) → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P218 reserve-stock: rejected inventory.out_of_stock ⇒ Compensated +P219 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: success ⇒ Completed +P220 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P221 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P222 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P223 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P224 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P225 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P226 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P227 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P228 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P229 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P230 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P231 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P232 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P233 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P234 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P235 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P236 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P237 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P238 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P239 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P240 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout (retries exhausted) ⇒ ManualIntervention +P241 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: timeout ⇒ ManualIntervention +P242 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: success ⇒ Completed +P243 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P244 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P245 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P246 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P247 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P248 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P249 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P250 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P251 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P252 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P253 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P254 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P255 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P256 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P257 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: success ⇒ Completed +P258 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P259 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P260 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P261 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P262 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P263 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P264 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P265 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P266 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P267 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P268 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P269 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P270 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P271 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P272 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P273 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P274 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P275 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P276 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P277 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P278 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout (retries exhausted) ⇒ ManualIntervention +P279 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: timeout ⇒ ManualIntervention +P280 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: success ⇒ Completed +P281 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P282 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P283 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P284 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P285 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P286 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P287 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P288 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P289 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P290 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P291 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P292 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P293 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P294 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P295 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensated ⇒ Compensated +P296 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P297 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P298 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: success ⇒ Completed +P299 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P300 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P301 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P302 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P303 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P304 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P305 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P306 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P307 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P308 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P309 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P310 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P311 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P312 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P313 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P314 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P315 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P316 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P317 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P318 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P319 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout (retries exhausted) ⇒ ManualIntervention +P320 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: timeout ⇒ ManualIntervention +P321 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: success ⇒ Completed +P322 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P323 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P324 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P325 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P326 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P327 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P328 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P329 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P330 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P331 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P332 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P333 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P334 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P335 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P336 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensated ⇒ Compensated +P337 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P338 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P339 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: timeout → charge-payment: timeout (retries exhausted) → reserve-stock: compensated ⇒ Compensated +P340 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: timeout → charge-payment: timeout (retries exhausted) → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P341 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: timeout → charge-payment: timeout (retries exhausted) → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P342 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined (retries exhausted) → reserve-stock: compensated ⇒ Compensated +P343 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined (retries exhausted) → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P344 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined (retries exhausted) → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P345 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensated ⇒ Compensated +P346 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P347 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P348 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: success ⇒ Completed +P349 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P350 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P351 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P352 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P353 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P354 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P355 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P356 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P357 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P358 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P359 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P360 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P361 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P362 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P363 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P364 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P365 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P366 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P367 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P368 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P369 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout (retries exhausted) ⇒ ManualIntervention +P370 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: timeout ⇒ ManualIntervention +P371 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: success ⇒ Completed +P372 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P373 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P374 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P375 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P376 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P377 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P378 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P379 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P380 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P381 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P382 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P383 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P384 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P385 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P386 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: success ⇒ Completed +P387 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P388 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P389 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P390 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P391 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P392 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P393 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P394 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P395 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P396 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P397 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P398 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P399 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P400 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P401 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P402 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P403 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P404 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P405 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P406 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P407 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout (retries exhausted) ⇒ ManualIntervention +P408 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: timeout ⇒ ManualIntervention +P409 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: success ⇒ Completed +P410 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P411 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P412 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P413 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P414 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P415 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P416 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P417 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P418 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P419 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P420 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P421 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P422 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P423 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P424 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensated ⇒ Compensated +P425 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P426 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P427 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined (retries exhausted) → reserve-stock: compensated ⇒ Compensated +P428 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined (retries exhausted) → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P429 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined (retries exhausted) → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P430 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensated ⇒ Compensated +P431 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P432 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P433 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: timeout → charge-payment: timeout (retries exhausted) → reserve-stock: compensated ⇒ Compensated +P434 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: timeout → charge-payment: timeout (retries exhausted) → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P435 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: timeout → charge-payment: timeout (retries exhausted) → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P436 reserve-stock: timeout → reserve-stock: rejected inventory.out_of_stock ⇒ Compensated +P437 reserve-stock: timeout → reserve-stock: timeout → reserve-stock: timeout (retries exhausted) ⇒ Compensated + +edges: 25, uncovered: none diff --git a/tests/Golden/cases/23-v14-personal-data/workflow.sfflow.yaml b/tests/Golden/cases/23-v14-personal-data/workflow.sfflow.yaml new file mode 100644 index 00000000..78960fdf --- /dev/null +++ b/tests/Golden/cases/23-v14-personal-data/workflow.sfflow.yaml @@ -0,0 +1,79 @@ +sourceflow.workflow: 1 +name: order-fulfilment +version: 1 +owner: orders # generated into the orders service +description: Reserve stock, take payment, ship. + +start: + on: orders.order-placed.v1 # local domain event of the owner + correlate: data.orderId # instance id +data: # instance data, typed from schemas + orderId: { from: start.data.orderId } + amount: { from: start.data.total } + lines: { from: start.data.lines } + email: { from: start.data.customerEmail } + contact: { type: string, personal: true } + +steps: + - id: reserve-stock + send: { command: inventory.reserve-stock.v1, map: { orderId: $data.orderId, lines: $data.lines } } + await: + success: inventory.stock-reserved.v1 + failure: + - rejected: inventory.out_of_stock + then: fail # compensate completed steps (none yet), then Compensated + timeout: { after: PT5M, retry: { max: 2 }, then: fail } + compensate: + send: { command: inventory.release-stock.v1, map: { orderId: $data.orderId } } + await: { success: inventory.stock-released.v1 } + retry: { max: 5, backoff: exponential, initial: PT30S, cap: PT10M } + timeout: { after: PT15M } + + - id: charge-payment + send: { command: payments.charge.v1, map: { orderId: $data.orderId, amount: $data.amount } } + await: + success: + on: payments.payment-captured.v1 + capture: { paymentId: event.data.paymentId, holder: event.data.cardHolder, contact: event.data.cardHolder } + failure: + - rejected: payments.declined + retry: { max: 3, backoff: fixed, initial: PT10M } # business retry + then: fail + - rejected: payments.fraud_suspected + then: fail + timeout: { after: PT2M, retry: { max: 2 }, then: fail } + compensate: + send: { command: payments.refund.v1, map: { paymentId: $data.paymentId, amount: $data.amount } } + await: { success: payments.refunded.v1 } + retry: { max: 5, backoff: exponential, initial: PT1M } + timeout: { after: PT30M } + + - id: review-large-order + when: "$data.amount > 5000" # CESQL guard; skipped when false + await: + success: orders.order-approved.v1 + failure: + - on: orders.order-rejected-by-review.v1 + then: fail + timeout: { after: P1D, then: manual } + + - id: create-shipment + pivot: true # point of no return + send: { command: shipping.create-shipment.v1, map: { orderId: $data.orderId, lines: $data.lines } } + await: + success: shipping.shipment-created.v1 + failure: + - rejected: shipping.address_invalid + then: { goto: await-address-fix } # forward recovery after pivot + timeout: { after: PT1H, retry: { max: 3, backoff: exponential, initial: PT5M }, then: manual } + next: complete + + - id: await-address-fix + await: { success: orders.address-corrected.v1 } + timeout: { after: P2D, then: manual } + next: create-shipment + +on: + completed: { send: { command: orders.mark-fulfilled.v1, map: { orderId: $data.orderId } } } + compensated: { send: { command: orders.cancel-order.v1, map: { orderId: $data.orderId, reason: $failure.code } } } + manual: { alert: true } # metric + structured log + dead-letter-style record diff --git a/tests/Golden/cases/24-v15-published-version/expected.diagnostics.json b/tests/Golden/cases/24-v15-published-version/expected.diagnostics.json new file mode 100644 index 00000000..38e170a5 --- /dev/null +++ b/tests/Golden/cases/24-v15-published-version/expected.diagnostics.json @@ -0,0 +1,9 @@ +[ + { + "id": "WF-V15", + "severity": "error", + "line": 3, + "column": 10, + "message": "published-flow@1 changed since it was published; in-flight instances run the published structure, so give the change 'version: 2' (doc 15 §5.6)." + } +] diff --git a/tests/Golden/cases/24-v15-published-version/workflow.sfflow.yaml b/tests/Golden/cases/24-v15-published-version/workflow.sfflow.yaml new file mode 100644 index 00000000..d478d6b6 --- /dev/null +++ b/tests/Golden/cases/24-v15-published-version/workflow.sfflow.yaml @@ -0,0 +1,12 @@ +sourceflow.workflow: 1 +name: published-flow +version: 1 +owner: orders +start: { on: orders.order-placed.v1, correlate: data.orderId } +data: + orderId: { from: start.data.orderId } +steps: + - id: approve + send: { command: orders.approve-order.v1, map: { orderId: $data.orderId } } + await: { success: orders.order-approved.v1 } + timeout: { after: PT1H, then: manual } diff --git a/tests/Golden/cases/25-v16-nested-compensation/expected.diagnostics.json b/tests/Golden/cases/25-v16-nested-compensation/expected.diagnostics.json new file mode 100644 index 00000000..13acfcb8 --- /dev/null +++ b/tests/Golden/cases/25-v16-nested-compensation/expected.diagnostics.json @@ -0,0 +1,16 @@ +[ + { + "id": "WF-V16", + "severity": "error", + "line": 47, + "column": 9, + "message": "A compensation awaits its success only; it can't branch on failures (its retry and timeout handle them)." + }, + { + "id": "WF-V16", + "severity": "error", + "line": 50, + "column": 7, + "message": "A compensation can't declare 'compensate': compensations are not compensated or redirected (no nested sagas)." + } +] diff --git a/tests/Golden/cases/25-v16-nested-compensation/workflow.sfflow.yaml b/tests/Golden/cases/25-v16-nested-compensation/workflow.sfflow.yaml new file mode 100644 index 00000000..53423096 --- /dev/null +++ b/tests/Golden/cases/25-v16-nested-compensation/workflow.sfflow.yaml @@ -0,0 +1,83 @@ +sourceflow.workflow: 1 +name: order-fulfilment +version: 1 +owner: orders # generated into the orders service +description: Reserve stock, take payment, ship. + +start: + on: orders.order-placed.v1 # local domain event of the owner + correlate: data.orderId # instance id +data: # instance data, typed from schemas + orderId: { from: start.data.orderId } + amount: { from: start.data.total } + lines: { from: start.data.lines } + +steps: + - id: reserve-stock + send: { command: inventory.reserve-stock.v1, map: { orderId: $data.orderId, lines: $data.lines } } + await: + success: inventory.stock-reserved.v1 + failure: + - rejected: inventory.out_of_stock + then: fail # compensate completed steps (none yet), then Compensated + timeout: { after: PT5M, retry: { max: 2 }, then: fail } + compensate: + send: { command: inventory.release-stock.v1, map: { orderId: $data.orderId } } + await: { success: inventory.stock-released.v1 } + retry: { max: 5, backoff: exponential, initial: PT30S, cap: PT10M } + timeout: { after: PT15M } + + - id: charge-payment + send: { command: payments.charge.v1, map: { orderId: $data.orderId, amount: $data.amount } } + await: + success: + on: payments.payment-captured.v1 + capture: { paymentId: event.data.paymentId } + failure: + - rejected: payments.declined + retry: { max: 3, backoff: fixed, initial: PT10M } # business retry + then: fail + - rejected: payments.fraud_suspected + then: fail + timeout: { after: PT2M, retry: { max: 2 }, then: fail } + compensate: + send: { command: payments.refund.v1, map: { paymentId: $data.paymentId, amount: $data.amount } } + await: + success: payments.refunded.v1 + failure: + - rejected: payments.declined + then: manual + compensate: + send: { command: payments.charge.v1, map: { orderId: $data.orderId, amount: $data.amount } } + retry: { max: 5, backoff: exponential, initial: PT1M } + timeout: { after: PT30M } + + - id: review-large-order + when: "$data.amount > 5000" # CESQL guard; skipped when false + await: + success: orders.order-approved.v1 + failure: + - on: orders.order-rejected-by-review.v1 + then: fail + timeout: { after: P1D, then: manual } + + - id: create-shipment + pivot: true # point of no return + send: { command: shipping.create-shipment.v1, map: { orderId: $data.orderId, lines: $data.lines } } + await: + success: shipping.shipment-created.v1 + failure: + - rejected: shipping.address_invalid + then: { goto: await-address-fix } # forward recovery after pivot + timeout: { after: PT1H, retry: { max: 3, backoff: exponential, initial: PT5M }, then: manual } + next: complete + + - id: await-address-fix + await: { success: orders.address-corrected.v1 } + timeout: { after: P2D, then: manual } + next: create-shipment + +on: + completed: { send: { command: orders.mark-fulfilled.v1, map: { orderId: $data.orderId } } } + compensated: { send: { command: orders.cancel-order.v1, map: { orderId: $data.orderId, reason: $failure.code } } } + manual: { alert: true } # metric + structured log + dead-letter-style record diff --git a/tests/Golden/cases/26-guards-and-hooks/expected.bpmn b/tests/Golden/cases/26-guards-and-hooks/expected.bpmn new file mode 100644 index 00000000..1f5a72cc --- /dev/null +++ b/tests/Golden/cases/26-guards-and-hooks/expected.bpmn @@ -0,0 +1,180 @@ + + + + + + + + + + + + + + + + + + + + Reserve stock, take payment, ship. + + Flow_2 + + + + Flow_18 + + + Flow_5 + Flow_6 + Flow_9 + Flow_10 + Flow_11 + Flow_15 + Flow_1 + + + + Flow_1 + + + An operator resumes, retries or aborts the instance. + Flow_16 + Flow_20 + Flow_22 + + + Flow_2 + Flow_3 + + + + + + await inventory.stock-released.v1; retry 5× (exponential, initial PT30S, cap PT10M); timeout PT15M, then manual intervention + + + Flow_3 + Flow_4 + + + Flow_5 + + + + retry 2× (fixed, initial PT0S) + Flow_6 + + PT5M + + + + Flow_4 + Flow_7 + + + + + + await payments.refunded.v1; retry 5× (exponential, initial PT1M); timeout PT30M, then manual intervention + + + Flow_7 + Flow_8 + + + retry 3× (fixed, initial PT10M) + Flow_9 + + + + Flow_10 + + + + retry 2× (fixed, initial PT0S) + Flow_11 + + PT2M + + + + Flow_8 + Flow_12 + Flow_skip_review_large_order + + + Flow_12 + Flow_14 + + + Flow_15 + + + + Flow_16 + + P1D + + + + Pivot: the point of no return. + Flow_skip_review_large_order + Flow_14 + Flow_21 + Flow_17 + + + Flow_17 + Flow_18 + + + Flow_19 + + + + retry 3× (exponential, initial PT5M) + Flow_20 + + PT1H + + + + Flow_19 + Flow_21 + + + Flow_22 + + P2D + + + + + + + + + + + + + + + ($data.amount > 5000 OR $data.priority) AND NOT EXISTS $data.reviewer + + + + + + + + + + + + + + + diff --git a/tests/Golden/cases/26-guards-and-hooks/expected.diagnostics.json b/tests/Golden/cases/26-guards-and-hooks/expected.diagnostics.json new file mode 100644 index 00000000..fe51488c --- /dev/null +++ b/tests/Golden/cases/26-guards-and-hooks/expected.diagnostics.json @@ -0,0 +1 @@ +[] diff --git a/tests/Golden/cases/26-guards-and-hooks/expected.graph.json b/tests/Golden/cases/26-guards-and-hooks/expected.graph.json new file mode 100644 index 00000000..47bc9c6e --- /dev/null +++ b/tests/Golden/cases/26-guards-and-hooks/expected.graph.json @@ -0,0 +1,316 @@ +{ + "nodes": [ + { + "id": "start", + "kind": "start", + "label": "orders.order-placed.v1", + "compensable": false + }, + { + "id": "reserve-stock", + "kind": "step", + "label": "reserve-stock", + "sends": "inventory.reserve-stock.v1", + "awaits": "inventory.stock-reserved.v1", + "timeout": "PT5M", + "compensable": true + }, + { + "id": "charge-payment", + "kind": "step", + "label": "charge-payment", + "sends": "payments.charge.v1", + "awaits": "payments.payment-captured.v1", + "timeout": "PT2M", + "compensable": true + }, + { + "id": "review-large-order", + "kind": "step", + "label": "review-large-order", + "awaits": "orders.order-approved.v1", + "when": "($data.amount > 5000 OR $data.priority) AND NOT EXISTS $data.reviewer", + "timeout": "P1D", + "compensable": false + }, + { + "id": "create-shipment", + "kind": "pivot", + "label": "create-shipment", + "sends": "shipping.create-shipment.v1", + "awaits": "shipping.shipment-created.v1", + "timeout": "PT1H", + "compensable": false + }, + { + "id": "await-address-fix", + "kind": "step", + "label": "await-address-fix", + "awaits": "orders.address-corrected.v1", + "timeout": "P2D", + "compensable": false + }, + { + "id": "Completed", + "kind": "terminal", + "label": "Completed", + "compensable": false + }, + { + "id": "Compensating", + "kind": "compensating", + "label": "Compensating", + "compensable": false + }, + { + "id": "undo:charge-payment", + "kind": "compensation", + "label": "⟲ 1 charge-payment", + "sends": "payments.refund.v1", + "awaits": "payments.refunded.v1", + "parent": "Compensating", + "compensable": false, + "order": 1 + }, + { + "id": "undo:reserve-stock", + "kind": "compensation", + "label": "⟲ 2 reserve-stock", + "sends": "inventory.release-stock.v1", + "awaits": "inventory.stock-released.v1", + "parent": "Compensating", + "compensable": false, + "order": 2 + }, + { + "id": "Compensated", + "kind": "terminal", + "label": "Compensated", + "compensable": false + }, + { + "id": "ManualIntervention", + "kind": "manual", + "label": "✋ Manual intervention", + "compensable": false + } + ], + "edges": [ + { + "id": "start->reserve-stock:start:0", + "source": "start", + "target": "reserve-stock", + "kind": "start", + "label": "▶ orders.order-placed.v1", + "description": "orders.order-placed.v1 starts the workflow at reserve-stock" + }, + { + "id": "reserve-stock->charge-payment:success:0", + "source": "reserve-stock", + "target": "charge-payment", + "kind": "success", + "label": "✓ inventory.stock-reserved.v1", + "description": "Success: inventory.stock-reserved.v1 moves from reserve-stock to charge-payment" + }, + { + "id": "reserve-stock->Compensating:failure:0", + "source": "reserve-stock", + "target": "Compensating", + "kind": "failure", + "label": "✕ inventory.out_of_stock", + "description": "Failure: inventory.out_of_stock at reserve-stock leads to Compensating" + }, + { + "id": "reserve-stock->reserve-stock:retry:0", + "source": "reserve-stock", + "target": "reserve-stock", + "kind": "retry", + "label": "↻ 2× on timeout", + "description": "Retry: reserve-stock is retried 2× when it times out" + }, + { + "id": "reserve-stock->Compensating:timeout:0", + "source": "reserve-stock", + "target": "Compensating", + "kind": "timeout", + "label": "⏱ PT5M", + "description": "Timeout: after PT5M reserve-stock leads to Compensating" + }, + { + "id": "charge-payment->review-large-order:success:0", + "source": "charge-payment", + "target": "review-large-order", + "kind": "success", + "label": "✓ payments.payment-captured.v1", + "description": "Success: payments.payment-captured.v1 moves from charge-payment to review-large-order" + }, + { + "id": "charge-payment->charge-payment:retry:0", + "source": "charge-payment", + "target": "charge-payment", + "kind": "retry", + "label": "↻ 3× every PT10M on payments.declined", + "description": "Retry: charge-payment is retried 3× every PT10M on payments.declined" + }, + { + "id": "charge-payment->Compensating:failure:0", + "source": "charge-payment", + "target": "Compensating", + "kind": "failure", + "label": "✕ payments.declined", + "description": "Failure: payments.declined at charge-payment leads to Compensating" + }, + { + "id": "charge-payment->Compensating:failure:1", + "source": "charge-payment", + "target": "Compensating", + "kind": "failure", + "label": "✕ payments.fraud_suspected", + "description": "Failure: payments.fraud_suspected at charge-payment leads to Compensating" + }, + { + "id": "charge-payment->charge-payment:retry:1", + "source": "charge-payment", + "target": "charge-payment", + "kind": "retry", + "label": "↻ 2× on timeout", + "description": "Retry: charge-payment is retried 2× when it times out" + }, + { + "id": "charge-payment->Compensating:timeout:0", + "source": "charge-payment", + "target": "Compensating", + "kind": "timeout", + "label": "⏱ PT2M", + "description": "Timeout: after PT2M charge-payment leads to Compensating" + }, + { + "id": "review-large-order->create-shipment:success:0", + "source": "review-large-order", + "target": "create-shipment", + "kind": "success", + "label": "✓ orders.order-approved.v1", + "description": "Success: orders.order-approved.v1 moves from review-large-order to create-shipment" + }, + { + "id": "review-large-order->create-shipment:skip:0", + "source": "review-large-order", + "target": "create-shipment", + "kind": "skip", + "label": "⤼ unless ($data.amount > 5000 OR $data.priority) AND NOT EXISTS $data.reviewer", + "description": "review-large-order is skipped to create-shipment unless ($data.amount > 5000 OR $data.priority) AND NOT EXISTS $data.reviewer" + }, + { + "id": "review-large-order->Compensating:failure:0", + "source": "review-large-order", + "target": "Compensating", + "kind": "failure", + "label": "✕ orders.order-rejected-by-review.v1", + "description": "Failure: orders.order-rejected-by-review.v1 at review-large-order leads to Compensating" + }, + { + "id": "review-large-order->ManualIntervention:timeout:0", + "source": "review-large-order", + "target": "ManualIntervention", + "kind": "timeout", + "label": "⏱ P1D", + "description": "Timeout: after P1D review-large-order leads to ManualIntervention" + }, + { + "id": "create-shipment->Completed:success:0", + "source": "create-shipment", + "target": "Completed", + "kind": "success", + "label": "✓ shipping.shipment-created.v1", + "description": "Success: shipping.shipment-created.v1 moves from create-shipment to Completed" + }, + { + "id": "create-shipment->await-address-fix:failure:0", + "source": "create-shipment", + "target": "await-address-fix", + "kind": "failure", + "label": "✕ shipping.address_invalid", + "description": "Failure: shipping.address_invalid at create-shipment leads to await-address-fix" + }, + { + "id": "create-shipment->create-shipment:retry:0", + "source": "create-shipment", + "target": "create-shipment", + "kind": "retry", + "label": "↻ 3× exponential from PT5M on timeout", + "description": "Retry: create-shipment is retried 3× exponential from PT5M when it times out" + }, + { + "id": "create-shipment->ManualIntervention:timeout:0", + "source": "create-shipment", + "target": "ManualIntervention", + "kind": "timeout", + "label": "⏱ PT1H", + "description": "Timeout: after PT1H create-shipment leads to ManualIntervention" + }, + { + "id": "await-address-fix->create-shipment:success:0", + "source": "await-address-fix", + "target": "create-shipment", + "kind": "success", + "label": "✓ orders.address-corrected.v1", + "description": "Success: orders.address-corrected.v1 moves from await-address-fix to create-shipment" + }, + { + "id": "await-address-fix->ManualIntervention:timeout:0", + "source": "await-address-fix", + "target": "ManualIntervention", + "kind": "timeout", + "label": "⏱ P2D", + "description": "Timeout: after P2D await-address-fix leads to ManualIntervention" + }, + { + "id": "Compensating->undo:charge-payment:compensation:0", + "source": "Compensating", + "target": "undo:charge-payment", + "kind": "compensation", + "label": "⟲ most recent first", + "description": "Compensation starts with charge-payment, the most recent completed step" + }, + { + "id": "undo:charge-payment->undo:charge-payment:retry:0", + "source": "undo:charge-payment", + "target": "undo:charge-payment", + "kind": "retry", + "label": "↻ 5× exponential from PT1M", + "description": "Retry: the compensation of charge-payment is retried 5× exponential from PT1M" + }, + { + "id": "undo:charge-payment->undo:reserve-stock:compensation:0", + "source": "undo:charge-payment", + "target": "undo:reserve-stock", + "kind": "compensation", + "label": "⟲ payments.refunded.v1", + "description": "Compensation: charge-payment is undone (payments.refunded.v1), then undo:reserve-stock" + }, + { + "id": "undo:reserve-stock->undo:reserve-stock:retry:0", + "source": "undo:reserve-stock", + "target": "undo:reserve-stock", + "kind": "retry", + "label": "↻ 5× exponential from PT30S", + "description": "Retry: the compensation of reserve-stock is retried 5× exponential from PT30S" + }, + { + "id": "undo:reserve-stock->Compensated:compensation:0", + "source": "undo:reserve-stock", + "target": "Compensated", + "kind": "compensation", + "label": "⟲ inventory.stock-released.v1", + "description": "Compensation: reserve-stock is undone (inventory.stock-released.v1), then Compensated" + }, + { + "id": "Compensating->ManualIntervention:manual:0", + "source": "Compensating", + "target": "ManualIntervention", + "kind": "manual", + "label": "✋ a compensation failed", + "description": "Manual: a compensation that keeps failing needs an operator" + } + ] +} diff --git a/tests/Golden/cases/26-guards-and-hooks/expected.mmd b/tests/Golden/cases/26-guards-and-hooks/expected.mmd new file mode 100644 index 00000000..0f17e7a9 --- /dev/null +++ b/tests/Golden/cases/26-guards-and-hooks/expected.mmd @@ -0,0 +1,57 @@ +--- +title: order-fulfilment@1 (orders) +--- +stateDiagram-v2 + state "Compensating" as Compensating + state "Manual intervention" as ManualIntervention + state "reserve-stock" as reserve_stock + reserve_stock : send inventory.reserve-stock.v1 + reserve_stock : await inventory.stock-reserved.v1 + state "charge-payment" as charge_payment + charge_payment : send payments.charge.v1 + charge_payment : await payments.payment-captured.v1 + state "review-large-order" as review_large_order + review_large_order : await orders.order-approved.v1 + state "create-shipment" as create_shipment + create_shipment : ◆ pivot + create_shipment : send shipping.create-shipment.v1 + create_shipment : await shipping.shipment-created.v1 + state "await-address-fix" as await_address_fix + await_address_fix : await orders.address-corrected.v1 + [*] --> reserve_stock : orders.order-placed.v1 + reserve_stock --> charge_payment : ✓ inventory.stock-reserved.v1 + reserve_stock --> Compensating : ✕ inventory.out_of_stock + reserve_stock --> reserve_stock : ↻ 2× on timeout + reserve_stock --> Compensating : ⏱ PT5M + charge_payment --> review_large_order : ✓ payments.payment-captured.v1 + charge_payment --> charge_payment : ↻ 3× every PT10M on payments.declined + charge_payment --> Compensating : ✕ payments.declined + charge_payment --> Compensating : ✕ payments.fraud_suspected + charge_payment --> charge_payment : ↻ 2× on timeout + charge_payment --> Compensating : ⏱ PT2M + review_large_order --> create_shipment : ✓ orders.order-approved.v1 + review_large_order --> create_shipment : skip unless ($data.amount > 5000 OR $data.priority) AND NOT EXISTS $data.reviewer + review_large_order --> Compensating : ✕ orders.order-rejected-by-review.v1 + review_large_order --> ManualIntervention : ⏱ P1D + create_shipment --> Completed : ✓ shipping.shipment-created.v1 + create_shipment --> await_address_fix : ✕ shipping.address_invalid + create_shipment --> create_shipment : ↻ 3× exponential from PT5M on timeout + create_shipment --> ManualIntervention : ⏱ PT1H + await_address_fix --> create_shipment : ✓ orders.address-corrected.v1 + await_address_fix --> ManualIntervention : ⏱ P2D + state Compensating { + state "⟲ 1 charge-payment" as undo_charge_payment + undo_charge_payment : send payments.refund.v1 + undo_charge_payment --> undo_charge_payment : ↻ 5× exponential from PT1M + state "⟲ 2 reserve-stock" as undo_reserve_stock + undo_reserve_stock : send inventory.release-stock.v1 + undo_reserve_stock --> undo_reserve_stock : ↻ 5× exponential from PT30S + [*] --> undo_charge_payment : most recent first + undo_charge_payment --> undo_reserve_stock : ✓ payments.refunded.v1 + undo_reserve_stock --> [*] : ✓ inventory.stock-released.v1 + } + Compensating --> Compensated : ⟲ all undone + Compensating --> ManualIntervention : ✋ a compensation failed + Completed --> [*] + Compensated --> [*] + ManualIntervention --> [*] : ✋ operator resumes or aborts diff --git a/tests/Golden/cases/26-guards-and-hooks/expected.paths.txt b/tests/Golden/cases/26-guards-and-hooks/expected.paths.txt new file mode 100644 index 00000000..341bd5c9 --- /dev/null +++ b/tests/Golden/cases/26-guards-and-hooks/expected.paths.txt @@ -0,0 +1,439 @@ +P01 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: success ⇒ Completed +P02 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P03 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P04 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P05 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P06 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P07 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P08 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P09 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P10 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P11 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P12 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P13 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P14 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P15 reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P16 reserve-stock: success → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P17 reserve-stock: success → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P18 reserve-stock: success → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P19 reserve-stock: success → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P20 reserve-stock: success → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P21 reserve-stock: success → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P22 reserve-stock: success → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout (retries exhausted) ⇒ ManualIntervention +P23 reserve-stock: success → charge-payment: success → review-large-order: timeout ⇒ ManualIntervention +P24 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: success ⇒ Completed +P25 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P26 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P27 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P28 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P29 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P30 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P31 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P32 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P33 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P34 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P35 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P36 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P37 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P38 reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P39 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: success ⇒ Completed +P40 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P41 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P42 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P43 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P44 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P45 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P46 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P47 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P48 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P49 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P50 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P51 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P52 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P53 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P54 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P55 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P56 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P57 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P58 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P59 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P60 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout (retries exhausted) ⇒ ManualIntervention +P61 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: timeout ⇒ ManualIntervention +P62 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: success ⇒ Completed +P63 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P64 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P65 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P66 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P67 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P68 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P69 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P70 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P71 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P72 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P73 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P74 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P75 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P76 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P77 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensated ⇒ Compensated +P78 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P79 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P80 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: success ⇒ Completed +P81 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P82 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P83 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P84 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P85 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P86 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P87 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P88 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P89 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P90 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P91 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P92 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P93 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P94 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P95 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P96 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P97 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P98 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P99 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P100 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P101 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout (retries exhausted) ⇒ ManualIntervention +P102 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: timeout ⇒ ManualIntervention +P103 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: success ⇒ Completed +P104 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P105 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P106 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P107 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P108 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P109 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P110 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P111 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P112 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P113 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P114 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P115 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P116 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P117 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P118 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensated ⇒ Compensated +P119 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P120 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P121 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: timeout → charge-payment: timeout (retries exhausted) → reserve-stock: compensated ⇒ Compensated +P122 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: timeout → charge-payment: timeout (retries exhausted) → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P123 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: timeout → charge-payment: timeout (retries exhausted) → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P124 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined (retries exhausted) → reserve-stock: compensated ⇒ Compensated +P125 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined (retries exhausted) → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P126 reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined (retries exhausted) → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P127 reserve-stock: success → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensated ⇒ Compensated +P128 reserve-stock: success → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P129 reserve-stock: success → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P130 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: success ⇒ Completed +P131 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P132 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P133 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P134 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P135 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P136 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P137 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P138 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P139 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P140 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P141 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P142 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P143 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P144 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P145 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P146 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P147 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P148 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P149 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P150 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P151 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout (retries exhausted) ⇒ ManualIntervention +P152 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: timeout ⇒ ManualIntervention +P153 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: success ⇒ Completed +P154 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P155 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P156 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P157 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P158 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P159 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P160 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P161 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P162 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P163 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P164 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P165 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P166 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P167 reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P168 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: success ⇒ Completed +P169 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P170 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P171 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P172 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P173 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P174 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P175 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P176 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P177 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P178 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P179 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P180 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P181 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P182 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P183 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P184 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P185 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P186 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P187 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P188 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P189 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout (retries exhausted) ⇒ ManualIntervention +P190 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: timeout ⇒ ManualIntervention +P191 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: success ⇒ Completed +P192 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P193 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P194 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P195 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P196 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P197 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P198 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P199 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P200 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P201 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P202 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P203 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P204 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P205 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P206 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensated ⇒ Compensated +P207 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P208 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P209 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined (retries exhausted) → reserve-stock: compensated ⇒ Compensated +P210 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined (retries exhausted) → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P211 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined (retries exhausted) → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P212 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensated ⇒ Compensated +P213 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P214 reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P215 reserve-stock: success → charge-payment: timeout → charge-payment: timeout → charge-payment: timeout (retries exhausted) → reserve-stock: compensated ⇒ Compensated +P216 reserve-stock: success → charge-payment: timeout → charge-payment: timeout → charge-payment: timeout (retries exhausted) → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P217 reserve-stock: success → charge-payment: timeout → charge-payment: timeout → charge-payment: timeout (retries exhausted) → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P218 reserve-stock: rejected inventory.out_of_stock ⇒ Compensated +P219 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: success ⇒ Completed +P220 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P221 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P222 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P223 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P224 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P225 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P226 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P227 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P228 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P229 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P230 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P231 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P232 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P233 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P234 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P235 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P236 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P237 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P238 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P239 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P240 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout (retries exhausted) ⇒ ManualIntervention +P241 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: timeout ⇒ ManualIntervention +P242 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: success ⇒ Completed +P243 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P244 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P245 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P246 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P247 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P248 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P249 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P250 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P251 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P252 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P253 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P254 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P255 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P256 reserve-stock: timeout → reserve-stock: success → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P257 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: success ⇒ Completed +P258 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P259 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P260 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P261 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P262 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P263 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P264 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P265 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P266 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P267 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P268 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P269 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P270 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P271 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P272 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P273 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P274 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P275 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P276 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P277 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P278 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout (retries exhausted) ⇒ ManualIntervention +P279 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: timeout ⇒ ManualIntervention +P280 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: success ⇒ Completed +P281 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P282 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P283 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P284 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P285 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P286 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P287 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P288 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P289 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P290 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P291 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P292 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P293 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P294 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P295 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensated ⇒ Compensated +P296 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P297 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P298 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: success ⇒ Completed +P299 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P300 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P301 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P302 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P303 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P304 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P305 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P306 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P307 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P308 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P309 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P310 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P311 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P312 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P313 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P314 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P315 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P316 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P317 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P318 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P319 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout (retries exhausted) ⇒ ManualIntervention +P320 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: timeout ⇒ ManualIntervention +P321 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: success ⇒ Completed +P322 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P323 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P324 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P325 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P326 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P327 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P328 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P329 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P330 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P331 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P332 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P333 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P334 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P335 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P336 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensated ⇒ Compensated +P337 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P338 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P339 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: timeout → charge-payment: timeout (retries exhausted) → reserve-stock: compensated ⇒ Compensated +P340 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: timeout → charge-payment: timeout (retries exhausted) → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P341 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: timeout → charge-payment: timeout → charge-payment: timeout (retries exhausted) → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P342 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined (retries exhausted) → reserve-stock: compensated ⇒ Compensated +P343 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined (retries exhausted) → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P344 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined (retries exhausted) → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P345 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensated ⇒ Compensated +P346 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P347 reserve-stock: timeout → reserve-stock: success → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P348 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: success ⇒ Completed +P349 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P350 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P351 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P352 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P353 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P354 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P355 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P356 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P357 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P358 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P359 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P360 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P361 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P362 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P363 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P364 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P365 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P366 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P367 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P368 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P369 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout (retries exhausted) ⇒ ManualIntervention +P370 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: timeout ⇒ ManualIntervention +P371 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: success ⇒ Completed +P372 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P373 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P374 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P375 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P376 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P377 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P378 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P379 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P380 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P381 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P382 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P383 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P384 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P385 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P386 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: success ⇒ Completed +P387 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P388 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P389 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P390 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P391 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P392 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P393 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P394 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P395 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P396 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P397 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P398 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P399 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P400 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P401 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P402 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P403 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P404 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensated ⇒ Compensated +P405 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P406 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensated → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P407 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: failed orders.order-rejected-by-review.v1 → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout → charge-payment: retry → charge-payment: compensation timeout (retries exhausted) ⇒ ManualIntervention +P408 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: timeout ⇒ ManualIntervention +P409 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: success ⇒ Completed +P410 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P411 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P412 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P413 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P414 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P415 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P416 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P417 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: success ⇒ Completed +P418 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P419 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: success ⇒ Completed +P420 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P421 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: success → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P422 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: rejected shipping.address_invalid → await-address-fix: timeout ⇒ ManualIntervention +P423 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: success → review-large-order: skipped → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout → create-shipment: retry → create-shipment: timeout (retries exhausted) ⇒ ManualIntervention +P424 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensated ⇒ Compensated +P425 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P426 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P427 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined (retries exhausted) → reserve-stock: compensated ⇒ Compensated +P428 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined (retries exhausted) → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P429 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined → charge-payment: retry → charge-payment: rejected payments.declined (retries exhausted) → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P430 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensated ⇒ Compensated +P431 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P432 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: rejected payments.fraud_suspected → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P433 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: timeout → charge-payment: timeout (retries exhausted) → reserve-stock: compensated ⇒ Compensated +P434 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: timeout → charge-payment: timeout (retries exhausted) → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensated ⇒ Compensated +P435 reserve-stock: timeout → reserve-stock: success → charge-payment: timeout → charge-payment: timeout → charge-payment: timeout (retries exhausted) → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout → reserve-stock: retry → reserve-stock: compensation timeout (retries exhausted) ⇒ ManualIntervention +P436 reserve-stock: timeout → reserve-stock: rejected inventory.out_of_stock ⇒ Compensated +P437 reserve-stock: timeout → reserve-stock: timeout → reserve-stock: timeout (retries exhausted) ⇒ Compensated + +edges: 25, uncovered: none diff --git a/tests/Golden/cases/26-guards-and-hooks/workflow.sfflow.yaml b/tests/Golden/cases/26-guards-and-hooks/workflow.sfflow.yaml new file mode 100644 index 00000000..906ac7f6 --- /dev/null +++ b/tests/Golden/cases/26-guards-and-hooks/workflow.sfflow.yaml @@ -0,0 +1,79 @@ +sourceflow.workflow: 1 +name: order-fulfilment +version: 1 +owner: orders # generated into the orders service +description: Reserve stock, take payment, ship. + +start: + on: orders.order-placed.v1 # local domain event of the owner + correlate: data.orderId # instance id +data: # instance data, typed from schemas + orderId: { from: start.data.orderId } + amount: { from: start.data.total } + lines: { from: start.data.lines } + priority: { from: start.data.priority } + reviewer: { type: string, default: null } + +steps: + - id: reserve-stock + send: { command: inventory.reserve-stock.v1, map: { orderId: $data.orderId, lines: $data.lines } } + await: + success: inventory.stock-reserved.v1 + failure: + - rejected: inventory.out_of_stock + then: fail # compensate completed steps (none yet), then Compensated + timeout: { after: PT5M, retry: { max: 2 }, then: fail } + compensate: + send: { command: inventory.release-stock.v1, map: { orderId: $data.orderId } } + await: { success: inventory.stock-released.v1 } + retry: { max: 5, backoff: exponential, initial: PT30S, cap: PT10M } + timeout: { after: PT15M } + + - id: charge-payment + send: { command: payments.charge.v1, map: { orderId: $data.orderId, amount: $data.amount } } + await: + success: + on: payments.payment-captured.v1 + capture: { paymentId: event.data.paymentId } + failure: + - rejected: payments.declined + retry: { max: 3, backoff: fixed, initial: PT10M } # business retry + then: fail + - rejected: payments.fraud_suspected + then: fail + timeout: { after: PT2M, retry: { max: 2 }, then: fail } + compensate: + send: { command: payments.refund.v1, map: { paymentId: $data.paymentId, amount: $data.amount } } + await: { success: payments.refunded.v1 } + retry: { max: 5, backoff: exponential, initial: PT1M } + timeout: { after: PT30M } + + - id: review-large-order + when: "($data.amount > 5000 OR $data.priority) AND NOT EXISTS $data.reviewer" # CESQL guard; skipped when false + await: + success: orders.order-approved.v1 + failure: + - on: orders.order-rejected-by-review.v1 + then: fail + timeout: { after: P1D, then: manual } + + - id: create-shipment + pivot: true # point of no return + send: { command: shipping.create-shipment.v1, map: { orderId: $data.orderId, lines: $data.lines, note: { $hook: ShippingNote } } } + await: + success: { on: shipping.shipment-created.v1, when: "event.data.shipmentId != '' AND $data.amount IN (1, 2, 3) OR $data.reviewer LIKE 'ops-%'" } + failure: + - rejected: shipping.address_invalid + then: { goto: await-address-fix } # forward recovery after pivot + timeout: { after: PT1H, retry: { max: 3, backoff: exponential, initial: PT5M }, then: manual } + next: complete + + - id: await-address-fix + await: { success: orders.address-corrected.v1 } + timeout: { after: P2D, then: manual } + next: create-shipment + +on: + completed: { send: { command: orders.mark-fulfilled.v1, map: { orderId: $data.orderId } } } + compensated: { send: { command: orders.cancel-order.v1, map: { orderId: $data.orderId, reason: $failure.code } } } + manual: { alert: true } # metric + structured log + dead-letter-style record diff --git a/tests/Golden/cases/27-local-steps/expected.bpmn b/tests/Golden/cases/27-local-steps/expected.bpmn new file mode 100644 index 00000000..c80495c7 --- /dev/null +++ b/tests/Golden/cases/27-local-steps/expected.bpmn @@ -0,0 +1,65 @@ + + + + + + + + + + Local steps, rejections of local commands and explicit no-timeout and no-compensation. + + Flow_2 + + + + Flow_6 + Flow_7 + + + Flow_1 + + + + Flow_1 + + + An operator resumes, retries or aborts the instance. + Flow_8 + + + Flow_2 + Flow_3 + + + Flow_3 + Flow_4 + + + Flow_4 + Flow_5 + + + Flow_5 + Flow_6 + + + Flow_7 + + + + Flow_8 + + PT10M + + + + + + + + + + + + diff --git a/tests/Golden/cases/27-local-steps/expected.diagnostics.json b/tests/Golden/cases/27-local-steps/expected.diagnostics.json new file mode 100644 index 00000000..fe51488c --- /dev/null +++ b/tests/Golden/cases/27-local-steps/expected.diagnostics.json @@ -0,0 +1 @@ +[] diff --git a/tests/Golden/cases/27-local-steps/expected.graph.json b/tests/Golden/cases/27-local-steps/expected.graph.json new file mode 100644 index 00000000..3b114fc8 --- /dev/null +++ b/tests/Golden/cases/27-local-steps/expected.graph.json @@ -0,0 +1,101 @@ +{ + "nodes": [ + { + "id": "start", + "kind": "start", + "label": "orders.order-placed.v1", + "compensable": false + }, + { + "id": "reject-if-needed", + "kind": "step", + "label": "reject-if-needed", + "sends": "orders.reject-order.v1", + "awaits": "orders.order-rejected-by-review.v1", + "compensable": false + }, + { + "id": "cancel", + "kind": "step", + "label": "cancel", + "sends": "orders.cancel-order.v1", + "awaits": "orders.order-cancelled.v1", + "timeout": "PT10M", + "compensable": false + }, + { + "id": "Completed", + "kind": "terminal", + "label": "Completed", + "compensable": false + }, + { + "id": "Compensating", + "kind": "compensating", + "label": "Compensating", + "compensable": false + }, + { + "id": "Compensated", + "kind": "terminal", + "label": "Compensated", + "compensable": false + }, + { + "id": "ManualIntervention", + "kind": "manual", + "label": "✋ Manual intervention", + "compensable": false + } + ], + "edges": [ + { + "id": "start->reject-if-needed:start:0", + "source": "start", + "target": "reject-if-needed", + "kind": "start", + "label": "▶ orders.order-placed.v1", + "description": "orders.order-placed.v1 starts the workflow at reject-if-needed" + }, + { + "id": "reject-if-needed->cancel:success:0", + "source": "reject-if-needed", + "target": "cancel", + "kind": "success", + "label": "✓ orders.order-rejected-by-review.v1", + "description": "Success: orders.order-rejected-by-review.v1 moves from reject-if-needed to cancel" + }, + { + "id": "cancel->Completed:success:0", + "source": "cancel", + "target": "Completed", + "kind": "success", + "label": "✓ orders.order-cancelled.v1", + "description": "Success: orders.order-cancelled.v1 moves from cancel to Completed" + }, + { + "id": "cancel->Completed:failure:0", + "source": "cancel", + "target": "Completed", + "kind": "failure", + "label": "✕ orders.already_shipped", + "description": "Failure: orders.already_shipped at cancel leads to Completed" + }, + { + "id": "cancel->ManualIntervention:timeout:0", + "source": "cancel", + "target": "ManualIntervention", + "kind": "timeout", + "label": "⏱ PT10M", + "description": "Timeout: after PT10M cancel leads to ManualIntervention" + }, + { + "id": "Compensating->Compensated:compensation:0", + "source": "Compensating", + "target": "Compensated", + "kind": "compensation", + "label": "⟲ nothing to undo", + "description": "Compensation: nothing to undo, the workflow is compensated" + } + ] +} diff --git a/tests/Golden/cases/27-local-steps/expected.mmd b/tests/Golden/cases/27-local-steps/expected.mmd new file mode 100644 index 00000000..adc1cf21 --- /dev/null +++ b/tests/Golden/cases/27-local-steps/expected.mmd @@ -0,0 +1,21 @@ +--- +title: review-order@3 (orders) +--- +stateDiagram-v2 + state "Compensating" as Compensating + state "Manual intervention" as ManualIntervention + state "reject-if-needed" as reject_if_needed + reject_if_needed : send orders.reject-order.v1 + reject_if_needed : await orders.order-rejected-by-review.v1 + state "cancel" as cancel + cancel : send orders.cancel-order.v1 + cancel : await orders.order-cancelled.v1 + [*] --> reject_if_needed : orders.order-placed.v1 + reject_if_needed --> cancel : ✓ orders.order-rejected-by-review.v1 + cancel --> Completed : ✓ orders.order-cancelled.v1 + cancel --> Completed : ✕ orders.already_shipped + cancel --> ManualIntervention : ⏱ PT10M + Compensating --> Compensated : nothing to undo + Completed --> [*] + Compensated --> [*] + ManualIntervention --> [*] : ✋ operator resumes or aborts diff --git a/tests/Golden/cases/27-local-steps/expected.paths.txt b/tests/Golden/cases/27-local-steps/expected.paths.txt new file mode 100644 index 00000000..2ceeb7db --- /dev/null +++ b/tests/Golden/cases/27-local-steps/expected.paths.txt @@ -0,0 +1,5 @@ +P01 reject-if-needed: success → cancel: success ⇒ Completed +P02 reject-if-needed: success → cancel: rejected orders.already_shipped ⇒ Completed +P03 reject-if-needed: success → cancel: timeout ⇒ ManualIntervention + +edges: 4, uncovered: none diff --git a/tests/Golden/cases/27-local-steps/workflow.sfflow.yaml b/tests/Golden/cases/27-local-steps/workflow.sfflow.yaml new file mode 100644 index 00000000..c3120d19 --- /dev/null +++ b/tests/Golden/cases/27-local-steps/workflow.sfflow.yaml @@ -0,0 +1,26 @@ +sourceflow.workflow: 1 +name: review-order +version: 3 +owner: orders +description: Local steps, rejections of local commands and explicit no-timeout and no-compensation. +start: + on: orders.order-placed.v1 + correlate: data.orderId + when: "event.data.total > 0" +data: + orderId: { from: start.data.orderId } + reason: { type: string, default: 'manual review' } +steps: + - id: reject-if-needed + send: { command: orders.reject-order.v1, map: { orderId: event.data.orderId, reason: $data.reason } } + await: { success: orders.order-rejected-by-review.v1 } + timeout: { none: true, reason: the order service always answers } + compensate: { none: true, reason: a rejection is final } + - id: cancel + send: { command: orders.cancel-order.v1, map: { orderId: $data.orderId, reason: $data.reason } } + await: + success: orders.order-cancelled.v1 + failure: + - rejected: orders.already_shipped + then: complete + timeout: { after: PT10M, then: manual } diff --git a/tests/Golden/cases/28-retries-and-backoff/expected.bpmn b/tests/Golden/cases/28-retries-and-backoff/expected.bpmn new file mode 100644 index 00000000..c2be3c78 --- /dev/null +++ b/tests/Golden/cases/28-retries-and-backoff/expected.bpmn @@ -0,0 +1,54 @@ + + + + + + + + + Flow_2 + + + + Flow_4 + Flow_5 + + + Flow_1 + + + + Flow_1 + + + An operator resumes, retries or aborts the instance. + + + Flow_2 + Flow_6 + Flow_3 + + + Flow_3 + Flow_4 + + + retry 1× (fixed, initial PT0S) + Flow_5 + + + + retry 20× (exponential, initial PT1S, cap PT1H) + Flow_6 + + PT1H + + + + + + + + + + diff --git a/tests/Golden/cases/28-retries-and-backoff/expected.diagnostics.json b/tests/Golden/cases/28-retries-and-backoff/expected.diagnostics.json new file mode 100644 index 00000000..fe51488c --- /dev/null +++ b/tests/Golden/cases/28-retries-and-backoff/expected.diagnostics.json @@ -0,0 +1 @@ +[] diff --git a/tests/Golden/cases/28-retries-and-backoff/expected.graph.json b/tests/Golden/cases/28-retries-and-backoff/expected.graph.json new file mode 100644 index 00000000..e4d95cbd --- /dev/null +++ b/tests/Golden/cases/28-retries-and-backoff/expected.graph.json @@ -0,0 +1,101 @@ +{ + "nodes": [ + { + "id": "start", + "kind": "start", + "label": "orders.order-placed.v1", + "compensable": false + }, + { + "id": "approve", + "kind": "step", + "label": "approve", + "sends": "orders.approve-order.v1", + "awaits": "orders.order-approved.v1", + "timeout": "PT1H", + "compensable": false + }, + { + "id": "Completed", + "kind": "terminal", + "label": "Completed", + "compensable": false + }, + { + "id": "Compensating", + "kind": "compensating", + "label": "Compensating", + "compensable": false + }, + { + "id": "Compensated", + "kind": "terminal", + "label": "Compensated", + "compensable": false + }, + { + "id": "ManualIntervention", + "kind": "manual", + "label": "✋ Manual intervention", + "compensable": false + } + ], + "edges": [ + { + "id": "start->approve:start:0", + "source": "start", + "target": "approve", + "kind": "start", + "label": "▶ orders.order-placed.v1", + "description": "orders.order-placed.v1 starts the workflow at approve" + }, + { + "id": "approve->Completed:success:0", + "source": "approve", + "target": "Completed", + "kind": "success", + "label": "✓ orders.order-approved.v1", + "description": "Success: orders.order-approved.v1 moves from approve to Completed" + }, + { + "id": "approve->approve:retry:0", + "source": "approve", + "target": "approve", + "kind": "retry", + "label": "↻ 1× on orders.order-rejected-by-review.v1", + "description": "Retry: approve is retried 1× on orders.order-rejected-by-review.v1" + }, + { + "id": "approve->Completed:failure:0", + "source": "approve", + "target": "Completed", + "kind": "failure", + "label": "✕ orders.order-rejected-by-review.v1", + "description": "Failure: orders.order-rejected-by-review.v1 at approve leads to Completed" + }, + { + "id": "approve->approve:retry:1", + "source": "approve", + "target": "approve", + "kind": "retry", + "label": "↻ 20× exponential from PT1S on timeout", + "description": "Retry: approve is retried 20× exponential from PT1S when it times out" + }, + { + "id": "approve->approve:timeout:0", + "source": "approve", + "target": "approve", + "kind": "timeout", + "label": "⏱ PT1H", + "description": "Timeout: after PT1H approve leads to approve" + }, + { + "id": "Compensating->Compensated:compensation:0", + "source": "Compensating", + "target": "Compensated", + "kind": "compensation", + "label": "⟲ nothing to undo", + "description": "Compensation: nothing to undo, the workflow is compensated" + } + ] +} diff --git a/tests/Golden/cases/28-retries-and-backoff/expected.mmd b/tests/Golden/cases/28-retries-and-backoff/expected.mmd new file mode 100644 index 00000000..3c6509ba --- /dev/null +++ b/tests/Golden/cases/28-retries-and-backoff/expected.mmd @@ -0,0 +1,19 @@ +--- +title: approve-order@1 (orders) +--- +stateDiagram-v2 + state "Compensating" as Compensating + state "Manual intervention" as ManualIntervention + state "approve" as approve + approve : send orders.approve-order.v1 + approve : await orders.order-approved.v1 + [*] --> approve : orders.order-placed.v1 + approve --> Completed : ✓ orders.order-approved.v1 + approve --> approve : ↻ 1× on orders.order-rejected-by-review.v1 + approve --> Completed : ✕ orders.order-rejected-by-review.v1 + approve --> approve : ↻ 20× exponential from PT1S on timeout + approve --> approve : ⏱ PT1H + Compensating --> Compensated : nothing to undo + Completed --> [*] + Compensated --> [*] + ManualIntervention --> [*] : ✋ operator resumes or aborts diff --git a/tests/Golden/cases/28-retries-and-backoff/expected.paths.txt b/tests/Golden/cases/28-retries-and-backoff/expected.paths.txt new file mode 100644 index 00000000..1dc02c5b --- /dev/null +++ b/tests/Golden/cases/28-retries-and-backoff/expected.paths.txt @@ -0,0 +1,13 @@ +P01 approve: success ⇒ Completed +P02 approve: failed orders.order-rejected-by-review.v1 → approve: success ⇒ Completed +P03 approve: failed orders.order-rejected-by-review.v1 → approve: timeout → approve: retry → approve: success ⇒ Completed +P04 approve: failed orders.order-rejected-by-review.v1 → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout (retries exhausted) → approve: success ⇒ Completed +P05 approve: failed orders.order-rejected-by-review.v1 → approve: failed orders.order-rejected-by-review.v1 (retries exhausted) ⇒ Completed +P06 approve: timeout → approve: retry → approve: success ⇒ Completed +P07 approve: timeout → approve: retry → approve: failed orders.order-rejected-by-review.v1 → approve: success ⇒ Completed +P08 approve: timeout → approve: retry → approve: failed orders.order-rejected-by-review.v1 → approve: failed orders.order-rejected-by-review.v1 (retries exhausted) ⇒ Completed +P09 approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout (retries exhausted) → approve: success ⇒ Completed +P10 approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout (retries exhausted) → approve: failed orders.order-rejected-by-review.v1 → approve: success ⇒ Completed +P11 approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout → approve: retry → approve: timeout (retries exhausted) → approve: failed orders.order-rejected-by-review.v1 → approve: failed orders.order-rejected-by-review.v1 (retries exhausted) ⇒ Completed + +edges: 4, uncovered: none diff --git a/tests/Golden/cases/28-retries-and-backoff/workflow.sfflow.yaml b/tests/Golden/cases/28-retries-and-backoff/workflow.sfflow.yaml new file mode 100644 index 00000000..c060a5d2 --- /dev/null +++ b/tests/Golden/cases/28-retries-and-backoff/workflow.sfflow.yaml @@ -0,0 +1,17 @@ +sourceflow.workflow: 1 +name: approve-order +version: 1 +owner: orders +start: { on: orders.order-placed.v1, correlate: data.orderId } +data: + orderId: { from: start.data.orderId } +steps: + - id: approve + send: { command: orders.approve-order.v1, map: { orderId: $data.orderId } } + await: + success: orders.order-approved.v1 + failure: + - on: orders.order-rejected-by-review.v1 + retry: { max: 1 } + then: complete + timeout: { after: PT1H, retry: { max: 20, backoff: exponential, initial: PT1S, cap: PT1H, jitter: false }, then: { goto: approve } } diff --git a/tests/Golden/cases/29-s01-anchors/expected.diagnostics.json b/tests/Golden/cases/29-s01-anchors/expected.diagnostics.json new file mode 100644 index 00000000..90d0820f --- /dev/null +++ b/tests/Golden/cases/29-s01-anchors/expected.diagnostics.json @@ -0,0 +1,9 @@ +[ + { + "id": "WF-S01", + "severity": "error", + "line": 12, + "column": 14, + "message": "Anchors and aliases are not allowed in workflow files; repeat the value instead (it keeps visual edits lossless)." + } +] diff --git a/tests/Golden/cases/29-s01-anchors/workflow.sfflow.yaml b/tests/Golden/cases/29-s01-anchors/workflow.sfflow.yaml new file mode 100644 index 00000000..4de78cff --- /dev/null +++ b/tests/Golden/cases/29-s01-anchors/workflow.sfflow.yaml @@ -0,0 +1,16 @@ +sourceflow.workflow: 1 +name: approve-order +version: 1 +owner: orders +start: { on: orders.order-placed.v1, correlate: data.orderId } +data: + orderId: { from: start.data.orderId } +steps: + - id: approve + send: { command: orders.approve-order.v1, map: { orderId: $data.orderId } } + await: { success: orders.order-approved.v1 } + timeout: &wait { after: PT1H, then: manual } + - id: again + send: { command: orders.approve-order.v1, map: { orderId: $data.orderId } } + await: { success: orders.order-approved.v1 } + timeout: *wait diff --git a/tests/Golden/cases/30-v03-start-not-received/expected.diagnostics.json b/tests/Golden/cases/30-v03-start-not-received/expected.diagnostics.json new file mode 100644 index 00000000..0a345b9e --- /dev/null +++ b/tests/Golden/cases/30-v03-start-not-received/expected.diagnostics.json @@ -0,0 +1,9 @@ +[ + { + "id": "WF-V03", + "severity": "error", + "line": 5, + "column": 14, + "message": "The owner never receives the start message inventory.audited.v1: it is published to inventory.events, which orders doesn't subscribe to (or filters out)." + } +] diff --git a/tests/Golden/cases/30-v03-start-not-received/workflow.sfflow.yaml b/tests/Golden/cases/30-v03-start-not-received/workflow.sfflow.yaml new file mode 100644 index 00000000..a9f79657 --- /dev/null +++ b/tests/Golden/cases/30-v03-start-not-received/workflow.sfflow.yaml @@ -0,0 +1,12 @@ +sourceflow.workflow: 1 +name: approve-order +version: 1 +owner: orders +start: { on: inventory.audited.v1, correlate: data.orderId } +data: + orderId: { from: start.data.orderId } +steps: + - id: approve + send: { command: orders.approve-order.v1, map: { orderId: $data.orderId } } + await: { success: orders.order-approved.v1 } + timeout: { after: PT1H, then: manual } diff --git a/tests/Golden/cases/31-v17-pivot-backward/expected.diagnostics.json b/tests/Golden/cases/31-v17-pivot-backward/expected.diagnostics.json new file mode 100644 index 00000000..01ec236e --- /dev/null +++ b/tests/Golden/cases/31-v17-pivot-backward/expected.diagnostics.json @@ -0,0 +1,9 @@ +[ + { + "id": "WF-V17", + "severity": "error", + "line": 23, + "column": 17, + "message": "Step 'create-shipment' is at or after the pivot 'create-shipment', so 'goto: approve' can't go back before it (forward recovery only)." + } +] diff --git a/tests/Golden/cases/31-v17-pivot-backward/workflow.sfflow.yaml b/tests/Golden/cases/31-v17-pivot-backward/workflow.sfflow.yaml new file mode 100644 index 00000000..f66dc2c8 --- /dev/null +++ b/tests/Golden/cases/31-v17-pivot-backward/workflow.sfflow.yaml @@ -0,0 +1,25 @@ +sourceflow.workflow: 1 +name: ship-order +version: 1 +owner: orders +description: WF-V17. After the pivot only forward recovery is possible, so no step at or after it may go back before it. +start: { on: orders.order-placed.v1, correlate: data.orderId } +data: + orderId: { from: start.data.orderId } + lines: { from: start.data.lines } +steps: + - id: approve + send: { command: orders.approve-order.v1, map: { orderId: $data.orderId } } + await: { success: orders.order-approved.v1 } + timeout: { after: PT1H, then: manual } + + - id: create-shipment + pivot: true + send: { command: shipping.create-shipment.v1, map: { orderId: $data.orderId, lines: $data.lines } } + await: + success: shipping.shipment-created.v1 + failure: + - rejected: shipping.address_invalid + then: { goto: approve } # WF-V17: back before the pivot + timeout: { after: PT1H, then: { goto: create-shipment } } # forward recovery, at the pivot: allowed + next: complete diff --git a/tests/Golden/domain/inventory.manifest.json b/tests/Golden/domain/inventory.manifest.json new file mode 100644 index 00000000..ddcbc3ca --- /dev/null +++ b/tests/Golden/domain/inventory.manifest.json @@ -0,0 +1,128 @@ +{ + "manifestVersion": 1, + "service": "inventory", + "endpoint": "inventory", + "sourceflowVersion": "3.0.0", + "messages": [ + { + "type": "inventory.audited", + "version": 1, + "kind": "event", + "clrType": "InventoryAudited", + "fields": [ + { + "name": "orderId", + "type": "uuid" + } + ] + }, + { + "type": "inventory.release-stock", + "version": 1, + "kind": "command", + "clrType": "InventoryReleaseStock", + "aggregate": "stock", + "fields": [ + { + "name": "orderId", + "type": "uuid" + } + ] + }, + { + "type": "inventory.reserve-stock", + "version": 1, + "kind": "command", + "clrType": "InventoryReserveStock", + "aggregate": "stock", + "fields": [ + { + "name": "orderId", + "type": "uuid" + }, + { + "name": "lines", + "type": "array" + } + ] + }, + { + "type": "inventory.stock-released", + "version": 1, + "kind": "event", + "clrType": "InventoryStockReleased", + "fields": [ + { + "name": "orderId", + "type": "uuid" + } + ] + }, + { + "type": "inventory.stock-reserved", + "version": 1, + "kind": "event", + "clrType": "InventoryStockReserved", + "fields": [ + { + "name": "orderId", + "type": "uuid" + } + ] + } + ], + "aggregates": [ + { + "name": "stock", + "clrType": "Inventory.Stock", + "commands": [ + { + "type": "inventory.release-stock", + "version": 1, + "emits": [ + "inventory.stock-released.v1" + ], + "rejects": [] + }, + { + "type": "inventory.reserve-stock", + "version": 1, + "emits": [ + "inventory.stock-reserved.v1" + ], + "rejects": [ + "inventory.out_of_stock" + ] + } + ], + "events": [ + "inventory.audited.v1", + "inventory.stock-released.v1", + "inventory.stock-reserved.v1" + ] + } + ], + "processManagers": [], + "projections": [], + "publishes": [ + { + "domainEvent": "inventory.audited.v1", + "as": "inventory.audited.v1", + "topic": "inventory.events" + }, + { + "domainEvent": "inventory.stock-released.v1", + "as": "inventory.stock-released.v1", + "topic": "inventory.events" + }, + { + "domainEvent": "inventory.stock-reserved.v1", + "as": "inventory.stock-reserved.v1", + "topic": "inventory.events" + } + ], + "subscribes": [], + "commandRoutes": [], + "workflows": [], + "schemas": "catalog://inventory" +} diff --git a/tests/Golden/domain/orders.manifest.json b/tests/Golden/domain/orders.manifest.json new file mode 100644 index 00000000..ca28a95a --- /dev/null +++ b/tests/Golden/domain/orders.manifest.json @@ -0,0 +1,608 @@ +{ + "manifestVersion": 1, + "service": "orders", + "endpoint": "orders", + "sourceflowVersion": "3.0.0", + "messages": [ + { + "type": "billing.invoice", + "version": 1, + "kind": "command", + "clrType": "BillingInvoice", + "fields": [ + { + "name": "orderId", + "type": "uuid" + } + ] + }, + { + "type": "inventory.audited", + "version": 1, + "kind": "event", + "clrType": "InventoryAudited", + "fields": [ + { + "name": "orderId", + "type": "uuid" + } + ] + }, + { + "type": "inventory.release-stock", + "version": 1, + "kind": "command", + "clrType": "InventoryReleaseStock", + "aggregate": "stock", + "fields": [ + { + "name": "orderId", + "type": "uuid" + } + ] + }, + { + "type": "inventory.reserve-stock", + "version": 1, + "kind": "command", + "clrType": "InventoryReserveStock", + "aggregate": "stock", + "fields": [ + { + "name": "orderId", + "type": "uuid" + }, + { + "name": "lines", + "type": "array" + } + ] + }, + { + "type": "inventory.stock-released", + "version": 1, + "kind": "event", + "clrType": "InventoryStockReleased", + "fields": [ + { + "name": "orderId", + "type": "uuid" + } + ] + }, + { + "type": "inventory.stock-reserved", + "version": 1, + "kind": "event", + "clrType": "InventoryStockReserved", + "fields": [ + { + "name": "orderId", + "type": "uuid" + } + ] + }, + { + "type": "legacy.adjust", + "version": 1, + "kind": "command", + "clrType": "LegacyAdjust", + "aggregate": "ledger", + "fields": [ + { + "name": "orderId", + "type": "uuid" + } + ] + }, + { + "type": "orders.address-corrected", + "version": 1, + "kind": "event", + "clrType": "OrdersAddressCorrected", + "fields": [ + { + "name": "orderId", + "type": "uuid" + } + ] + }, + { + "type": "orders.approve-order", + "version": 1, + "kind": "command", + "clrType": "OrdersApproveOrder", + "aggregate": "order", + "fields": [ + { + "name": "orderId", + "type": "uuid" + } + ] + }, + { + "type": "orders.audit-noted", + "version": 1, + "kind": "event", + "clrType": "OrdersAuditNoted", + "fields": [ + { + "name": "note", + "type": "string" + } + ] + }, + { + "type": "orders.cancel-order", + "version": 1, + "kind": "command", + "clrType": "OrdersCancelOrder", + "aggregate": "order", + "fields": [ + { + "name": "orderId", + "type": "uuid" + }, + { + "name": "reason", + "type": "string" + } + ] + }, + { + "type": "orders.correct-address", + "version": 1, + "kind": "command", + "clrType": "OrdersCorrectAddress", + "aggregate": "order", + "fields": [ + { + "name": "orderId", + "type": "uuid" + } + ] + }, + { + "type": "orders.mark-fulfilled", + "version": 1, + "kind": "command", + "clrType": "OrdersMarkFulfilled", + "aggregate": "order", + "fields": [ + { + "name": "orderId", + "type": "uuid" + } + ] + }, + { + "type": "orders.note-audit", + "version": 1, + "kind": "command", + "clrType": "OrdersNoteAudit", + "aggregate": "order", + "fields": [ + { + "name": "note", + "type": "string" + } + ] + }, + { + "type": "orders.order-approved", + "version": 1, + "kind": "event", + "clrType": "OrdersOrderApproved", + "fields": [ + { + "name": "orderId", + "type": "uuid" + } + ] + }, + { + "type": "orders.order-cancelled", + "version": 1, + "kind": "event", + "clrType": "OrdersOrderCancelled", + "fields": [ + { + "name": "orderId", + "type": "uuid" + }, + { + "name": "reason", + "type": "string" + } + ] + }, + { + "type": "orders.order-fulfilled", + "version": 1, + "kind": "event", + "clrType": "OrdersOrderFulfilled", + "fields": [ + { + "name": "orderId", + "type": "uuid" + } + ] + }, + { + "type": "orders.order-placed", + "version": 1, + "kind": "event", + "clrType": "OrdersOrderPlaced", + "fields": [ + { + "name": "orderId", + "type": "uuid" + }, + { + "name": "total", + "type": "number" + }, + { + "name": "lines", + "type": "array" + }, + { + "name": "customerEmail", + "type": "string", + "personalData": true + }, + { + "name": "priority", + "type": "boolean" + } + ] + }, + { + "type": "orders.order-rejected-by-review", + "version": 1, + "kind": "event", + "clrType": "OrdersOrderRejectedByReview", + "fields": [ + { + "name": "orderId", + "type": "uuid" + }, + { + "name": "reason", + "type": "string" + } + ] + }, + { + "type": "orders.place-order", + "version": 1, + "kind": "command", + "clrType": "OrdersPlaceOrder", + "aggregate": "order", + "fields": [ + { + "name": "orderId", + "type": "uuid" + }, + { + "name": "total", + "type": "number" + }, + { + "name": "lines", + "type": "array" + }, + { + "name": "customerEmail", + "type": "string", + "personalData": true + } + ] + }, + { + "type": "orders.reject-order", + "version": 1, + "kind": "command", + "clrType": "OrdersRejectOrder", + "aggregate": "order", + "fields": [ + { + "name": "orderId", + "type": "uuid" + }, + { + "name": "reason", + "type": "string" + } + ] + }, + { + "type": "payments.charge", + "version": 1, + "kind": "command", + "clrType": "PaymentsCharge", + "aggregate": "payment", + "fields": [ + { + "name": "orderId", + "type": "uuid" + }, + { + "name": "amount", + "type": "number" + } + ] + }, + { + "type": "payments.payment-captured", + "version": 1, + "kind": "event", + "clrType": "PaymentsPaymentCaptured", + "fields": [ + { + "name": "paymentId", + "type": "uuid" + }, + { + "name": "orderId", + "type": "uuid" + }, + { + "name": "amount", + "type": "number" + }, + { + "name": "cardHolder", + "type": "string", + "personalData": true + } + ] + }, + { + "type": "payments.refund", + "version": 1, + "kind": "command", + "clrType": "PaymentsRefund", + "aggregate": "payment", + "fields": [ + { + "name": "paymentId", + "type": "uuid" + }, + { + "name": "amount", + "type": "number" + } + ] + }, + { + "type": "payments.refunded", + "version": 1, + "kind": "event", + "clrType": "PaymentsRefunded", + "fields": [ + { + "name": "paymentId", + "type": "uuid" + }, + { + "name": "orderId", + "type": "uuid" + } + ] + }, + { + "type": "payments.void", + "version": 1, + "kind": "command", + "clrType": "PaymentsVoid", + "aggregate": "payment", + "fields": [ + { + "name": "paymentId", + "type": "uuid" + } + ] + }, + { + "type": "payments.voided", + "version": 1, + "kind": "event", + "clrType": "PaymentsVoided", + "fields": [ + { + "name": "paymentId", + "type": "uuid" + } + ] + }, + { + "type": "shipping.create-shipment", + "version": 1, + "kind": "command", + "clrType": "ShippingCreateShipment", + "aggregate": "shipment", + "fields": [ + { + "name": "orderId", + "type": "uuid" + }, + { + "name": "lines", + "type": "array" + }, + { + "name": "note", + "type": "string", + "nullable": true + } + ] + }, + { + "type": "shipping.shipment-created", + "version": 1, + "kind": "event", + "clrType": "ShippingShipmentCreated", + "fields": [ + { + "name": "orderId", + "type": "uuid" + }, + { + "name": "shipmentId", + "type": "uuid" + } + ] + } + ], + "aggregates": [ + { + "name": "ledger", + "clrType": "Orders.Ledger", + "commands": [ + { + "type": "legacy.adjust", + "version": 1, + "emits": [], + "rejects": [] + } + ], + "events": [] + }, + { + "name": "order", + "clrType": "Orders.Order", + "commands": [ + { + "type": "orders.approve-order", + "version": 1, + "emits": [ + "orders.order-approved.v1" + ], + "rejects": [] + }, + { + "type": "orders.cancel-order", + "version": 1, + "emits": [ + "orders.order-cancelled.v1" + ], + "rejects": [ + "orders.already_shipped" + ] + }, + { + "type": "orders.correct-address", + "version": 1, + "emits": [ + "orders.address-corrected.v1" + ], + "rejects": [] + }, + { + "type": "orders.mark-fulfilled", + "version": 1, + "emits": [ + "orders.order-fulfilled.v1" + ], + "rejects": [] + }, + { + "type": "orders.note-audit", + "version": 1, + "emits": [ + "orders.audit-noted.v1" + ], + "rejects": [] + }, + { + "type": "orders.place-order", + "version": 1, + "emits": [ + "orders.order-placed.v1" + ], + "rejects": [ + "orders.empty" + ] + }, + { + "type": "orders.reject-order", + "version": 1, + "emits": [ + "orders.order-rejected-by-review.v1" + ], + "rejects": [] + } + ], + "events": [ + "orders.address-corrected.v1", + "orders.audit-noted.v1", + "orders.order-approved.v1", + "orders.order-cancelled.v1", + "orders.order-fulfilled.v1", + "orders.order-placed.v1", + "orders.order-rejected-by-review.v1" + ] + } + ], + "processManagers": [], + "projections": [], + "publishes": [ + { + "domainEvent": "orders.order-placed.v1", + "as": "orders.order-placed.v1", + "topic": "orders.events" + } + ], + "subscribes": [ + { + "topic": "inventory.events", + "only": [ + "inventory.stock-reserved.v1", + "inventory.stock-released.v1" + ] + }, + { + "topic": "payments.events" + }, + { + "topic": "shipping.events" + } + ], + "commandRoutes": [ + { + "command": "inventory.release-stock.v1", + "to": "inventory", + "replyOnReject": false + }, + { + "command": "inventory.reserve-stock.v1", + "to": "inventory", + "replyOnReject": true + }, + { + "command": "payments.charge.v1", + "to": "payments", + "replyOnReject": true + }, + { + "command": "payments.refund.v1", + "to": "payments", + "replyOnReject": false + }, + { + "command": "shipping.create-shipment.v1", + "to": "shipping", + "replyOnReject": true + } + ], + "workflows": [ + { + "name": "published-flow", + "version": 1, + "file": "workflows/published.sfflow.yaml", + "fingerprint": "sha256:0000000000000000" + } + ], + "schemas": "catalog://orders" +} diff --git a/tests/Golden/domain/payments.manifest.json b/tests/Golden/domain/payments.manifest.json new file mode 100644 index 00000000..2a7a41e6 --- /dev/null +++ b/tests/Golden/domain/payments.manifest.json @@ -0,0 +1,170 @@ +{ + "manifestVersion": 1, + "service": "payments", + "endpoint": "payments", + "sourceflowVersion": "3.0.0", + "messages": [ + { + "type": "payments.charge", + "version": 1, + "kind": "command", + "clrType": "PaymentsCharge", + "aggregate": "payment", + "fields": [ + { + "name": "orderId", + "type": "uuid" + }, + { + "name": "amount", + "type": "number" + } + ] + }, + { + "type": "payments.payment-captured", + "version": 1, + "kind": "event", + "clrType": "PaymentsPaymentCaptured", + "fields": [ + { + "name": "paymentId", + "type": "uuid" + }, + { + "name": "orderId", + "type": "uuid" + }, + { + "name": "amount", + "type": "number" + }, + { + "name": "cardHolder", + "type": "string", + "personalData": true + } + ] + }, + { + "type": "payments.refund", + "version": 1, + "kind": "command", + "clrType": "PaymentsRefund", + "aggregate": "payment", + "fields": [ + { + "name": "paymentId", + "type": "uuid" + }, + { + "name": "amount", + "type": "number" + } + ] + }, + { + "type": "payments.refunded", + "version": 1, + "kind": "event", + "clrType": "PaymentsRefunded", + "fields": [ + { + "name": "paymentId", + "type": "uuid" + }, + { + "name": "orderId", + "type": "uuid" + } + ] + }, + { + "type": "payments.void", + "version": 1, + "kind": "command", + "clrType": "PaymentsVoid", + "aggregate": "payment", + "fields": [ + { + "name": "paymentId", + "type": "uuid" + } + ] + }, + { + "type": "payments.voided", + "version": 1, + "kind": "event", + "clrType": "PaymentsVoided", + "fields": [ + { + "name": "paymentId", + "type": "uuid" + } + ] + } + ], + "aggregates": [ + { + "name": "payment", + "clrType": "Payments.Payment", + "commands": [ + { + "type": "payments.charge", + "version": 1, + "emits": [ + "payments.payment-captured.v1" + ], + "rejects": [ + "payments.declined", + "payments.fraud_suspected" + ] + }, + { + "type": "payments.refund", + "version": 1, + "emits": [ + "payments.refunded.v1" + ], + "rejects": [] + }, + { + "type": "payments.void", + "version": 1, + "emits": [ + "payments.voided.v1" + ], + "rejects": [] + } + ], + "events": [ + "payments.payment-captured.v1", + "payments.refunded.v1", + "payments.voided.v1" + ] + } + ], + "processManagers": [], + "projections": [], + "publishes": [ + { + "domainEvent": "payments.payment-captured.v1", + "as": "payments.payment-captured.v1", + "topic": "payments.events" + }, + { + "domainEvent": "payments.refunded.v1", + "as": "payments.refunded.v1", + "topic": "payments.events" + } + ], + "subscribes": [ + { + "topic": "orders.events" + } + ], + "commandRoutes": [], + "workflows": [], + "schemas": "catalog://payments" +} diff --git a/tests/Golden/domain/shipping.manifest.json b/tests/Golden/domain/shipping.manifest.json new file mode 100644 index 00000000..9b075ed3 --- /dev/null +++ b/tests/Golden/domain/shipping.manifest.json @@ -0,0 +1,106 @@ +{ + "manifestVersion": 1, + "service": "shipping", + "endpoint": "shipping", + "sourceflowVersion": "3.0.0", + "messages": [ + { + "type": "legacy.adjust", + "version": 1, + "kind": "command", + "clrType": "LegacyAdjust", + "aggregate": "ledger", + "fields": [ + { + "name": "orderId", + "type": "uuid" + } + ] + }, + { + "type": "shipping.create-shipment", + "version": 1, + "kind": "command", + "clrType": "ShippingCreateShipment", + "aggregate": "shipment", + "fields": [ + { + "name": "orderId", + "type": "uuid" + }, + { + "name": "lines", + "type": "array" + }, + { + "name": "note", + "type": "string", + "nullable": true + } + ] + }, + { + "type": "shipping.shipment-created", + "version": 1, + "kind": "event", + "clrType": "ShippingShipmentCreated", + "fields": [ + { + "name": "orderId", + "type": "uuid" + }, + { + "name": "shipmentId", + "type": "uuid" + } + ] + } + ], + "aggregates": [ + { + "name": "ledger", + "clrType": "Shipping.Ledger", + "commands": [ + { + "type": "legacy.adjust", + "version": 1, + "emits": [], + "rejects": [] + } + ], + "events": [] + }, + { + "name": "shipment", + "clrType": "Shipping.Shipment", + "commands": [ + { + "type": "shipping.create-shipment", + "version": 1, + "emits": [ + "shipping.shipment-created.v1" + ], + "rejects": [ + "shipping.address_invalid" + ] + } + ], + "events": [ + "shipping.shipment-created.v1" + ] + } + ], + "processManagers": [], + "projections": [], + "publishes": [ + { + "domainEvent": "shipping.shipment-created.v1", + "as": "shipping.shipment-created.v1", + "topic": "shipping.events" + } + ], + "subscribes": [], + "commandRoutes": [], + "workflows": [], + "schemas": "catalog://shipping" +} diff --git a/tests/Golden/domain/sourceflow.domain.yaml b/tests/Golden/domain/sourceflow.domain.yaml new file mode 100644 index 00000000..c930c75f --- /dev/null +++ b/tests/Golden/domain/sourceflow.domain.yaml @@ -0,0 +1,13 @@ +# The golden-suite domain (WF-GOLD): four services of a commerce domain. The manifests are hand-written in +# the exported shape; the orders service owns the workflows under ../cases. +domain: commerce +description: Order to delivery +services: + - name: orders + manifest: orders.manifest.json + - name: inventory + manifest: inventory.manifest.json + - name: payments + manifest: payments.manifest.json + - name: shipping + manifest: shipping.manifest.json diff --git a/tests/Hosting/SourceFlow.Hosting.Tests/CommandEndpointTests.cs b/tests/Hosting/SourceFlow.Hosting.Tests/CommandEndpointTests.cs new file mode 100644 index 00000000..b6653e47 --- /dev/null +++ b/tests/Hosting/SourceFlow.Hosting.Tests/CommandEndpointTests.cs @@ -0,0 +1,166 @@ +using System.Net; +using System.Net.Http.Json; +using System.Text.Json; +using Bank.Accounts; +using Microsoft.AspNetCore.Builder; +using Microsoft.AspNetCore.Hosting; +using Microsoft.AspNetCore.TestHost; +using SourceFlow.AspNetCore; +using SourceFlow.Hosting; + +namespace SourceFlow.Hosting.Tests; + +/// UT-ASP (plan 05): MapCommand HTTP semantics (doc 03 §5.1). +[Trait("Category", "Unit")] +public sealed class CommandEndpointTests : IAsyncLifetime +{ + private WebApplication _app = null!; + private HttpClient _client = null!; + + public async ValueTask InitializeAsync() + { + WebApplicationBuilder builder = WebApplication.CreateSlimBuilder(); + builder.WebHost.UseTestServer(); + builder.Services.AddSourceFlow(sf => + { + sf.ServiceName = "accounts"; + sf.AddModule(); + sf.UseInMemoryStorage(); + sf.UseInMemoryTransport(); + sf.Projections(p => p.Add().Inline()); + }); + _app = builder.Build(); + _app.MapCommand("/accounts/{accountId}"); + _app.MapCommand("/accounts/{accountId}/deposits"); + _app.MapCommand("/accounts/{accountId}/withdrawals"); + await _app.StartAsync(); + _client = _app.GetTestClient(); + } + + public async ValueTask DisposeAsync() + { + _client.Dispose(); + await _app.DisposeAsync(); + } + + [Fact] + [Trait("Id", "UT-ASP-01")] + public async Task Accepted_Returns200_WithETagAndConsistencyToken() + { + var id = AccountId.New(); + + HttpResponseMessage response = await Post($"/accounts/{id}", new { holder = "Ada", initialDeposit = 10 }); + + response.StatusCode.ShouldBe(HttpStatusCode.OK); + response.Headers.ETag!.Tag.ShouldBe("\"1\""); + response.Headers.GetValues(SourceFlowHeaders.Consistency).ShouldHaveSingleItem().ShouldContain(":"); + JsonDocument body = JsonDocument.Parse(await response.Content.ReadAsStringAsync()); + body.RootElement.GetProperty("status").GetString().ShouldBe("Accepted"); + body.RootElement.GetProperty("version").GetInt64().ShouldBe(1); + } + + [Fact] + [Trait("Id", "UT-ASP-02")] + [Trait("Covers", "ADR-018")] + public async Task Rejection_Returns422ProblemDetails_WithTheErrorCode() + { + var id = AccountId.New(); + await Post($"/accounts/{id}", new { holder = "Ada", initialDeposit = 10 }); + + HttpResponseMessage response = await Post($"/accounts/{id}/withdrawals", new { amount = 50 }); + + response.StatusCode.ShouldBe(HttpStatusCode.UnprocessableEntity); + response.Content.Headers.ContentType!.MediaType.ShouldBe("application/problem+json"); + JsonDocument problem = JsonDocument.Parse(await response.Content.ReadAsStringAsync()); + problem.RootElement.GetProperty("title").GetString().ShouldBe("account.insufficient_funds"); + } + + [Fact] + [Trait("Id", "UT-ASP-03")] + [Trait("Covers", "ADR-006")] + public async Task IdempotencyKey_RepeatReturnsTheOriginalResult() + { + var id = AccountId.New(); + await Post($"/accounts/{id}", new { holder = "Ada", initialDeposit = 10 }); + + HttpResponseMessage first = await Post($"/accounts/{id}/deposits", new { amount = 5 }, ("Idempotency-Key", "req-1")); + HttpResponseMessage second = await Post($"/accounts/{id}/deposits", new { amount = 5 }, ("Idempotency-Key", "req-1")); + + first.Headers.ETag!.Tag.ShouldBe("\"2\""); + second.StatusCode.ShouldBe(HttpStatusCode.OK); + second.Headers.ETag!.Tag.ShouldBe("\"2\""); + JsonDocument.Parse(await second.Content.ReadAsStringAsync()).RootElement.GetProperty("status").GetString().ShouldBe("Duplicate"); + } + + [Fact] + [Trait("Id", "UT-ASP-04")] + public async Task IfMatch_StaleVersion_Returns412() + { + var id = AccountId.New(); + await Post($"/accounts/{id}", new { holder = "Ada", initialDeposit = 10 }); + + HttpResponseMessage stale = await Post($"/accounts/{id}/deposits", new { amount = 5 }, ("If-Match", "\"7\"")); + HttpResponseMessage current = await Post($"/accounts/{id}/deposits", new { amount = 5 }, ("If-Match", "\"1\"")); + + stale.StatusCode.ShouldBe(HttpStatusCode.PreconditionFailed); + current.StatusCode.ShouldBe(HttpStatusCode.OK); + } + + [Theory] + [Trait("Id", "UT-ASP-05")] + [InlineData("not json")] + [InlineData("[1,2]")] + [InlineData("{\"amount\":\"lots\"}")] + public async Task UnreadableBody_Returns400(string body) + { + var request = new HttpRequestMessage(HttpMethod.Post, $"/accounts/{AccountId.New()}/deposits") + { + Content = new StringContent(body, System.Text.Encoding.UTF8, "application/json"), + }; + + HttpResponseMessage response = await _client.SendAsync(request); + + response.StatusCode.ShouldBe(HttpStatusCode.BadRequest); + } + + [Fact] + [Trait("Id", "UT-ASP-06")] + public async Task HealthCheck_ReportsReady() + { + SourceFlowHost host = (SourceFlowHost)_app.Services.GetService(typeof(SourceFlowHost))!; + + (await host.CheckHealthAsync(new Microsoft.Extensions.Diagnostics.HealthChecks.HealthCheckContext())).Status + .ShouldBe(Microsoft.Extensions.Diagnostics.HealthChecks.HealthStatus.Healthy); + } + + [Fact] + [Trait("Id", "UT-ASP-42")] + [Trait("Covers", "doc 03 5.1")] + public async Task ABodyNamingAnotherAggregateThanTheRoute_Is400_AndTheBodyCanRepeatTheRouteValue() + { + var route = AccountId.New(); + var other = AccountId.New(); + await Post($"/accounts/{route}", new { holder = "Ada", initialDeposit = 10 }); + await Post($"/accounts/{other}", new { holder = "Eve", initialDeposit = 10 }); + + // The route identifies the aggregate: a body that names another one must not redirect the command (CR-06). + HttpResponseMessage redirected = await Post($"/accounts/{route}/deposits", new { accountId = other.ToString(), amount = 5 }); + HttpResponseMessage repeated = await Post($"/accounts/{route}/deposits", new { accountId = route.ToString(), amount = 5 }); + + redirected.StatusCode.ShouldBe(HttpStatusCode.BadRequest); + (await redirected.Content.ReadAsStringAsync()).ShouldNotContain(other.ToString(), customMessage: "the error doesn't echo the values"); + repeated.StatusCode.ShouldBe(HttpStatusCode.OK); + repeated.Headers.ETag!.Tag.ShouldBe("\"2\""); + } + + private async Task Post(string path, object body, params (string Name, string Value)[] headers) + { + var request = new HttpRequestMessage(HttpMethod.Post, path) { Content = JsonContent.Create(body) }; + foreach ((string name, string value) in headers) + { + request.Headers.TryAddWithoutValidation(name, value); + } + + return await _client.SendAsync(request); + } +} diff --git a/tests/Hosting/SourceFlow.Hosting.Tests/FluentConfigurationTests.cs b/tests/Hosting/SourceFlow.Hosting.Tests/FluentConfigurationTests.cs new file mode 100644 index 00000000..0e053698 --- /dev/null +++ b/tests/Hosting/SourceFlow.Hosting.Tests/FluentConfigurationTests.cs @@ -0,0 +1,121 @@ +using System.Net; +using Bank.Accounts; +using Microsoft.AspNetCore.Builder; +using Microsoft.AspNetCore.Hosting; +using Microsoft.AspNetCore.TestHost; +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.Diagnostics.HealthChecks; +using Microsoft.Extensions.Options; +using SourceFlow.AspNetCore; +using SourceFlow.Hosting; +using SourceFlow.Query; +using SourceFlow.Transport; + +namespace SourceFlow.Hosting.Tests; + +/// +/// The fluent configuration: a service and its features enabled in one chain +/// (WithServiceName, WithRoles, WithProvisioning, WithHealthChecks, WithQueryApi, When), +/// and the endpoints mapped with MapSourceFlowHealthChecks. +/// +[Trait("Category", "Unit")] +public sealed class FluentConfigurationTests +{ + private static CancellationToken Ct => TestContext.Current.CancellationToken; + + [Fact] + [Trait("Id", "UT-HOST-09")] + public void TheChain_SetsTheServiceAndItsFeatures_AndWhenAppliesOnlyWhenTrue() + { + SourceFlowBuilder? configured = null; + var services = new ServiceCollection(); + services.AddSourceFlow(sf => configured = sf + .WithServiceName("accounts") + .WithRoles(SourceFlowRoles.Api) + .WithProvisioning(ProvisioningMode.Validate) + .AddModule() + .UseInMemoryStorage() + .UseInMemoryTransport() + .When(false, s => s.WithServiceName("never")) + .When(true, s => s.Configure(o => o.PollInterval = TimeSpan.FromSeconds(3)))); + + configured.ShouldNotBeNull(); + configured.ServiceName.ShouldBe("accounts"); + configured.Roles.ShouldBe(SourceFlowRoles.Api); + configured.Provisioning.ShouldBe(ProvisioningMode.Validate); + using ServiceProvider provider = services.BuildServiceProvider(); + provider.GetRequiredService>().Value.PollInterval.ShouldBe(TimeSpan.FromSeconds(3)); + Should.Throw(() => new ServiceCollection().AddSourceFlow(sf => sf.WithServiceName(" "))); + } + + [Fact] + [Trait("Id", "UT-ASP-38")] + public async Task WithHealthChecks_AndMapSourceFlowHealthChecks_ServeLivenessReadinessAndEveryCheck() + { + await using WebApplication app = await StartAsync(sf => sf.WithHealthChecks(), queries: false, health: true); + using HttpClient client = app.GetTestClient(); + + foreach (string path in (string[])["/health", "/health/ready", "/health/sourceflow"]) + { + HttpResponseMessage response = await client.GetAsync(path, Ct); + response.StatusCode.ShouldBe(HttpStatusCode.OK, path); + (await response.Content.ReadAsStringAsync(Ct)).ShouldBe("Healthy", path); + } + + app.Services.GetRequiredService>().Value.Registrations.Select(r => r.Name) + .ShouldBe(["sourceflow.ready", "sourceflow.store", "sourceflow.transport", "sourceflow.outbox", "sourceflow.subscriptions", "sourceflow.leases", "sourceflow.keys"], ignoreOrder: true); + } + + [Theory] + [Trait("Id", "UT-ASP-39")] + [InlineData(true)] + [InlineData(false)] + public async Task WithQueryApi_IsSwitchedOnAndOff_ByWhen(bool enabled) + { + if (!enabled) + { + // Mapping the query API without enabling it fails at startup, not at the first request. + (await Should.ThrowAsync(() => StartAsync(sf => sf.When(false, s => s.WithQueryApi()), queries: true))) + .Message.ShouldContain("AddSourceFlowQueryApi"); + return; + } + + await using WebApplication app = await StartAsync( + sf => sf.When(true, s => s.WithQueryApi(o => o.Permissions = _ => QueryPermissions.Of([QueryPermission.Schema]))), queries: true); + using HttpClient client = app.GetTestClient(); + + (await client.GetAsync("/query/schema", Ct)).StatusCode.ShouldBe(HttpStatusCode.OK); + } + + private static async Task StartAsync(Func features, bool queries, bool health = false) + { + WebApplicationBuilder builder = WebApplication.CreateSlimBuilder(); + builder.WebHost.UseTestServer(); + builder.Services.AddSourceFlow(sf => features(sf + .WithServiceName("accounts") + .AddModule() + .UseInMemoryStorage() + .UseInMemoryTransport())); + WebApplication app = builder.Build(); + if (health) + { + app.MapSourceFlowHealthChecks(); + } + + try + { + if (queries) + { + app.MapSourceFlowQueryApi().AllowAnonymous(); + } + + await app.StartAsync(Ct); + return app; + } + catch + { + await app.DisposeAsync(); + throw; + } + } +} diff --git a/tests/Hosting/SourceFlow.Hosting.Tests/QueryApiTests.cs b/tests/Hosting/SourceFlow.Hosting.Tests/QueryApiTests.cs new file mode 100644 index 00000000..337915c2 --- /dev/null +++ b/tests/Hosting/SourceFlow.Hosting.Tests/QueryApiTests.cs @@ -0,0 +1,550 @@ +using System.Net; +using System.Net.Http.Headers; +using System.Security.Claims; +using System.Text; +using System.Text.Encodings.Web; +using System.Text.Json; +using Bank.Accounts; +using Microsoft.AspNetCore.Authentication; +using Microsoft.AspNetCore.Authorization; +using Microsoft.AspNetCore.Builder; +using Microsoft.AspNetCore.Hosting; +using Microsoft.AspNetCore.Http; +using Microsoft.AspNetCore.Routing; +using Microsoft.AspNetCore.TestHost; +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.Logging; +using Microsoft.Extensions.Options; +using SourceFlow.AspNetCore; +using SourceFlow.Hosting; +using SourceFlow.Query; + +namespace SourceFlow.Hosting.Tests; + +/// UT-ASP-21..36 (plan 05): the per-service query API and domain queries over HTTP (doc 14 §9, ADR-026). +[Trait("Category", "Unit")] +public sealed class QueryApiTests : IAsyncLifetime +{ + private const string All = "sourceflow.query.adhoc sourceflow.query.readmodels sourceflow.query.events sourceflow.query.validate sourceflow.query.explain sourceflow.query.schema"; + private const string Summary = "from readmodel \"account-summary\""; + + private WebApplication _app = null!; + private HttpClient _client = null!; + + private static CancellationToken Ct => TestContext.Current.CancellationToken; + + public async ValueTask InitializeAsync() + { + (_app, _client) = await StartAsync(api => api.RequireAuthorization("sourceflow-query"), o => o.RequestsPerMinute = 1000); + foreach ((string holder, decimal balance) in new[] { ("Ada", 20m), ("=cmd|' /C calc'!A0", 50m), ("Grace", 900m) }) + { + (await Post($"/accounts/{AccountId.New()}", JsonSerializer.Serialize(new { holder, initialDeposit = balance }), user: null)).EnsureSuccessStatusCode(); + } + } + + public async ValueTask DisposeAsync() + { + _client.Dispose(); + await _app.DisposeAsync(); + } + + [Fact] + [Trait("Id", "UT-ASP-21")] + [Trait("Covers", "ADR-026")] + public async Task Mapping_WithoutAnAuthorizationPolicy_FailsStartup() + { + InvalidOperationException e = await Should.ThrowAsync(async () => await StartAsync(_ => { })); + + e.Message.ShouldStartWith(QueryCodes.AuthorizationRequired); + } + + [Fact] + [Trait("Id", "UT-ASP-22")] + public async Task Mapping_WithAnExplicitAllowAnonymous_Starts() + { + (WebApplication app, HttpClient client) = await StartAsync(api => api.AllowAnonymous()); + await using (app) + { + client.Dispose(); + } + } + + [Fact] + [Trait("Id", "UT-ASP-23")] + [Trait("Covers", "doc 14 9.1")] + public async Task Query_ReturnsColumnsRowsAndConsistency_WithSecurityHeaders() + { + HttpResponseMessage response = await Query(Summary + " | where balance < 100 | project holder, balance | order by balance"); + + response.StatusCode.ShouldBe(HttpStatusCode.OK); + response.Headers.GetValues("X-Content-Type-Options").ShouldBe(["nosniff"]); + response.Headers.GetValues("Cross-Origin-Resource-Policy").ShouldBe(["same-origin"]); + response.Headers.GetValues("Content-Security-Policy").Single().ShouldContain("default-src 'none'"); + response.Headers.CacheControl!.NoStore.ShouldBeTrue(); + JsonElement body = await Json(response); + body.GetProperty("columns").EnumerateArray().Select(c => c.GetProperty("name").GetString()).ShouldBe(["holder", "balance"]); + body.GetProperty("rows")[0][1].GetString().ShouldBe("20"); // decimals are exact strings + body.GetProperty("consistency").GetProperty("sources")[0].GetProperty("level").GetString().ShouldBe("eventual"); + body.GetProperty("queryHash").GetString()!.ShouldStartWith("sha256:"); + } + + [Fact] + [Trait("Id", "UT-ASP-24")] + [Trait("Covers", "doc 14 8")] + public async Task Query_WithoutTheAdhocPermission_Is403() + { + HttpResponseMessage response = await Query(Summary, permissions: "sourceflow.query.readmodels"); + + response.StatusCode.ShouldBe(HttpStatusCode.Forbidden); + response.Content.Headers.ContentType!.MediaType.ShouldBe("application/problem+json"); + (await Json(response)).GetProperty("code").GetString().ShouldBe(QueryCodes.PermissionDenied); + } + + [Fact] + [Trait("Id", "UT-ASP-25")] + public async Task Validate_NeverExecutes_AndReturnsDiagnostics() + { + JsonElement valid = await Json(await Post("/query/validate", Body(Summary + " | project holder"))); + JsonElement invalid = await Json(await Post("/query/validate", Body("DELETE FROM x", "sql"))); + + valid.GetProperty("valid").GetBoolean().ShouldBeTrue(); + valid.GetProperty("columns")[0].GetProperty("name").GetString().ShouldBe("holder"); + invalid.GetProperty("valid").GetBoolean().ShouldBeFalse(); + invalid.GetProperty("diagnostics")[0].GetProperty("code").GetString().ShouldBe(QueryCodes.Unsupported); + (await Post("/query/validate", Body(Summary), permissions: "sourceflow.query.adhoc")).StatusCode.ShouldBe(HttpStatusCode.Forbidden); + } + + [Fact] + [Trait("Id", "UT-ASP-26")] + public async Task Explain_ShowsThePlan_AndNeedsItsPermission() + { + JsonElement plan = await Json(await Post("/query/explain", Body(Summary + " | where balance < @b", parameters: "{\"b\": 5}"))); + + plan.GetProperty("engine").GetString().ShouldBe("in-memory"); + plan.GetProperty("parameterCount").GetInt32().ShouldBe(1); + (await Post("/query/explain", Body(Summary), permissions: "sourceflow.query.adhoc sourceflow.query.readmodels")).StatusCode.ShouldBe(HttpStatusCode.Forbidden); + } + + [Fact] + [Trait("Id", "UT-ASP-27")] + public async Task Schema_ListsSourcesAndFlagsPersonalData() + { + HttpRequestMessage request = new(HttpMethod.Get, "/query/schema"); + Authenticate(request, All, null); + JsonElement schema = await Json(await _client.SendAsync(request, Ct)); + + JsonElement opened = schema.GetProperty("events").EnumerateArray().Single(e => e.GetProperty("name").GetString() == "bank.account.opened"); + opened.GetProperty("versions")[0].GetProperty("fields").EnumerateArray().Single(f => f.GetProperty("name").GetString() == "holder") + .GetProperty("personalData").GetBoolean().ShouldBeTrue(); + schema.GetProperty("readModels")[0].GetProperty("name").GetString().ShouldBe("account-summary"); + } + + [Fact] + [Trait("Id", "UT-ASP-28")] + [Trait("Covers", "ADR-026")] + public async Task Problems_NeverEchoTheCallersText() + { + const string text = "SELECT * FROM readmodel.\"account-summary\"; DROP TABLE secret_marker_xyz"; + HttpResponseMessage response = await Query(text, language: "sql"); + string body = await response.Content.ReadAsStringAsync(Ct); + + response.StatusCode.ShouldBe(HttpStatusCode.BadRequest); + body.ShouldNotContain("secret_marker_xyz"); + body.ShouldNotContain("DROP TABLE"); + JsonDocument.Parse(body).RootElement.GetProperty("diagnostics")[0].GetProperty("code").GetString().ShouldBe(QueryCodes.Unsupported); + } + + [Fact] + [Trait("Id", "UT-ASP-29")] + public async Task TransportGuard_JsonOnly_BodySize_AndDepth() + { + HttpResponseMessage text = await Post("/query", "query", contentType: "text/plain"); + HttpResponseMessage large = await Post("/query", Body(Summary + " | where holder = '" + new string('a', 70_000) + "'")); + HttpResponseMessage deep = await Post("/query", "{\"query\":\"x\",\"parameters\":" + string.Concat(Enumerable.Repeat("{\"a\":", 20)) + "1" + new string('}', 20) + "}"); + + text.StatusCode.ShouldBe(HttpStatusCode.UnsupportedMediaType); + large.StatusCode.ShouldBe(HttpStatusCode.RequestEntityTooLarge); + deep.StatusCode.ShouldBe(HttpStatusCode.BadRequest); + } + + [Fact] + [Trait("Id", "UT-ASP-30")] + public async Task NdJson_StreamsRows_ThenATrailer() + { + HttpResponseMessage response = await Query(Summary + " | project holder | order by holder", accept: "application/x-ndjson", pageSize: 2); + string[] lines = (await response.Content.ReadAsStringAsync(Ct)).Split('\n', StringSplitOptions.RemoveEmptyEntries); + + response.Content.Headers.ContentType!.MediaType.ShouldBe("application/x-ndjson"); + lines.Length.ShouldBe(3); + JsonDocument.Parse(lines[0]).RootElement.GetProperty("holder").GetString().ShouldBe("=cmd|' /C calc'!A0"); + JsonDocument.Parse(lines[2]).RootElement.GetProperty("continuation").GetString().ShouldNotBeNullOrEmpty(); + } + + [Fact] + [Trait("Id", "UT-ASP-31")] + [Trait("Covers", "ADR-026")] + public async Task Csv_NeutralisesFormulas() + { + HttpResponseMessage response = await Query(Summary + " | project holder, balance | order by holder", accept: "text/csv"); + string csv = await response.Content.ReadAsStringAsync(Ct); + + response.Content.Headers.ContentType!.MediaType.ShouldBe("text/csv"); + string[] lines = csv.Split("\r\n", StringSplitOptions.RemoveEmptyEntries); + lines[0].ShouldBe("holder,balance"); + lines[1].ShouldBe("'=cmd|' /C calc'!A0,50"); + lines[2].ShouldBe("Ada,20"); + } + + [Fact] + [Trait("Id", "UT-ASP-32")] + public async Task RateLimit_Returns429_WithRetryAfter() + { + (WebApplication app, HttpClient client) = await StartAsync(api => api.RequireAuthorization("sourceflow-query"), o => o.RequestsPerMinute = 2); + await using (app) + { + HttpResponseMessage[] responses = new HttpResponseMessage[3]; + for (int i = 0; i < 3; i++) + { + var request = new HttpRequestMessage(HttpMethod.Post, "/query") { Content = new StringContent(Body(Summary), Encoding.UTF8, "application/json") }; + Authenticate(request, All, null); + responses[i] = await client.SendAsync(request, Ct); + } + + responses[0].StatusCode.ShouldBe(HttpStatusCode.OK); + responses[1].StatusCode.ShouldBe(HttpStatusCode.OK); + responses[2].StatusCode.ShouldBe(HttpStatusCode.TooManyRequests); + responses[2].Headers.RetryAfter.ShouldNotBeNull(); + (await Json(responses[2])).GetProperty("code").GetString().ShouldBe(QueryCodes.RateLimited); + client.Dispose(); + } + } + + [Fact] + [Trait("Id", "UT-ASP-33")] + public async Task InvalidContinuation_Is409() + { + HttpResponseMessage response = await Post("/query", Body(Summary, continuation: "not-a-token")); + + response.StatusCode.ShouldBe(HttpStatusCode.Conflict); + (await Json(response)).GetProperty("code").GetString().ShouldBe(QueryCodes.Continuation); + } + + [Fact] + [Trait("Id", "UT-ASP-34")] + [Trait("Covers", "doc 14 8")] + public async Task Tenant_ComesFromThePrincipal() + { + JsonElement own = await Json(await Query(Summary)); + JsonElement other = await Json(await Query(Summary, tenant: "another-tenant")); + + own.GetProperty("rows").GetArrayLength().ShouldBe(3); + other.GetProperty("rows").GetArrayLength().ShouldBe(0); + } + + [Fact] + [Trait("Id", "UT-ASP-35")] + [Trait("Covers", "Q-B4")] + public async Task DomainQueries_AreListed_AndRunWithQueryStringParameters() + { + var list = new HttpRequestMessage(HttpMethod.Get, "/queries"); + Authenticate(list, "", null); + JsonElement queries = await Json(await _client.SendAsync(list, Ct)); + var run = new HttpRequestMessage(HttpMethod.Get, "/queries/accounts.low-balance/v1?below=60"); + Authenticate(run, "", null); + JsonElement rows = await Json(await _client.SendAsync(run, Ct)); + var missing = new HttpRequestMessage(HttpMethod.Get, "/queries/accounts.nothing/v1"); + Authenticate(missing, "", null); + + JsonElement query = queries.GetProperty("queries").EnumerateArray().ShouldHaveSingleItem(); + query.GetProperty("path").GetString().ShouldBe("accounts.low-balance/v1"); + query.GetProperty("parameters")[0].GetString().ShouldBe("below"); + rows.GetProperty("columns").EnumerateArray().Select(c => c.GetProperty("name").GetString()).ShouldBe(["accountId", "holder", "balance"]); + rows.GetProperty("rows").EnumerateArray().Select(r => r[1].GetString()).ShouldBe(["Ada", "=cmd|' /C calc'!A0"]); + (await _client.SendAsync(missing, Ct)).StatusCode.ShouldBe(HttpStatusCode.NotFound); + } + + [Fact] + [Trait("Id", "UT-ASP-36")] + public async Task Unauthenticated_Is401() + { + var request = new HttpRequestMessage(HttpMethod.Post, "/query") { Content = new StringContent(Body(Summary), Encoding.UTF8, "application/json") }; + + (await _client.SendAsync(request, Ct)).StatusCode.ShouldBe(HttpStatusCode.Unauthorized); + } + + [Fact] + [Trait("Id", "UT-ASP-37")] + [Trait("Covers", "doc 14 9")] + public void DastOpenApiDocument_ListsExactlyTheMappedQueryEndpoints() + { + // deploy/dast/query-api.openapi.json drives the nightly OWASP ZAP scan: it must not miss an endpoint. + string? root = AppContext.BaseDirectory; + while (root is not null && !File.Exists(Path.Combine(root, "SourceFlow.slnx"))) + { + root = Path.GetDirectoryName(root); + } + + using JsonDocument document = JsonDocument.Parse(File.ReadAllText(Path.Combine(root!, "deploy", "dast", "query-api.openapi.json"))); + string[] documented = [.. document.RootElement.GetProperty("paths").EnumerateObject() + .SelectMany(p => p.Value.EnumerateObject().Select(m => m.Name.ToUpperInvariant() + " " + p.Name)) + .Order(StringComparer.Ordinal)]; + string[] mapped = [.. _app.Services.GetRequiredService().Endpoints.OfType() + .Where(e => e.Metadata.GetMetadata() is not null) + .SelectMany(e => e.Metadata.GetMetadata()!.HttpMethods.Select(m => m + " " + System.Text.RegularExpressions.Regex.Replace(e.RoutePattern.RawText!, ":[a-z]+}", "}").TrimEnd('/'))) + .Order(StringComparer.Ordinal)]; + + documented.ShouldBe(mapped); + } + + [Fact] + [Trait("Id", "UT-ASP-43")] + [Trait("Covers", "doc 14 9")] + public void Options_AreValidatedWhenTheApiIsRegistered() + { + Should.Throw(() => new ServiceCollection().AddSourceFlowQueryApi(o => o.MaxBodyBytes = 0)).Message.ShouldContain("MaxBodyBytes"); + Should.Throw(() => new ServiceCollection().AddSourceFlowQueryApi(o => (o.ConcurrencyPerPrincipal, o.ConcurrencyPerService) = (8, 4))).Message.ShouldContain("ConcurrencyPerPrincipal"); + Should.Throw(() => new ServiceCollection().AddSourceFlowQueryApi(o => o.Permissions = null!)).Message.ShouldContain("Permissions and Tenant"); + Should.NotThrow(() => new SourceFlowQueryApiOptions().Validate()); + } + + [Fact] + [Trait("Id", "UT-ASP-44")] + [Trait("Covers", "ADR-022")] + public void TheTenantResolver_ReadsTheCallersClaim_UnlessTheApplicationHasItsOwn() + { + static ServiceProvider Services(Action? before = null) + { + var services = new ServiceCollection(); + before?.Invoke(services); + services.AddSourceFlow(sf => + { + sf.ServiceName = "accounts"; + sf.AddModule(); + sf.UseInMemoryStorage(); + }); + services.AddSourceFlowQueryApi(); + return services.BuildServiceProvider(); + } + + using ServiceProvider claims = Services(); + var accessor = claims.GetRequiredService(); + var resolver = claims.GetRequiredService().ShouldBeOfType(); + resolver.TenantId.ShouldBeNull(); // outside a request: the default tenant + accessor.HttpContext = new DefaultHttpContext { User = new ClaimsPrincipal(new ClaimsIdentity([new Claim("tenant", "t-2"), new Claim("sourceflow:tenant", "t-1")], "test")) }; + resolver.TenantId.ShouldBe("t-1"); + accessor.HttpContext = new DefaultHttpContext { User = new ClaimsPrincipal(new ClaimsIdentity([new Claim("tenant", "t-2")], "test")) }; + resolver.TenantId.ShouldBe("t-2"); + + using ServiceProvider own = Services(s => s.AddSingleton()); + own.GetRequiredService().ShouldBeOfType(); + } + + private sealed class FixedTenant : SourceFlow.Runtime.ITenantResolver + { + public string? TenantId => "fixed"; + } + + [Fact] + [Trait("Id", "UT-ASP-41")] + [Trait("Covers", "Q-B4;doc 14 9.1")] + public async Task DomainQueries_WithTheirOwnPolicy_AreHiddenAndRefusedToCallersWithoutIt() + { + (WebApplication app, HttpClient client) = await StartAsync( + api => api.RequireAuthorization("sourceflow-query"), + sourceFlow: sf => sf.AddModule(), + authorization: a => a.AddPolicy(StatementHolders.Policy, p => p.RequireAssertion(c => + (c.User.FindFirst("scope")?.Value ?? string.Empty).Split(' ').Contains("accounts.statements")))); + await using (app) + { + async Task<(HttpStatusCode Status, JsonElement Body)> Get(string path, string scope) + { + var request = new HttpRequestMessage(HttpMethod.Get, path); + Authenticate(request, scope, null); + HttpResponseMessage response = await client.SendAsync(request, Ct); + return (response.StatusCode, JsonDocument.Parse(await response.Content.ReadAsStringAsync(Ct)).RootElement); + } + + (_, JsonElement listedWithout) = await Get("/queries", ""); + (HttpStatusCode refused, JsonElement problem) = await Get("/queries/accounts.statement-holders/v1", ""); + (_, JsonElement listedWith) = await Get("/queries", "accounts.statements"); + (HttpStatusCode allowed, _) = await Get("/queries/accounts.statement-holders/v1", "accounts.statements"); + (HttpStatusCode open, _) = await Get("/queries/accounts.low-balance/v1?below=60", ""); + + listedWithout.GetProperty("queries").EnumerateArray().Select(q => q.GetProperty("name").GetString()).ShouldBe(["accounts.low-balance"]); + refused.ShouldBe(HttpStatusCode.Forbidden); + problem.GetProperty("code").GetString().ShouldBe(QueryCodes.PermissionDenied); + listedWith.GetProperty("queries").EnumerateArray().Select(q => q.GetProperty("name").GetString()) + .ShouldBe(["accounts.low-balance", "accounts.statement-holders"], ignoreOrder: true); + allowed.ShouldBe(HttpStatusCode.OK); + open.ShouldBe(HttpStatusCode.OK, "a query without its own policy needs the group's policy only"); + } + + // A policy name that isn't registered fails startup, not every call. + InvalidOperationException unknown = await Should.ThrowAsync(() => + StartAsync(api => api.RequireAuthorization("sourceflow-query"), sourceFlow: sf => sf.AddModule())); + unknown.Message.ShouldContain(QueryCodes.AuthorizationRequired); + unknown.Message.ShouldContain(StatementHolders.Policy); + } + + // ================================================================ helpers + + private static async Task<(WebApplication App, HttpClient Client)> StartAsync( + Action secure, Action? configure = null, Action? sourceFlow = null, Action? authorization = null) + { + WebApplicationBuilder builder = WebApplication.CreateSlimBuilder(); + builder.WebHost.UseTestServer(); + builder.Services.AddSourceFlow(sf => + { + sf.ServiceName = "accounts"; + sf.AddModule(); + sf.UseInMemoryStorage(); + sf.UseInMemoryTransport(); + sf.Projections(p => p.Add().Inline()); + sourceFlow?.Invoke(sf); + }); + builder.Services.AddAuthentication("Test").AddScheme("Test", null); + AuthorizationBuilder policies = builder.Services.AddAuthorizationBuilder().AddPolicy("sourceflow-query", p => p.RequireAuthenticatedUser()); + authorization?.Invoke(policies); + builder.Services.AddSourceFlowQueryApi(configure); + WebApplication app = builder.Build(); + app.UseAuthentication(); + app.UseAuthorization(); + app.MapCommand("/accounts/{accountId}"); + secure(app.MapSourceFlowQueryApi()); + secure(app.MapDomainQueries()); + try + { + await app.StartAsync(); + } + catch + { + await app.DisposeAsync(); + throw; + } + + return (app, app.GetTestClient()); + } + + private Task Query(string text, string? language = null, string permissions = All, string? tenant = null, string? accept = null, int? pageSize = null) + { + return Post("/query", Body(text, language, pageSize: pageSize), permissions: permissions, tenant: tenant, accept: accept); + } + + private async Task Post(string path, string body, string? permissions = All, string? tenant = null, string? accept = null, string contentType = "application/json", string? user = "alice") + { + var request = new HttpRequestMessage(HttpMethod.Post, path) { Content = new StringContent(body, Encoding.UTF8) }; + request.Content.Headers.ContentType = new MediaTypeHeaderValue(contentType); + if (user is not null) + { + Authenticate(request, permissions ?? string.Empty, tenant); + } + + if (accept is not null) + { + request.Headers.Accept.ParseAdd(accept); + } + + return await _client.SendAsync(request, Ct); + } + + private static void Authenticate(HttpRequestMessage request, string permissions, string? tenant) + { + request.Headers.Add("X-Test-User", "alice"); + request.Headers.Add("X-Test-Permissions", permissions); + if (tenant is not null) + { + request.Headers.Add("X-Test-Tenant", tenant); + } + } + + private static string Body(string query, string? language = null, string? parameters = null, string? continuation = null, int? pageSize = null) + { + var body = new StringBuilder("{\"query\":").Append(JsonSerializer.Serialize(query)); + if (language is not null) + { + body.Append(",\"language\":\"").Append(language).Append('"'); + } + + if (parameters is not null) + { + body.Append(",\"parameters\":").Append(parameters); + } + + if (continuation is not null) + { + body.Append(",\"continuation\":\"").Append(continuation).Append('"'); + } + + if (pageSize is not null) + { + body.Append(",\"pageSize\":").Append(pageSize.Value); + } + + return body.Append('}').ToString(); + } + + private static async Task Json(HttpResponseMessage response) + { + return JsonDocument.Parse(await response.Content.ReadAsStringAsync(Ct)).RootElement.Clone(); + } + + /// Authenticates from X-Test-User / X-Test-Permissions / X-Test-Tenant headers. + private sealed class HeaderAuthentication(IOptionsMonitor options, ILoggerFactory logger, UrlEncoder encoder) + : AuthenticationHandler(options, logger, encoder) + { + protected override Task HandleAuthenticateAsync() + { + if (!Request.Headers.TryGetValue("X-Test-User", out Microsoft.Extensions.Primitives.StringValues user)) + { + return Task.FromResult(AuthenticateResult.NoResult()); + } + + var claims = new List { new(ClaimTypes.Name, user.ToString()), new("scope", Request.Headers["X-Test-Permissions"].ToString()) }; + if (Request.Headers.TryGetValue("X-Test-Tenant", out Microsoft.Extensions.Primitives.StringValues tenant)) + { + claims.Add(new Claim("tenant", tenant.ToString())); + } + + return Task.FromResult(AuthenticateResult.Success(new AuthenticationTicket(new ClaimsPrincipal(new ClaimsIdentity(claims, "Test")), "Test"))); + } + } +} + +/// A domain query guarded by its own policy, written by hand (this project doesn't run the generator). +public sealed record StatementHolders : IDomainQueryRuntime +{ + public const string Policy = "accounts-statements"; + + private static readonly DomainQueryParameter[] NoParameters = []; + private static readonly string[] Columns = ["holder"]; + + static string IDomainQueryRuntime.QueryName => "accounts.statement-holders"; + + static int IDomainQueryRuntime.QueryVersion => 1; + + static string? IDomainQueryRuntime.QueryPolicy => Policy; + + static string IDomainQueryRuntime.QueryText => "from readmodel \"account-summary\" | project holder | order by holder"; + + static bool IDomainQueryRuntime.IsSql => false; + + static IReadOnlyList IDomainQueryRuntime.QueryParameters => NoParameters; + + static IReadOnlyList IDomainQueryRuntime.ResultColumns => Columns; + + IReadOnlyDictionary IDomainQueryRuntime.ToParameters() => new Dictionary(); + + static StatementHolder IDomainQueryRuntime.Materialize(IQueryRow row) => + new(DomainQueryValues.Get(DomainQueryValues.Column(row, "holder"))); +} + +/// A row of . +public sealed record StatementHolder(string Holder); + +/// Registers . +public sealed class StatementQueriesModule : ISourceFlowModule +{ + static string ISourceFlowModule.ModuleName => nameof(StatementQueriesModule); + + static void ISourceFlowModule.Register(ISourceFlowModuleBuilder builder) => builder.AddDomainQuery(); +} diff --git a/tests/Hosting/SourceFlow.Hosting.Tests/SourceFlow.Hosting.Tests.csproj b/tests/Hosting/SourceFlow.Hosting.Tests/SourceFlow.Hosting.Tests.csproj new file mode 100644 index 00000000..a4ce4713 --- /dev/null +++ b/tests/Hosting/SourceFlow.Hosting.Tests/SourceFlow.Hosting.Tests.csproj @@ -0,0 +1,12 @@ + + + + + + + + + + + + diff --git a/tests/Shared/PublicApiApproval.cs b/tests/Shared/PublicApiApproval.cs new file mode 100644 index 00000000..011e1992 --- /dev/null +++ b/tests/Shared/PublicApiApproval.cs @@ -0,0 +1,29 @@ +using System.Reflection; +using System.Runtime.CompilerServices; +using PublicApiGenerator; +using SourceFlow.Testing; + +namespace SourceFlow.Tests.Shared; + +/// +/// Public API approval (plan 04 §6): renders an assembly's public surface with PublicApiGenerator and compares it +/// with an approved snapshot. Linked into category test projects that set IncludePublicApiApproval=true. +/// +internal static class PublicApiApproval +{ + public static void AssertApproved(Assembly assembly, [CallerFilePath] string callerFilePath = "") + { + var options = new ApiGeneratorOptions + { + ExcludeAttributes = + [ + "System.Runtime.CompilerServices.InternalsVisibleToAttribute", + "System.Reflection.AssemblyMetadataAttribute", + "System.Runtime.Versioning.TargetFrameworkAttribute", + ], + }; + + string api = assembly.GeneratePublicApi(options); + Approvals.AssertMatches(api, assembly.GetName().Name + ".PublicApi", callerFilePath); + } +} diff --git a/tests/Shared/StorageLinearizability.cs b/tests/Shared/StorageLinearizability.cs new file mode 100644 index 00000000..5e429f4d --- /dev/null +++ b/tests/Shared/StorageLinearizability.cs @@ -0,0 +1,194 @@ +using System.Text; +using System.Text.Json; +using CsCheck; +using SourceFlow.Messaging; +using SourceFlow.Storage; +using SourceFlow.Testing.Conformance; + +namespace SourceFlow.Tests.Shared; + +/// +/// CsCheck linearisability of appends and the outbox (WP-2.9, plan 06 §2). Parallel threads run a random mix of +/// Any appends, NoStream appends (which fail on an existing stream), and appends that publish an outbox +/// row. The resulting streams and outbox must equal the model after some sequential ordering of the same operations. +/// That checks the compare-and-set and that an append and its outbox row commit or fail together. +/// +internal static class StorageLinearizability +{ + private const string Tenant = MessageEnvelope.DefaultTenant; + private static readonly string[] Keys = ["k1", "k2"]; + + public static void AppendsAndOutbox(Func create, int iterations, int threads) + { + Gen<(Actual, Model)> initial = Gen.Const(0).Select(_ => (new Actual(create), new Model())); + Gen<(int Stream, int Payload, int Key)> args = Gen.Select(Gen.Int[0, 2], Gen.Int[1, 1_000_000], Gen.Int[0, 1]); + + GenOperation any = GenOperation.Create( + args, a => $"Any(s{a.Stream}, {a.Payload})", + (actual, a) => actual.Append(a.Stream, ExpectedVersion.Any, a.Payload, key: null), + (model, a) => model.Append(a.Stream, noStream: false, a.Payload, key: null)); + GenOperation noStream = GenOperation.Create( + args, a => $"NoStream(s{a.Stream}, {a.Payload})", + (actual, a) => actual.Append(a.Stream, ExpectedVersion.NoStream, a.Payload, key: null), + (model, a) => model.Append(a.Stream, noStream: true, a.Payload, key: null)); + GenOperation publish = GenOperation.Create( + args, a => $"Publish(s{a.Stream}, {a.Payload}, {Keys[a.Key]})", + (actual, a) => actual.Append(a.Stream, ExpectedVersion.NoStream, a.Payload, Keys[a.Key]), + (model, a) => model.Append(a.Stream, noStream: true, a.Payload, Keys[a.Key])); + + CsCheck.Check.SampleParallel(initial, [any, noStream, publish], (actual, model) => actual.Final.Equals(model.Final), + iter: iterations, threads: threads, printActual: a => a.Final.ToString(), printModel: m => m.Final.ToString()); + } + + /// The final observable state: stream payloads in version order and outbox payloads per key in order. + private sealed record State(SortedDictionary> Streams, SortedDictionary> Outbox) + { + public bool Equals(State? other) + { + return other is not null && Same(Streams, other.Streams) && Same(Outbox, other.Outbox); + } + + public override int GetHashCode() + { + return Streams.Count; + } + + public override string ToString() + { + return string.Join("; ", Streams.Select(s => $"s{s.Key}=[{string.Join(",", s.Value)}]")) + + " | " + string.Join("; ", Outbox.Select(o => $"{o.Key}=[{string.Join(",", o.Value)}]")); + } + + private static bool Same(SortedDictionary> a, SortedDictionary> b) + where TKey : notnull + { + return a.Count == b.Count && a.All(pair => b.TryGetValue(pair.Key, out List? other) && pair.Value.SequenceEqual(other)); + } + } + + private sealed class Model + { + private readonly SortedDictionary> _streams = []; + private readonly SortedDictionary> _outbox = new(StringComparer.Ordinal); + + public State Final => new(_streams, _outbox); + + public void Append(int stream, bool noStream, int payload, string? key) + { + if (noStream && _streams.ContainsKey(stream)) + { + return; + } + + (_streams.TryGetValue(stream, out List? list) ? list : _streams[stream] = []).Add(payload); + if (key is not null) + { + (_outbox.TryGetValue(key, out List? rows) ? rows : _outbox[key] = []).Add(payload); + } + } + } + + /// The store under test, created on first use so CsCheck's model-only replays never touch a database. + private sealed class Actual + { + private readonly Lazy _fixture; + private readonly string _prefix = "lin" + Guid.CreateVersion7().ToString("N")[..8]; + private readonly Lazy _final; + + // CsCheck compares against orderings on parallel threads; draining the outbox is destructive, so read once. + public State Final => _final.Value; + + public Actual(Func create) + { + _fixture = new Lazy(create, LazyThreadSafetyMode.ExecutionAndPublication); + _final = new Lazy(Read, LazyThreadSafetyMode.ExecutionAndPublication); + } + + public void Append(int stream, ExpectedVersion expected, int payload, string? key) + { + try + { + AppendAsync(stream, expected, payload, key).GetAwaiter().GetResult(); + } + catch (ConcurrencyException) + { + // NoStream on an existing stream: nothing is written. + } + } + + private async Task AppendAsync(int stream, ExpectedVersion expected, int payload, string? key) + { + await using IStorageSession session = await _fixture.Value.Sessions.BeginAsync(Tenant, CancellationToken.None); + session.Append(Stream(stream), "lin", expected, [StorageConformance.Event(data: $"{{\"n\":{payload}}}")]); + if (key is not null) + { + var envelope = new MessageEnvelope + { + MessageId = new MessageId(Guid.CreateVersion7()), + Type = "lin.published", + TypeVersion = 1, + Source = "lin", + Time = DateTimeOffset.UnixEpoch, + PartitionKey = key, + Body = Encoding.UTF8.GetBytes($"{{\"n\":{payload}}}"), + }; + session.EnqueueOutbox(new OutboxMessage(envelope, "dest", OutboxKind.Publish, DateTimeOffset.MinValue, 0)); + } + + await session.CommitAsync(CancellationToken.None); + } + + private State Read() + { + return ReadAsync().GetAwaiter().GetResult(); + } + + private async Task ReadAsync() + { + IStorageFixture f = _fixture.Value; + var streams = new SortedDictionary>(); + for (int s = 0; s < 3; s++) + { + StreamSlice slice = await f.Events.ReadStreamAsync(Tenant, Stream(s), new StreamVersion(1), 1000, CancellationToken.None); + if (slice.Events.Count > 0) + { + streams[s] = [.. slice.Events.Select(e => Payload(e.Data))]; + } + } + + // Drain the outbox through the relay contract: only heads are claimable, so this also checks per-key order. + var outbox = new SortedDictionary>(StringComparer.Ordinal); + LeaseToken lease = (await f.Leases.TryAcquireAsync("outbox:0", "lin-check", TimeSpan.FromMinutes(5), CancellationToken.None))!; + while (true) + { + IReadOnlyList claimed = await f.Outbox.ClaimAsync(0, lease, 100, CancellationToken.None); + if (claimed.Count == 0) + { + break; + } + + foreach (OutboxRecord record in claimed) + { + string key = record.Message.Envelope.PartitionKey!; + (outbox.TryGetValue(key, out List? rows) ? rows : outbox[key] = []).Add(Payload(record.Message.Envelope.Body)); + } + + await f.Outbox.CompleteAsync(lease, [.. claimed.Select(r => r.Sequence)], CancellationToken.None); + } + + // The final state is read once; release the store's connections now. + await f.DisposeAsync(); + return new State(streams, outbox); + } + + private StreamId Stream(int index) + { + return new StreamId($"{_prefix}-{index}"); + } + + private static int Payload(ReadOnlyMemory data) + { + return JsonDocument.Parse(data).RootElement.GetProperty("n").GetInt32(); + } + } +} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/Integration/AwsCircuitBreakerTests.cs b/tests/SourceFlow.Cloud.AWS.Tests/Integration/AwsCircuitBreakerTests.cs deleted file mode 100644 index 8f2ecddd..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/Integration/AwsCircuitBreakerTests.cs +++ /dev/null @@ -1,781 +0,0 @@ -using Amazon.SQS; -using Amazon.SQS.Model; -using Amazon.SimpleNotificationService; -using Amazon.SimpleNotificationService.Model; -using Microsoft.Extensions.DependencyInjection; -using Microsoft.Extensions.Logging; -using Microsoft.Extensions.Options; -using SourceFlow.Cloud.Resilience; -using SourceFlow.Cloud.AWS.Tests.TestHelpers; -using Xunit; -using Xunit.Abstractions; - -namespace SourceFlow.Cloud.AWS.Tests.Integration; - -/// -/// Integration tests for AWS circuit breaker pattern implementation -/// Tests automatic circuit opening on SQS/SNS service failures, half-open state recovery, -/// circuit closing on successful recovery, and circuit breaker configuration and monitoring -/// -[Collection("AWS Integration Tests")] -[Trait("Category", "Integration")] -[Trait("Category", "RequiresLocalStack")] -public class AwsCircuitBreakerTests : IAsyncLifetime -{ - private readonly ITestOutputHelper _output; - private IAwsTestEnvironment _environment = null!; - private readonly ILogger _logger; - private readonly string _testPrefix; - - public AwsCircuitBreakerTests(ITestOutputHelper output) - { - _output = output; - _testPrefix = $"cb-test-{Guid.NewGuid():N}"; - - var loggerFactory = LoggerFactory.Create(builder => - { - builder.AddConsole(); - builder.SetMinimumLevel(LogLevel.Debug); - }); - - _logger = loggerFactory.CreateLogger(); - } - - public async Task InitializeAsync() - { - _environment = await AwsTestEnvironmentFactory.CreateLocalStackEnvironmentAsync(_testPrefix); - } - - public async Task DisposeAsync() - { - await _environment.DisposeAsync(); - } - - /// - /// Test that circuit breaker opens automatically after consecutive SQS failures - /// Validates: Requirement 7.1 - Automatic circuit opening on SQS service failures - /// - [Fact] - public async Task CircuitBreaker_OpensAutomatically_OnConsecutiveSqsFailures() - { - // Arrange - var options = new CircuitBreakerOptions - { - FailureThreshold = 3, - OpenDuration = TimeSpan.FromSeconds(5), - SuccessThreshold = 2, - OperationTimeout = TimeSpan.FromSeconds(2) - }; - - var circuitBreaker = CreateCircuitBreaker(options); - var invalidQueueUrl = "http://localhost:4566/000000000000/nonexistent-queue"; - - // Track state changes - var stateChanges = new List(); - circuitBreaker.StateChanged += (sender, args) => stateChanges.Add(args.NewState); - - // Act - Execute operations that will fail - for (int i = 0; i < options.FailureThreshold; i++) - { - try - { - await circuitBreaker.ExecuteAsync(async () => - { - await _environment.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = invalidQueueUrl, - MessageBody = "test" - }); - }); - } - catch (Exception ex) - { - _output.WriteLine($"Expected failure {i + 1}: {ex.Message}"); - } - } - - // Assert - Circuit should be open - Assert.Equal(CircuitState.Open, circuitBreaker.State); - Assert.Contains(CircuitState.Open, stateChanges); - - var stats = circuitBreaker.GetStatistics(); - Assert.Equal(options.FailureThreshold, stats.FailedCalls); - Assert.Equal(options.FailureThreshold, stats.ConsecutiveFailures); - - // Verify that subsequent calls are rejected - await Assert.ThrowsAsync(async () => - { - await circuitBreaker.ExecuteAsync(async () => - { - await _environment.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = invalidQueueUrl, - MessageBody = "test" - }); - }); - }); - - var finalStats = circuitBreaker.GetStatistics(); - Assert.True(finalStats.RejectedCalls > 0, "Circuit breaker should reject calls when open"); - } - - /// - /// Test that circuit breaker opens automatically after consecutive SNS failures - /// Validates: Requirement 7.1 - Automatic circuit opening on SNS service failures - /// - [Fact] - public async Task CircuitBreaker_OpensAutomatically_OnConsecutiveSnsFailures() - { - // Arrange - var options = new CircuitBreakerOptions - { - FailureThreshold = 3, - OpenDuration = TimeSpan.FromSeconds(5), - SuccessThreshold = 2, - OperationTimeout = TimeSpan.FromSeconds(2) - }; - - var circuitBreaker = CreateCircuitBreaker(options); - var invalidTopicArn = "arn:aws:sns:us-east-1:000000000000:nonexistent-topic"; - - // Track state changes - var stateChanges = new List(); - circuitBreaker.StateChanged += (sender, args) => stateChanges.Add(args.NewState); - - // Act - Execute operations that will fail - for (int i = 0; i < options.FailureThreshold; i++) - { - try - { - await circuitBreaker.ExecuteAsync(async () => - { - await _environment.SnsClient.PublishAsync(new PublishRequest - { - TopicArn = invalidTopicArn, - Message = "test" - }); - }); - } - catch (Exception ex) - { - _output.WriteLine($"Expected failure {i + 1}: {ex.Message}"); - } - } - - // Assert - Circuit should be open - Assert.Equal(CircuitState.Open, circuitBreaker.State); - Assert.Contains(CircuitState.Open, stateChanges); - - var stats = circuitBreaker.GetStatistics(); - Assert.Equal(options.FailureThreshold, stats.FailedCalls); - } - - /// - /// Test that circuit breaker transitions to half-open state after timeout - /// Validates: Requirement 7.1 - Half-open state and recovery testing - /// - [Fact] - public async Task CircuitBreaker_TransitionsToHalfOpen_AfterTimeout() - { - // Arrange - var options = new CircuitBreakerOptions - { - FailureThreshold = 2, - OpenDuration = TimeSpan.FromSeconds(2), // Short duration for testing - SuccessThreshold = 2, - OperationTimeout = TimeSpan.FromSeconds(2) - }; - - var circuitBreaker = CreateCircuitBreaker(options); - var invalidQueueUrl = "http://localhost:4566/000000000000/nonexistent-queue"; - - // Track state changes - var stateChanges = new List<(CircuitState Previous, CircuitState New)>(); - circuitBreaker.StateChanged += (sender, args) => - stateChanges.Add((args.PreviousState, args.NewState)); - - // Act - Trigger circuit to open - for (int i = 0; i < options.FailureThreshold; i++) - { - try - { - await circuitBreaker.ExecuteAsync(async () => - { - await _environment.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = invalidQueueUrl, - MessageBody = "test" - }); - }); - } - catch { /* Expected */ } - } - - Assert.Equal(CircuitState.Open, circuitBreaker.State); - - // Wait for circuit to transition to half-open - await Task.Delay(options.OpenDuration + TimeSpan.FromMilliseconds(500)); - - // Trigger state check by attempting an operation - var queueUrl = await _environment.CreateStandardQueueAsync($"{_testPrefix}-halfopen"); - try - { - await circuitBreaker.ExecuteAsync(async () => - { - await _environment.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = queueUrl, - MessageBody = "test" - }); - }); - } - catch { /* May fail, but should trigger state transition */ } - - // Assert - Circuit should have transitioned through half-open - Assert.Contains(stateChanges, sc => sc.Previous == CircuitState.Open && sc.New == CircuitState.HalfOpen); - - // Cleanup - await _environment.DeleteQueueAsync(queueUrl); - } - - /// - /// Test that circuit breaker closes after successful operations in half-open state - /// Validates: Requirement 7.1 - Circuit closing on successful recovery - /// - [Fact] - public async Task CircuitBreaker_ClosesSuccessfully_AfterRecoveryInHalfOpenState() - { - // Arrange - var options = new CircuitBreakerOptions - { - FailureThreshold = 2, - OpenDuration = TimeSpan.FromSeconds(2), - SuccessThreshold = 2, // Need 2 successes to close - OperationTimeout = TimeSpan.FromSeconds(5) - }; - - var circuitBreaker = CreateCircuitBreaker(options); - var invalidQueueUrl = "http://localhost:4566/000000000000/nonexistent-queue"; - var validQueueUrl = await _environment.CreateStandardQueueAsync($"{_testPrefix}-recovery"); - - // Track state changes - var stateChanges = new List<(CircuitState Previous, CircuitState New, DateTime Time)>(); - circuitBreaker.StateChanged += (sender, args) => - stateChanges.Add((args.PreviousState, args.NewState, args.ChangedAt)); - - try - { - // Act - Step 1: Open the circuit - for (int i = 0; i < options.FailureThreshold; i++) - { - try - { - await circuitBreaker.ExecuteAsync(async () => - { - await _environment.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = invalidQueueUrl, - MessageBody = "test" - }); - }); - } - catch { /* Expected */ } - } - - Assert.Equal(CircuitState.Open, circuitBreaker.State); - _output.WriteLine($"Circuit opened at {DateTime.UtcNow}"); - - // Step 2: Wait for half-open transition - await Task.Delay(options.OpenDuration + TimeSpan.FromMilliseconds(500)); - - // Step 3: Execute successful operations to close the circuit - for (int i = 0; i < options.SuccessThreshold; i++) - { - await circuitBreaker.ExecuteAsync(async () => - { - await _environment.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = validQueueUrl, - MessageBody = $"Recovery test {i}" - }); - }); - _output.WriteLine($"Successful operation {i + 1} completed"); - } - - // Assert - Circuit should be closed - Assert.Equal(CircuitState.Closed, circuitBreaker.State); - - // Verify state transition sequence: Closed -> Open -> HalfOpen -> Closed - Assert.Contains(stateChanges, sc => sc.Previous == CircuitState.Closed && sc.New == CircuitState.Open); - Assert.Contains(stateChanges, sc => sc.Previous == CircuitState.Open && sc.New == CircuitState.HalfOpen); - Assert.Contains(stateChanges, sc => sc.Previous == CircuitState.HalfOpen && sc.New == CircuitState.Closed); - - var stats = circuitBreaker.GetStatistics(); - Assert.True(stats.SuccessfulCalls >= options.SuccessThreshold, - $"Should have at least {options.SuccessThreshold} successful calls, got {stats.SuccessfulCalls}"); - Assert.Equal(CircuitState.Closed, stats.CurrentState); - - _output.WriteLine($"Circuit closed successfully. Stats: {stats.SuccessfulCalls} successes, {stats.FailedCalls} failures"); - } - finally - { - // Cleanup - await _environment.DeleteQueueAsync(validQueueUrl); - } - } - - /// - /// Test that circuit breaker reopens if failure occurs in half-open state - /// Validates: Requirement 7.1 - Half-open state failure handling - /// - [Fact] - public async Task CircuitBreaker_ReopensImmediately_OnFailureInHalfOpenState() - { - // Arrange - var options = new CircuitBreakerOptions - { - FailureThreshold = 2, - OpenDuration = TimeSpan.FromSeconds(2), - SuccessThreshold = 2, - OperationTimeout = TimeSpan.FromSeconds(2) - }; - - var circuitBreaker = CreateCircuitBreaker(options); - var invalidQueueUrl = "http://localhost:4566/000000000000/nonexistent-queue"; - - // Track state changes - var stateChanges = new List<(CircuitState Previous, CircuitState New)>(); - circuitBreaker.StateChanged += (sender, args) => - stateChanges.Add((args.PreviousState, args.NewState)); - - // Act - Step 1: Open the circuit - for (int i = 0; i < options.FailureThreshold; i++) - { - try - { - await circuitBreaker.ExecuteAsync(async () => - { - await _environment.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = invalidQueueUrl, - MessageBody = "test" - }); - }); - } - catch { /* Expected */ } - } - - Assert.Equal(CircuitState.Open, circuitBreaker.State); - - // Step 2: Wait for half-open transition - await Task.Delay(options.OpenDuration + TimeSpan.FromMilliseconds(500)); - - // Step 3: Fail in half-open state - try - { - await circuitBreaker.ExecuteAsync(async () => - { - await _environment.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = invalidQueueUrl, - MessageBody = "test" - }); - }); - } - catch { /* Expected */ } - - // Assert - Circuit should be open again - Assert.Equal(CircuitState.Open, circuitBreaker.State); - - // Verify we transitioned: Open -> HalfOpen -> Open - var halfOpenToOpen = stateChanges.Where(sc => - sc.Previous == CircuitState.HalfOpen && sc.New == CircuitState.Open).ToList(); - Assert.NotEmpty(halfOpenToOpen); - } - - /// - /// Test circuit breaker configuration options - /// Validates: Requirement 7.1 - Circuit breaker configuration - /// - [Fact] - public void CircuitBreaker_Configuration_IsAppliedCorrectly() - { - // Arrange & Act - var options = new CircuitBreakerOptions - { - FailureThreshold = 10, - OpenDuration = TimeSpan.FromMinutes(5), - SuccessThreshold = 3, - OperationTimeout = TimeSpan.FromSeconds(60), - EnableFallback = true - }; - - var circuitBreaker = CreateCircuitBreaker(options); - - // Assert - Initial state - Assert.Equal(CircuitState.Closed, circuitBreaker.State); - - var stats = circuitBreaker.GetStatistics(); - Assert.Equal(CircuitState.Closed, stats.CurrentState); - Assert.Equal(0, stats.TotalCalls); - Assert.Equal(0, stats.FailedCalls); - Assert.Equal(0, stats.SuccessfulCalls); - Assert.Equal(0, stats.RejectedCalls); - } - - /// - /// Test circuit breaker statistics and monitoring - /// Validates: Requirement 7.1 - Circuit breaker monitoring - /// - [Fact] - public async Task CircuitBreaker_Statistics_TrackOperationsCorrectly() - { - // Arrange - var options = new CircuitBreakerOptions - { - FailureThreshold = 5, - OpenDuration = TimeSpan.FromSeconds(10), - SuccessThreshold = 2, - OperationTimeout = TimeSpan.FromSeconds(5) - }; - - var circuitBreaker = CreateCircuitBreaker(options); - var validQueueUrl = await _environment.CreateStandardQueueAsync($"{_testPrefix}-stats"); - var invalidQueueUrl = "http://localhost:4566/000000000000/nonexistent-queue"; - - try - { - // Act - Execute mix of successful and failed operations - // Successful operations - for (int i = 0; i < 3; i++) - { - await circuitBreaker.ExecuteAsync(async () => - { - await _environment.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = validQueueUrl, - MessageBody = $"Success {i}" - }); - }); - } - - // Failed operations (but not enough to open circuit) - for (int i = 0; i < 2; i++) - { - try - { - await circuitBreaker.ExecuteAsync(async () => - { - await _environment.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = invalidQueueUrl, - MessageBody = "test" - }); - }); - } - catch { /* Expected */ } - } - - // Assert - Verify statistics - var stats = circuitBreaker.GetStatistics(); - - Assert.Equal(5, stats.TotalCalls); - Assert.Equal(3, stats.SuccessfulCalls); - Assert.Equal(2, stats.FailedCalls); - Assert.Equal(0, stats.RejectedCalls); - Assert.Equal(CircuitState.Closed, stats.CurrentState); - Assert.Equal(2, stats.ConsecutiveFailures); - Assert.NotNull(stats.LastFailure); - Assert.NotNull(stats.LastException); - - _output.WriteLine($"Statistics: Total={stats.TotalCalls}, Success={stats.SuccessfulCalls}, " + - $"Failed={stats.FailedCalls}, Rejected={stats.RejectedCalls}"); - } - finally - { - // Cleanup - await _environment.DeleteQueueAsync(validQueueUrl); - } - } - - /// - /// Test circuit breaker with manual reset - /// Validates: Requirement 7.1 - Manual circuit breaker control - /// - [Fact] - public async Task CircuitBreaker_ManualReset_ClosesCircuitImmediately() - { - // Arrange - var options = new CircuitBreakerOptions - { - FailureThreshold = 2, - OpenDuration = TimeSpan.FromMinutes(10), // Long duration - SuccessThreshold = 2, - OperationTimeout = TimeSpan.FromSeconds(2) - }; - - var circuitBreaker = CreateCircuitBreaker(options); - var invalidQueueUrl = "http://localhost:4566/000000000000/nonexistent-queue"; - - // Act - Open the circuit - for (int i = 0; i < options.FailureThreshold; i++) - { - try - { - await circuitBreaker.ExecuteAsync(async () => - { - await _environment.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = invalidQueueUrl, - MessageBody = "test" - }); - }); - } - catch { /* Expected */ } - } - - Assert.Equal(CircuitState.Open, circuitBreaker.State); - - // Manually reset the circuit - circuitBreaker.Reset(); - - // Assert - Circuit should be closed immediately - Assert.Equal(CircuitState.Closed, circuitBreaker.State); - - var stats = circuitBreaker.GetStatistics(); - Assert.Equal(0, stats.ConsecutiveFailures); - Assert.Equal(0, stats.ConsecutiveSuccesses); - } - - /// - /// Test circuit breaker with manual trip - /// Validates: Requirement 7.1 - Manual circuit breaker control - /// - [Fact] - public void CircuitBreaker_ManualTrip_OpensCircuitImmediately() - { - // Arrange - var options = new CircuitBreakerOptions - { - FailureThreshold = 10, - OpenDuration = TimeSpan.FromSeconds(5), - SuccessThreshold = 2, - OperationTimeout = TimeSpan.FromSeconds(5) - }; - - var circuitBreaker = CreateCircuitBreaker(options); - - Assert.Equal(CircuitState.Closed, circuitBreaker.State); - - // Act - Manually trip the circuit - circuitBreaker.Trip(); - - // Assert - Circuit should be open immediately - Assert.Equal(CircuitState.Open, circuitBreaker.State); - } - - /// - /// Test circuit breaker state change events - /// Validates: Requirement 7.1 - Circuit breaker monitoring - /// - [Fact] - public async Task CircuitBreaker_StateChangeEvents_AreRaisedCorrectly() - { - // Arrange - var options = new CircuitBreakerOptions - { - FailureThreshold = 2, - OpenDuration = TimeSpan.FromSeconds(2), - SuccessThreshold = 1, - OperationTimeout = TimeSpan.FromSeconds(2) - }; - - var circuitBreaker = CreateCircuitBreaker(options); - var invalidQueueUrl = "http://localhost:4566/000000000000/nonexistent-queue"; - var validQueueUrl = await _environment.CreateStandardQueueAsync($"{_testPrefix}-events"); - - // Track state change events - var events = new List(); - circuitBreaker.StateChanged += (sender, args) => events.Add(args); - - try - { - // Act - Trigger state changes - // 1. Closed -> Open - for (int i = 0; i < options.FailureThreshold; i++) - { - try - { - await circuitBreaker.ExecuteAsync(async () => - { - await _environment.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = invalidQueueUrl, - MessageBody = "test" - }); - }); - } - catch { /* Expected */ } - } - - // 2. Wait for Open -> HalfOpen - await Task.Delay(options.OpenDuration + TimeSpan.FromMilliseconds(500)); - - // 3. HalfOpen -> Closed - await circuitBreaker.ExecuteAsync(async () => - { - await _environment.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = validQueueUrl, - MessageBody = "recovery" - }); - }); - - // Assert - Verify events were raised - Assert.NotEmpty(events); - - // Should have: Closed->Open, Open->HalfOpen, HalfOpen->Closed - var closedToOpen = events.FirstOrDefault(e => - e.PreviousState == CircuitState.Closed && e.NewState == CircuitState.Open); - Assert.NotNull(closedToOpen); - Assert.NotNull(closedToOpen.LastException); - - var openToHalfOpen = events.FirstOrDefault(e => - e.PreviousState == CircuitState.Open && e.NewState == CircuitState.HalfOpen); - Assert.NotNull(openToHalfOpen); - - var halfOpenToClosed = events.FirstOrDefault(e => - e.PreviousState == CircuitState.HalfOpen && e.NewState == CircuitState.Closed); - Assert.NotNull(halfOpenToClosed); - - _output.WriteLine($"Total state change events: {events.Count}"); - foreach (var evt in events) - { - _output.WriteLine($" {evt.PreviousState} -> {evt.NewState} at {evt.ChangedAt}"); - } - } - finally - { - // Cleanup - await _environment.DeleteQueueAsync(validQueueUrl); - } - } - - /// - /// Test circuit breaker with operation timeout - /// Validates: Requirement 7.1 - Operation timeout handling - /// - [Fact] - public async Task CircuitBreaker_OperationTimeout_TriggersFailure() - { - // Arrange - var options = new CircuitBreakerOptions - { - FailureThreshold = 2, - OpenDuration = TimeSpan.FromSeconds(5), - SuccessThreshold = 2, - OperationTimeout = TimeSpan.FromMilliseconds(100) // Very short timeout - }; - - var circuitBreaker = CreateCircuitBreaker(options); - - // Act - Execute operations that will timeout - for (int i = 0; i < options.FailureThreshold; i++) - { - try - { - await circuitBreaker.ExecuteAsync(async () => - { - // Simulate slow operation - await Task.Delay(TimeSpan.FromSeconds(5)); - }); - } - catch (OperationCanceledException) - { - _output.WriteLine($"Operation {i + 1} timed out as expected"); - } - catch (Exception ex) - { - _output.WriteLine($"Operation {i + 1} failed: {ex.GetType().Name}"); - } - } - - // Assert - Circuit should be open due to timeouts - Assert.Equal(CircuitState.Open, circuitBreaker.State); - - var stats = circuitBreaker.GetStatistics(); - Assert.True(stats.FailedCalls >= options.FailureThreshold); - } - - /// - /// Test circuit breaker with concurrent operations - /// Validates: Requirement 7.1 - Thread-safe circuit breaker operation - /// - [Fact] - public async Task CircuitBreaker_ConcurrentOperations_AreThreadSafe() - { - // Arrange - var options = new CircuitBreakerOptions - { - FailureThreshold = 10, - OpenDuration = TimeSpan.FromSeconds(5), - SuccessThreshold = 2, - OperationTimeout = TimeSpan.FromSeconds(5) - }; - - var circuitBreaker = CreateCircuitBreaker(options); - var validQueueUrl = await _environment.CreateStandardQueueAsync($"{_testPrefix}-concurrent"); - - try - { - // Act - Execute concurrent operations - var tasks = Enumerable.Range(0, 20).Select(async i => - { - try - { - await circuitBreaker.ExecuteAsync(async () => - { - await _environment.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = validQueueUrl, - MessageBody = $"Concurrent message {i}" - }); - }); - return true; - } - catch - { - return false; - } - }); - - var results = await Task.WhenAll(tasks); - - // Assert - All operations should complete without race conditions - var stats = circuitBreaker.GetStatistics(); - Assert.Equal(20, stats.TotalCalls); - Assert.True(stats.SuccessfulCalls > 0); - Assert.Equal(CircuitState.Closed, stats.CurrentState); - - _output.WriteLine($"Concurrent operations: {stats.SuccessfulCalls} succeeded, {stats.FailedCalls} failed"); - } - finally - { - // Cleanup - await _environment.DeleteQueueAsync(validQueueUrl); - } - } - - private ICircuitBreaker CreateCircuitBreaker(CircuitBreakerOptions options) - { - var optionsWrapper = Options.Create(options); - var loggerFactory = LoggerFactory.Create(builder => - { - builder.AddConsole(); - builder.SetMinimumLevel(LogLevel.Debug); - }); - var logger = loggerFactory.CreateLogger(); - - return new CircuitBreaker(optionsWrapper, logger); - } -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/Integration/AwsDeadLetterQueueProcessingTests.cs b/tests/SourceFlow.Cloud.AWS.Tests/Integration/AwsDeadLetterQueueProcessingTests.cs deleted file mode 100644 index c2547970..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/Integration/AwsDeadLetterQueueProcessingTests.cs +++ /dev/null @@ -1,1461 +0,0 @@ -using Amazon.SQS; -using Amazon.SQS.Model; -using Microsoft.Extensions.DependencyInjection; -using Microsoft.Extensions.Logging; -using SourceFlow.Cloud.AWS.Monitoring; -using SourceFlow.Cloud.AWS.Tests.TestHelpers; -using SourceFlow.Cloud.DeadLetter; -using System.Text.Json; - -namespace SourceFlow.Cloud.AWS.Tests.Integration; - -/// -/// Comprehensive integration tests for AWS dead letter queue processing -/// Tests failed message capture, analysis, categorization, reprocessing, and monitoring -/// Validates Requirement 7.3 -/// -[Collection("AWS Integration Tests")] -[Trait("Category", "Integration")] -[Trait("Category", "RequiresLocalStack")] -public class AwsDeadLetterQueueProcessingTests : IClassFixture, IAsyncDisposable -{ - private readonly LocalStackTestFixture _localStack; - private readonly List _createdQueues = new(); - private readonly IDeadLetterStore _deadLetterStore; - private readonly ILogger _logger; - - public AwsDeadLetterQueueProcessingTests(LocalStackTestFixture localStack) - { - _localStack = localStack; - - // Create in-memory dead letter store for testing - var services = new ServiceCollection(); - services.AddLogging(builder => builder.AddConsole()); - services.AddSingleton(); - - var serviceProvider = services.BuildServiceProvider(); - _deadLetterStore = serviceProvider.GetRequiredService(); - _logger = serviceProvider.GetRequiredService>(); - } - - [Fact] - public async Task DeadLetterProcessing_ShouldCaptureCompleteMetadata() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.SqsClient == null) - { - return; - } - - // Arrange - Create main queue with DLQ - var mainQueueName = $"test-dlq-processing-main-{Guid.NewGuid():N}"; - var dlqName = $"test-dlq-processing-dead-{Guid.NewGuid():N}"; - - var dlqUrl = await CreateStandardQueueAsync(dlqName); - var dlqArn = await GetQueueArnAsync(dlqUrl); - - var mainQueueUrl = await CreateStandardQueueAsync(mainQueueName, new Dictionary - { - ["VisibilityTimeout"] = "2", - ["RedrivePolicy"] = JsonSerializer.Serialize(new - { - deadLetterTargetArn = dlqArn, - maxReceiveCount = 2 - }) - }); - - // Create test message with comprehensive metadata - var testCommand = new - { - CommandId = Guid.NewGuid(), - EntityId = 12345, - SequenceNo = 42, - CommandType = "ProcessOrderCommand", - PayloadType = "ProcessOrderPayload", - Timestamp = DateTime.UtcNow, - Data = new - { - OrderId = Guid.NewGuid(), - CustomerId = 9876, - Amount = 299.99m, - Items = new[] { "Item1", "Item2", "Item3" } - }, - Metadata = new Dictionary - { - ["CorrelationId"] = Guid.NewGuid().ToString(), - ["UserId"] = "user-123", - ["TenantId"] = "tenant-456" - } - }; - - // Act - Send message with comprehensive attributes - var sendResponse = await _localStack.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = mainQueueUrl, - MessageBody = JsonSerializer.Serialize(testCommand), - MessageAttributes = new Dictionary - { - ["CommandType"] = new MessageAttributeValue - { - DataType = "String", - StringValue = testCommand.CommandType - }, - ["PayloadType"] = new MessageAttributeValue - { - DataType = "String", - StringValue = testCommand.PayloadType - }, - ["EntityId"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = testCommand.EntityId.ToString() - }, - ["SequenceNo"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = testCommand.SequenceNo.ToString() - }, - ["CorrelationId"] = new MessageAttributeValue - { - DataType = "String", - StringValue = testCommand.Metadata["CorrelationId"] - }, - ["UserId"] = new MessageAttributeValue - { - DataType = "String", - StringValue = testCommand.Metadata["UserId"] - }, - ["TenantId"] = new MessageAttributeValue - { - DataType = "String", - StringValue = testCommand.Metadata["TenantId"] - }, - ["FailureReason"] = new MessageAttributeValue - { - DataType = "String", - StringValue = "ValidationError" - }, - ["SourceQueue"] = new MessageAttributeValue - { - DataType = "String", - StringValue = mainQueueUrl - } - } - }); - - Assert.NotNull(sendResponse.MessageId); - - // Act - Simulate processing failures by receiving without deleting - // The message will be moved to DLQ after maxReceiveCount (2) attempts - for (int attempt = 1; attempt <= 3; attempt++) - { - var receiveResponse = await _localStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = mainQueueUrl, - MaxNumberOfMessages = 1, - MessageAttributeNames = new List { "All" }, - AttributeNames = new List { "All" }, - WaitTimeSeconds = 2 - }); - - if (receiveResponse.Messages.Any()) - { - // Don't delete - simulate failure - // Wait for visibility timeout to expire so message becomes available again - await Task.Delay(2500); // Slightly longer than VisibilityTimeout (2s) - } - } - - // Wait a bit more for DLQ processing to complete - await Task.Delay(1000); - - // Act - Retrieve from DLQ and process - var dlqReceiveResponse = await _localStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = dlqUrl, - MaxNumberOfMessages = 1, - MessageAttributeNames = new List { "All" }, - AttributeNames = new List { "All" }, - WaitTimeSeconds = 5 - }); - - // Assert - Message should be in DLQ - Assert.Single(dlqReceiveResponse.Messages); - var dlqMessage = dlqReceiveResponse.Messages[0]; - - // Assert - All metadata should be preserved - Assert.Equal(testCommand.CommandType, dlqMessage.MessageAttributes["CommandType"].StringValue); - Assert.Equal(testCommand.PayloadType, dlqMessage.MessageAttributes["PayloadType"].StringValue); - Assert.Equal(testCommand.EntityId.ToString(), dlqMessage.MessageAttributes["EntityId"].StringValue); - Assert.Equal(testCommand.SequenceNo.ToString(), dlqMessage.MessageAttributes["SequenceNo"].StringValue); - Assert.Equal(testCommand.Metadata["CorrelationId"], dlqMessage.MessageAttributes["CorrelationId"].StringValue); - Assert.Equal(testCommand.Metadata["UserId"], dlqMessage.MessageAttributes["UserId"].StringValue); - Assert.Equal(testCommand.Metadata["TenantId"], dlqMessage.MessageAttributes["TenantId"].StringValue); - Assert.Equal("ValidationError", dlqMessage.MessageAttributes["FailureReason"].StringValue); - Assert.Equal(mainQueueUrl, dlqMessage.MessageAttributes["SourceQueue"].StringValue); - - // Assert - Message body should be intact - var dlqBody = JsonSerializer.Deserialize>(dlqMessage.Body); - Assert.NotNull(dlqBody); - Assert.True(dlqBody.ContainsKey("CommandId")); - Assert.True(dlqBody.ContainsKey("EntityId")); - Assert.True(dlqBody.ContainsKey("Data")); - Assert.True(dlqBody.ContainsKey("Metadata")); - - // Assert - SQS attributes should be available - Assert.True(dlqMessage.Attributes.ContainsKey("ApproximateReceiveCount")); - Assert.True(dlqMessage.Attributes.ContainsKey("SentTimestamp")); - - // Clean up - await _localStack.SqsClient.DeleteMessageAsync(new DeleteMessageRequest - { - QueueUrl = dlqUrl, - ReceiptHandle = dlqMessage.ReceiptHandle - }); - } - - [Fact] - public async Task DeadLetterProcessing_ShouldCategorizeMessagesByFailureType() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.SqsClient == null) - { - return; - } - - // Arrange - Create DLQ - var dlqName = $"test-dlq-categorization-{Guid.NewGuid():N}"; - var dlqUrl = await CreateStandardQueueAsync(dlqName); - - // Create messages with different failure types - var failureTypes = new[] - { - new { Type = "ValidationError", Description = "Invalid input data", Count = 3 }, - new { Type = "TimeoutError", Description = "External service timeout", Count = 2 }, - new { Type = "DataCorruption", Description = "Corrupted message payload", Count = 2 }, - new { Type = "ExternalServiceError", Description = "Third-party API failure", Count = 1 }, - new { Type = "InsufficientResources", Description = "Resource exhaustion", Count = 1 } - }; - - var sentMessages = new List(); - - // Act - Send messages with different failure types - foreach (var failureType in failureTypes) - { - for (int i = 0; i < failureType.Count; i++) - { - var messageBody = JsonSerializer.Serialize(new - { - CommandId = Guid.NewGuid(), - EntityId = 1000 + i, - FailureType = failureType.Type, - Description = failureType.Description, - Timestamp = DateTime.UtcNow - }); - - var sendResponse = await _localStack.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = dlqUrl, - MessageBody = messageBody, - MessageAttributes = new Dictionary - { - ["FailureType"] = new MessageAttributeValue - { - DataType = "String", - StringValue = failureType.Type - }, - ["FailureDescription"] = new MessageAttributeValue - { - DataType = "String", - StringValue = failureType.Description - }, - ["CommandType"] = new MessageAttributeValue - { - DataType = "String", - StringValue = "TestCommand" - }, - ["EntityId"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = (1000 + i).ToString() - } - } - }); - - sentMessages.Add(sendResponse.MessageId); - } - } - - // Act - Retrieve and categorize messages - var categorizedMessages = new Dictionary>(); - var maxAttempts = 10; - var attempts = 0; - - while (attempts < maxAttempts) - { - var receiveResponse = await _localStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = dlqUrl, - MaxNumberOfMessages = 10, - MessageAttributeNames = new List { "All" }, - WaitTimeSeconds = 1 - }); - - foreach (var message in receiveResponse.Messages) - { - if (message.MessageAttributes.TryGetValue("FailureType", out var failureTypeAttr)) - { - var failureType = failureTypeAttr.StringValue ?? "Unknown"; - - if (!categorizedMessages.ContainsKey(failureType)) - { - categorizedMessages[failureType] = new List(); - } - - categorizedMessages[failureType].Add(message); - } - } - - if (receiveResponse.Messages.Count == 0) - { - break; - } - - attempts++; - } - - // Assert - All failure types should be categorized - Assert.Equal(failureTypes.Length, categorizedMessages.Count); - - // Assert - Each category should have the correct count - foreach (var failureType in failureTypes) - { - Assert.True(categorizedMessages.ContainsKey(failureType.Type), - $"Missing failure type category: {failureType.Type}"); - - Assert.Equal(failureType.Count, categorizedMessages[failureType.Type].Count); - - // Verify all messages in category have correct attributes - foreach (var message in categorizedMessages[failureType.Type]) - { - Assert.Equal(failureType.Type, message.MessageAttributes["FailureType"].StringValue); - Assert.Equal(failureType.Description, message.MessageAttributes["FailureDescription"].StringValue); - Assert.True(message.MessageAttributes.ContainsKey("CommandType")); - Assert.True(message.MessageAttributes.ContainsKey("EntityId")); - } - } - - // Clean up - foreach (var category in categorizedMessages.Values) - { - foreach (var message in category) - { - await _localStack.SqsClient.DeleteMessageAsync(new DeleteMessageRequest - { - QueueUrl = dlqUrl, - ReceiptHandle = message.ReceiptHandle - }); - } - } - } - - [Fact] - public async Task DeadLetterProcessing_ShouldSupportMessageAnalysis() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.SqsClient == null) - { - return; - } - - // Arrange - Create DLQ with various failed messages - var dlqName = $"test-dlq-analysis-{Guid.NewGuid():N}"; - var dlqUrl = await CreateStandardQueueAsync(dlqName); - - // Create messages with different characteristics for analysis - var testMessages = new[] - { - new { EntityId = 1001, FailureType = "ValidationError", RetryCount = 3, Age = TimeSpan.FromHours(1) }, - new { EntityId = 1002, FailureType = "ValidationError", RetryCount = 5, Age = TimeSpan.FromHours(2) }, - new { EntityId = 1003, FailureType = "TimeoutError", RetryCount = 2, Age = TimeSpan.FromMinutes(30) }, - new { EntityId = 1004, FailureType = "TimeoutError", RetryCount = 4, Age = TimeSpan.FromHours(3) }, - new { EntityId = 1005, FailureType = "DataCorruption", RetryCount = 1, Age = TimeSpan.FromHours(24) } - }; - - // Send messages - foreach (var testMsg in testMessages) - { - var timestamp = DateTime.UtcNow.Subtract(testMsg.Age); - - await _localStack.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = dlqUrl, - MessageBody = JsonSerializer.Serialize(new - { - EntityId = testMsg.EntityId, - FailureType = testMsg.FailureType, - OriginalTimestamp = timestamp - }), - MessageAttributes = new Dictionary - { - ["EntityId"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = testMsg.EntityId.ToString() - }, - ["FailureType"] = new MessageAttributeValue - { - DataType = "String", - StringValue = testMsg.FailureType - }, - ["RetryCount"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = testMsg.RetryCount.ToString() - }, - ["OriginalTimestamp"] = new MessageAttributeValue - { - DataType = "String", - StringValue = timestamp.ToString("O") - }, - ["CommandType"] = new MessageAttributeValue - { - DataType = "String", - StringValue = "TestCommand" - } - } - }); - } - - // Act - Retrieve and analyze messages - var receiveResponse = await _localStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = dlqUrl, - MaxNumberOfMessages = 10, - MessageAttributeNames = new List { "All" }, - WaitTimeSeconds = 2 - }); - - var messages = receiveResponse.Messages; - - // Assert - All messages retrieved - Assert.Equal(testMessages.Length, messages.Count); - - // Analyze - Group by failure type - var failureTypeGroups = messages - .GroupBy(m => m.MessageAttributes["FailureType"].StringValue) - .ToDictionary(g => g.Key ?? "Unknown", g => g.ToList()); - - Assert.Equal(3, failureTypeGroups.Count); // ValidationError, TimeoutError, DataCorruption - Assert.Equal(2, failureTypeGroups["ValidationError"].Count); - Assert.Equal(2, failureTypeGroups["TimeoutError"].Count); - Assert.Single(failureTypeGroups["DataCorruption"]); - - // Analyze - Find high retry count messages (>= 4) - var highRetryMessages = messages - .Where(m => int.Parse(m.MessageAttributes["RetryCount"].StringValue ?? "0") >= 4) - .ToList(); - - Assert.Equal(2, highRetryMessages.Count); - - // Analyze - Find old messages (> 12 hours) - var oldMessages = messages - .Where(m => - { - if (m.MessageAttributes.TryGetValue("OriginalTimestamp", out var tsAttr)) - { - if (DateTime.TryParse(tsAttr.StringValue, out var timestamp)) - { - return DateTime.UtcNow.Subtract(timestamp).TotalHours > 12; - } - } - return false; - }) - .ToList(); - - Assert.Single(oldMessages); - - // Analyze - Calculate statistics - var totalRetries = messages - .Sum(m => int.Parse(m.MessageAttributes["RetryCount"].StringValue ?? "0")); - - var averageRetries = (double)totalRetries / messages.Count; - - Assert.True(averageRetries > 0); - Assert.True(averageRetries < 10); // Reasonable average - - // Clean up - foreach (var message in messages) - { - await _localStack.SqsClient.DeleteMessageAsync(new DeleteMessageRequest - { - QueueUrl = dlqUrl, - ReceiptHandle = message.ReceiptHandle - }); - } - } - - [Fact] - public async Task DeadLetterProcessing_ShouldSupportReprocessingWorkflow() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.SqsClient == null) - { - return; - } - - // Arrange - Create DLQ and reprocessing queue - var dlqName = $"test-dlq-reprocess-workflow-{Guid.NewGuid():N}"; - var dlqUrl = await CreateStandardQueueAsync(dlqName); - - var reprocessQueueName = $"test-reprocess-target-{Guid.NewGuid():N}"; - var reprocessQueueUrl = await CreateStandardQueueAsync(reprocessQueueName); - - // Add failed messages to DLQ - var failedMessages = new[] - { - new { OrderId = Guid.NewGuid(), EntityId = 2001, Status = "Failed", Reason = "PaymentTimeout" }, - new { OrderId = Guid.NewGuid(), EntityId = 2002, Status = "Failed", Reason = "InventoryUnavailable" }, - new { OrderId = Guid.NewGuid(), EntityId = 2003, Status = "Failed", Reason = "AddressValidationFailed" } - }; - - foreach (var failedMsg in failedMessages) - { - await _localStack.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = dlqUrl, - MessageBody = JsonSerializer.Serialize(failedMsg), - MessageAttributes = new Dictionary - { - ["EntityId"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = failedMsg.EntityId.ToString() - }, - ["OriginalFailureReason"] = new MessageAttributeValue - { - DataType = "String", - StringValue = failedMsg.Reason - }, - ["CommandType"] = new MessageAttributeValue - { - DataType = "String", - StringValue = "ProcessOrderCommand" - }, - ["FailureTimestamp"] = new MessageAttributeValue - { - DataType = "String", - StringValue = DateTime.UtcNow.ToString("O") - }, - ["ReprocessAttempt"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = "0" - } - } - }); - } - - // Act - Retrieve messages from DLQ - var dlqMessages = new List(); - var receiveResponse = await _localStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = dlqUrl, - MaxNumberOfMessages = 10, - MessageAttributeNames = new List { "All" }, - WaitTimeSeconds = 2 - }); - - dlqMessages.AddRange(receiveResponse.Messages); - - // Assert - Retrieved all failed messages - Assert.Equal(failedMessages.Length, dlqMessages.Count); - - // Act - Reprocess messages with enrichment - var reprocessedCount = 0; - - foreach (var dlqMessage in dlqMessages) - { - var originalBody = JsonSerializer.Deserialize>(dlqMessage.Body); - Assert.NotNull(originalBody); - - // Enrich message for reprocessing - var reprocessedBody = new Dictionary - { - ["OrderId"] = originalBody["OrderId"].GetGuid(), - ["EntityId"] = originalBody["EntityId"].GetInt32(), - ["Status"] = "Reprocessing", - ["OriginalStatus"] = originalBody["Status"].GetString() ?? "", - ["OriginalReason"] = originalBody["Reason"].GetString() ?? "", - ["ReprocessedAt"] = DateTime.UtcNow.ToString("O"), - ["ReprocessingStrategy"] = DetermineReprocessingStrategy( - dlqMessage.MessageAttributes["OriginalFailureReason"].StringValue ?? ""), - ["Priority"] = "High" // Reprocessed messages get high priority - }; - - // Send to reprocessing queue - var reprocessResponse = await _localStack.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = reprocessQueueUrl, - MessageBody = JsonSerializer.Serialize(reprocessedBody), - MessageAttributes = new Dictionary - { - ["ReprocessedFrom"] = new MessageAttributeValue - { - DataType = "String", - StringValue = "DeadLetterQueue" - }, - ["OriginalEntityId"] = new MessageAttributeValue - { - DataType = "String", - StringValue = dlqMessage.MessageAttributes["EntityId"].StringValue - }, - ["OriginalFailureReason"] = new MessageAttributeValue - { - DataType = "String", - StringValue = dlqMessage.MessageAttributes["OriginalFailureReason"].StringValue - }, - ["CommandType"] = new MessageAttributeValue - { - DataType = "String", - StringValue = dlqMessage.MessageAttributes["CommandType"].StringValue - }, - ["ReprocessAttempt"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = (int.Parse(dlqMessage.MessageAttributes["ReprocessAttempt"].StringValue ?? "0") + 1).ToString() - }, - ["ReprocessingStrategy"] = new MessageAttributeValue - { - DataType = "String", - StringValue = (string)reprocessedBody["ReprocessingStrategy"] - } - } - }); - - Assert.NotNull(reprocessResponse.MessageId); - - // Delete from DLQ after successful reprocessing - await _localStack.SqsClient.DeleteMessageAsync(new DeleteMessageRequest - { - QueueUrl = dlqUrl, - ReceiptHandle = dlqMessage.ReceiptHandle - }); - - reprocessedCount++; - } - - // Assert - All messages reprocessed - Assert.Equal(failedMessages.Length, reprocessedCount); - - // Act - Verify reprocessed messages in target queue - var reprocessedReceiveResponse = await _localStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = reprocessQueueUrl, - MaxNumberOfMessages = 10, - MessageAttributeNames = new List { "All" }, - WaitTimeSeconds = 2 - }); - - // Assert - All reprocessed messages available - Assert.Equal(failedMessages.Length, reprocessedReceiveResponse.Messages.Count); - - // Assert - Verify reprocessing metadata - foreach (var reprocessedMessage in reprocessedReceiveResponse.Messages) - { - Assert.Equal("DeadLetterQueue", reprocessedMessage.MessageAttributes["ReprocessedFrom"].StringValue); - Assert.True(int.Parse(reprocessedMessage.MessageAttributes["ReprocessAttempt"].StringValue ?? "0") > 0); - Assert.True(reprocessedMessage.MessageAttributes.ContainsKey("OriginalEntityId")); - Assert.True(reprocessedMessage.MessageAttributes.ContainsKey("OriginalFailureReason")); - Assert.True(reprocessedMessage.MessageAttributes.ContainsKey("ReprocessingStrategy")); - - var messageBody = JsonSerializer.Deserialize>(reprocessedMessage.Body); - Assert.NotNull(messageBody); - Assert.Equal("Reprocessing", messageBody["Status"].GetString()); - Assert.True(messageBody.ContainsKey("ReprocessedAt")); - Assert.True(messageBody.ContainsKey("ReprocessingStrategy")); - Assert.Equal("High", messageBody["Priority"].GetString()); - } - - // Clean up - foreach (var message in reprocessedReceiveResponse.Messages) - { - await _localStack.SqsClient.DeleteMessageAsync(new DeleteMessageRequest - { - QueueUrl = reprocessQueueUrl, - ReceiptHandle = message.ReceiptHandle - }); - } - - // Verify DLQ is empty - var dlqCheckResponse = await _localStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = dlqUrl, - MaxNumberOfMessages = 1, - WaitTimeSeconds = 1 - }); - - Assert.Empty(dlqCheckResponse.Messages); - } - - [Fact] - public async Task DeadLetterProcessing_ShouldSupportMonitoringAndAlerting() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.SqsClient == null) - { - return; - } - - // Arrange - Create DLQ for monitoring - var dlqName = $"test-dlq-monitoring-{Guid.NewGuid():N}"; - var dlqUrl = await CreateStandardQueueAsync(dlqName); - - // Configure monitoring options - var monitorOptions = new AwsDeadLetterMonitorOptions - { - Enabled = true, - DeadLetterQueues = new List { dlqUrl }, - CheckIntervalSeconds = 5, - BatchSize = 10, - StoreRecords = true, - SendAlerts = true, - AlertThreshold = 5, - DeleteAfterProcessing = false - }; - - // Add messages to DLQ to trigger monitoring - var messageCount = 7; // Above alert threshold - - for (int i = 0; i < messageCount; i++) - { - await _localStack.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = dlqUrl, - MessageBody = JsonSerializer.Serialize(new - { - CommandId = Guid.NewGuid(), - EntityId = 3000 + i, - FailureType = i % 2 == 0 ? "ValidationError" : "TimeoutError" - }), - MessageAttributes = new Dictionary - { - ["CommandType"] = new MessageAttributeValue - { - DataType = "String", - StringValue = "TestCommand" - }, - ["EntityId"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = (3000 + i).ToString() - }, - ["FailureType"] = new MessageAttributeValue - { - DataType = "String", - StringValue = i % 2 == 0 ? "ValidationError" : "TimeoutError" - } - } - }); - } - - // Act - Check queue depth (monitoring metric) - var attributesResponse = await _localStack.SqsClient.GetQueueAttributesAsync(new GetQueueAttributesRequest - { - QueueUrl = dlqUrl, - AttributeNames = new List - { - "ApproximateNumberOfMessages", - "ApproximateNumberOfMessagesNotVisible", - "ApproximateNumberOfMessagesDelayed" - } - }); - - var queueDepth = 0; - if (attributesResponse.Attributes.TryGetValue("ApproximateNumberOfMessages", out var depthStr)) - { - int.TryParse(depthStr, out queueDepth); - } - - // Assert - Queue depth should match sent messages - Assert.True(queueDepth >= messageCount * 0.8, // Allow some variance - $"Expected queue depth around {messageCount}, got {queueDepth}"); - - // Assert - Should trigger alert (depth > threshold) - Assert.True(queueDepth >= monitorOptions.AlertThreshold, - $"Queue depth {queueDepth} should exceed alert threshold {monitorOptions.AlertThreshold}"); - - // Act - Retrieve messages for monitoring analysis - var monitoredMessages = new List(); - var receiveResponse = await _localStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = dlqUrl, - MaxNumberOfMessages = 10, - MessageAttributeNames = new List { "All" }, - AttributeNames = new List { "All" }, - WaitTimeSeconds = 2 - }); - - monitoredMessages.AddRange(receiveResponse.Messages); - - // Assert - Messages retrieved for monitoring - Assert.True(monitoredMessages.Count >= messageCount * 0.8); - - // Act - Create dead letter records for monitoring - var deadLetterRecords = new List(); - - foreach (var message in monitoredMessages) - { - var receiveCount = 0; - if (message.Attributes.TryGetValue("ApproximateReceiveCount", out var countStr)) - { - int.TryParse(countStr, out receiveCount); - } - - var record = new DeadLetterRecord - { - MessageId = message.MessageId, - Body = message.Body, - MessageType = message.MessageAttributes["CommandType"].StringValue ?? "Unknown", - Reason = "DeadLetterQueueThresholdExceeded", - ErrorDescription = $"Message exceeded max receive count. Receive count: {receiveCount}", - OriginalSource = "TestQueue", - DeadLetterSource = dlqUrl, - CloudProvider = "aws", - DeadLetteredAt = DateTime.UtcNow, - DeliveryCount = receiveCount, - Metadata = new Dictionary() - }; - - // Add message attributes to metadata - foreach (var attr in message.MessageAttributes) - { - record.Metadata[attr.Key] = attr.Value.StringValue ?? string.Empty; - } - - // Save to store - await _deadLetterStore.SaveAsync(record); - deadLetterRecords.Add(record); - } - - // Assert - All records stored - Assert.Equal(monitoredMessages.Count, deadLetterRecords.Count); - - // Act - Query stored records - var query = new DeadLetterQuery - { - CloudProvider = "aws", - FromDate = DateTime.UtcNow.AddHours(-1) - }; - - var storedRecords = await _deadLetterStore.QueryAsync(query); - var storedRecordsList = storedRecords.ToList(); - - // Assert - Records can be queried - Assert.True(storedRecordsList.Count >= deadLetterRecords.Count); - - // Act - Generate monitoring statistics - var validationErrors = storedRecordsList.Count(r => r.Metadata.ContainsKey("FailureType") && - r.Metadata["FailureType"] == "ValidationError"); - var timeoutErrors = storedRecordsList.Count(r => r.Metadata.ContainsKey("FailureType") && - r.Metadata["FailureType"] == "TimeoutError"); - - // Assert - Statistics are meaningful - Assert.True(validationErrors > 0); - Assert.True(timeoutErrors > 0); - Assert.Equal(storedRecordsList.Count, validationErrors + timeoutErrors); - - // Clean up - foreach (var message in monitoredMessages) - { - await _localStack.SqsClient.DeleteMessageAsync(new DeleteMessageRequest - { - QueueUrl = dlqUrl, - ReceiptHandle = message.ReceiptHandle - }); - } - } - - [Fact] - public async Task DeadLetterProcessing_ShouldSupportBatchReprocessing() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.SqsClient == null) - { - return; - } - - // Arrange - Create DLQ with multiple messages - var dlqName = $"test-dlq-batch-reprocess-{Guid.NewGuid():N}"; - var dlqUrl = await CreateStandardQueueAsync(dlqName); - - var targetQueueName = $"test-batch-reprocess-target-{Guid.NewGuid():N}"; - var targetQueueUrl = await CreateStandardQueueAsync(targetQueueName); - - var batchSize = 10; - var sentMessageIds = new List(); - - // Add messages to DLQ - for (int i = 0; i < batchSize; i++) - { - var sendResponse = await _localStack.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = dlqUrl, - MessageBody = JsonSerializer.Serialize(new - { - CommandId = Guid.NewGuid(), - EntityId = 4000 + i, - BatchIndex = i, - Data = $"Batch message {i}" - }), - MessageAttributes = new Dictionary - { - ["EntityId"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = (4000 + i).ToString() - }, - ["CommandType"] = new MessageAttributeValue - { - DataType = "String", - StringValue = "BatchTestCommand" - }, - ["BatchIndex"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = i.ToString() - } - } - }); - - sentMessageIds.Add(sendResponse.MessageId); - } - - // Act - Batch retrieve from DLQ - var dlqMessages = new List(); - var receiveResponse = await _localStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = dlqUrl, - MaxNumberOfMessages = 10, // AWS max batch size - MessageAttributeNames = new List { "All" }, - WaitTimeSeconds = 2 - }); - - dlqMessages.AddRange(receiveResponse.Messages); - - // Assert - Retrieved batch - Assert.Equal(batchSize, dlqMessages.Count); - - // Act - Batch reprocess to target queue - var reprocessTasks = dlqMessages.Select(async message => - { - var reprocessedBody = JsonSerializer.Deserialize>(message.Body); - Assert.NotNull(reprocessedBody); - - // Add reprocessing metadata - var enrichedBody = new Dictionary - { - ["CommandId"] = reprocessedBody["CommandId"].GetGuid(), - ["EntityId"] = reprocessedBody["EntityId"].GetInt32(), - ["BatchIndex"] = reprocessedBody["BatchIndex"].GetInt32(), - ["Data"] = reprocessedBody["Data"].GetString() ?? "", - ["ReprocessedAt"] = DateTime.UtcNow.ToString("O"), - ["ReprocessedFromDLQ"] = true - }; - - return await _localStack.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = targetQueueUrl, - MessageBody = JsonSerializer.Serialize(enrichedBody), - MessageAttributes = new Dictionary - { - ["ReprocessedFrom"] = new MessageAttributeValue - { - DataType = "String", - StringValue = "DeadLetterQueue" - }, - ["OriginalEntityId"] = new MessageAttributeValue - { - DataType = "String", - StringValue = message.MessageAttributes["EntityId"].StringValue - }, - ["CommandType"] = new MessageAttributeValue - { - DataType = "String", - StringValue = message.MessageAttributes["CommandType"].StringValue - }, - ["BatchIndex"] = new MessageAttributeValue - { - DataType = "String", - StringValue = message.MessageAttributes["BatchIndex"].StringValue - } - } - }); - }); - - var reprocessResults = await Task.WhenAll(reprocessTasks); - - // Assert - All batch reprocessed - Assert.Equal(batchSize, reprocessResults.Length); - Assert.All(reprocessResults, result => Assert.NotNull(result.MessageId)); - - // Act - Batch delete from DLQ - var deleteTasks = dlqMessages.Select(message => - _localStack.SqsClient.DeleteMessageAsync(new DeleteMessageRequest - { - QueueUrl = dlqUrl, - ReceiptHandle = message.ReceiptHandle - })); - - await Task.WhenAll(deleteTasks); - - // Act - Verify reprocessed messages in target queue - var targetReceiveResponse = await _localStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = targetQueueUrl, - MaxNumberOfMessages = 10, - MessageAttributeNames = new List { "All" }, - WaitTimeSeconds = 2 - }); - - // Assert - All messages in target queue - Assert.Equal(batchSize, targetReceiveResponse.Messages.Count); - - // Assert - Verify batch ordering preserved - var orderedMessages = targetReceiveResponse.Messages - .OrderBy(m => int.Parse(m.MessageAttributes["BatchIndex"].StringValue ?? "0")) - .ToList(); - - for (int i = 0; i < orderedMessages.Count; i++) - { - Assert.Equal(i.ToString(), orderedMessages[i].MessageAttributes["BatchIndex"].StringValue); - } - - // Clean up - var cleanupTasks = targetReceiveResponse.Messages.Select(message => - _localStack.SqsClient.DeleteMessageAsync(new DeleteMessageRequest - { - QueueUrl = targetQueueUrl, - ReceiptHandle = message.ReceiptHandle - })); - - await Task.WhenAll(cleanupTasks); - - // Verify DLQ is empty - var dlqCheckResponse = await _localStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = dlqUrl, - MaxNumberOfMessages = 1, - WaitTimeSeconds = 1 - }); - - Assert.Empty(dlqCheckResponse.Messages); - } - - [Fact] - public async Task DeadLetterProcessing_ShouldSupportFifoQueueReprocessing() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.SqsClient == null) - { - return; - } - - // Arrange - Create FIFO DLQ and target queue - var dlqName = $"test-dlq-fifo-reprocess-{Guid.NewGuid():N}.fifo"; - var dlqUrl = await CreateFifoQueueAsync(dlqName); - - var targetQueueName = $"test-fifo-reprocess-target-{Guid.NewGuid():N}.fifo"; - var targetQueueUrl = await CreateFifoQueueAsync(targetQueueName); - - var entityId = 5000; - var messageGroupId = $"entity-{entityId}"; - - // Add ordered messages to FIFO DLQ - var fifoMessages = new[] - { - new { SequenceNo = 1, Command = "CreateOrder", Data = "Order data 1" }, - new { SequenceNo = 2, Command = "UpdateOrder", Data = "Order data 2" }, - new { SequenceNo = 3, Command = "ProcessPayment", Data = "Payment data" }, - new { SequenceNo = 4, Command = "ShipOrder", Data = "Shipping data" } - }; - - foreach (var msg in fifoMessages) - { - await _localStack.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = dlqUrl, - MessageBody = JsonSerializer.Serialize(msg), - MessageGroupId = messageGroupId, - MessageDeduplicationId = $"dlq-msg-{entityId}-{msg.SequenceNo}-{Guid.NewGuid():N}", - MessageAttributes = new Dictionary - { - ["EntityId"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = entityId.ToString() - }, - ["SequenceNo"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = msg.SequenceNo.ToString() - }, - ["CommandType"] = new MessageAttributeValue - { - DataType = "String", - StringValue = msg.Command - } - } - }); - } - - // Act - Retrieve messages from FIFO DLQ (should maintain order) - var dlqMessages = new List(); - var receiveResponse = await _localStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = dlqUrl, - MaxNumberOfMessages = 10, - MessageAttributeNames = new List { "All" }, - WaitTimeSeconds = 2 - }); - - dlqMessages.AddRange(receiveResponse.Messages); - - // Assert - All messages retrieved - Assert.Equal(fifoMessages.Length, dlqMessages.Count); - - // Act - Reprocess to target FIFO queue maintaining order - var reprocessedCount = 0; - - foreach (var dlqMessage in dlqMessages) - { - var originalBody = JsonSerializer.Deserialize>(dlqMessage.Body); - Assert.NotNull(originalBody); - - var sequenceNo = int.Parse(dlqMessage.MessageAttributes["SequenceNo"].StringValue ?? "0"); - - var reprocessedBody = new Dictionary - { - ["SequenceNo"] = sequenceNo, - ["Command"] = originalBody["Command"].GetString() ?? "", - ["Data"] = originalBody["Data"].GetString() ?? "", - ["ReprocessedAt"] = DateTime.UtcNow.ToString("O"), - ["ReprocessedFromDLQ"] = true - }; - - // Send to target FIFO queue with same message group - await _localStack.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = targetQueueUrl, - MessageBody = JsonSerializer.Serialize(reprocessedBody), - MessageGroupId = messageGroupId, // Maintain same group for ordering - MessageDeduplicationId = $"reprocess-{entityId}-{sequenceNo}-{Guid.NewGuid():N}", - MessageAttributes = new Dictionary - { - ["ReprocessedFrom"] = new MessageAttributeValue - { - DataType = "String", - StringValue = "DeadLetterQueue" - }, - ["EntityId"] = new MessageAttributeValue - { - DataType = "String", - StringValue = dlqMessage.MessageAttributes["EntityId"].StringValue - }, - ["SequenceNo"] = new MessageAttributeValue - { - DataType = "String", - StringValue = dlqMessage.MessageAttributes["SequenceNo"].StringValue - }, - ["CommandType"] = new MessageAttributeValue - { - DataType = "String", - StringValue = dlqMessage.MessageAttributes["CommandType"].StringValue - } - } - }); - - // Delete from DLQ - await _localStack.SqsClient.DeleteMessageAsync(new DeleteMessageRequest - { - QueueUrl = dlqUrl, - ReceiptHandle = dlqMessage.ReceiptHandle - }); - - reprocessedCount++; - } - - // Assert - All messages reprocessed - Assert.Equal(fifoMessages.Length, reprocessedCount); - - // Act - Verify messages in target queue maintain FIFO order - var targetMessages = new List(); - var targetReceiveResponse = await _localStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = targetQueueUrl, - MaxNumberOfMessages = 10, - MessageAttributeNames = new List { "All" }, - WaitTimeSeconds = 2 - }); - - targetMessages.AddRange(targetReceiveResponse.Messages); - - // Assert - All messages in target queue - Assert.Equal(fifoMessages.Length, targetMessages.Count); - - // Assert - FIFO ordering maintained - var orderedTargetMessages = targetMessages - .OrderBy(m => int.Parse(m.MessageAttributes["SequenceNo"].StringValue ?? "0")) - .ToList(); - - for (int i = 0; i < orderedTargetMessages.Count; i++) - { - var expectedSequenceNo = i + 1; - Assert.Equal(expectedSequenceNo.ToString(), orderedTargetMessages[i].MessageAttributes["SequenceNo"].StringValue); - } - - // Clean up - foreach (var message in targetMessages) - { - await _localStack.SqsClient.DeleteMessageAsync(new DeleteMessageRequest - { - QueueUrl = targetQueueUrl, - ReceiptHandle = message.ReceiptHandle - }); - } - } - - [Fact] - public async Task DeadLetterProcessing_ShouldTrackReprocessingHistory() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.SqsClient == null) - { - return; - } - - // Arrange - Create DLQ - var dlqName = $"test-dlq-history-{Guid.NewGuid():N}"; - var dlqUrl = await CreateStandardQueueAsync(dlqName); - - // Add message with reprocessing history - var messageId = Guid.NewGuid().ToString(); - var entityId = 6000; - - await _localStack.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = dlqUrl, - MessageBody = JsonSerializer.Serialize(new - { - CommandId = messageId, - EntityId = entityId, - Data = "Test data" - }), - MessageAttributes = new Dictionary - { - ["EntityId"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = entityId.ToString() - }, - ["CommandType"] = new MessageAttributeValue - { - DataType = "String", - StringValue = "TestCommand" - }, - ["OriginalFailureReason"] = new MessageAttributeValue - { - DataType = "String", - StringValue = "ValidationError" - }, - ["FirstFailureTimestamp"] = new MessageAttributeValue - { - DataType = "String", - StringValue = DateTime.UtcNow.AddHours(-2).ToString("O") - }, - ["ReprocessAttempt"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = "0" - } - } - }); - - // Act - Create dead letter record with history tracking - var receiveResponse = await _localStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = dlqUrl, - MaxNumberOfMessages = 1, - MessageAttributeNames = new List { "All" }, - WaitTimeSeconds = 2 - }); - - Assert.Single(receiveResponse.Messages); - var message = receiveResponse.Messages[0]; - - // Create dead letter record - var record = new DeadLetterRecord - { - MessageId = messageId, - Body = message.Body, - MessageType = message.MessageAttributes["CommandType"].StringValue ?? "Unknown", - Reason = message.MessageAttributes["OriginalFailureReason"].StringValue ?? "Unknown", - ErrorDescription = "Message failed validation and was moved to DLQ", - OriginalSource = "TestQueue", - DeadLetterSource = dlqUrl, - CloudProvider = "aws", - DeadLetteredAt = DateTime.UtcNow, - DeliveryCount = int.Parse(message.MessageAttributes["ReprocessAttempt"].StringValue ?? "0"), - Replayed = false, - Metadata = new Dictionary - { - ["EntityId"] = message.MessageAttributes["EntityId"].StringValue ?? "", - ["FirstFailureTimestamp"] = message.MessageAttributes["FirstFailureTimestamp"].StringValue ?? "", - ["ReprocessAttempt"] = message.MessageAttributes["ReprocessAttempt"].StringValue ?? "0" - } - }; - - // Save record - await _deadLetterStore.SaveAsync(record); - - // Assert - Record saved - var savedRecord = await _deadLetterStore.GetAsync(record.Id); - Assert.NotNull(savedRecord); - Assert.Equal(messageId, savedRecord.MessageId); - Assert.False(savedRecord.Replayed); - - // Act - Mark as replayed - await _deadLetterStore.MarkAsReplayedAsync(record.Id); - - // Assert - Record marked as replayed - var replayedRecord = await _deadLetterStore.GetAsync(record.Id); - Assert.NotNull(replayedRecord); - Assert.True(replayedRecord.Replayed); - Assert.NotNull(replayedRecord.ReplayedAt); - - // Act - Query reprocessing history - var query = new DeadLetterQuery - { - MessageType = "TestCommand", - Replayed = true, - CloudProvider = "aws" - }; - - var replayedRecords = await _deadLetterStore.QueryAsync(query); - var replayedRecordsList = replayedRecords.ToList(); - - // Assert - Can query replayed messages - Assert.True(replayedRecordsList.Any(r => r.MessageId == messageId)); - - // Clean up - await _localStack.SqsClient.DeleteMessageAsync(new DeleteMessageRequest - { - QueueUrl = dlqUrl, - ReceiptHandle = message.ReceiptHandle - }); - } - - // Helper methods - - private static string DetermineReprocessingStrategy(string failureReason) - { - return failureReason switch - { - "PaymentTimeout" => "RetryWithExtendedTimeout", - "InventoryUnavailable" => "RetryAfterInventoryCheck", - "AddressValidationFailed" => "ManualReview", - "ValidationError" => "RetryWithValidation", - "TimeoutError" => "RetryWithBackoff", - "DataCorruption" => "ManualIntervention", - _ => "StandardRetry" - }; - } - - private async Task CreateStandardQueueAsync(string queueName, Dictionary? additionalAttributes = null) - { - var attributes = new Dictionary - { - ["MessageRetentionPeriod"] = "1209600", - ["VisibilityTimeout"] = "30" - }; - - if (additionalAttributes != null) - { - foreach (var attr in additionalAttributes) - { - attributes[attr.Key] = attr.Value; - } - } - - var response = await _localStack.SqsClient.CreateQueueAsync(new CreateQueueRequest - { - QueueName = queueName, - Attributes = attributes - }); - - _createdQueues.Add(response.QueueUrl); - return response.QueueUrl; - } - - private async Task CreateFifoQueueAsync(string queueName, Dictionary? additionalAttributes = null) - { - var attributes = new Dictionary - { - ["FifoQueue"] = "true", - ["ContentBasedDeduplication"] = "true", - ["MessageRetentionPeriod"] = "1209600", - ["VisibilityTimeout"] = "30" - }; - - if (additionalAttributes != null) - { - foreach (var attr in additionalAttributes) - { - attributes[attr.Key] = attr.Value; - } - } - - var response = await _localStack.SqsClient.CreateQueueAsync(new CreateQueueRequest - { - QueueName = queueName, - Attributes = attributes - }); - - _createdQueues.Add(response.QueueUrl); - return response.QueueUrl; - } - - private async Task GetQueueArnAsync(string queueUrl) - { - var response = await _localStack.SqsClient.GetQueueAttributesAsync(new GetQueueAttributesRequest - { - QueueUrl = queueUrl, - AttributeNames = new List { "QueueArn" } - }); - - return response.Attributes["QueueArn"]; - } - - public async ValueTask DisposeAsync() - { - if (_localStack.SqsClient != null) - { - foreach (var queueUrl in _createdQueues) - { - try - { - await _localStack.SqsClient.DeleteQueueAsync(new DeleteQueueRequest - { - QueueUrl = queueUrl - }); - } - catch (Exception) - { - // Ignore cleanup errors - } - } - } - - _createdQueues.Clear(); - } -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/Integration/AwsHealthCheckIntegrationTests.cs b/tests/SourceFlow.Cloud.AWS.Tests/Integration/AwsHealthCheckIntegrationTests.cs deleted file mode 100644 index 089534d6..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/Integration/AwsHealthCheckIntegrationTests.cs +++ /dev/null @@ -1,830 +0,0 @@ -using Amazon.KeyManagementService.Model; -using Amazon.SimpleNotificationService.Model; -using Amazon.SQS.Model; -using SourceFlow.Cloud.AWS.Tests.TestHelpers; - -namespace SourceFlow.Cloud.AWS.Tests.Integration; - -/// -/// Comprehensive integration tests for AWS health check functionality -/// Tests SQS queue health, SNS topic health, KMS key health, service connectivity, and health check performance -/// **Validates: Requirements 4.1, 4.2, 4.3, 4.4, 4.5** -/// -[Collection("AWS Integration Tests")] -[Trait("Category", "Integration")] -[Trait("Category", "RequiresLocalStack")] -public class AwsHealthCheckIntegrationTests : IClassFixture, IAsyncDisposable -{ - private readonly LocalStackTestFixture _localStack; - private readonly List _createdQueues = new(); - private readonly List _createdTopics = new(); - private readonly List _createdKeys = new(); - - public AwsHealthCheckIntegrationTests(LocalStackTestFixture localStack) - { - _localStack = localStack; - } - - #region SQS Health Checks (Requirement 4.1) - - [Fact] - public async Task SqsHealthCheck_ShouldDetectQueueExistence() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.SqsClient == null) - { - return; - } - - // Arrange - var queueName = $"test-health-queue-{Guid.NewGuid():N}"; - var queueUrl = await CreateStandardQueueAsync(queueName); - - // Act - Check if queue exists - var listResponse = await _localStack.SqsClient.ListQueuesAsync(new ListQueuesRequest - { - QueueNamePrefix = queueName - }); - - // Assert - Assert.NotEmpty(listResponse.QueueUrls); - Assert.Contains(queueUrl, listResponse.QueueUrls); - } - - [Fact] - public async Task SqsHealthCheck_ShouldDetectQueueAccessibility() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.SqsClient == null) - { - return; - } - - // Arrange - var queueName = $"test-health-access-{Guid.NewGuid():N}"; - var queueUrl = await CreateStandardQueueAsync(queueName); - - // Act - Try to get queue attributes (tests accessibility) - var attributesResponse = await _localStack.SqsClient.GetQueueAttributesAsync(new GetQueueAttributesRequest - { - QueueUrl = queueUrl, - AttributeNames = new List { "All" } - }); - - // Assert - Assert.NotNull(attributesResponse); - Assert.NotEmpty(attributesResponse.Attributes); - Assert.True(attributesResponse.Attributes.ContainsKey("QueueArn")); - } - - [Fact] - public async Task SqsHealthCheck_ShouldValidateSendMessagePermissions() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.SqsClient == null) - { - return; - } - - // Arrange - var queueName = $"test-health-send-{Guid.NewGuid():N}"; - var queueUrl = await CreateStandardQueueAsync(queueName); - - // Act - Try to send a test message (validates send permissions) - var sendResponse = await _localStack.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = queueUrl, - MessageBody = "Health check test message" - }); - - // Assert - Assert.NotNull(sendResponse); - Assert.NotNull(sendResponse.MessageId); - Assert.NotEmpty(sendResponse.MessageId); - } - - [Fact] - public async Task SqsHealthCheck_ShouldValidateReceiveMessagePermissions() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.SqsClient == null) - { - return; - } - - // Arrange - var queueName = $"test-health-receive-{Guid.NewGuid():N}"; - var queueUrl = await CreateStandardQueueAsync(queueName); - - // Send a test message first - await _localStack.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = queueUrl, - MessageBody = "Health check test message" - }); - - // Act - Try to receive messages (validates receive permissions) - var receiveResponse = await _localStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = queueUrl, - MaxNumberOfMessages = 1, - WaitTimeSeconds = 1 - }); - - // Assert - Assert.NotNull(receiveResponse); - Assert.NotEmpty(receiveResponse.Messages); - } - - [Fact] - public async Task SqsHealthCheck_ShouldDetectNonExistentQueue() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.SqsClient == null) - { - return; - } - - // Arrange - var nonExistentQueueUrl = $"http://localhost:4566/000000000000/non-existent-queue-{Guid.NewGuid():N}"; - - // Act & Assert - Should throw exception for non-existent queue - await Assert.ThrowsAsync(async () => - { - await _localStack.SqsClient.GetQueueAttributesAsync(new GetQueueAttributesRequest - { - QueueUrl = nonExistentQueueUrl, - AttributeNames = new List { "QueueArn" } - }); - }); - } - - #endregion - - #region SNS Health Checks (Requirement 4.2) - - [Fact] - public async Task SnsHealthCheck_ShouldDetectTopicAvailability() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.SnsClient == null) - { - return; - } - - // Arrange - var topicName = $"test-health-topic-{Guid.NewGuid():N}"; - var topicArn = await CreateTopicAsync(topicName); - - // Act - List topics to verify availability - var listResponse = await _localStack.SnsClient.ListTopicsAsync(new ListTopicsRequest()); - - // Assert - Assert.NotNull(listResponse); - Assert.NotEmpty(listResponse.Topics); - Assert.Contains(listResponse.Topics, t => t.TopicArn == topicArn); - } - - [Fact] - public async Task SnsHealthCheck_ShouldValidateTopicAttributes() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.SnsClient == null) - { - return; - } - - // Arrange - var topicName = $"test-health-attrs-{Guid.NewGuid():N}"; - var topicArn = await CreateTopicAsync(topicName); - - // Act - Get topic attributes - var attributesResponse = await _localStack.SnsClient.GetTopicAttributesAsync(new GetTopicAttributesRequest - { - TopicArn = topicArn - }); - - // Assert - Assert.NotNull(attributesResponse); - Assert.NotEmpty(attributesResponse.Attributes); - Assert.True(attributesResponse.Attributes.ContainsKey("TopicArn")); - } - - [Fact] - public async Task SnsHealthCheck_ShouldValidatePublishPermissions() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.SnsClient == null) - { - return; - } - - // Arrange - var topicName = $"test-health-publish-{Guid.NewGuid():N}"; - var topicArn = await CreateTopicAsync(topicName); - - // Act - Try to publish a test message - var publishResponse = await _localStack.SnsClient.PublishAsync(new PublishRequest - { - TopicArn = topicArn, - Message = "Health check test message", - Subject = "Health Check" - }); - - // Assert - Assert.NotNull(publishResponse); - Assert.NotNull(publishResponse.MessageId); - Assert.NotEmpty(publishResponse.MessageId); - } - - [Fact] - public async Task SnsHealthCheck_ShouldDetectSubscriptionStatus() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.SnsClient == null || _localStack.SqsClient == null) - { - return; - } - - // Arrange - var topicName = $"test-health-sub-{Guid.NewGuid():N}"; - var topicArn = await CreateTopicAsync(topicName); - - var queueName = $"test-health-sub-queue-{Guid.NewGuid():N}"; - var queueUrl = await CreateStandardQueueAsync(queueName); - var queueArn = await GetQueueArnAsync(queueUrl); - - // Subscribe queue to topic - var subscribeResponse = await _localStack.SnsClient.SubscribeAsync(new SubscribeRequest - { - TopicArn = topicArn, - Protocol = "sqs", - Endpoint = queueArn - }); - - // Act - List subscriptions for the topic - var subscriptionsResponse = await _localStack.SnsClient.ListSubscriptionsByTopicAsync(new ListSubscriptionsByTopicRequest - { - TopicArn = topicArn - }); - - // Assert - Assert.NotNull(subscriptionsResponse); - Assert.NotEmpty(subscriptionsResponse.Subscriptions); - Assert.Contains(subscriptionsResponse.Subscriptions, s => s.SubscriptionArn == subscribeResponse.SubscriptionArn); - } - - [Fact] - public async Task SnsHealthCheck_ShouldDetectNonExistentTopic() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.SnsClient == null) - { - return; - } - - // Arrange - var nonExistentTopicArn = $"arn:aws:sns:us-east-1:000000000000:non-existent-topic-{Guid.NewGuid():N}"; - - // Act & Assert - Should throw exception for non-existent topic - await Assert.ThrowsAsync(async () => - { - await _localStack.SnsClient.GetTopicAttributesAsync(new GetTopicAttributesRequest - { - TopicArn = nonExistentTopicArn - }); - }); - } - - #endregion - - #region KMS Health Checks (Requirement 4.3) - - [Fact] - public async Task KmsHealthCheck_ShouldDetectKeyAccessibility() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.KmsClient == null) - { - return; - } - - // Arrange - var keyAlias = $"test-health-key-{Guid.NewGuid():N}"; - string? keyId = null; - - try - { - keyId = await CreateKmsKeyAsync(keyAlias); - - // Act - Describe the key to verify accessibility - var describeResponse = await _localStack.KmsClient.DescribeKeyAsync(new DescribeKeyRequest - { - KeyId = keyId - }); - - // Assert - Assert.NotNull(describeResponse); - Assert.NotNull(describeResponse.KeyMetadata); - Assert.Equal(keyId, describeResponse.KeyMetadata.KeyId); - Assert.True(describeResponse.KeyMetadata.Enabled); - } - catch (Exception ex) when (ex.Message.Contains("not supported") || ex.Message.Contains("not implemented")) - { - // KMS might not be fully supported in LocalStack free tier - // Skip this test gracefully - return; - } - } - - [Fact] - public async Task KmsHealthCheck_ShouldValidateEncryptionPermissions() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.KmsClient == null) - { - return; - } - - // Arrange - var keyAlias = $"test-health-encrypt-{Guid.NewGuid():N}"; - string? keyId = null; - - try - { - keyId = await CreateKmsKeyAsync(keyAlias); - - var plaintext = System.Text.Encoding.UTF8.GetBytes("Health check test data"); - - // Act - Try to encrypt data - var encryptResponse = await _localStack.KmsClient.EncryptAsync(new EncryptRequest - { - KeyId = keyId, - Plaintext = new MemoryStream(plaintext) - }); - - // Assert - Assert.NotNull(encryptResponse); - Assert.NotNull(encryptResponse.CiphertextBlob); - Assert.True(encryptResponse.CiphertextBlob.Length > 0); - } - catch (Exception ex) when (ex.Message.Contains("not supported") || ex.Message.Contains("not implemented")) - { - // KMS might not be fully supported in LocalStack free tier - // Skip this test gracefully - return; - } - } - - [Fact] - public async Task KmsHealthCheck_ShouldValidateDecryptionPermissions() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.KmsClient == null) - { - return; - } - - // Arrange - var keyAlias = $"test-health-decrypt-{Guid.NewGuid():N}"; - string? keyId = null; - - try - { - keyId = await CreateKmsKeyAsync(keyAlias); - - var plaintext = System.Text.Encoding.UTF8.GetBytes("Health check test data"); - - // Encrypt first - var encryptResponse = await _localStack.KmsClient.EncryptAsync(new EncryptRequest - { - KeyId = keyId, - Plaintext = new MemoryStream(plaintext) - }); - - // Act - Try to decrypt data - var decryptResponse = await _localStack.KmsClient.DecryptAsync(new DecryptRequest - { - CiphertextBlob = encryptResponse.CiphertextBlob - }); - - // Assert - Assert.NotNull(decryptResponse); - Assert.NotNull(decryptResponse.Plaintext); - - var decryptedData = new byte[decryptResponse.Plaintext.Length]; - decryptResponse.Plaintext.Read(decryptedData, 0, decryptedData.Length); - Assert.Equal(plaintext, decryptedData); - } - catch (Exception ex) when (ex.Message.Contains("not supported") || ex.Message.Contains("not implemented")) - { - // KMS might not be fully supported in LocalStack free tier - // Skip this test gracefully - return; - } - } - - [Fact] - public async Task KmsHealthCheck_ShouldDetectKeyStatus() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.KmsClient == null) - { - return; - } - - // Arrange - var keyAlias = $"test-health-status-{Guid.NewGuid():N}"; - string? keyId = null; - - try - { - keyId = await CreateKmsKeyAsync(keyAlias); - - // Act - Get key metadata to check status - var describeResponse = await _localStack.KmsClient.DescribeKeyAsync(new DescribeKeyRequest - { - KeyId = keyId - }); - - // Assert - Assert.NotNull(describeResponse.KeyMetadata); - Assert.Equal(KeyState.Enabled, describeResponse.KeyMetadata.KeyState); - Assert.True(describeResponse.KeyMetadata.Enabled); - } - catch (Exception ex) when (ex.Message.Contains("not supported") || ex.Message.Contains("not implemented")) - { - // KMS might not be fully supported in LocalStack free tier - // Skip this test gracefully - return; - } - } - - [Fact] - public async Task KmsHealthCheck_ShouldDetectNonExistentKey() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.KmsClient == null) - { - return; - } - - // Arrange - var nonExistentKeyId = Guid.NewGuid().ToString(); - - try - { - // Act & Assert - Should throw exception for non-existent key - await Assert.ThrowsAsync(async () => - { - await _localStack.KmsClient.DescribeKeyAsync(new DescribeKeyRequest - { - KeyId = nonExistentKeyId - }); - }); - } - catch (Exception ex) when (ex.Message.Contains("not supported") || ex.Message.Contains("not implemented")) - { - // KMS might not be fully supported in LocalStack free tier - // Skip this test gracefully - return; - } - } - - #endregion - - #region Service Connectivity (Requirement 4.4) - - [Fact] - public async Task ServiceConnectivity_ShouldValidateSqsEndpointAvailability() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.SqsClient == null) - { - return; - } - - // Act - Simple list operation to test connectivity - var stopwatch = System.Diagnostics.Stopwatch.StartNew(); - var listResponse = await _localStack.SqsClient.ListQueuesAsync(new ListQueuesRequest()); - stopwatch.Stop(); - - // Assert - Assert.NotNull(listResponse); - Assert.True(stopwatch.ElapsedMilliseconds < 5000, "SQS endpoint should respond within 5 seconds"); - } - - [Fact] - public async Task ServiceConnectivity_ShouldValidateSnsEndpointAvailability() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.SnsClient == null) - { - return; - } - - // Act - Simple list operation to test connectivity - var stopwatch = System.Diagnostics.Stopwatch.StartNew(); - var listResponse = await _localStack.SnsClient.ListTopicsAsync(new ListTopicsRequest()); - stopwatch.Stop(); - - // Assert - Assert.NotNull(listResponse); - Assert.True(stopwatch.ElapsedMilliseconds < 5000, "SNS endpoint should respond within 5 seconds"); - } - - [Fact] - public async Task ServiceConnectivity_ShouldValidateKmsEndpointAvailability() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.KmsClient == null) - { - return; - } - - try - { - // Act - Simple list operation to test connectivity - var stopwatch = System.Diagnostics.Stopwatch.StartNew(); - var listResponse = await _localStack.KmsClient.ListKeysAsync(new ListKeysRequest()); - stopwatch.Stop(); - - // Assert - Assert.NotNull(listResponse); - Assert.True(stopwatch.ElapsedMilliseconds < 5000, "KMS endpoint should respond within 5 seconds"); - } - catch (Exception ex) when (ex.Message.Contains("not supported") || ex.Message.Contains("not implemented")) - { - // KMS might not be fully supported in LocalStack free tier - // Skip this test gracefully - return; - } - } - - [Fact] - public async Task ServiceConnectivity_ShouldHandleMultipleConcurrentRequests() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.SqsClient == null || _localStack.SnsClient == null) - { - return; - } - - // Act - Make concurrent requests to multiple services - var tasks = new List - { - _localStack.SqsClient.ListQueuesAsync(new ListQueuesRequest()), - _localStack.SnsClient.ListTopicsAsync(new ListTopicsRequest()), - _localStack.SqsClient.ListQueuesAsync(new ListQueuesRequest()), - _localStack.SnsClient.ListTopicsAsync(new ListTopicsRequest()) - }; - - var stopwatch = System.Diagnostics.Stopwatch.StartNew(); - await Task.WhenAll(tasks); - stopwatch.Stop(); - - // Assert - All requests should complete successfully - Assert.True(stopwatch.ElapsedMilliseconds < 10000, "Concurrent requests should complete within 10 seconds"); - } - - #endregion - - #region Health Check Performance (Requirement 4.5) - - [Fact] - public async Task HealthCheckPerformance_ShouldCompleteWithinAcceptableLatency() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.SqsClient == null || _localStack.SnsClient == null) - { - return; - } - - // Arrange - var queueName = $"test-health-perf-{Guid.NewGuid():N}"; - var queueUrl = await CreateStandardQueueAsync(queueName); - - var topicName = $"test-health-perf-{Guid.NewGuid():N}"; - var topicArn = await CreateTopicAsync(topicName); - - // Act - Perform comprehensive health check - var stopwatch = System.Diagnostics.Stopwatch.StartNew(); - - var sqsCheck = await _localStack.SqsClient.GetQueueAttributesAsync(new GetQueueAttributesRequest - { - QueueUrl = queueUrl, - AttributeNames = new List { "QueueArn" } - }); - - var snsCheck = await _localStack.SnsClient.GetTopicAttributesAsync(new GetTopicAttributesRequest - { - TopicArn = topicArn - }); - - stopwatch.Stop(); - - // Assert - Assert.NotNull(sqsCheck); - Assert.NotNull(snsCheck); - Assert.True(stopwatch.ElapsedMilliseconds < 2000, "Health checks should complete within 2 seconds"); - } - - [Fact] - public async Task HealthCheckPerformance_ShouldBeReliableUnderLoad() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.SqsClient == null) - { - return; - } - - // Arrange - var queueName = $"test-health-load-{Guid.NewGuid():N}"; - var queueUrl = await CreateStandardQueueAsync(queueName); - - var successCount = 0; - var failureCount = 0; - var iterations = 20; - - // Act - Perform multiple health checks rapidly - var tasks = Enumerable.Range(0, iterations).Select(async i => - { - try - { - await _localStack.SqsClient.GetQueueAttributesAsync(new GetQueueAttributesRequest - { - QueueUrl = queueUrl, - AttributeNames = new List { "QueueArn" } - }); - Interlocked.Increment(ref successCount); - } - catch - { - Interlocked.Increment(ref failureCount); - } - }); - - await Task.WhenAll(tasks); - - // Assert - At least 95% success rate - var successRate = (double)successCount / iterations; - Assert.True(successRate >= 0.95, $"Health check success rate should be at least 95%, got {successRate:P}"); - } - - [Fact] - public async Task HealthCheckPerformance_ShouldMeasureResponseTimes() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.SqsClient == null || _localStack.SnsClient == null) - { - return; - } - - // Arrange - var measurements = new List<(string Service, TimeSpan ResponseTime)>(); - - // Act - Measure response times for each service - var sqsStopwatch = System.Diagnostics.Stopwatch.StartNew(); - await _localStack.SqsClient.ListQueuesAsync(new ListQueuesRequest()); - sqsStopwatch.Stop(); - measurements.Add(("SQS", sqsStopwatch.Elapsed)); - - var snsStopwatch = System.Diagnostics.Stopwatch.StartNew(); - await _localStack.SnsClient.ListTopicsAsync(new ListTopicsRequest()); - snsStopwatch.Stop(); - measurements.Add(("SNS", snsStopwatch.Elapsed)); - - try - { - var kmsStopwatch = System.Diagnostics.Stopwatch.StartNew(); - await _localStack.KmsClient.ListKeysAsync(new ListKeysRequest()); - kmsStopwatch.Stop(); - measurements.Add(("KMS", kmsStopwatch.Elapsed)); - } - catch (Exception ex) when (ex.Message.Contains("not supported") || ex.Message.Contains("not implemented")) - { - // KMS might not be fully supported in LocalStack free tier - } - - // Assert - All services should respond within reasonable time - foreach (var (service, responseTime) in measurements) - { - Assert.True(responseTime.TotalMilliseconds < 3000, - $"{service} health check should complete within 3 seconds, took {responseTime.TotalMilliseconds}ms"); - } - } - - #endregion - - #region Helper Methods - - private async Task CreateStandardQueueAsync(string queueName) - { - var response = await _localStack.SqsClient!.CreateQueueAsync(new CreateQueueRequest - { - QueueName = queueName - }); - - _createdQueues.Add(response.QueueUrl); - return response.QueueUrl; - } - - private async Task CreateTopicAsync(string topicName) - { - var response = await _localStack.SnsClient!.CreateTopicAsync(new CreateTopicRequest - { - Name = topicName - }); - - _createdTopics.Add(response.TopicArn); - return response.TopicArn; - } - - private async Task CreateKmsKeyAsync(string keyAlias) - { - var createKeyResponse = await _localStack.KmsClient!.CreateKeyAsync(new CreateKeyRequest - { - Description = $"Test key for health checks - {keyAlias}", - KeyUsage = KeyUsageType.ENCRYPT_DECRYPT - }); - - var keyId = createKeyResponse.KeyMetadata.KeyId; - _createdKeys.Add(keyId); - - // Create alias - var aliasName = keyAlias.StartsWith("alias/") ? keyAlias : $"alias/{keyAlias}"; - await _localStack.KmsClient.CreateAliasAsync(new CreateAliasRequest - { - AliasName = aliasName, - TargetKeyId = keyId - }); - - return keyId; - } - - private async Task GetQueueArnAsync(string queueUrl) - { - var response = await _localStack.SqsClient!.GetQueueAttributesAsync(new GetQueueAttributesRequest - { - QueueUrl = queueUrl, - AttributeNames = new List { "QueueArn" } - }); - - return response.Attributes["QueueArn"]; - } - - #endregion - - public async ValueTask DisposeAsync() - { - // Clean up created resources - if (_localStack.SqsClient != null) - { - foreach (var queueUrl in _createdQueues) - { - try - { - await _localStack.SqsClient.DeleteQueueAsync(new DeleteQueueRequest { QueueUrl = queueUrl }); - } - catch - { - // Ignore cleanup errors - } - } - } - - if (_localStack.SnsClient != null) - { - foreach (var topicArn in _createdTopics) - { - try - { - await _localStack.SnsClient.DeleteTopicAsync(new DeleteTopicRequest { TopicArn = topicArn }); - } - catch - { - // Ignore cleanup errors - } - } - } - - if (_localStack.KmsClient != null) - { - foreach (var keyId in _createdKeys) - { - try - { - await _localStack.KmsClient.ScheduleKeyDeletionAsync(new ScheduleKeyDeletionRequest - { - KeyId = keyId, - PendingWindowInDays = 7 - }); - } - catch - { - // Ignore cleanup errors - KMS might not be fully supported - } - } - } - } -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/Integration/AwsHealthCheckPropertyTests.cs b/tests/SourceFlow.Cloud.AWS.Tests/Integration/AwsHealthCheckPropertyTests.cs deleted file mode 100644 index fe60fd0a..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/Integration/AwsHealthCheckPropertyTests.cs +++ /dev/null @@ -1,832 +0,0 @@ -using Amazon.KeyManagementService.Model; -using Amazon.SimpleNotificationService.Model; -using Amazon.SQS.Model; -using FsCheck; -using FsCheck.Xunit; -using SourceFlow.Cloud.AWS.Tests.TestHelpers; - -namespace SourceFlow.Cloud.AWS.Tests.Integration; - -/// -/// Property-based tests for AWS health check accuracy -/// Validates that health checks correctly identify service availability and permission issues -/// **Feature: aws-cloud-integration-testing, Property 8: AWS Health Check Accuracy** -/// -[Collection("AWS Integration Tests")] -[Trait("Category", "Integration")] -[Trait("Category", "RequiresLocalStack")] -public class AwsHealthCheckPropertyTests : IClassFixture, IAsyncDisposable -{ - private readonly LocalStackTestFixture _localStack; - private readonly List _createdQueues = new(); - private readonly List _createdTopics = new(); - private readonly List _createdKeys = new(); - - public AwsHealthCheckPropertyTests(LocalStackTestFixture localStack) - { - _localStack = localStack; - } - - /// - /// Property 8: AWS Health Check Accuracy - /// For any AWS service configuration (SQS, SNS, KMS), health checks should accurately - /// reflect the actual availability, accessibility, and permission status of the service, - /// returning true when services are operational and false when they are not. - /// **Validates: Requirements 4.1, 4.2, 4.3, 4.4, 4.5** - /// - // FsCheck 2.x does not support async Task properties — method must be void - [Property(MaxTest = 10, Arbitrary = new[] { typeof(AwsHealthCheckGenerators) })] - public void Property_AwsHealthCheckAccuracy(AwsHealthCheckScenario scenario) => - Property_AwsHealthCheckAccuracyAsync(scenario).GetAwaiter().GetResult(); - - private async Task Property_AwsHealthCheckAccuracyAsync(AwsHealthCheckScenario scenario) - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.SqsClient == null) - { - return; - } - - // Arrange - Create resources based on scenario - var resources = await CreateTestResourcesAsync(scenario); - - try - { - // Act - Perform health checks on all services - var healthResults = await PerformHealthChecksAsync(resources, scenario); - - // Assert - Health checks accurately reflect service availability - AssertHealthCheckAccuracy(healthResults, resources, scenario); - - // Assert - Health checks detect accessibility issues - AssertAccessibilityDetection(healthResults, resources, scenario); - - // Assert - Health checks validate permissions correctly - AssertPermissionValidation(healthResults, resources, scenario); - - // Assert - Health checks complete within acceptable latency - AssertHealthCheckPerformance(healthResults, scenario); - - // Assert - Health checks are reliable under concurrent access - if (scenario.TestConcurrency) - { - await AssertConcurrentHealthCheckReliability(resources, scenario); - } - } - finally - { - // Clean up resources - await CleanupResourcesAsync(resources); - } - } - - /// - /// Create test resources based on the scenario - /// - private async Task CreateTestResourcesAsync(AwsHealthCheckScenario scenario) - { - var resources = new AwsHealthCheckResources(); - - // Create SQS resources if needed - if (scenario.TestSqs) - { - if (scenario.CreateValidQueue) - { - var queueName = $"health-test-{Guid.NewGuid():N}"; - resources.QueueUrl = await CreateStandardQueueAsync(queueName); - resources.QueueExists = true; - } - else - { - // Use non-existent queue URL - resources.QueueUrl = $"http://localhost:4566/000000000000/non-existent-{Guid.NewGuid():N}"; - resources.QueueExists = false; - } - } - - // Create SNS resources if needed - if (scenario.TestSns) - { - if (scenario.CreateValidTopic) - { - var topicName = $"health-test-{Guid.NewGuid():N}"; - resources.TopicArn = await CreateTopicAsync(topicName); - resources.TopicExists = true; - } - else - { - // Use non-existent topic ARN - resources.TopicArn = $"arn:aws:sns:us-east-1:000000000000:non-existent-{Guid.NewGuid():N}"; - resources.TopicExists = false; - } - } - - // Create KMS resources if needed - if (scenario.TestKms) - { - if (scenario.CreateValidKey) - { - try - { - var keyAlias = $"health-test-{Guid.NewGuid():N}"; - resources.KeyId = await CreateKmsKeyAsync(keyAlias); - resources.KeyExists = true; - } - catch (Exception ex) when (ex.Message.Contains("not supported") || ex.Message.Contains("not implemented")) - { - // KMS might not be fully supported in LocalStack free tier - resources.KmsNotSupported = true; - } - } - else - { - // Use non-existent key ID - resources.KeyId = Guid.NewGuid().ToString(); - resources.KeyExists = false; - } - } - - return resources; - } - - /// - /// Perform health checks on all configured services - /// - private async Task PerformHealthChecksAsync( - AwsHealthCheckResources resources, - AwsHealthCheckScenario scenario) - { - var results = new AwsHealthCheckResults(); - - // SQS health checks - if (scenario.TestSqs && !string.IsNullOrEmpty(resources.QueueUrl)) - { - results.SqsResult = await PerformSqsHealthCheckAsync(resources.QueueUrl); - } - - // SNS health checks - if (scenario.TestSns && !string.IsNullOrEmpty(resources.TopicArn)) - { - results.SnsResult = await PerformSnsHealthCheckAsync(resources.TopicArn); - } - - // KMS health checks - if (scenario.TestKms && !string.IsNullOrEmpty(resources.KeyId) && !resources.KmsNotSupported) - { - results.KmsResult = await PerformKmsHealthCheckAsync(resources.KeyId); - } - - return results; - } - - /// - /// Perform SQS health check - /// - private async Task PerformSqsHealthCheckAsync(string queueUrl) - { - var result = new ServiceHealthCheckResult { ServiceName = "SQS" }; - var stopwatch = System.Diagnostics.Stopwatch.StartNew(); - - try - { - // Check queue existence and accessibility - var attributesResponse = await _localStack.SqsClient!.GetQueueAttributesAsync(new GetQueueAttributesRequest - { - QueueUrl = queueUrl, - AttributeNames = new List { "QueueArn", "ApproximateNumberOfMessages" } - }); - - result.IsAvailable = true; - result.IsAccessible = attributesResponse.Attributes.ContainsKey("QueueArn"); - - // Check send permission - try - { - await _localStack.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = queueUrl, - MessageBody = "Health check test" - }); - result.HasSendPermission = true; - } - catch - { - result.HasSendPermission = false; - } - - // Check receive permission - try - { - await _localStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = queueUrl, - MaxNumberOfMessages = 1, - WaitTimeSeconds = 0 - }); - result.HasReceivePermission = true; - } - catch - { - result.HasReceivePermission = false; - } - } - catch (Amazon.SQS.Model.QueueDoesNotExistException) - { - result.IsAvailable = false; - result.IsAccessible = false; - result.ErrorMessage = "Queue does not exist"; - } - catch (Exception ex) - { - result.IsAvailable = false; - result.ErrorMessage = ex.Message; - } - finally - { - stopwatch.Stop(); - result.ResponseTime = stopwatch.Elapsed; - } - - return result; - } - - /// - /// Perform SNS health check - /// - private async Task PerformSnsHealthCheckAsync(string topicArn) - { - var result = new ServiceHealthCheckResult { ServiceName = "SNS" }; - var stopwatch = System.Diagnostics.Stopwatch.StartNew(); - - try - { - // Check topic existence and accessibility - var attributesResponse = await _localStack.SnsClient!.GetTopicAttributesAsync(new GetTopicAttributesRequest - { - TopicArn = topicArn - }); - - result.IsAvailable = true; - result.IsAccessible = attributesResponse.Attributes.ContainsKey("TopicArn"); - - // Check publish permission - try - { - await _localStack.SnsClient.PublishAsync(new PublishRequest - { - TopicArn = topicArn, - Message = "Health check test" - }); - result.HasPublishPermission = true; - } - catch - { - result.HasPublishPermission = false; - } - - // Check subscription management permission - try - { - await _localStack.SnsClient.ListSubscriptionsByTopicAsync(new ListSubscriptionsByTopicRequest - { - TopicArn = topicArn - }); - result.HasSubscriptionPermission = true; - } - catch - { - result.HasSubscriptionPermission = false; - } - } - catch (Amazon.SimpleNotificationService.Model.NotFoundException) - { - result.IsAvailable = false; - result.IsAccessible = false; - result.ErrorMessage = "Topic does not exist"; - } - catch (Exception ex) - { - result.IsAvailable = false; - result.ErrorMessage = ex.Message; - } - finally - { - stopwatch.Stop(); - result.ResponseTime = stopwatch.Elapsed; - } - - return result; - } - - /// - /// Perform KMS health check - /// - private async Task PerformKmsHealthCheckAsync(string keyId) - { - var result = new ServiceHealthCheckResult { ServiceName = "KMS" }; - var stopwatch = System.Diagnostics.Stopwatch.StartNew(); - - try - { - // Check key existence and accessibility - var describeResponse = await _localStack.KmsClient!.DescribeKeyAsync(new DescribeKeyRequest - { - KeyId = keyId - }); - - result.IsAvailable = true; - result.IsAccessible = describeResponse.KeyMetadata != null; - result.KeyEnabled = describeResponse.KeyMetadata?.Enabled ?? false; - - // Check encryption permission - try - { - var plaintext = System.Text.Encoding.UTF8.GetBytes("Health check test"); - await _localStack.KmsClient.EncryptAsync(new EncryptRequest - { - KeyId = keyId, - Plaintext = new MemoryStream(plaintext) - }); - result.HasEncryptPermission = true; - } - catch - { - result.HasEncryptPermission = false; - } - } - catch (Amazon.KeyManagementService.Model.NotFoundException) - { - result.IsAvailable = false; - result.IsAccessible = false; - result.ErrorMessage = "Key does not exist"; - } - catch (Exception ex) - { - result.IsAvailable = false; - result.ErrorMessage = ex.Message; - } - finally - { - stopwatch.Stop(); - result.ResponseTime = stopwatch.Elapsed; - } - - return result; - } - - /// - /// Assert that health checks accurately reflect service availability - /// - private void AssertHealthCheckAccuracy( - AwsHealthCheckResults results, - AwsHealthCheckResources resources, - AwsHealthCheckScenario scenario) - { - // SQS availability accuracy - if (scenario.TestSqs && results.SqsResult != null) - { - if (resources.QueueExists) - { - Assert.True(results.SqsResult.IsAvailable, - "Health check should report SQS queue as available when it exists"); - } - else - { - Assert.False(results.SqsResult.IsAvailable, - "Health check should report SQS queue as unavailable when it doesn't exist"); - } - } - - // SNS availability accuracy - if (scenario.TestSns && results.SnsResult != null) - { - if (resources.TopicExists) - { - Assert.True(results.SnsResult.IsAvailable, - "Health check should report SNS topic as available when it exists"); - } - else - { - Assert.False(results.SnsResult.IsAvailable, - "Health check should report SNS topic as unavailable when it doesn't exist"); - } - } - - // KMS availability accuracy - if (scenario.TestKms && results.KmsResult != null && !resources.KmsNotSupported) - { - if (resources.KeyExists) - { - Assert.True(results.KmsResult.IsAvailable, - "Health check should report KMS key as available when it exists"); - } - else - { - Assert.False(results.KmsResult.IsAvailable, - "Health check should report KMS key as unavailable when it doesn't exist"); - } - } - } - - /// - /// Assert that health checks detect accessibility issues - /// - private void AssertAccessibilityDetection( - AwsHealthCheckResults results, - AwsHealthCheckResources resources, - AwsHealthCheckScenario scenario) - { - // SQS accessibility - if (scenario.TestSqs && results.SqsResult != null && resources.QueueExists) - { - Assert.True(results.SqsResult.IsAccessible, - "Health check should detect that existing SQS queue is accessible"); - } - - // SNS accessibility - if (scenario.TestSns && results.SnsResult != null && resources.TopicExists) - { - Assert.True(results.SnsResult.IsAccessible, - "Health check should detect that existing SNS topic is accessible"); - } - - // KMS accessibility - if (scenario.TestKms && results.KmsResult != null && resources.KeyExists && !resources.KmsNotSupported) - { - Assert.True(results.KmsResult.IsAccessible, - "Health check should detect that existing KMS key is accessible"); - } - } - - /// - /// Assert that health checks validate permissions correctly - /// - private void AssertPermissionValidation( - AwsHealthCheckResults results, - AwsHealthCheckResources resources, - AwsHealthCheckScenario scenario) - { - // SQS permissions (in LocalStack, permissions are typically granted) - if (scenario.TestSqs && results.SqsResult != null && resources.QueueExists) - { - Assert.True(results.SqsResult.HasSendPermission, - "Health check should detect send permission for existing SQS queue"); - Assert.True(results.SqsResult.HasReceivePermission, - "Health check should detect receive permission for existing SQS queue"); - } - - // SNS permissions - if (scenario.TestSns && results.SnsResult != null && resources.TopicExists) - { - Assert.True(results.SnsResult.HasPublishPermission, - "Health check should detect publish permission for existing SNS topic"); - Assert.True(results.SnsResult.HasSubscriptionPermission, - "Health check should detect subscription permission for existing SNS topic"); - } - - // KMS permissions - if (scenario.TestKms && results.KmsResult != null && resources.KeyExists && !resources.KmsNotSupported) - { - Assert.True(results.KmsResult.HasEncryptPermission, - "Health check should detect encryption permission for existing KMS key"); - } - } - - /// - /// Assert that health checks complete within acceptable latency - /// - private void AssertHealthCheckPerformance( - AwsHealthCheckResults results, - AwsHealthCheckScenario scenario) - { - var maxAcceptableLatency = TimeSpan.FromSeconds(5); - - if (scenario.TestSqs && results.SqsResult != null) - { - Assert.True(results.SqsResult.ResponseTime < maxAcceptableLatency, - $"SQS health check should complete within {maxAcceptableLatency.TotalSeconds}s, took {results.SqsResult.ResponseTime.TotalSeconds}s"); - } - - if (scenario.TestSns && results.SnsResult != null) - { - Assert.True(results.SnsResult.ResponseTime < maxAcceptableLatency, - $"SNS health check should complete within {maxAcceptableLatency.TotalSeconds}s, took {results.SnsResult.ResponseTime.TotalSeconds}s"); - } - - if (scenario.TestKms && results.KmsResult != null) - { - Assert.True(results.KmsResult.ResponseTime < maxAcceptableLatency, - $"KMS health check should complete within {maxAcceptableLatency.TotalSeconds}s, took {results.KmsResult.ResponseTime.TotalSeconds}s"); - } - } - - /// - /// Assert that health checks are reliable under concurrent access - /// - private async Task AssertConcurrentHealthCheckReliability( - AwsHealthCheckResources resources, - AwsHealthCheckScenario scenario) - { - var concurrentChecks = 10; - var successCount = 0; - var failureCount = 0; - - var tasks = Enumerable.Range(0, concurrentChecks).Select(async i => - { - try - { - var results = await PerformHealthChecksAsync(resources, scenario); - - // Verify consistency of results - if (scenario.TestSqs && results.SqsResult != null) - { - if (results.SqsResult.IsAvailable == resources.QueueExists) - { - Interlocked.Increment(ref successCount); - } - else - { - Interlocked.Increment(ref failureCount); - } - } - - if (scenario.TestSns && results.SnsResult != null) - { - if (results.SnsResult.IsAvailable == resources.TopicExists) - { - Interlocked.Increment(ref successCount); - } - else - { - Interlocked.Increment(ref failureCount); - } - } - } - catch - { - Interlocked.Increment(ref failureCount); - } - }); - - await Task.WhenAll(tasks); - - // At least 90% of concurrent health checks should be consistent - var totalChecks = successCount + failureCount; - if (totalChecks > 0) - { - var successRate = (double)successCount / totalChecks; - Assert.True(successRate >= 0.9, - $"Concurrent health checks should be at least 90% consistent, got {successRate:P}"); - } - } - - /// - /// Clean up test resources - /// - private async Task CleanupResourcesAsync(AwsHealthCheckResources resources) - { - if (!string.IsNullOrEmpty(resources.QueueUrl) && resources.QueueExists) - { - try - { - await _localStack.SqsClient!.DeleteQueueAsync(new DeleteQueueRequest - { - QueueUrl = resources.QueueUrl - }); - } - catch - { - // Ignore cleanup errors - } - } - - if (!string.IsNullOrEmpty(resources.TopicArn) && resources.TopicExists) - { - try - { - await _localStack.SnsClient!.DeleteTopicAsync(new DeleteTopicRequest - { - TopicArn = resources.TopicArn - }); - } - catch - { - // Ignore cleanup errors - } - } - - if (!string.IsNullOrEmpty(resources.KeyId) && resources.KeyExists && !resources.KmsNotSupported) - { - try - { - await _localStack.KmsClient!.ScheduleKeyDeletionAsync(new ScheduleKeyDeletionRequest - { - KeyId = resources.KeyId, - PendingWindowInDays = 7 - }); - } - catch - { - // Ignore cleanup errors - } - } - } - - #region Helper Methods - - private async Task CreateStandardQueueAsync(string queueName) - { - var response = await _localStack.SqsClient!.CreateQueueAsync(new CreateQueueRequest - { - QueueName = queueName - }); - - _createdQueues.Add(response.QueueUrl); - return response.QueueUrl; - } - - private async Task CreateTopicAsync(string topicName) - { - var response = await _localStack.SnsClient!.CreateTopicAsync(new CreateTopicRequest - { - Name = topicName - }); - - _createdTopics.Add(response.TopicArn); - return response.TopicArn; - } - - private async Task CreateKmsKeyAsync(string keyAlias) - { - var createKeyResponse = await _localStack.KmsClient!.CreateKeyAsync(new CreateKeyRequest - { - Description = $"Test key for health checks - {keyAlias}", - KeyUsage = KeyUsageType.ENCRYPT_DECRYPT - }); - - var keyId = createKeyResponse.KeyMetadata.KeyId; - _createdKeys.Add(keyId); - - // Create alias - var aliasName = keyAlias.StartsWith("alias/") ? keyAlias : $"alias/{keyAlias}"; - await _localStack.KmsClient.CreateAliasAsync(new CreateAliasRequest - { - AliasName = aliasName, - TargetKeyId = keyId - }); - - return keyId; - } - - #endregion - - public async ValueTask DisposeAsync() - { - // Clean up created resources - if (_localStack.SqsClient != null) - { - foreach (var queueUrl in _createdQueues) - { - try - { - await _localStack.SqsClient.DeleteQueueAsync(new DeleteQueueRequest { QueueUrl = queueUrl }); - } - catch - { - // Ignore cleanup errors - } - } - } - - if (_localStack.SnsClient != null) - { - foreach (var topicArn in _createdTopics) - { - try - { - await _localStack.SnsClient.DeleteTopicAsync(new DeleteTopicRequest { TopicArn = topicArn }); - } - catch - { - // Ignore cleanup errors - } - } - } - - if (_localStack.KmsClient != null) - { - foreach (var keyId in _createdKeys) - { - try - { - await _localStack.KmsClient.ScheduleKeyDeletionAsync(new ScheduleKeyDeletionRequest - { - KeyId = keyId, - PendingWindowInDays = 7 - }); - } - catch - { - // Ignore cleanup errors - } - } - } - } -} - -#region Test Models and Generators - -/// -/// Scenario for AWS health check property testing -/// -public class AwsHealthCheckScenario -{ - public bool TestSqs { get; set; } - public bool TestSns { get; set; } - public bool TestKms { get; set; } - public bool CreateValidQueue { get; set; } - public bool CreateValidTopic { get; set; } - public bool CreateValidKey { get; set; } - public bool TestConcurrency { get; set; } -} - -/// -/// Resources created for health check testing -/// -public class AwsHealthCheckResources -{ - public string? QueueUrl { get; set; } - public bool QueueExists { get; set; } - - public string? TopicArn { get; set; } - public bool TopicExists { get; set; } - - public string? KeyId { get; set; } - public bool KeyExists { get; set; } - public bool KmsNotSupported { get; set; } -} - -/// -/// Results from health check operations -/// -public class AwsHealthCheckResults -{ - public ServiceHealthCheckResult? SqsResult { get; set; } - public ServiceHealthCheckResult? SnsResult { get; set; } - public ServiceHealthCheckResult? KmsResult { get; set; } -} - -/// -/// Individual service health check result -/// -public class ServiceHealthCheckResult -{ - public string ServiceName { get; set; } = ""; - public bool IsAvailable { get; set; } - public bool IsAccessible { get; set; } - public bool HasSendPermission { get; set; } - public bool HasReceivePermission { get; set; } - public bool HasPublishPermission { get; set; } - public bool HasSubscriptionPermission { get; set; } - public bool HasEncryptPermission { get; set; } - public bool KeyEnabled { get; set; } - public TimeSpan ResponseTime { get; set; } - public string? ErrorMessage { get; set; } -} - -/// -/// FsCheck generators for AWS health check scenarios -/// -public static class AwsHealthCheckGenerators -{ - /// - /// Generate valid AWS health check scenarios - /// - public static Arbitrary AwsHealthCheckScenario() - { - var generator = from testSqs in Arb.Generate() - from testSns in Arb.Generate() - from testKms in Arb.Generate() - from createValidQueue in Arb.Generate() - from createValidTopic in Arb.Generate() - from createValidKey in Arb.Generate() - from testConcurrency in Gen.Frequency( - Tuple.Create(8, Gen.Constant(false)), // 80% no concurrency test - Tuple.Create(2, Gen.Constant(true))) // 20% with concurrency test - where testSqs || testSns || testKms // At least one service must be tested - select new AwsHealthCheckScenario - { - TestSqs = testSqs, - TestSns = testSns, - TestKms = testKms, - CreateValidQueue = testSqs && createValidQueue, - CreateValidTopic = testSns && createValidTopic, - CreateValidKey = testKms && createValidKey, - TestConcurrency = testConcurrency - }; - - return Arb.From(generator); - } -} - -#endregion diff --git a/tests/SourceFlow.Cloud.AWS.Tests/Integration/AwsIntegrationTests.cs b/tests/SourceFlow.Cloud.AWS.Tests/Integration/AwsIntegrationTests.cs deleted file mode 100644 index 2da881ca..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/Integration/AwsIntegrationTests.cs +++ /dev/null @@ -1,38 +0,0 @@ -using Microsoft.Extensions.DependencyInjection; -using SourceFlow.Cloud.AWS.Configuration; -using SourceFlow.Cloud.AWS.Tests.TestHelpers; - -namespace SourceFlow.Cloud.AWS.Tests.Integration; - -[Collection("AWS Integration Tests")] -[Trait("Category", "Integration")] -[Trait("Category", "RequiresLocalStack")] -public class AwsIntegrationTests -{ - [Fact] - public void AwsOptions_CanBeConfigured() - { - // Arrange - var services = new ServiceCollection(); - - // Act - services.UseSourceFlowAws( - options => - { - options.Region = Amazon.RegionEndpoint.USEast1; - options.EnableCommandRouting = true; - options.EnableEventRouting = true; - }, - bus => bus - .Send.Command(q => q.Queue("test-queue.fifo")) - .Listen.To.CommandQueue("test-queue.fifo")); - - var provider = services.BuildServiceProvider(); - var options = provider.GetRequiredService(); - - // Assert - Assert.Equal(Amazon.RegionEndpoint.USEast1, options.Region); - Assert.True(options.EnableCommandRouting); - Assert.True(options.EnableEventRouting); - } -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/Integration/AwsRetryPolicyTests.cs b/tests/SourceFlow.Cloud.AWS.Tests/Integration/AwsRetryPolicyTests.cs deleted file mode 100644 index a7d431a5..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/Integration/AwsRetryPolicyTests.cs +++ /dev/null @@ -1,764 +0,0 @@ -using Amazon.SQS; -using Amazon.SQS.Model; -using Amazon.SimpleNotificationService; -using Amazon.SimpleNotificationService.Model; -using Amazon.Runtime; -using Microsoft.Extensions.Logging; -using SourceFlow.Cloud.AWS.Configuration; -using SourceFlow.Cloud.AWS.Tests.TestHelpers; -using Xunit; -using Xunit.Abstractions; - -namespace SourceFlow.Cloud.AWS.Tests.Integration; - -/// -/// Integration tests for AWS retry policy implementation -/// Tests exponential backoff with jitter, maximum retry limit enforcement, -/// retry policy configuration and customization, and retry behavior under various failure scenarios -/// Validates: Requirement 7.2 - AWS retry policies -/// -[Collection("AWS Integration Tests")] -[Trait("Category", "Integration")] -[Trait("Category", "RequiresLocalStack")] -public class AwsRetryPolicyTests : IAsyncLifetime -{ - private readonly ITestOutputHelper _output; - private IAwsTestEnvironment _environment = null!; - private readonly ILogger _logger; - private readonly string _testPrefix; - - public AwsRetryPolicyTests(ITestOutputHelper output) - { - _output = output; - _testPrefix = $"retry-test-{Guid.NewGuid():N}"; - - var loggerFactory = LoggerFactory.Create(builder => - { - builder.AddConsole(); - builder.SetMinimumLevel(LogLevel.Debug); - }); - - _logger = loggerFactory.CreateLogger(); - } - - public async Task InitializeAsync() - { - _environment = await AwsTestEnvironmentFactory.CreateLocalStackEnvironmentAsync(_testPrefix); - } - - public async Task DisposeAsync() - { - await _environment.DisposeAsync(); - } - - /// - /// Test that AWS SDK applies exponential backoff for SQS operations - /// Validates: Requirement 7.2 - Exponential backoff implementation - /// - [Fact] - public async Task AwsSdk_AppliesExponentialBackoff_ForSqsOperations() - { - // LocalStack returns 404 errors immediately without retry delays (non-retryable errors) - if (_environment.IsLocalEmulator) return; - - // Arrange - var invalidQueueUrl = "http://localhost:4566/000000000000/nonexistent-queue"; - var retryAttempts = new List(); - var maxRetries = 3; - - // Create SQS client with custom retry configuration - var config = new AmazonSQSConfig - { - ServiceURL = _environment.IsLocalEmulator ? "http://localhost:4566" : null, - MaxErrorRetry = maxRetries, - AuthenticationRegion = "us-east-1" - }; - - var sqsClient = new AmazonSQSClient("test", "test", config); - - // Act - Attempt operation that will fail and retry - var startTime = DateTime.UtcNow; - try - { - await sqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = invalidQueueUrl, - MessageBody = "test" - }); - } - catch (QueueDoesNotExistException ex) - { - _output.WriteLine($"Expected exception after retries: {ex.Message}"); - } - catch (AmazonServiceException ex) - { - _output.WriteLine($"Service exception after retries: {ex.Message}"); - } - - var totalDuration = DateTime.UtcNow - startTime; - - // Assert - Verify that operation took time indicating retries occurred - // With exponential backoff, retries should take progressively longer - // Expected minimum duration: initial attempt + retry delays - // For 3 retries with exponential backoff: ~0ms + ~100ms + ~200ms + ~400ms = ~700ms minimum - Assert.True(totalDuration.TotalMilliseconds > 100, - $"Operation should take time for retries, but took only {totalDuration.TotalMilliseconds}ms"); - - _output.WriteLine($"Total operation duration with {maxRetries} retries: {totalDuration.TotalMilliseconds}ms"); - } - - /// - /// Test that AWS SDK applies exponential backoff for SNS operations - /// Validates: Requirement 7.2 - Exponential backoff implementation - /// - [Fact] - public async Task AwsSdk_AppliesExponentialBackoff_ForSnsOperations() - { - // LocalStack returns 404 errors immediately without retry delays (non-retryable errors) - if (_environment.IsLocalEmulator) return; - - // Arrange - var invalidTopicArn = "arn:aws:sns:us-east-1:000000000000:nonexistent-topic"; - var maxRetries = 3; - - // Create SNS client with custom retry configuration - var config = new AmazonSimpleNotificationServiceConfig - { - ServiceURL = _environment.IsLocalEmulator ? "http://localhost:4566" : null, - MaxErrorRetry = maxRetries, - AuthenticationRegion = "us-east-1" - }; - - var snsClient = new AmazonSimpleNotificationServiceClient("test", "test", config); - - // Act - Attempt operation that will fail and retry - var startTime = DateTime.UtcNow; - try - { - await snsClient.PublishAsync(new PublishRequest - { - TopicArn = invalidTopicArn, - Message = "test" - }); - } - catch (NotFoundException ex) - { - _output.WriteLine($"Expected exception after retries: {ex.Message}"); - } - catch (AmazonServiceException ex) - { - _output.WriteLine($"Service exception after retries: {ex.Message}"); - } - - var totalDuration = DateTime.UtcNow - startTime; - - // Assert - Verify that operation took time indicating retries occurred - Assert.True(totalDuration.TotalMilliseconds > 100, - $"Operation should take time for retries, but took only {totalDuration.TotalMilliseconds}ms"); - - _output.WriteLine($"Total operation duration with {maxRetries} retries: {totalDuration.TotalMilliseconds}ms"); - } - - /// - /// Test that maximum retry limit is enforced for SQS operations - /// Validates: Requirement 7.2 - Maximum retry limit enforcement - /// - [Fact] - public async Task AwsSdk_EnforcesMaximumRetryLimit_ForSqsOperations() - { - // Arrange - var invalidQueueUrl = "http://localhost:4566/000000000000/nonexistent-queue"; - var maxRetries = 2; // Set low retry limit - - var config = new AmazonSQSConfig - { - ServiceURL = _environment.IsLocalEmulator ? "http://localhost:4566" : null, - MaxErrorRetry = maxRetries, - AuthenticationRegion = "us-east-1" - }; - - var sqsClient = new AmazonSQSClient("test", "test", config); - - // Act & Assert - Operation should fail after max retries - var startTime = DateTime.UtcNow; - var exceptionThrown = false; - - try - { - await sqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = invalidQueueUrl, - MessageBody = "test" - }); - } - catch (AmazonServiceException ex) - { - exceptionThrown = true; - _output.WriteLine($"Exception thrown after max retries: {ex.Message}"); - _output.WriteLine($"Error code: {ex.ErrorCode}"); - } - - var totalDuration = DateTime.UtcNow - startTime; - - Assert.True(exceptionThrown, "Exception should be thrown after max retries"); - - // With 2 retries, duration should be less than with more retries - // This validates that we're not retrying indefinitely - Assert.True(totalDuration.TotalSeconds < 10, - $"Operation should fail quickly with low retry limit, but took {totalDuration.TotalSeconds}s"); - - _output.WriteLine($"Operation failed after {totalDuration.TotalMilliseconds}ms with max {maxRetries} retries"); - } - - /// - /// Test that maximum retry limit is enforced for SNS operations - /// Validates: Requirement 7.2 - Maximum retry limit enforcement - /// - [Fact] - public async Task AwsSdk_EnforcesMaximumRetryLimit_ForSnsOperations() - { - // Arrange - var invalidTopicArn = "arn:aws:sns:us-east-1:000000000000:nonexistent-topic"; - var maxRetries = 2; - - var config = new AmazonSimpleNotificationServiceConfig - { - ServiceURL = _environment.IsLocalEmulator ? "http://localhost:4566" : null, - MaxErrorRetry = maxRetries, - AuthenticationRegion = "us-east-1" - }; - - var snsClient = new AmazonSimpleNotificationServiceClient("test", "test", config); - - // Act & Assert - var startTime = DateTime.UtcNow; - var exceptionThrown = false; - - try - { - await snsClient.PublishAsync(new PublishRequest - { - TopicArn = invalidTopicArn, - Message = "test" - }); - } - catch (AmazonServiceException ex) - { - exceptionThrown = true; - _output.WriteLine($"Exception thrown after max retries: {ex.Message}"); - } - - var totalDuration = DateTime.UtcNow - startTime; - - Assert.True(exceptionThrown, "Exception should be thrown after max retries"); - Assert.True(totalDuration.TotalSeconds < 10, - $"Operation should fail quickly with low retry limit, but took {totalDuration.TotalSeconds}s"); - - _output.WriteLine($"Operation failed after {totalDuration.TotalMilliseconds}ms with max {maxRetries} retries"); - } - - /// - /// Test retry policy configuration with different retry limits - /// Validates: Requirement 7.2 - Retry policy configuration and customization - /// - [Fact] - public async Task RetryPolicy_Configuration_SupportsCustomRetryLimits() - { - // Arrange - Test with different retry limits - var testCases = new[] { 0, 1, 3, 5 }; - var invalidQueueUrl = "http://localhost:4566/000000000000/nonexistent-queue"; - - foreach (var maxRetries in testCases) - { - var config = new AmazonSQSConfig - { - ServiceURL = _environment.IsLocalEmulator ? "http://localhost:4566" : null, - MaxErrorRetry = maxRetries, - AuthenticationRegion = "us-east-1" - }; - - var sqsClient = new AmazonSQSClient("test", "test", config); - - // Act - var startTime = DateTime.UtcNow; - try - { - await sqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = invalidQueueUrl, - MessageBody = "test" - }); - } - catch (AmazonServiceException) - { - // Expected - } - - var duration = DateTime.UtcNow - startTime; - - // Assert - Higher retry counts should take longer - _output.WriteLine($"MaxRetries={maxRetries}: Duration={duration.TotalMilliseconds}ms"); - - // With 0 retries, should fail immediately (< 1 second) - if (maxRetries == 0) - { - Assert.True(duration.TotalSeconds < 1, - $"With 0 retries, should fail immediately, but took {duration.TotalSeconds}s"); - } - } - } - - /// - /// Test retry policy with AwsOptions configuration - /// Validates: Requirement 7.2 - Retry policy configuration and customization - /// - [Fact] - public void AwsOptions_RetryConfiguration_IsAppliedToClients() - { - // Arrange - var options = new AwsOptions - { - MaxRetries = 5, - RetryDelay = TimeSpan.FromSeconds(2), - Region = Amazon.RegionEndpoint.USEast1 - }; - - // Act - Create client configuration from options - var sqsConfig = new AmazonSQSConfig - { - MaxErrorRetry = options.MaxRetries, - RegionEndpoint = options.Region - }; - - var snsConfig = new AmazonSimpleNotificationServiceConfig - { - MaxErrorRetry = options.MaxRetries, - RegionEndpoint = options.Region - }; - - // Assert - Configuration should match options - Assert.Equal(options.MaxRetries, sqsConfig.MaxErrorRetry); - Assert.Equal(options.MaxRetries, snsConfig.MaxErrorRetry); - Assert.Equal(options.Region, sqsConfig.RegionEndpoint); - Assert.Equal(options.Region, snsConfig.RegionEndpoint); - - _output.WriteLine($"AwsOptions configuration applied: MaxRetries={options.MaxRetries}, " + - $"RetryDelay={options.RetryDelay}, Region={options.Region.SystemName}"); - } - - /// - /// Test retry behavior with transient failures - /// Validates: Requirement 7.2 - Retry behavior under various failure scenarios - /// - [Fact] - public async Task RetryPolicy_RetriesTransientFailures_AndEventuallySucceeds() - { - // Arrange - Create a queue that exists - var queueUrl = await _environment.CreateStandardQueueAsync($"{_testPrefix}-transient"); - - var config = new AmazonSQSConfig - { - ServiceURL = _environment.IsLocalEmulator ? "http://localhost:4566" : null, - MaxErrorRetry = 3, - AuthenticationRegion = "us-east-1" - }; - - var sqsClient = new AmazonSQSClient("test", "test", config); - - try - { - // Act - Send message (should succeed, possibly after retries if transient issues occur) - var response = await sqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = queueUrl, - MessageBody = "Test message for retry policy" - }); - - // Assert - Operation should succeed - Assert.NotNull(response); - Assert.NotNull(response.MessageId); - Assert.False(string.IsNullOrEmpty(response.MessageId)); - - _output.WriteLine($"Message sent successfully with ID: {response.MessageId}"); - - // Verify message was actually sent - var receiveResponse = await sqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = queueUrl, - MaxNumberOfMessages = 1, - WaitTimeSeconds = 2 - }); - - Assert.NotEmpty(receiveResponse.Messages); - Assert.Equal("Test message for retry policy", receiveResponse.Messages[0].Body); - } - finally - { - // Cleanup - await _environment.DeleteQueueAsync(queueUrl); - } - } - - /// - /// Test retry behavior with permanent failures - /// Validates: Requirement 7.2 - Retry behavior under various failure scenarios - /// - [Fact] - public async Task RetryPolicy_StopsRetrying_OnPermanentFailures() - { - // Arrange - Use invalid queue URL (permanent failure) - var invalidQueueUrl = "http://localhost:4566/000000000000/nonexistent-queue"; - var maxRetries = 3; - - var config = new AmazonSQSConfig - { - ServiceURL = _environment.IsLocalEmulator ? "http://localhost:4566" : null, - MaxErrorRetry = maxRetries, - AuthenticationRegion = "us-east-1" - }; - - var sqsClient = new AmazonSQSClient("test", "test", config); - - // Act - var startTime = DateTime.UtcNow; - AmazonServiceException? caughtException = null; - - try - { - await sqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = invalidQueueUrl, - MessageBody = "test" - }); - } - catch (AmazonServiceException ex) - { - caughtException = ex; - } - - var duration = DateTime.UtcNow - startTime; - - // Assert - Should fail with appropriate exception - Assert.NotNull(caughtException); - Assert.True(caughtException is QueueDoesNotExistException || - caughtException.ErrorCode.Contains("NotFound") || - caughtException.ErrorCode.Contains("QueueDoesNotExist"), - $"Expected queue not found error, got: {caughtException.ErrorCode}"); - - // Should have attempted retries (duration > 0) - Assert.True(duration.TotalMilliseconds > 0); - - _output.WriteLine($"Permanent failure detected after {duration.TotalMilliseconds}ms"); - _output.WriteLine($"Error code: {caughtException.ErrorCode}"); - _output.WriteLine($"Error message: {caughtException.Message}"); - } - - /// - /// Test retry behavior with throttling errors - /// Validates: Requirement 7.2 - Retry behavior under various failure scenarios - /// - [Fact] - public async Task RetryPolicy_HandlesThrottlingErrors_WithBackoff() - { - // Arrange - Create queue for testing - var queueUrl = await _environment.CreateStandardQueueAsync($"{_testPrefix}-throttle"); - - var config = new AmazonSQSConfig - { - ServiceURL = _environment.IsLocalEmulator ? "http://localhost:4566" : null, - MaxErrorRetry = 5, // Higher retry count for throttling - AuthenticationRegion = "us-east-1" - }; - - var sqsClient = new AmazonSQSClient("test", "test", config); - - try - { - // Act - Send many messages rapidly to potentially trigger throttling - // Note: LocalStack may not enforce throttling, but this tests the retry mechanism - var tasks = Enumerable.Range(0, 50).Select(async i => - { - try - { - var response = await sqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = queueUrl, - MessageBody = $"Message {i}" - }); - return (Success: true, MessageId: response.MessageId, Error: (string?)null); - } - catch (AmazonServiceException ex) when ( - ex.ErrorCode == "Throttling" || - ex.ErrorCode == "ThrottlingException" || - ex.ErrorCode == "RequestLimitExceeded") - { - _output.WriteLine($"Throttling detected for message {i}: {ex.Message}"); - return (Success: false, MessageId: (string?)null, Error: ex.ErrorCode); - } - catch (Exception ex) - { - return (Success: false, MessageId: (string?)null, Error: ex.Message); - } - }); - - var results = await Task.WhenAll(tasks); - - // Assert - Most messages should succeed (with retries handling any throttling) - var successCount = results.Count(r => r.Success); - var throttleCount = results.Count(r => r.Error?.Contains("Throttl") == true); - - Assert.True(successCount > 0, "At least some messages should succeed"); - - _output.WriteLine($"Results: {successCount} succeeded, {throttleCount} throttled"); - - if (throttleCount > 0) - { - _output.WriteLine("Throttling was detected and handled by retry policy"); - } - } - finally - { - // Cleanup - await _environment.DeleteQueueAsync(queueUrl); - } - } - - /// - /// Test retry behavior with network timeout errors - /// Validates: Requirement 7.2 - Retry behavior under various failure scenarios - /// - [Fact] - public async Task RetryPolicy_RetriesNetworkTimeouts_WithExponentialBackoff() - { - // Arrange - Configure with short timeout to simulate network issues - var queueUrl = await _environment.CreateStandardQueueAsync($"{_testPrefix}-timeout"); - - var config = new AmazonSQSConfig - { - ServiceURL = _environment.IsLocalEmulator ? "http://localhost:4566" : null, - MaxErrorRetry = 3, - Timeout = TimeSpan.FromMilliseconds(100), // Very short timeout - AuthenticationRegion = "us-east-1" - }; - - var sqsClient = new AmazonSQSClient("test", "test", config); - - try - { - // Act - Attempt operation that may timeout - var startTime = DateTime.UtcNow; - Exception? caughtException = null; - - try - { - // Send a larger message that might timeout with short timeout setting - var largeMessage = new string('x', 10000); - await sqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = queueUrl, - MessageBody = largeMessage - }); - } - catch (Exception ex) - { - caughtException = ex; - _output.WriteLine($"Exception caught: {ex.GetType().Name} - {ex.Message}"); - } - - var duration = DateTime.UtcNow - startTime; - - // Assert - Should either succeed (after retries) or fail with timeout - // The key is that retries were attempted (duration > timeout) - _output.WriteLine($"Operation completed in {duration.TotalMilliseconds}ms"); - - if (caughtException != null) - { - // If it failed, it should have taken time for retries - Assert.True(duration.TotalMilliseconds > config.Timeout.Value.TotalMilliseconds, - "Should have attempted retries before failing"); - _output.WriteLine("Operation failed after retry attempts"); - } - else - { - _output.WriteLine("Operation succeeded (possibly after retries)"); - } - } - finally - { - // Cleanup - await _environment.DeleteQueueAsync(queueUrl); - } - } - - /// - /// Test that retry delays increase exponentially - /// Validates: Requirement 7.2 - Exponential backoff implementation - /// - [Fact] - public async Task RetryPolicy_DelaysIncreaseExponentially_BetweenRetries() - { - // LocalStack returns 404 errors immediately without retry delays (non-retryable errors) - if (_environment.IsLocalEmulator) return; - - // Arrange - var invalidQueueUrl = "http://localhost:4566/000000000000/nonexistent-queue"; - var maxRetries = 4; - - var config = new AmazonSQSConfig - { - ServiceURL = _environment.IsLocalEmulator ? "http://localhost:4566" : null, - MaxErrorRetry = maxRetries, - AuthenticationRegion = "us-east-1" - }; - - var sqsClient = new AmazonSQSClient("test", "test", config); - - // Act - Measure total duration with retries - var startTime = DateTime.UtcNow; - try - { - await sqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = invalidQueueUrl, - MessageBody = "test" - }); - } - catch (AmazonServiceException) - { - // Expected - } - - var totalDuration = DateTime.UtcNow - startTime; - - // Assert - With exponential backoff, total duration should be significant - // Expected pattern: base + 2*base + 4*base + 8*base - // With AWS SDK default base delay (~100ms): ~100 + ~200 + ~400 + ~800 = ~1500ms minimum - Assert.True(totalDuration.TotalMilliseconds > 500, - $"With {maxRetries} retries and exponential backoff, expected > 500ms, got {totalDuration.TotalMilliseconds}ms"); - - _output.WriteLine($"Total duration with {maxRetries} retries: {totalDuration.TotalMilliseconds}ms"); - _output.WriteLine("This duration indicates exponential backoff was applied"); - } - - /// - /// Test retry policy with jitter to prevent thundering herd - /// Validates: Requirement 7.2 - Exponential backoff with jitter - /// - [Fact] - public async Task RetryPolicy_AppliesJitter_ToPreventThunderingHerd() - { - // LocalStack returns 404 errors immediately without retry delays (non-retryable errors) - if (_environment.IsLocalEmulator) return; - - // Arrange - Execute same failing operation multiple times - var invalidQueueUrl = "http://localhost:4566/000000000000/nonexistent-queue"; - var maxRetries = 3; - var iterations = 5; - - var config = new AmazonSQSConfig - { - ServiceURL = _environment.IsLocalEmulator ? "http://localhost:4566" : null, - MaxErrorRetry = maxRetries, - AuthenticationRegion = "us-east-1" - }; - - var durations = new List(); - - // Act - Execute multiple times and measure durations - for (int i = 0; i < iterations; i++) - { - var sqsClient = new AmazonSQSClient("test", "test", config); - var startTime = DateTime.UtcNow; - - try - { - await sqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = invalidQueueUrl, - MessageBody = "test" - }); - } - catch (AmazonServiceException) - { - // Expected - } - - var duration = (DateTime.UtcNow - startTime).TotalMilliseconds; - durations.Add(duration); - _output.WriteLine($"Iteration {i + 1}: {duration}ms"); - } - - // Assert - Durations should vary due to jitter - // Calculate variance to verify jitter is applied - var average = durations.Average(); - var variance = durations.Select(d => Math.Pow(d - average, 2)).Average(); - var standardDeviation = Math.Sqrt(variance); - - _output.WriteLine($"Average duration: {average}ms"); - _output.WriteLine($"Standard deviation: {standardDeviation}ms"); - - // With jitter, we expect meaningful variation in durations across multiple runs. - // A standard deviation of at least 10ms indicates that jitter is actually shifting - // the retry delays rather than producing identical timings every time. - Assert.True(standardDeviation > 10, - $"Standard deviation ({standardDeviation:F2}ms) should be > 10ms when jitter is enabled, " + - "indicating that jitter produces real variation in retry delays"); - - _output.WriteLine("Jitter analysis complete - durations show expected variation pattern"); - } - - /// - /// Test retry policy respects cancellation tokens - /// Validates: Requirement 7.2 - Retry behavior under various failure scenarios - /// - [Fact] - public async Task RetryPolicy_RespectsCancellationToken_DuringRetries() - { - // Arrange - var invalidQueueUrl = "http://localhost:4566/000000000000/nonexistent-queue"; - var maxRetries = 10; // High retry count - - var config = new AmazonSQSConfig - { - ServiceURL = _environment.IsLocalEmulator ? "http://localhost:4566" : null, - MaxErrorRetry = maxRetries, - AuthenticationRegion = "us-east-1" - }; - - var sqsClient = new AmazonSQSClient("test", "test", config); - var cts = new CancellationTokenSource(); - - // Cancel after short delay - cts.CancelAfter(TimeSpan.FromMilliseconds(500)); - - // Act - var startTime = DateTime.UtcNow; - var operationCancelled = false; - - try - { - await sqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = invalidQueueUrl, - MessageBody = "test" - }, cts.Token); - } - catch (OperationCanceledException) - { - operationCancelled = true; - _output.WriteLine("Operation was cancelled as expected"); - } - catch (AmazonServiceException ex) - { - _output.WriteLine($"Operation failed with: {ex.Message}"); - } - - var duration = DateTime.UtcNow - startTime; - - // Assert - Operation should be cancelled or complete quickly - Assert.True(duration.TotalSeconds < 5, - $"Operation should be cancelled quickly, but took {duration.TotalSeconds}s"); - - _output.WriteLine($"Operation completed/cancelled in {duration.TotalMilliseconds}ms"); - } -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/Integration/AwsServiceThrottlingAndFailureTests.cs b/tests/SourceFlow.Cloud.AWS.Tests/Integration/AwsServiceThrottlingAndFailureTests.cs deleted file mode 100644 index b7a1561b..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/Integration/AwsServiceThrottlingAndFailureTests.cs +++ /dev/null @@ -1,1061 +0,0 @@ -using Amazon.SQS; -using Amazon.SQS.Model; -using Amazon.SimpleNotificationService; -using Amazon.SimpleNotificationService.Model; -using Amazon.Runtime; -using Microsoft.Extensions.Logging; -using SourceFlow.Cloud.AWS.Tests.TestHelpers; -using Xunit; -using Xunit.Abstractions; -using System.Diagnostics; -using System.Net; -using System.Net.Sockets; - -namespace SourceFlow.Cloud.AWS.Tests.Integration; - -/// -/// Integration tests for AWS service throttling and failure handling -/// Tests graceful handling of AWS service throttling, automatic backoff when service limits are exceeded, -/// network failure handling and connection recovery, timeout handling and connection pooling -/// Validates: Requirements 7.4, 7.5 - AWS service throttling and network failure handling -/// -[Collection("AWS Integration Tests")] -[Trait("Category", "Integration")] -[Trait("Category", "RequiresLocalStack")] -public class AwsServiceThrottlingAndFailureTests : IAsyncLifetime -{ - private readonly ITestOutputHelper _output; - private IAwsTestEnvironment _environment = null!; - private readonly ILogger _logger; - private readonly string _testPrefix; - - public AwsServiceThrottlingAndFailureTests(ITestOutputHelper output) - { - _output = output; - _testPrefix = $"throttle-test-{Guid.NewGuid():N}"; - - var loggerFactory = LoggerFactory.Create(builder => - { - builder.AddConsole(); - builder.SetMinimumLevel(LogLevel.Debug); - }); - - _logger = loggerFactory.CreateLogger(); - } - - public async Task InitializeAsync() - { - _environment = await AwsTestEnvironmentFactory.CreateLocalStackEnvironmentAsync(_testPrefix); - } - - public async Task DisposeAsync() - { - await _environment.DisposeAsync(); - } - - /// - /// Test graceful handling of SQS service throttling with automatic backoff - /// Validates: Requirement 7.4 - Graceful handling of AWS service throttling - /// - [Fact] - public async Task SqsClient_HandlesThrottling_WithAutomaticBackoff() - { - // Arrange - var queueUrl = await _environment.CreateStandardQueueAsync($"{_testPrefix}-throttle-sqs"); - var config = new AmazonSQSConfig - { - ServiceURL = _environment.IsLocalEmulator ? "http://localhost:4566" : null, - MaxErrorRetry = 5, - AuthenticationRegion = "us-east-1" - }; - - var sqsClient = new AmazonSQSClient("test", "test", config); - var successCount = 0; - var throttleCount = 0; - var totalMessages = 100; - - try - { - // Act - Send many messages rapidly to potentially trigger throttling - var stopwatch = Stopwatch.StartNew(); - var tasks = Enumerable.Range(0, totalMessages).Select(async i => - { - try - { - await sqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = queueUrl, - MessageBody = $"Throttle test message {i}", - MessageAttributes = new Dictionary - { - ["MessageNumber"] = new Amazon.SQS.Model.MessageAttributeValue - { - DataType = "Number", - StringValue = i.ToString() - } - } - }); - Interlocked.Increment(ref successCount); - return (Success: true, Throttled: false); - } - catch (AmazonServiceException ex) when ( - ex.ErrorCode == "Throttling" || - ex.ErrorCode == "ThrottlingException" || - ex.ErrorCode == "RequestLimitExceeded" || - ex.StatusCode == HttpStatusCode.TooManyRequests) - { - Interlocked.Increment(ref throttleCount); - _output.WriteLine($"Message {i} throttled: {ex.ErrorCode}"); - return (Success: false, Throttled: true); - } - catch (Exception ex) - { - _output.WriteLine($"Message {i} failed: {ex.Message}"); - return (Success: false, Throttled: false); - } - }); - - var results = await Task.WhenAll(tasks); - stopwatch.Stop(); - - // Assert - Most messages should succeed (with retries handling throttling) - Assert.True(successCount > totalMessages * 0.7, - $"At least 70% of messages should succeed, got {successCount}/{totalMessages}"); - - _output.WriteLine($"Results: {successCount} succeeded, {throttleCount} throttled"); - _output.WriteLine($"Total duration: {stopwatch.ElapsedMilliseconds}ms"); - _output.WriteLine($"Average: {stopwatch.ElapsedMilliseconds / (double)totalMessages}ms per message"); - - // If throttling occurred, verify automatic backoff was applied - if (throttleCount > 0) - { - _output.WriteLine($"Throttling detected and handled: {throttleCount} throttled requests"); - Assert.True(stopwatch.ElapsedMilliseconds > 1000, - "With throttling, total duration should show backoff delays"); - } - } - finally - { - await _environment.DeleteQueueAsync(queueUrl); - } - } - - /// - /// Test graceful handling of SNS service throttling with automatic backoff - /// Validates: Requirement 7.4 - Graceful handling of AWS service throttling - /// - [Fact] - public async Task SnsClient_HandlesThrottling_WithAutomaticBackoff() - { - // Arrange - var topicArn = await _environment.CreateTopicAsync($"{_testPrefix}-throttle-sns"); - var config = new AmazonSimpleNotificationServiceConfig - { - ServiceURL = _environment.IsLocalEmulator ? "http://localhost:4566" : null, - MaxErrorRetry = 5, - AuthenticationRegion = "us-east-1" - }; - - var snsClient = new AmazonSimpleNotificationServiceClient("test", "test", config); - var successCount = 0; - var throttleCount = 0; - var totalMessages = 100; - - try - { - // Act - Publish many messages rapidly to potentially trigger throttling - var stopwatch = Stopwatch.StartNew(); - var tasks = Enumerable.Range(0, totalMessages).Select(async i => - { - try - { - await snsClient.PublishAsync(new PublishRequest - { - TopicArn = topicArn, - Message = $"Throttle test message {i}", - MessageAttributes = new Dictionary - { - ["MessageNumber"] = new Amazon.SimpleNotificationService.Model.MessageAttributeValue - { - DataType = "Number", - StringValue = i.ToString() - } - } - }); - Interlocked.Increment(ref successCount); - return (Success: true, Throttled: false); - } - catch (AmazonServiceException ex) when ( - ex.ErrorCode == "Throttling" || - ex.ErrorCode == "ThrottlingException" || - ex.ErrorCode == "RequestLimitExceeded" || - ex.StatusCode == HttpStatusCode.TooManyRequests) - { - Interlocked.Increment(ref throttleCount); - _output.WriteLine($"Message {i} throttled: {ex.ErrorCode}"); - return (Success: false, Throttled: true); - } - catch (Exception ex) - { - _output.WriteLine($"Message {i} failed: {ex.Message}"); - return (Success: false, Throttled: false); - } - }); - - var results = await Task.WhenAll(tasks); - stopwatch.Stop(); - - // Assert - Most messages should succeed - Assert.True(successCount > totalMessages * 0.7, - $"At least 70% of messages should succeed, got {successCount}/{totalMessages}"); - - _output.WriteLine($"Results: {successCount} succeeded, {throttleCount} throttled"); - _output.WriteLine($"Total duration: {stopwatch.ElapsedMilliseconds}ms"); - - if (throttleCount > 0) - { - _output.WriteLine($"Throttling detected and handled: {throttleCount} throttled requests"); - } - } - finally - { - await _environment.DeleteTopicAsync(topicArn); - } - } - - /// - /// Test automatic backoff when SQS service limits are exceeded - /// Validates: Requirement 7.4 - Automatic backoff when service limits are exceeded - /// - [Fact] - public async Task SqsClient_AppliesBackoff_WhenServiceLimitsExceeded() - { - // Arrange - var queueUrl = await _environment.CreateStandardQueueAsync($"{_testPrefix}-limits-sqs"); - var config = new AmazonSQSConfig - { - ServiceURL = _environment.IsLocalEmulator ? "http://localhost:4566" : null, - MaxErrorRetry = 5, - AuthenticationRegion = "us-east-1" - }; - - var sqsClient = new AmazonSQSClient("test", "test", config); - var attemptDurations = new List(); - - try - { - // Act - Send messages in bursts to test backoff behavior - for (int burst = 0; burst < 3; burst++) - { - var stopwatch = Stopwatch.StartNew(); - var burstTasks = Enumerable.Range(0, 50).Select(async i => - { - try - { - await sqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = queueUrl, - MessageBody = $"Burst {burst}, Message {i}" - }); - return true; - } - catch (AmazonServiceException ex) when ( - ex.ErrorCode == "Throttling" || - ex.ErrorCode == "RequestLimitExceeded") - { - // Expected throttling - return false; - } - }); - - await Task.WhenAll(burstTasks); - stopwatch.Stop(); - attemptDurations.Add(stopwatch.ElapsedMilliseconds); - - _output.WriteLine($"Burst {burst + 1} completed in {stopwatch.ElapsedMilliseconds}ms"); - - // Small delay between bursts - await Task.Delay(100); - } - - // Assert - Verify backoff behavior - // If throttling occurs, later bursts may take longer due to backoff - Assert.NotEmpty(attemptDurations); - Assert.All(attemptDurations, duration => Assert.True(duration >= 0)); - - var avgDuration = attemptDurations.Average(); - _output.WriteLine($"Average burst duration: {avgDuration}ms"); - - // Verify that the SDK is applying backoff (durations should be reasonable) - Assert.True(avgDuration < 30000, - $"Average duration should be reasonable with backoff, got {avgDuration}ms"); - } - finally - { - await _environment.DeleteQueueAsync(queueUrl); - } - } - - /// - /// Test automatic backoff when SNS service limits are exceeded - /// Validates: Requirement 7.4 - Automatic backoff when service limits are exceeded - /// - [Fact] - public async Task SnsClient_AppliesBackoff_WhenServiceLimitsExceeded() - { - // Arrange - var topicArn = await _environment.CreateTopicAsync($"{_testPrefix}-limits-sns"); - var config = new AmazonSimpleNotificationServiceConfig - { - ServiceURL = _environment.IsLocalEmulator ? "http://localhost:4566" : null, - MaxErrorRetry = 5, - AuthenticationRegion = "us-east-1" - }; - - var snsClient = new AmazonSimpleNotificationServiceClient("test", "test", config); - var attemptDurations = new List(); - - try - { - // Act - Publish messages in bursts to test backoff behavior - for (int burst = 0; burst < 3; burst++) - { - var stopwatch = Stopwatch.StartNew(); - var burstTasks = Enumerable.Range(0, 50).Select(async i => - { - try - { - await snsClient.PublishAsync(new PublishRequest - { - TopicArn = topicArn, - Message = $"Burst {burst}, Message {i}" - }); - return true; - } - catch (AmazonServiceException ex) when ( - ex.ErrorCode == "Throttling" || - ex.ErrorCode == "RequestLimitExceeded") - { - return false; - } - }); - - await Task.WhenAll(burstTasks); - stopwatch.Stop(); - attemptDurations.Add(stopwatch.ElapsedMilliseconds); - - _output.WriteLine($"Burst {burst + 1} completed in {stopwatch.ElapsedMilliseconds}ms"); - - await Task.Delay(100); - } - - // Assert - Assert.NotEmpty(attemptDurations); - var avgDuration = attemptDurations.Average(); - _output.WriteLine($"Average burst duration: {avgDuration}ms"); - - Assert.True(avgDuration < 30000, - $"Average duration should be reasonable with backoff, got {avgDuration}ms"); - } - finally - { - await _environment.DeleteTopicAsync(topicArn); - } - } - - /// - /// Test network failure handling for SQS operations - /// Validates: Requirement 7.5 - Network failure handling - /// - [Fact] - public async Task SqsClient_HandlesNetworkFailures_Gracefully() - { - // Arrange - Use invalid endpoint to simulate network failure - var config = new AmazonSQSConfig - { - ServiceURL = "http://invalid-endpoint-that-does-not-exist.local:9999", - MaxErrorRetry = 2, - Timeout = TimeSpan.FromSeconds(2), - AuthenticationRegion = "us-east-1" - }; - - var sqsClient = new AmazonSQSClient("test", "test", config); - var queueUrl = "http://invalid-endpoint-that-does-not-exist.local:9999/000000000000/test-queue"; - - // Act - var stopwatch = Stopwatch.StartNew(); - Exception? caughtException = null; - - try - { - await sqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = queueUrl, - MessageBody = "test" - }); - } - catch (Exception ex) - { - caughtException = ex; - _output.WriteLine($"Network failure handled: {ex.GetType().Name}"); - _output.WriteLine($"Message: {ex.Message}"); - } - - stopwatch.Stop(); - - // Assert - Should fail gracefully with appropriate exception - Assert.NotNull(caughtException); - Assert.True( - caughtException is AmazonServiceException || - caughtException is HttpRequestException || - caughtException is SocketException || - caughtException is WebException || - caughtException is TimeoutException || - caughtException is TaskCanceledException || - caughtException.InnerException is SocketException || - caughtException.InnerException is HttpRequestException, - $"Expected network-related exception, got: {caughtException.GetType().Name}"); - - // Should have attempted operation (exception was caught) - _output.WriteLine($"Operation failed after {stopwatch.ElapsedMilliseconds}ms"); - Assert.NotNull(caughtException); - } - - /// - /// Test network failure handling for SNS operations - /// Validates: Requirement 7.5 - Network failure handling - /// - [Fact] - public async Task SnsClient_HandlesNetworkFailures_Gracefully() - { - // Arrange - Use invalid endpoint to simulate network failure - var config = new AmazonSimpleNotificationServiceConfig - { - ServiceURL = "http://invalid-endpoint-that-does-not-exist.local:9999", - MaxErrorRetry = 2, - Timeout = TimeSpan.FromSeconds(2), - AuthenticationRegion = "us-east-1" - }; - - var snsClient = new AmazonSimpleNotificationServiceClient("test", "test", config); - var topicArn = "arn:aws:sns:us-east-1:000000000000:test-topic"; - - // Act - var stopwatch = Stopwatch.StartNew(); - Exception? caughtException = null; - - try - { - await snsClient.PublishAsync(new PublishRequest - { - TopicArn = topicArn, - Message = "test" - }); - } - catch (Exception ex) - { - caughtException = ex; - _output.WriteLine($"Network failure handled: {ex.GetType().Name}"); - _output.WriteLine($"Message: {ex.Message}"); - } - - stopwatch.Stop(); - - // Assert - Assert.NotNull(caughtException); - Assert.True( - caughtException is AmazonServiceException || - caughtException is HttpRequestException || - caughtException is SocketException || - caughtException is WebException || - caughtException is TimeoutException || - caughtException is TaskCanceledException || - caughtException.InnerException is SocketException || - caughtException.InnerException is HttpRequestException, - $"Expected network-related exception, got: {caughtException.GetType().Name}"); - - _output.WriteLine($"Operation failed after {stopwatch.ElapsedMilliseconds}ms"); - } - - /// - /// Test connection recovery after network failure for SQS - /// Validates: Requirement 7.5 - Connection recovery - /// - [Fact] - public async Task SqsClient_RecoversConnection_AfterNetworkFailure() - { - // Arrange - var queueUrl = await _environment.CreateStandardQueueAsync($"{_testPrefix}-recovery-sqs"); - - try - { - // Act - Step 1: Successful operation - var response1 = await _environment.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = queueUrl, - MessageBody = "Before failure" - }); - - Assert.NotNull(response1.MessageId); - _output.WriteLine($"First message sent successfully: {response1.MessageId}"); - - // Step 2: Simulate failure by using invalid endpoint temporarily - var invalidConfig = new AmazonSQSConfig - { - ServiceURL = "http://invalid-endpoint.local:9999", - MaxErrorRetry = 1, - Timeout = TimeSpan.FromSeconds(1), - AuthenticationRegion = "us-east-1" - }; - - var failingClient = new AmazonSQSClient("test", "test", invalidConfig); - - try - { - await failingClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = queueUrl, - MessageBody = "During failure" - }); - } - catch (Exception ex) - { - _output.WriteLine($"Expected failure: {ex.GetType().Name}"); - } - - // Step 3: Recover with valid client - var response2 = await _environment.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = queueUrl, - MessageBody = "After recovery" - }); - - // Assert - Connection should recover - Assert.NotNull(response2.MessageId); - _output.WriteLine($"Message sent after recovery: {response2.MessageId}"); - - // Verify both messages were received - var receiveResponse = await _environment.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = queueUrl, - MaxNumberOfMessages = 10, - WaitTimeSeconds = 2 - }); - - Assert.True(receiveResponse.Messages.Count >= 2, - $"Should receive at least 2 messages, got {receiveResponse.Messages.Count}"); - - _output.WriteLine($"Successfully recovered and received {receiveResponse.Messages.Count} messages"); - } - finally - { - await _environment.DeleteQueueAsync(queueUrl); - } - } - - /// - /// Test connection recovery after network failure for SNS - /// Validates: Requirement 7.5 - Connection recovery - /// - [Fact] - public async Task SnsClient_RecoversConnection_AfterNetworkFailure() - { - // Arrange - var topicArn = await _environment.CreateTopicAsync($"{_testPrefix}-recovery-sns"); - - try - { - // Act - Step 1: Successful operation - var response1 = await _environment.SnsClient.PublishAsync(new PublishRequest - { - TopicArn = topicArn, - Message = "Before failure" - }); - - Assert.NotNull(response1.MessageId); - _output.WriteLine($"First message published successfully: {response1.MessageId}"); - - // Step 2: Simulate failure - var invalidConfig = new AmazonSimpleNotificationServiceConfig - { - ServiceURL = "http://invalid-endpoint.local:9999", - MaxErrorRetry = 1, - Timeout = TimeSpan.FromSeconds(1), - AuthenticationRegion = "us-east-1" - }; - - var failingClient = new AmazonSimpleNotificationServiceClient("test", "test", invalidConfig); - - try - { - await failingClient.PublishAsync(new PublishRequest - { - TopicArn = topicArn, - Message = "During failure" - }); - } - catch (Exception ex) - { - _output.WriteLine($"Expected failure: {ex.GetType().Name}"); - } - - // Step 3: Recover with valid client - var response2 = await _environment.SnsClient.PublishAsync(new PublishRequest - { - TopicArn = topicArn, - Message = "After recovery" - }); - - // Assert - Connection should recover - Assert.NotNull(response2.MessageId); - _output.WriteLine($"Message published after recovery: {response2.MessageId}"); - _output.WriteLine("Connection successfully recovered"); - } - finally - { - await _environment.DeleteTopicAsync(topicArn); - } - } - - /// - /// Test timeout handling for SQS operations - /// Validates: Requirement 7.5 - Timeout handling - /// - [Fact] - public async Task SqsClient_HandlesTimeouts_Appropriately() - { - // Arrange - Configure with very short timeout - var queueUrl = await _environment.CreateStandardQueueAsync($"{_testPrefix}-timeout-sqs"); - var config = new AmazonSQSConfig - { - ServiceURL = _environment.IsLocalEmulator ? "http://localhost:4566" : null, - MaxErrorRetry = 2, - Timeout = TimeSpan.FromMilliseconds(50), // Very short timeout - AuthenticationRegion = "us-east-1" - }; - - var sqsClient = new AmazonSQSClient("test", "test", config); - - try - { - // Act - Send large message that may timeout - var stopwatch = Stopwatch.StartNew(); - var largeMessage = new string('x', 50000); // Large message - Exception? caughtException = null; - - try - { - await sqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = queueUrl, - MessageBody = largeMessage - }); - } - catch (Exception ex) - { - caughtException = ex; - _output.WriteLine($"Timeout handled: {ex.GetType().Name}"); - _output.WriteLine($"Message: {ex.Message}"); - } - - stopwatch.Stop(); - - // Assert - Should handle timeout gracefully - if (caughtException != null) - { - // Timeout or related exception expected - Assert.True( - caughtException is TaskCanceledException || - caughtException is OperationCanceledException || - caughtException is AmazonServiceException || - caughtException.InnerException is TaskCanceledException, - $"Expected timeout-related exception, got: {caughtException.GetType().Name}"); - - _output.WriteLine($"Operation timed out after {stopwatch.ElapsedMilliseconds}ms"); - } - else - { - _output.WriteLine($"Operation succeeded in {stopwatch.ElapsedMilliseconds}ms"); - } - - // Verify timeout was respected (with generous margin for LocalStack overhead) - var maxExpectedDuration = config.Timeout.Value.TotalMilliseconds * (config.MaxErrorRetry + 1) * 2 + 5000; - Assert.True(stopwatch.ElapsedMilliseconds < maxExpectedDuration, - $"Operation should respect timeout settings, took {stopwatch.ElapsedMilliseconds}ms"); - } - finally - { - await _environment.DeleteQueueAsync(queueUrl); - } - } - - /// - /// Test timeout handling for SNS operations - /// Validates: Requirement 7.5 - Timeout handling - /// - [Fact] - public async Task SnsClient_HandlesTimeouts_Appropriately() - { - // Arrange - var topicArn = await _environment.CreateTopicAsync($"{_testPrefix}-timeout-sns"); - var config = new AmazonSimpleNotificationServiceConfig - { - ServiceURL = _environment.IsLocalEmulator ? "http://localhost:4566" : null, - MaxErrorRetry = 2, - Timeout = TimeSpan.FromMilliseconds(50), - AuthenticationRegion = "us-east-1" - }; - - var snsClient = new AmazonSimpleNotificationServiceClient("test", "test", config); - - try - { - // Act - var stopwatch = Stopwatch.StartNew(); - var largeMessage = new string('x', 50000); - Exception? caughtException = null; - - try - { - await snsClient.PublishAsync(new PublishRequest - { - TopicArn = topicArn, - Message = largeMessage - }); - } - catch (Exception ex) - { - caughtException = ex; - _output.WriteLine($"Timeout handled: {ex.GetType().Name}"); - } - - stopwatch.Stop(); - - // Assert - if (caughtException != null) - { - Assert.True( - caughtException is TaskCanceledException || - caughtException is OperationCanceledException || - caughtException is AmazonServiceException || - caughtException.InnerException is TaskCanceledException, - $"Expected timeout-related exception, got: {caughtException.GetType().Name}"); - - _output.WriteLine($"Operation timed out after {stopwatch.ElapsedMilliseconds}ms"); - } - - var maxExpectedDuration = config.Timeout.Value.TotalMilliseconds * (config.MaxErrorRetry + 1) * 2; - Assert.True(stopwatch.ElapsedMilliseconds < maxExpectedDuration, - $"Operation should respect timeout settings"); - } - finally - { - await _environment.DeleteTopicAsync(topicArn); - } - } - - /// - /// Test connection pooling behavior for SQS clients - /// Validates: Requirement 7.5 - Connection pooling - /// - [Fact] - public async Task SqsClient_UsesConnectionPooling_Efficiently() - { - // Arrange - var queueUrl = await _environment.CreateStandardQueueAsync($"{_testPrefix}-pool-sqs"); - var config = new AmazonSQSConfig - { - ServiceURL = _environment.IsLocalEmulator ? "http://localhost:4566" : null, - MaxErrorRetry = 3, - AuthenticationRegion = "us-east-1" - }; - - // Create single client instance (simulating connection pooling) - var sqsClient = new AmazonSQSClient("test", "test", config); - - try - { - // Act - Execute many operations with same client - var stopwatch = Stopwatch.StartNew(); - var tasks = Enumerable.Range(0, 100).Select(async i => - { - try - { - await sqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = queueUrl, - MessageBody = $"Pooling test message {i}" - }); - return true; - } - catch - { - return false; - } - }); - - var results = await Task.WhenAll(tasks); - stopwatch.Stop(); - - var successCount = results.Count(r => r); - - // Assert - Connection pooling should enable efficient concurrent operations - Assert.True(successCount > 90, - $"At least 90% should succeed with connection pooling, got {successCount}/100"); - - var avgTimePerMessage = stopwatch.ElapsedMilliseconds / 100.0; - _output.WriteLine($"100 messages sent in {stopwatch.ElapsedMilliseconds}ms"); - _output.WriteLine($"Average: {avgTimePerMessage}ms per message"); - - // With connection pooling, should be efficient - Assert.True(avgTimePerMessage < 1000, - $"Connection pooling should enable efficient operations, got {avgTimePerMessage}ms per message"); - } - finally - { - await _environment.DeleteQueueAsync(queueUrl); - } - } - - /// - /// Test connection pooling behavior for SNS clients - /// Validates: Requirement 7.5 - Connection pooling - /// - [Fact] - public async Task SnsClient_UsesConnectionPooling_Efficiently() - { - // Arrange - var topicArn = await _environment.CreateTopicAsync($"{_testPrefix}-pool-sns"); - var config = new AmazonSimpleNotificationServiceConfig - { - ServiceURL = _environment.IsLocalEmulator ? "http://localhost:4566" : null, - MaxErrorRetry = 3, - AuthenticationRegion = "us-east-1" - }; - - var snsClient = new AmazonSimpleNotificationServiceClient("test", "test", config); - - try - { - // Act - var stopwatch = Stopwatch.StartNew(); - var tasks = Enumerable.Range(0, 100).Select(async i => - { - try - { - await snsClient.PublishAsync(new PublishRequest - { - TopicArn = topicArn, - Message = $"Pooling test message {i}" - }); - return true; - } - catch - { - return false; - } - }); - - var results = await Task.WhenAll(tasks); - stopwatch.Stop(); - - var successCount = results.Count(r => r); - - // Assert - Assert.True(successCount > 90, - $"At least 90% should succeed with connection pooling, got {successCount}/100"); - - var avgTimePerMessage = stopwatch.ElapsedMilliseconds / 100.0; - _output.WriteLine($"100 messages published in {stopwatch.ElapsedMilliseconds}ms"); - _output.WriteLine($"Average: {avgTimePerMessage}ms per message"); - - Assert.True(avgTimePerMessage < 1000, - $"Connection pooling should enable efficient operations, got {avgTimePerMessage}ms per message"); - } - finally - { - await _environment.DeleteTopicAsync(topicArn); - } - } - - /// - /// Test handling of intermittent network failures with retry - /// Validates: Requirements 7.4, 7.5 - Throttling and network failure handling - /// - [Fact] - public async Task AwsClients_HandleIntermittentFailures_WithRetry() - { - // Arrange - var queueUrl = await _environment.CreateStandardQueueAsync($"{_testPrefix}-intermittent"); - var config = new AmazonSQSConfig - { - ServiceURL = _environment.IsLocalEmulator ? "http://localhost:4566" : null, - MaxErrorRetry = 5, - AuthenticationRegion = "us-east-1" - }; - - var sqsClient = new AmazonSQSClient("test", "test", config); - var successCount = 0; - var failureCount = 0; - - try - { - // Act - Send messages with potential intermittent failures - var tasks = Enumerable.Range(0, 50).Select(async i => - { - try - { - await sqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = queueUrl, - MessageBody = $"Intermittent test {i}" - }); - Interlocked.Increment(ref successCount); - return true; - } - catch (Exception ex) - { - Interlocked.Increment(ref failureCount); - _output.WriteLine($"Message {i} failed: {ex.Message}"); - return false; - } - }); - - var results = await Task.WhenAll(tasks); - - // Assert - Most should succeed due to retry mechanism - Assert.True(successCount > 40, - $"Retry mechanism should handle intermittent failures, got {successCount}/50 successes"); - - _output.WriteLine($"Results: {successCount} succeeded, {failureCount} failed"); - _output.WriteLine("Retry mechanism successfully handled intermittent failures"); - } - finally - { - await _environment.DeleteQueueAsync(queueUrl); - } - } - - /// - /// Test that service errors are properly categorized and handled - /// Validates: Requirements 7.4, 7.5 - Error categorization and handling - /// - [Fact] - public async Task AwsClients_CategorizeServiceErrors_Appropriately() - { - // Arrange - var testCases = new[] - { - new { QueueUrl = "http://localhost:4566/000000000000/nonexistent", - ExpectedErrorType = "NotFound", Description = "Queue not found" }, - new { QueueUrl = "", - ExpectedErrorType = "Validation", Description = "Invalid queue URL" } - }; - - var config = new AmazonSQSConfig - { - ServiceURL = _environment.IsLocalEmulator ? "http://localhost:4566" : null, - MaxErrorRetry = 2, - AuthenticationRegion = "us-east-1" - }; - - var sqsClient = new AmazonSQSClient("test", "test", config); - - // Act & Assert - Test each error scenario - foreach (var testCase in testCases) - { - Exception? caughtException = null; - - try - { - await sqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = testCase.QueueUrl, - MessageBody = "test" - }); - } - catch (Exception ex) - { - caughtException = ex; - _output.WriteLine($"{testCase.Description}: {ex.GetType().Name}"); - - if (ex is AmazonServiceException awsEx) - { - _output.WriteLine($" Error Code: {awsEx.ErrorCode}"); - _output.WriteLine($" Status Code: {awsEx.StatusCode}"); - _output.WriteLine($" Retryable: {awsEx.Retryable}"); - } - } - - Assert.NotNull(caughtException); - _output.WriteLine($"Error properly categorized for: {testCase.Description}"); - } - } - - /// - /// Test concurrent operations under throttling conditions - /// Validates: Requirement 7.4 - Concurrent throttling handling - /// - [Fact] - public async Task AwsClients_HandleConcurrentThrottling_Gracefully() - { - // Arrange - var queueUrl = await _environment.CreateStandardQueueAsync($"{_testPrefix}-concurrent-throttle"); - var config = new AmazonSQSConfig - { - ServiceURL = _environment.IsLocalEmulator ? "http://localhost:4566" : null, - MaxErrorRetry = 5, - AuthenticationRegion = "us-east-1" - }; - - var sqsClient = new AmazonSQSClient("test", "test", config); - var concurrentOperations = 200; - var successCount = 0; - - try - { - // Act - Execute many concurrent operations - var stopwatch = Stopwatch.StartNew(); - var tasks = Enumerable.Range(0, concurrentOperations).Select(async i => - { - try - { - await sqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = queueUrl, - MessageBody = $"Concurrent message {i}" - }); - Interlocked.Increment(ref successCount); - return true; - } - catch (AmazonServiceException ex) when ( - ex.ErrorCode == "Throttling" || - ex.ErrorCode == "RequestLimitExceeded") - { - _output.WriteLine($"Message {i} throttled"); - return false; - } - catch (Exception ex) - { - _output.WriteLine($"Message {i} failed: {ex.Message}"); - return false; - } - }); - - var results = await Task.WhenAll(tasks); - stopwatch.Stop(); - - // Assert - System should handle concurrent throttling gracefully - Assert.True(successCount > concurrentOperations * 0.6, - $"At least 60% should succeed under concurrent load, got {successCount}/{concurrentOperations}"); - - _output.WriteLine($"Concurrent operations: {successCount}/{concurrentOperations} succeeded"); - _output.WriteLine($"Total duration: {stopwatch.ElapsedMilliseconds}ms"); - _output.WriteLine($"Average: {stopwatch.ElapsedMilliseconds / (double)concurrentOperations}ms per operation"); - } - finally - { - await _environment.DeleteQueueAsync(queueUrl); - } - } -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/Integration/EnhancedAwsTestEnvironmentTests.cs b/tests/SourceFlow.Cloud.AWS.Tests/Integration/EnhancedAwsTestEnvironmentTests.cs deleted file mode 100644 index 52e5d6f4..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/Integration/EnhancedAwsTestEnvironmentTests.cs +++ /dev/null @@ -1,255 +0,0 @@ -using SourceFlow.Cloud.AWS.Tests.TestHelpers; -using Microsoft.Extensions.DependencyInjection; -using Xunit.Abstractions; - -namespace SourceFlow.Cloud.AWS.Tests.Integration; - -/// -/// Integration tests for the enhanced AWS test environment abstractions -/// Validates that the new IAwsTestEnvironment, ILocalStackManager, and IAwsResourceManager work correctly -/// -[Collection("AWS Integration Tests")] -[Trait("Category", "Integration")] -[Trait("Category", "RequiresLocalStack")] -public class EnhancedAwsTestEnvironmentTests : IAsyncLifetime -{ - private readonly ITestOutputHelper _output; - private IAwsTestEnvironment? _testEnvironment; - - public EnhancedAwsTestEnvironmentTests(ITestOutputHelper output) - { - _output = output ?? throw new ArgumentNullException(nameof(output)); - } - - public async Task InitializeAsync() - { - _output.WriteLine("Initializing enhanced AWS test environment..."); - - // Create test environment using the factory - _testEnvironment = await AwsTestEnvironmentFactory.CreateLocalStackEnvironmentAsync("enhanced-test"); - - _output.WriteLine($"Test environment initialized (LocalStack: {_testEnvironment.IsLocalEmulator})"); - } - - public async Task DisposeAsync() - { - if (_testEnvironment != null) - { - _output.WriteLine("Disposing test environment..."); - await _testEnvironment.DisposeAsync(); - } - } - - [Fact] - public async Task TestEnvironment_ShouldBeAvailable() - { - // Arrange & Act - var isAvailable = await _testEnvironment!.IsAvailableAsync(); - - // Assert - Assert.True(isAvailable, "Test environment should be available"); - _output.WriteLine("✓ Test environment is available"); - } - - [Fact] - public async Task TestEnvironment_ShouldProvideAwsClients() - { - // Arrange & Act & Assert - Assert.NotNull(_testEnvironment!.SqsClient); - Assert.NotNull(_testEnvironment.SnsClient); - Assert.NotNull(_testEnvironment.KmsClient); - Assert.NotNull(_testEnvironment.IamClient); - - _output.WriteLine("✓ All AWS clients are available"); - } - - [Fact] - public async Task CreateFifoQueue_ShouldCreateQueueSuccessfully() - { - // Arrange - var queueName = "test-fifo-queue"; - - // Act - var queueUrl = await _testEnvironment!.CreateFifoQueueAsync(queueName); - - // Assert - Assert.NotNull(queueUrl); - Assert.NotEmpty(queueUrl); - Assert.Contains(".fifo", queueUrl); - - _output.WriteLine($"✓ Created FIFO queue: {queueUrl}"); - - // Cleanup - await _testEnvironment.DeleteQueueAsync(queueUrl); - _output.WriteLine("✓ Cleaned up FIFO queue"); - } - - [Fact] - public async Task CreateStandardQueue_ShouldCreateQueueSuccessfully() - { - // Arrange - var queueName = "test-standard-queue"; - - // Act - var queueUrl = await _testEnvironment!.CreateStandardQueueAsync(queueName); - - // Assert - Assert.NotNull(queueUrl); - Assert.NotEmpty(queueUrl); - Assert.DoesNotContain(".fifo", queueUrl); - - _output.WriteLine($"✓ Created standard queue: {queueUrl}"); - - // Cleanup - await _testEnvironment.DeleteQueueAsync(queueUrl); - _output.WriteLine("✓ Cleaned up standard queue"); - } - - [Fact] - public async Task CreateTopic_ShouldCreateTopicSuccessfully() - { - // Arrange - var topicName = "test-topic"; - - // Act - var topicArn = await _testEnvironment!.CreateTopicAsync(topicName); - - // Assert - Assert.NotNull(topicArn); - Assert.NotEmpty(topicArn); - Assert.Contains(topicName, topicArn); - - _output.WriteLine($"✓ Created SNS topic: {topicArn}"); - - // Cleanup - await _testEnvironment.DeleteTopicAsync(topicArn); - _output.WriteLine("✓ Cleaned up SNS topic"); - } - - [Fact] - public async Task GetHealthStatus_ShouldReturnHealthForAllServices() - { - // Act - var healthStatus = await _testEnvironment!.GetHealthStatusAsync(); - - // Assert - Assert.NotNull(healthStatus); - Assert.True(healthStatus.Count > 0, "Should have health status for at least one service"); - - foreach (var service in healthStatus) - { - _output.WriteLine($"Service: {service.Key}, Available: {service.Value.IsAvailable}, Response Time: {service.Value.ResponseTime.TotalMilliseconds}ms"); - } - - // At least SQS should be available - Assert.True(healthStatus.ContainsKey("sqs"), "Should have SQS health status"); - _output.WriteLine("✓ Health status retrieved for all services"); - } - - [Fact] - public async Task CreateTestServices_ShouldReturnConfiguredServiceCollection() - { - // Act - var services = _testEnvironment!.CreateTestServices(); - - // Assert - Assert.NotNull(services); - - // Build service provider to verify services are registered - var serviceProvider = services.BuildServiceProvider(); - - // Verify AWS clients are registered - var sqsClient = serviceProvider.GetService(); - var snsClient = serviceProvider.GetService(); - - Assert.NotNull(sqsClient); - Assert.NotNull(snsClient); - - _output.WriteLine("✓ Test services collection created and configured correctly"); - } - - [Fact] - public async Task TestScenarioRunner_ShouldRunBasicSqsScenario() - { - // Arrange - var services = AwsTestEnvironmentFactory.CreateTestServiceCollection(_testEnvironment!); - var serviceProvider = services.BuildServiceProvider(); - var scenarioRunner = serviceProvider.GetRequiredService(); - - // Act - var result = await scenarioRunner.RunSqsBasicScenarioAsync(); - - // Assert - Assert.True(result, "Basic SQS scenario should succeed"); - _output.WriteLine("✓ Basic SQS scenario completed successfully"); - } - - [Fact] - public async Task TestScenarioRunner_ShouldRunBasicSnsScenario() - { - // Arrange - var services = AwsTestEnvironmentFactory.CreateTestServiceCollection(_testEnvironment!); - var serviceProvider = services.BuildServiceProvider(); - var scenarioRunner = serviceProvider.GetRequiredService(); - - // Act - var result = await scenarioRunner.RunSnsBasicScenarioAsync(); - - // Assert - Assert.True(result, "Basic SNS scenario should succeed"); - _output.WriteLine("✓ Basic SNS scenario completed successfully"); - } - - [Fact] - public async Task PerformanceTestRunner_ShouldMeasureSqsThroughput() - { - // Arrange - var services = AwsTestEnvironmentFactory.CreateTestServiceCollection(_testEnvironment!); - var serviceProvider = services.BuildServiceProvider(); - var performanceRunner = serviceProvider.GetRequiredService(); - - // Act - var result = await performanceRunner.RunSqsThroughputTestAsync(messageCount: 10, messageSize: 512); - - // Assert - Assert.NotNull(result); - Assert.True(result.TotalDuration > TimeSpan.Zero, "Test should take some time"); - Assert.True(result.OperationsPerSecond > 0, "Should have positive throughput"); - Assert.Equal(10, result.Iterations); - - _output.WriteLine($"✓ SQS throughput test: {result.OperationsPerSecond:F2} ops/sec, Duration: {result.TotalDuration.TotalMilliseconds}ms"); - } - - [Fact] - public async Task TestEnvironmentBuilder_ShouldCreateCustomEnvironment() - { - // Arrange & Act - var customEnvironment = await AwsTestEnvironmentFactory.CreateBuilder() - .UseLocalStack(true) - .EnableIntegrationTests(true) - .EnablePerformanceTests(false) - .ConfigureLocalStack(config => - { - config.Debug = true; - config.EnabledServices = new List { "sqs", "sns" }; - }) - .WithTestPrefix("custom-test") - .BuildAsync(); - - try - { - // Assert - Assert.NotNull(customEnvironment); - Assert.True(customEnvironment.IsLocalEmulator); - - var isAvailable = await customEnvironment.IsAvailableAsync(); - Assert.True(isAvailable); - - _output.WriteLine("✓ Custom test environment created successfully using builder pattern"); - } - finally - { - await customEnvironment.DisposeAsync(); - } - } -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/Integration/EnhancedLocalStackManagerTests.cs b/tests/SourceFlow.Cloud.AWS.Tests/Integration/EnhancedLocalStackManagerTests.cs deleted file mode 100644 index 03b4de80..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/Integration/EnhancedLocalStackManagerTests.cs +++ /dev/null @@ -1,365 +0,0 @@ -using System.Linq; -using Microsoft.Extensions.Logging; -using SourceFlow.Cloud.AWS.Tests.TestHelpers; -using Amazon.SQS; -using Amazon.SimpleNotificationService; -using Amazon.KeyManagementService; -using Amazon.IdentityManagement; -using LocalStackConfig = SourceFlow.Cloud.AWS.Tests.TestHelpers.LocalStackConfiguration; - -namespace SourceFlow.Cloud.AWS.Tests.Integration; - -/// -/// Integration tests for the enhanced LocalStack manager -/// Validates full AWS service emulation with comprehensive container management -/// -[Collection("AWS Integration Tests")] -[Trait("Category", "Integration")] -[Trait("Category", "RequiresLocalStack")] -public class EnhancedLocalStackManagerTests : IAsyncDisposable -{ - private readonly ILogger _logger; - private readonly LocalStackManager _localStackManager; - - public EnhancedLocalStackManagerTests() - { - var loggerFactory = LoggerFactory.Create(builder => builder.AddConsole().SetMinimumLevel(LogLevel.Debug)); - _logger = loggerFactory.CreateLogger(); - _localStackManager = new LocalStackManager(_logger); - } - - [Fact] - public async Task StartAsync_WithDefaultConfiguration_ShouldStartSuccessfully() - { - // Arrange - var config = LocalStackConfig.CreateDefault(); - - // Act - await _localStackManager.StartAsync(config); - - // Assert - Assert.True(_localStackManager.IsRunning); - Assert.NotNull(_localStackManager.Endpoint); - Assert.Contains("localhost", _localStackManager.Endpoint); - } - - [Fact] - public async Task StartAsync_WithPortConflict_ShouldUseAlternativePort() - { - // Arrange - var config = LocalStackConfig.CreateDefault(); - config.Port = 4566; // Standard LocalStack port - - // Act - await _localStackManager.StartAsync(config); - - // Assert - Assert.True(_localStackManager.IsRunning); - // Port might be different if 4566 was already in use - Assert.NotNull(_localStackManager.Endpoint); - } - - [Fact] - public async Task WaitForServicesAsync_WithAllServices_ShouldCompleteSuccessfully() - { - // Arrange - var config = LocalStackConfig.CreateForIntegrationTesting(); - await _localStackManager.StartAsync(config); - - // Act & Assert - Should not throw - // IAM is lazily initialized in LocalStack Community and won't appear in health endpoint until first use - await _localStackManager.WaitForServicesAsync( - new[] { "sqs", "sns", "kms" }, - TimeSpan.FromMinutes(2)); - } - - [Fact] - public async Task IsServiceAvailableAsync_ForEachEnabledService_ShouldReturnTrue() - { - // Arrange - var config = LocalStackConfig.CreateDefault(); - await _localStackManager.StartAsync(config); - // IAM is lazily initialized in LocalStack Community — only wait for core services - await _localStackManager.WaitForServicesAsync(config.EnabledServices.Where(s => s != "iam").ToArray()); - - // Act & Assert (skip iam — lazily initialized in LocalStack Community) - foreach (var service in config.EnabledServices.Where(s => s != "iam")) - { - var isAvailable = await _localStackManager.IsServiceAvailableAsync(service); - Assert.True(isAvailable, $"Service {service} should be available"); - } - } - - [Fact] - public async Task GetServicesHealthAsync_ShouldReturnHealthStatusForAllServices() - { - // Arrange - var config = LocalStackConfig.CreateDefault(); - await _localStackManager.StartAsync(config); - // IAM is lazily initialized in LocalStack Community — only wait for core services - await _localStackManager.WaitForServicesAsync(config.EnabledServices.Where(s => s != "iam").ToArray()); - - // Act - var healthStatus = await _localStackManager.GetServicesHealthAsync(); - - // Assert - Assert.NotEmpty(healthStatus); - // Skip iam — lazily initialized in LocalStack Community - foreach (var service in config.EnabledServices.Where(s => s != "iam")) - { - Assert.True(healthStatus.ContainsKey(service), $"Health status should contain {service}"); - Assert.True(healthStatus[service].IsAvailable, $"Service {service} should be available"); - Assert.True(healthStatus[service].ResponseTime > TimeSpan.Zero, $"Service {service} should have response time"); - } - } - - [Fact] - public async Task ValidateAwsServices_SqsService_ShouldAllowBasicOperations() - { - // Arrange - var config = LocalStackConfig.CreateDefault(); - await _localStackManager.StartAsync(config); - await _localStackManager.WaitForServicesAsync(new[] { "sqs" }); - - var sqsClient = new AmazonSQSClient("test", "test", new AmazonSQSConfig - { - ServiceURL = _localStackManager.Endpoint, - UseHttp = true, - AuthenticationRegion = "us-east-1" - }); - - // Act & Assert - // Should be able to list queues - var listResponse = await sqsClient.ListQueuesAsync(new Amazon.SQS.Model.ListQueuesRequest()); - Assert.NotNull(listResponse); - - // Should be able to create a queue - var queueName = $"test-queue-{Guid.NewGuid():N}"; - var createResponse = await sqsClient.CreateQueueAsync(queueName); - Assert.NotNull(createResponse.QueueUrl); - - // Should be able to send a message - var sendResponse = await sqsClient.SendMessageAsync(createResponse.QueueUrl, "test message"); - Assert.NotNull(sendResponse.MessageId); - - // Should be able to receive the message - var receiveResponse = await sqsClient.ReceiveMessageAsync(createResponse.QueueUrl); - Assert.NotEmpty(receiveResponse.Messages); - Assert.Equal("test message", receiveResponse.Messages[0].Body); - - // Cleanup - await sqsClient.DeleteQueueAsync(createResponse.QueueUrl); - } - - [Fact] - public async Task ValidateAwsServices_SnsService_ShouldAllowBasicOperations() - { - // Arrange - var config = LocalStackConfig.CreateDefault(); - await _localStackManager.StartAsync(config); - await _localStackManager.WaitForServicesAsync(new[] { "sns" }); - - var snsClient = new AmazonSimpleNotificationServiceClient("test", "test", new AmazonSimpleNotificationServiceConfig - { - ServiceURL = _localStackManager.Endpoint, - UseHttp = true, - AuthenticationRegion = "us-east-1" - }); - - // Act & Assert - // Should be able to list topics - var listResponse = await snsClient.ListTopicsAsync(); - Assert.NotNull(listResponse); - - // Should be able to create a topic - var topicName = $"test-topic-{Guid.NewGuid():N}"; - var createResponse = await snsClient.CreateTopicAsync(topicName); - Assert.NotNull(createResponse.TopicArn); - - // Should be able to publish a message - var publishResponse = await snsClient.PublishAsync(createResponse.TopicArn, "test message"); - Assert.NotNull(publishResponse.MessageId); - - // Cleanup - await snsClient.DeleteTopicAsync(createResponse.TopicArn); - } - - [Fact] - public async Task ValidateAwsServices_KmsService_ShouldAllowBasicOperations() - { - // Arrange - var config = LocalStackConfig.CreateDefault(); - await _localStackManager.StartAsync(config); - await _localStackManager.WaitForServicesAsync(new[] { "kms" }); - - var kmsClient = new AmazonKeyManagementServiceClient("test", "test", new AmazonKeyManagementServiceConfig - { - ServiceURL = _localStackManager.Endpoint, - UseHttp = true, - AuthenticationRegion = "us-east-1" - }); - - // Act & Assert - // Should be able to list keys - var listResponse = await kmsClient.ListKeysAsync(new Amazon.KeyManagementService.Model.ListKeysRequest()); - Assert.NotNull(listResponse); - - // Should be able to create a key - var createResponse = await kmsClient.CreateKeyAsync(new Amazon.KeyManagementService.Model.CreateKeyRequest - { - Description = "Test key for LocalStack validation" - }); - Assert.NotNull(createResponse.KeyMetadata.KeyId); - - // Should be able to encrypt/decrypt data - var plaintext = System.Text.Encoding.UTF8.GetBytes("test data"); - var encryptResponse = await kmsClient.EncryptAsync(new Amazon.KeyManagementService.Model.EncryptRequest - { - KeyId = createResponse.KeyMetadata.KeyId, - Plaintext = new MemoryStream(plaintext) - }); - Assert.NotNull(encryptResponse.CiphertextBlob); - - var decryptResponse = await kmsClient.DecryptAsync(new Amazon.KeyManagementService.Model.DecryptRequest - { - CiphertextBlob = encryptResponse.CiphertextBlob - }); - var decryptedText = System.Text.Encoding.UTF8.GetString(decryptResponse.Plaintext.ToArray()); - Assert.Equal("test data", decryptedText); - } - - [Fact] - public async Task ValidateAwsServices_IamService_ShouldAllowBasicOperations() - { - // IAM is disabled/lazily initialized in LocalStack Community Edition - // Skip this test when running against LocalStack Community - var config = LocalStackConfig.CreateDefault(); - await _localStackManager.StartAsync(config); - - var health = await _localStackManager.GetServicesHealthAsync(); - if (!health.ContainsKey("iam") || !health["iam"].IsAvailable) - return; // Skip — IAM not available in this LocalStack edition - - var iamClient = new AmazonIdentityManagementServiceClient("test", "test", new AmazonIdentityManagementServiceConfig - { - ServiceURL = _localStackManager.Endpoint, - UseHttp = true, - AuthenticationRegion = "us-east-1" - }); - - // Act & Assert - // Should be able to list roles - var listResponse = await iamClient.ListRolesAsync(); - Assert.NotNull(listResponse); - - // Should be able to create a role - var roleName = $"test-role-{Guid.NewGuid():N}"; - var assumeRolePolicyDocument = @"{ - ""Version"": ""2012-10-17"", - ""Statement"": [ - { - ""Effect"": ""Allow"", - ""Principal"": { - ""Service"": ""lambda.amazonaws.com"" - }, - ""Action"": ""sts:AssumeRole"" - } - ] - }"; - - var createResponse = await iamClient.CreateRoleAsync(new Amazon.IdentityManagement.Model.CreateRoleRequest - { - RoleName = roleName, - AssumeRolePolicyDocument = assumeRolePolicyDocument - }); - Assert.NotNull(createResponse.Role.Arn); - - // Cleanup - await iamClient.DeleteRoleAsync(new Amazon.IdentityManagement.Model.DeleteRoleRequest - { - RoleName = roleName - }); - } - - [Fact] - public async Task GetLogsAsync_ShouldReturnContainerLogs() - { - // Arrange - var config = LocalStackConfig.CreateWithDiagnostics(); - await _localStackManager.StartAsync(config); - - // Act - var logs = await _localStackManager.GetLogsAsync(50); - - // Assert - Assert.NotNull(logs); - Assert.NotEmpty(logs); - // When using an external LocalStack instance, no container logs are available - if (!logs.Contains("Container not available", StringComparison.OrdinalIgnoreCase)) - { - Assert.Contains("LocalStack", logs, StringComparison.OrdinalIgnoreCase); - } - } - - [Fact] - public async Task ResetDataAsync_ShouldClearAllData() - { - // Arrange - var config = LocalStackConfig.CreateDefault(); - await _localStackManager.StartAsync(config); - await _localStackManager.WaitForServicesAsync(new[] { "sqs" }); - - var sqsClient = new AmazonSQSClient("test", "test", new AmazonSQSConfig - { - ServiceURL = _localStackManager.Endpoint, - UseHttp = true, - AuthenticationRegion = "us-east-1" - }); - - // Create a queue - var queueName = $"test-queue-{Guid.NewGuid():N}"; - var createResponse = await sqsClient.CreateQueueAsync(queueName); - - // Verify queue exists - var listBefore = await sqsClient.ListQueuesAsync(new Amazon.SQS.Model.ListQueuesRequest()); - Assert.Contains(createResponse.QueueUrl, listBefore.QueueUrls); - - // Act - await _localStackManager.ResetDataAsync(); - // IAM is lazily initialized in LocalStack Community — only wait for core services - await _localStackManager.WaitForServicesAsync(config.EnabledServices.Where(s => s != "iam").ToArray()); - - // Assert - Queue should be gone after reset (for managed containers) - // For external instances, the state reset API may not clear all resources - var listAfter = await sqsClient.ListQueuesAsync(new Amazon.SQS.Model.ListQueuesRequest()); - if (!_localStackManager.IsRunning || listAfter.QueueUrls.Contains(createResponse.QueueUrl)) - { - // External instance reset may not clear all state — just verify reset didn't crash - Assert.NotNull(listAfter); - } - else - { - Assert.DoesNotContain(createResponse.QueueUrl, listAfter.QueueUrls); - } - } - - [Fact] - public async Task StopAsync_ShouldStopContainerCleanly() - { - // Arrange - var config = LocalStackConfig.CreateDefault(); - await _localStackManager.StartAsync(config); - Assert.True(_localStackManager.IsRunning); - - // Act - await _localStackManager.StopAsync(); - - // Assert - Assert.False(_localStackManager.IsRunning); - } - - public async ValueTask DisposeAsync() - { - await _localStackManager.DisposeAsync(); - } -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/Integration/KmsEncryptionIntegrationTests.cs b/tests/SourceFlow.Cloud.AWS.Tests/Integration/KmsEncryptionIntegrationTests.cs deleted file mode 100644 index e69de29b..00000000 diff --git a/tests/SourceFlow.Cloud.AWS.Tests/Integration/KmsEncryptionRoundTripPropertyTests.cs b/tests/SourceFlow.Cloud.AWS.Tests/Integration/KmsEncryptionRoundTripPropertyTests.cs deleted file mode 100644 index b93a95d3..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/Integration/KmsEncryptionRoundTripPropertyTests.cs +++ /dev/null @@ -1,436 +0,0 @@ -using Amazon.KeyManagementService; -using Amazon.KeyManagementService.Model; -using FsCheck; -using FsCheck.Xunit; -using Microsoft.Extensions.Caching.Memory; -using Microsoft.Extensions.Logging; -using SourceFlow.Cloud.AWS.Security; -using SourceFlow.Cloud.AWS.Tests.TestHelpers; -using System.Text; -using System.Text.Json; - -namespace SourceFlow.Cloud.AWS.Tests.Integration; - -/// -/// Property-based tests for KMS encryption round-trip consistency -/// Validates universal properties that should hold across all KMS encryption operations -/// -[Collection("AWS Integration Tests")] -[Trait("Category", "Integration")] -[Trait("Category", "RequiresLocalStack")] -public class KmsEncryptionRoundTripPropertyTests : IClassFixture, IAsyncDisposable -{ - private readonly LocalStackTestFixture _localStack; - private readonly List _createdKeyIds = new(); - private readonly ILogger _logger; - private readonly IMemoryCache _memoryCache; - - public KmsEncryptionRoundTripPropertyTests(LocalStackTestFixture localStack) - { - _localStack = localStack; - - // Create logger for tests - var loggerFactory = LoggerFactory.Create(builder => builder.AddConsole().SetMinimumLevel(LogLevel.Debug)); - _logger = loggerFactory.CreateLogger(); - - // Create memory cache for encryption tests - _memoryCache = new MemoryCache(new MemoryCacheOptions()); - } - - /// - /// Property 5: KMS Encryption Round-Trip Consistency - /// For any message containing sensitive data, when encrypted using AWS KMS and then decrypted, - /// the resulting message should be identical to the original message with all sensitive data - /// properly protected. - /// **Validates: Requirements 3.1** - /// - [Property(MaxTest = 100, Arbitrary = new[] { typeof(KmsEncryptionGenerators) })] - // FsCheck 2.x does not support async Task properties — method must be void - public void Property_KmsEncryptionRoundTripConsistency(KmsTestMessage message) => - Property_KmsEncryptionRoundTripConsistencyAsync(message).GetAwaiter().GetResult(); - - private async Task Property_KmsEncryptionRoundTripConsistencyAsync(KmsTestMessage message) - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.KmsClient == null) - { - return; - } - - // Skip invalid messages - if (message == null || string.IsNullOrEmpty(message.Content)) - { - return; - } - - // Arrange - Create KMS key for this test - var keyId = await CreateKmsKeyAsync($"prop-test-{Guid.NewGuid():N}"); - var encryption = CreateEncryptionService(keyId); - - try - { - // Act - Encrypt the message - var ciphertext = await encryption.EncryptAsync(message.Content); - - // Assert - Ciphertext should be different from plaintext - AssertEncryptionProducedCiphertext(message.Content, ciphertext); - - // Act - Decrypt the ciphertext - var decrypted = await encryption.DecryptAsync(ciphertext); - - // Assert - Round-trip consistency: decrypted should match original - AssertRoundTripConsistency(message.Content, decrypted); - - // Assert - Encryption should be deterministic for same input (different ciphertext each time) - await AssertEncryptionNonDeterminism(encryption, message.Content); - - // Assert - Sensitive data protection (ciphertext should not contain plaintext) - AssertSensitiveDataProtection(message.Content, ciphertext, message.SensitiveFields); - - // Assert - Encryption performance should be reasonable - await AssertEncryptionPerformance(encryption, message); - } - finally - { - // Cleanup is handled in DisposeAsync - } - } - - /// - /// Assert that encryption produced valid ciphertext - /// - private static void AssertEncryptionProducedCiphertext(string plaintext, string ciphertext) - { - // Ciphertext should not be null or empty - Assert.NotNull(ciphertext); - Assert.NotEmpty(ciphertext); - - // Ciphertext should be different from plaintext - Assert.NotEqual(plaintext, ciphertext); - - // Ciphertext should be base64 encoded (AWS KMS returns base64) - Assert.True(IsBase64String(ciphertext), "Ciphertext should be base64 encoded"); - - // Ciphertext should be longer than plaintext (due to encryption overhead) - // Note: This may not always be true for very short plaintexts with compression - if (plaintext.Length > 10) - { - Assert.True(ciphertext.Length > plaintext.Length * 0.5, - "Ciphertext should have reasonable length relative to plaintext"); - } - } - - /// - /// Assert round-trip consistency: decrypt(encrypt(plaintext)) == plaintext - /// - private static void AssertRoundTripConsistency(string original, string decrypted) - { - // Decrypted text should match original exactly - Assert.Equal(original, decrypted); - - // Length should match - Assert.Equal(original.Length, decrypted.Length); - - // Character-by-character comparison for Unicode safety - for (int i = 0; i < original.Length; i++) - { - Assert.Equal(original[i], decrypted[i]); - } - - // Byte-level comparison for complete accuracy - var originalBytes = Encoding.UTF8.GetBytes(original); - var decryptedBytes = Encoding.UTF8.GetBytes(decrypted); - Assert.Equal(originalBytes, decryptedBytes); - } - - /// - /// Assert that encryption is non-deterministic (produces different ciphertext for same plaintext) - /// - private static async Task AssertEncryptionNonDeterminism(AwsKmsMessageEncryption encryption, string plaintext) - { - // Encrypt the same message multiple times - var ciphertext1 = await encryption.EncryptAsync(plaintext); - var ciphertext2 = await encryption.EncryptAsync(plaintext); - var ciphertext3 = await encryption.EncryptAsync(plaintext); - - // Each encryption should produce different ciphertext (due to random nonce/IV) - Assert.NotEqual(ciphertext1, ciphertext2); - Assert.NotEqual(ciphertext2, ciphertext3); - Assert.NotEqual(ciphertext1, ciphertext3); - - // But all should decrypt to the same plaintext - var decrypted1 = await encryption.DecryptAsync(ciphertext1); - var decrypted2 = await encryption.DecryptAsync(ciphertext2); - var decrypted3 = await encryption.DecryptAsync(ciphertext3); - - Assert.Equal(plaintext, decrypted1); - Assert.Equal(plaintext, decrypted2); - Assert.Equal(plaintext, decrypted3); - } - - /// - /// Assert that sensitive data is protected (not visible in ciphertext) - /// - private static void AssertSensitiveDataProtection(string plaintext, string ciphertext, List sensitiveFields) - { - // Ciphertext should not contain plaintext substrings - if (plaintext.Length > 10) - { - // Check that no significant substring of plaintext appears in ciphertext - var substringLength = Math.Min(10, plaintext.Length / 2); - for (int i = 0; i <= plaintext.Length - substringLength; i++) - { - var substring = plaintext.Substring(i, substringLength); - Assert.DoesNotContain(substring, ciphertext); - } - } - - // Sensitive fields should not appear in ciphertext - foreach (var sensitiveField in sensitiveFields) - { - if (!string.IsNullOrEmpty(sensitiveField) && sensitiveField.Length > 3) - { - Assert.DoesNotContain(sensitiveField, ciphertext, StringComparison.OrdinalIgnoreCase); - } - } - } - - /// - /// Assert that encryption performance is reasonable - /// - private static async Task AssertEncryptionPerformance(AwsKmsMessageEncryption encryption, KmsTestMessage message) - { - var iterations = 5; - var encryptionTimes = new List(); - var decryptionTimes = new List(); - - for (int i = 0; i < iterations; i++) - { - // Measure encryption time - var encryptStart = DateTime.UtcNow; - var ciphertext = await encryption.EncryptAsync(message.Content); - var encryptEnd = DateTime.UtcNow; - encryptionTimes.Add(encryptEnd - encryptStart); - - // Measure decryption time - var decryptStart = DateTime.UtcNow; - await encryption.DecryptAsync(ciphertext); - var decryptEnd = DateTime.UtcNow; - decryptionTimes.Add(decryptEnd - decryptStart); - } - - // Average encryption time should be reasonable (< 5 seconds for LocalStack, < 1 second for real AWS) - var avgEncryptionTime = encryptionTimes.Average(t => t.TotalMilliseconds); - Assert.True(avgEncryptionTime < 5000, - $"Average encryption time ({avgEncryptionTime}ms) should be less than 5000ms"); - - // Average decryption time should be reasonable - var avgDecryptionTime = decryptionTimes.Average(t => t.TotalMilliseconds); - Assert.True(avgDecryptionTime < 5000, - $"Average decryption time ({avgDecryptionTime}ms) should be less than 5000ms"); - - // Encryption should not be instantaneous (indicates potential issue) - Assert.True(avgEncryptionTime > 0, "Encryption should take measurable time"); - Assert.True(avgDecryptionTime > 0, "Decryption should take measurable time"); - } - - /// - /// Check if a string is valid base64 - /// - private static bool IsBase64String(string value) - { - if (string.IsNullOrEmpty(value)) - return false; - - try - { - Convert.FromBase64String(value); - return true; - } - catch - { - return false; - } - } - - /// - /// Create a KMS key for testing - /// - private async Task CreateKmsKeyAsync(string keyAlias) - { - try - { - var createKeyResponse = await _localStack.KmsClient.CreateKeyAsync(new CreateKeyRequest - { - Description = $"Test key for property-based testing: {keyAlias}", - KeyUsage = KeyUsageType.ENCRYPT_DECRYPT, - Origin = OriginType.AWS_KMS - }); - - var keyId = createKeyResponse.KeyMetadata.KeyId; - _createdKeyIds.Add(keyId); - - // Create alias for the key - try - { - await _localStack.KmsClient.CreateAliasAsync(new CreateAliasRequest - { - AliasName = $"alias/{keyAlias}", - TargetKeyId = keyId - }); - } - catch (Exception) - { - // Alias creation might fail in LocalStack, continue without it - } - - return keyId; - } - catch (Exception ex) - { - _logger.LogError(ex, "Failed to create KMS key: {KeyAlias}", keyAlias); - throw; - } - } - - /// - /// Create encryption service for testing - /// - private AwsKmsMessageEncryption CreateEncryptionService(string keyId) - { - var options = new AwsKmsOptions - { - MasterKeyId = keyId, - CacheDataKeySeconds = 0 // Disable caching for tests - }; - - // Create a logger with the correct type - var loggerFactory = LoggerFactory.Create(builder => builder.AddConsole().SetMinimumLevel(LogLevel.Debug)); - var encryptionLogger = loggerFactory.CreateLogger(); - - return new AwsKmsMessageEncryption( - _localStack.KmsClient, - encryptionLogger, - _memoryCache, - options); - } - - /// - /// Clean up created KMS keys - /// - public async ValueTask DisposeAsync() - { - if (_localStack.KmsClient != null) - { - foreach (var keyId in _createdKeyIds) - { - try - { - // Schedule key deletion (minimum 7 days for real AWS, immediate for LocalStack) - await _localStack.KmsClient.ScheduleKeyDeletionAsync(new ScheduleKeyDeletionRequest - { - KeyId = keyId, - PendingWindowInDays = 7 - }); - } - catch (Exception) - { - // Ignore cleanup errors - } - } - } - - _createdKeyIds.Clear(); - _memoryCache?.Dispose(); - } -} - -/// -/// FsCheck generators for KMS encryption property tests -/// -public static class KmsEncryptionGenerators -{ - /// - /// Generate test messages for KMS encryption - /// - public static Arbitrary KmsTestMessage() - { - var contentGen = Gen.OneOf( - // Simple strings - Gen.Elements("Hello, World!", "Test message", "Simple text"), - - // Empty and whitespace - Gen.Elements("", " ", " ", "\t", "\n"), - - // Special characters - Gen.Elements("!@#$%^&*()_+-=[]{}|;':\",./<>?`~", "Line1\nLine2\rLine3\r\n", "\0\t\n\r"), - - // Unicode characters - Gen.Elements("你好世界", "Привет мир", "مرحبا بالعالم", "🌍🌎🌏", "Ñoño Café"), - - // JSON-like content - Gen.Elements("{\"key\":\"value\"}", "[1,2,3]", "{\"nested\":{\"data\":true}}"), - - // Large content - from size in Gen.Choose(100, 10000) - from c in Gen.Elements('A', 'B', 'C', '1', '2', '3', ' ', '\n') - select new string(c, size), - - // Random alphanumeric - from length in Gen.Choose(1, 1000) - from chars in Gen.ArrayOf(length, Gen.Elements( - "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789 ".ToCharArray())) - select new string(chars), - - // Mixed content with sensitive data patterns - from ssn in Gen.Choose(100000000, 999999999) - from ccn in Gen.Choose(1000000000, 1999999999) // Use int range instead of long - from email in Gen.Elements("user@example.com", "test@test.com", "admin@domain.org") - select $"SSN: {ssn}, Credit Card: {ccn}, Email: {email}" - ); - - var sensitiveFieldsGen = Gen.ListOf(Gen.Elements( - "password", "ssn", "credit_card", "api_key", "secret", "token", - "email", "phone", "address", "account_number" - )); - - var messageGen = from content in contentGen - from sensitiveFields in sensitiveFieldsGen - from messageType in Gen.Elements( - KmsMessageType.PlainText, - KmsMessageType.Json, - KmsMessageType.Binary, - KmsMessageType.Structured) - select new KmsTestMessage - { - Content = content ?? "", - SensitiveFields = sensitiveFields.Distinct().ToList(), - MessageType = messageType, - Timestamp = DateTime.UtcNow - }; - - return Arb.From(messageGen); - } -} - -/// -/// Test message for KMS encryption property tests -/// -public class KmsTestMessage -{ - public string Content { get; set; } = ""; - public List SensitiveFields { get; set; } = new(); - public KmsMessageType MessageType { get; set; } - public DateTime Timestamp { get; set; } -} - -/// -/// Message type enumeration for KMS tests -/// -public enum KmsMessageType -{ - PlainText, - Json, - Binary, - Structured -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/Integration/KmsKeyRotationIntegrationTests.cs b/tests/SourceFlow.Cloud.AWS.Tests/Integration/KmsKeyRotationIntegrationTests.cs deleted file mode 100644 index e69de29b..00000000 diff --git a/tests/SourceFlow.Cloud.AWS.Tests/Integration/KmsKeyRotationPropertyTests.cs b/tests/SourceFlow.Cloud.AWS.Tests/Integration/KmsKeyRotationPropertyTests.cs deleted file mode 100644 index e2bb9136..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/Integration/KmsKeyRotationPropertyTests.cs +++ /dev/null @@ -1,580 +0,0 @@ -using Amazon.KeyManagementService; -using Amazon.KeyManagementService.Model; -using FsCheck; -using FsCheck.Xunit; -using Microsoft.Extensions.Caching.Memory; -using Microsoft.Extensions.Logging; -using SourceFlow.Cloud.AWS.Security; -using SourceFlow.Cloud.AWS.Tests.TestHelpers; -using System.Collections.Concurrent; -using System.Diagnostics; -using System.Text; - -namespace SourceFlow.Cloud.AWS.Tests.Integration; - -/// -/// Property-based tests for KMS key rotation seamlessness -/// Validates that key rotation happens without service interruption and maintains backward compatibility -/// **Feature: aws-cloud-integration-testing, Property 6: KMS Key Rotation Seamlessness** -/// -[Collection("AWS Integration Tests")] -[Trait("Category", "Integration")] -[Trait("Category", "RequiresLocalStack")] -public class KmsKeyRotationPropertyTests : IClassFixture, IAsyncDisposable -{ - private readonly LocalStackTestFixture _localStack; - private readonly List _createdKeyIds = new(); - private readonly ILogger _logger; - private readonly IMemoryCache _memoryCache; - - public KmsKeyRotationPropertyTests(LocalStackTestFixture localStack) - { - _localStack = localStack; - - // Create logger for tests - var loggerFactory = LoggerFactory.Create(builder => builder.AddConsole().SetMinimumLevel(LogLevel.Debug)); - _logger = loggerFactory.CreateLogger(); - - // Create memory cache for encryption tests - _memoryCache = new MemoryCache(new MemoryCacheOptions()); - } - - /// - /// Property 6: KMS Key Rotation Seamlessness - /// For any encrypted message flow, when KMS keys are rotated, existing messages should continue - /// to be decryptable using the old key version and new messages should use the new key without - /// service interruption. - /// **Validates: Requirements 3.2** - /// - [Property(MaxTest = 100, Arbitrary = new[] { typeof(KeyRotationGenerators) })] - // FsCheck 2.x does not support async Task properties — method must be void - public void Property_KmsKeyRotationSeamlessness(KeyRotationScenario scenario) => - Property_KmsKeyRotationSeamlessnessAsync(scenario).GetAwaiter().GetResult(); - - private async Task Property_KmsKeyRotationSeamlessnessAsync(KeyRotationScenario scenario) - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.KmsClient == null) - { - return; - } - - // Skip invalid scenarios - if (scenario == null || scenario.MessageBatches == null || scenario.MessageBatches.Count == 0) - { - return; - } - - // Arrange - Create initial KMS key - var keyId = await CreateKmsKeyAsync($"rotation-test-{Guid.NewGuid():N}"); - var encryption = CreateEncryptionService(keyId); - - // Track encrypted messages with their key versions - var encryptedMessages = new ConcurrentBag(); - var decryptionErrors = new ConcurrentBag(); - - try - { - // Phase 1: Encrypt messages with original key - _logger.LogInformation("Phase 1: Encrypting {Count} messages with original key", - scenario.MessageBatches[0].Messages.Count); - - await EncryptMessageBatch(encryption, scenario.MessageBatches[0], encryptedMessages, "original"); - - // Assert: All messages should be encrypted successfully - Assert.True(encryptedMessages.Count == scenario.MessageBatches[0].Messages.Count, - $"Expected {scenario.MessageBatches[0].Messages.Count} encrypted messages, got {encryptedMessages.Count}"); - - // Phase 2: Simulate key rotation - _logger.LogInformation("Phase 2: Simulating key rotation"); - - // In LocalStack, we simulate rotation by creating a new key version - // In real AWS, this would be EnableKeyRotation, but LocalStack doesn't fully support it - var rotatedKeyId = await SimulateKeyRotation(keyId); - var rotatedEncryption = CreateEncryptionService(rotatedKeyId); - - // Phase 3: Verify old messages are still decryptable (backward compatibility) - _logger.LogInformation("Phase 3: Verifying {Count} old messages are still decryptable", - encryptedMessages.Count); - - await VerifyMessagesDecryptable(encryption, encryptedMessages, decryptionErrors); - - // Assert: No decryption errors for old messages - Assert.Empty(decryptionErrors); - - // Phase 4: Encrypt new messages with rotated key (if scenario has multiple batches) - if (scenario.MessageBatches.Count > 1) - { - _logger.LogInformation("Phase 4: Encrypting {Count} new messages with rotated key", - scenario.MessageBatches[1].Messages.Count); - - var newEncryptedMessages = new ConcurrentBag(); - await EncryptMessageBatch(rotatedEncryption, scenario.MessageBatches[1], newEncryptedMessages, "rotated"); - - // Assert: New messages should be encrypted successfully - Assert.True(newEncryptedMessages.Count == scenario.MessageBatches[1].Messages.Count, - $"Expected {scenario.MessageBatches[1].Messages.Count} new encrypted messages, got {newEncryptedMessages.Count}"); - - // Phase 5: Verify new messages are decryptable - _logger.LogInformation("Phase 5: Verifying {Count} new messages are decryptable", - newEncryptedMessages.Count); - - var newDecryptionErrors = new ConcurrentBag(); - await VerifyMessagesDecryptable(rotatedEncryption, newEncryptedMessages, newDecryptionErrors); - - // Assert: No decryption errors for new messages - Assert.Empty(newDecryptionErrors); - - // Add new messages to the collection - foreach (var msg in newEncryptedMessages) - { - encryptedMessages.Add(msg); - } - } - - // Phase 6: Verify service continuity - no interruption during rotation - _logger.LogInformation("Phase 6: Verifying service continuity during rotation"); - - await VerifyServiceContinuity(encryption, rotatedEncryption, scenario); - - // Phase 7: Verify all messages (old and new) are still decryptable - _logger.LogInformation("Phase 7: Final verification - all {Count} messages decryptable", - encryptedMessages.Count); - - var finalDecryptionErrors = new ConcurrentBag(); - - // Try decrypting with both encryption services to verify backward compatibility - foreach (var record in encryptedMessages) - { - try - { - // Try with original encryption service - var decrypted = await encryption.DecryptAsync(record.Ciphertext); - Assert.Equal(record.Plaintext, decrypted); - } - catch (Exception ex) - { - // If original fails, try with rotated service - try - { - var decrypted = await rotatedEncryption.DecryptAsync(record.Ciphertext); - Assert.Equal(record.Plaintext, decrypted); - } - catch (Exception ex2) - { - finalDecryptionErrors.Add($"Failed to decrypt message with both keys: {ex.Message}, {ex2.Message}"); - } - } - } - - // Assert: No final decryption errors - Assert.Empty(finalDecryptionErrors); - - // Phase 8: Verify performance impact of rotation - _logger.LogInformation("Phase 8: Verifying performance impact of rotation"); - - await VerifyRotationPerformanceImpact(encryption, rotatedEncryption, scenario); - } - finally - { - // Cleanup is handled in DisposeAsync - } - } - - /// - /// Encrypt a batch of messages - /// - private async Task EncryptMessageBatch( - AwsKmsMessageEncryption encryption, - MessageBatch batch, - ConcurrentBag encryptedMessages, - string keyVersion) - { - var tasks = batch.Messages.Select(async message => - { - try - { - var ciphertext = await encryption.EncryptAsync(message); - encryptedMessages.Add(new EncryptedMessageRecord - { - Plaintext = message, - Ciphertext = ciphertext, - KeyVersion = keyVersion, - EncryptedAt = DateTime.UtcNow - }); - } - catch (Exception ex) - { - _logger.LogError(ex, "Failed to encrypt message: {Message}", message); - throw; - } - }); - - await Task.WhenAll(tasks); - } - - /// - /// Verify that messages are decryptable - /// - private async Task VerifyMessagesDecryptable( - AwsKmsMessageEncryption encryption, - ConcurrentBag messages, - ConcurrentBag errors) - { - var tasks = messages.Select(async record => - { - try - { - var decrypted = await encryption.DecryptAsync(record.Ciphertext); - - if (decrypted != record.Plaintext) - { - errors.Add($"Decrypted message does not match original. Expected: {record.Plaintext}, Got: {decrypted}"); - } - } - catch (Exception ex) - { - errors.Add($"Failed to decrypt message encrypted at {record.EncryptedAt} with key version {record.KeyVersion}: {ex.Message}"); - } - }); - - await Task.WhenAll(tasks); - } - - /// - /// Verify service continuity during key rotation - /// - private async Task VerifyServiceContinuity( - AwsKmsMessageEncryption originalEncryption, - AwsKmsMessageEncryption rotatedEncryption, - KeyRotationScenario scenario) - { - // Simulate concurrent encryption operations during rotation - var continuityMessages = new List - { - "Continuity test message 1", - "Continuity test message 2", - "Continuity test message 3", - "Continuity test message 4", - "Continuity test message 5" - }; - - var encryptionTasks = new List>(); - - // Interleave operations between original and rotated keys - for (int i = 0; i < continuityMessages.Count; i++) - { - var message = continuityMessages[i]; - var useRotated = i % 2 == 0; - var encryptionService = useRotated ? rotatedEncryption : originalEncryption; - - encryptionTasks.Add(Task.Run(async () => - { - try - { - var ciphertext = await encryptionService.EncryptAsync(message); - var decrypted = await encryptionService.DecryptAsync(ciphertext); - return (message, ciphertext, decrypted == message); - } - catch (Exception ex) - { - _logger.LogError(ex, "Service continuity test failed for message: {Message}", message); - return (message, "", false); - } - })); - } - - var results = await Task.WhenAll(encryptionTasks); - - // Assert: All operations should succeed without interruption - var failures = results.Where(r => !r.success).ToList(); - Assert.Empty(failures); - - // Assert: No service interruption (all operations completed) - Assert.Equal(continuityMessages.Count, results.Length); - } - - /// - /// Verify that key rotation doesn't significantly impact performance - /// - private async Task VerifyRotationPerformanceImpact( - AwsKmsMessageEncryption originalEncryption, - AwsKmsMessageEncryption rotatedEncryption, - KeyRotationScenario scenario) - { - const int performanceTestIterations = 10; - var testMessage = "Performance test message for key rotation"; - - // Measure performance with original key - var originalTimes = new List(); - for (int i = 0; i < performanceTestIterations; i++) - { - var sw = Stopwatch.StartNew(); - var ciphertext = await originalEncryption.EncryptAsync(testMessage); - await originalEncryption.DecryptAsync(ciphertext); - sw.Stop(); - originalTimes.Add(sw.Elapsed); - } - - // Measure performance with rotated key - var rotatedTimes = new List(); - for (int i = 0; i < performanceTestIterations; i++) - { - var sw = Stopwatch.StartNew(); - var ciphertext = await rotatedEncryption.EncryptAsync(testMessage); - await rotatedEncryption.DecryptAsync(ciphertext); - sw.Stop(); - rotatedTimes.Add(sw.Elapsed); - } - - var avgOriginal = originalTimes.Average(t => t.TotalMilliseconds); - var avgRotated = rotatedTimes.Average(t => t.TotalMilliseconds); - - _logger.LogInformation("Performance comparison - Original: {Original}ms, Rotated: {Rotated}ms", - avgOriginal, avgRotated); - - // Assert: Performance degradation should be within acceptable bounds - // LocalStack KMS timing is extremely variable; use very generous threshold - var performanceDegradation = (avgRotated - avgOriginal) / Math.Max(avgOriginal, 1); - Assert.True(performanceDegradation < 50.0, - $"Performance degradation after rotation ({performanceDegradation:P}) exceeds 5000% threshold"); - - // Assert: Both should complete in reasonable time - Assert.True(avgOriginal < 5000, $"Original key operations too slow: {avgOriginal}ms"); - Assert.True(avgRotated < 5000, $"Rotated key operations too slow: {avgRotated}ms"); - } - - /// - /// Simulate key rotation (LocalStack doesn't fully support automatic rotation) - /// - private async Task SimulateKeyRotation(string originalKeyId) - { - try - { - // In LocalStack, we simulate rotation by creating a new key - // In real AWS, this would be EnableKeyRotation API call - var createKeyResponse = await _localStack.KmsClient.CreateKeyAsync(new CreateKeyRequest - { - Description = $"Rotated key for {originalKeyId}", - KeyUsage = KeyUsageType.ENCRYPT_DECRYPT, - Origin = OriginType.AWS_KMS - }); - - var newKeyId = createKeyResponse.KeyMetadata.KeyId; - _createdKeyIds.Add(newKeyId); - - _logger.LogInformation("Simulated key rotation: {OriginalKey} -> {NewKey}", - originalKeyId, newKeyId); - - return newKeyId; - } - catch (Exception ex) - { - _logger.LogError(ex, "Failed to simulate key rotation for key: {KeyId}", originalKeyId); - throw; - } - } - - /// - /// Create a KMS key for testing - /// - private async Task CreateKmsKeyAsync(string keyAlias) - { - try - { - var createKeyResponse = await _localStack.KmsClient.CreateKeyAsync(new CreateKeyRequest - { - Description = $"Test key for key rotation property testing: {keyAlias}", - KeyUsage = KeyUsageType.ENCRYPT_DECRYPT, - Origin = OriginType.AWS_KMS - }); - - var keyId = createKeyResponse.KeyMetadata.KeyId; - _createdKeyIds.Add(keyId); - - // Create alias for the key - try - { - await _localStack.KmsClient.CreateAliasAsync(new CreateAliasRequest - { - AliasName = $"alias/{keyAlias}", - TargetKeyId = keyId - }); - } - catch (Exception) - { - // Alias creation might fail in LocalStack, continue without it - } - - return keyId; - } - catch (Exception ex) - { - _logger.LogError(ex, "Failed to create KMS key: {KeyAlias}", keyAlias); - throw; - } - } - - /// - /// Create encryption service for testing - /// - private AwsKmsMessageEncryption CreateEncryptionService(string keyId) - { - var options = new AwsKmsOptions - { - MasterKeyId = keyId, - CacheDataKeySeconds = 0 // Disable caching for tests to ensure fresh encryption - }; - - var loggerFactory = LoggerFactory.Create(builder => builder.AddConsole().SetMinimumLevel(LogLevel.Debug)); - var encryptionLogger = loggerFactory.CreateLogger(); - - return new AwsKmsMessageEncryption( - _localStack.KmsClient, - encryptionLogger, - _memoryCache, - options); - } - - /// - /// Clean up created KMS keys - /// - public async ValueTask DisposeAsync() - { - if (_localStack.KmsClient != null) - { - foreach (var keyId in _createdKeyIds) - { - try - { - // Schedule key deletion (minimum 7 days for real AWS, immediate for LocalStack) - await _localStack.KmsClient.ScheduleKeyDeletionAsync(new ScheduleKeyDeletionRequest - { - KeyId = keyId, - PendingWindowInDays = 7 - }); - } - catch (Exception) - { - // Ignore cleanup errors - } - } - } - - _createdKeyIds.Clear(); - _memoryCache?.Dispose(); - } -} - -/// -/// FsCheck generators for key rotation property tests -/// -public static class KeyRotationGenerators -{ - /// - /// Generate key rotation test scenarios - /// - public static Arbitrary KeyRotationScenario() - { - // Generate message batches (before and after rotation) - var messageBatchGen = from batchSize in Gen.Choose(1, 10) - from messages in Gen.ListOf(batchSize, MessageContentGen()) - select new MessageBatch - { - Messages = messages.Where(m => !string.IsNullOrEmpty(m)).ToList(), - BatchId = Guid.NewGuid().ToString() - }; - - var scenarioGen = from batchCount in Gen.Choose(1, 3) - from batches in Gen.ListOf(batchCount, messageBatchGen) - from rotationType in Gen.Elements( - RotationType.Automatic, - RotationType.Manual, - RotationType.OnDemand) - from concurrentOperations in Gen.Choose(1, 5) - select new KeyRotationScenario - { - MessageBatches = batches.Where(b => b.Messages.Count > 0).ToList(), - RotationType = rotationType, - ConcurrentOperations = concurrentOperations, - ScenarioId = Guid.NewGuid().ToString() - }; - - return Arb.From(scenarioGen); - } - - /// - /// Generate message content for testing - /// - private static Gen MessageContentGen() - { - return Gen.OneOf( - // Simple messages - Gen.Elements("Hello", "Test message", "Key rotation test", "Encrypted data"), - - // Structured data - Gen.Elements( - "{\"userId\":123,\"action\":\"login\"}", - "{\"orderId\":\"ORD-001\",\"amount\":99.99}", - "{\"event\":\"key_rotation\",\"timestamp\":\"2024-01-01T00:00:00Z\"}" - ), - - // Sensitive data patterns - from ssn in Gen.Choose(100000000, 999999999) - from ccn in Gen.Choose(1000000000, 1999999999) - select $"SSN:{ssn},CC:{ccn}", - - // Variable length messages - from length in Gen.Choose(10, 500) - from chars in Gen.ArrayOf(length, Gen.Elements("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789 ".ToCharArray())) - select new string(chars), - - // Unicode content - Gen.Elements("你好世界", "Привет мир", "مرحبا", "🔐🔑🔒"), - - // Special characters - Gen.Elements("Line1\nLine2", "Tab\tSeparated", "Quote\"Test", "Backslash\\Test") - ); - } -} - -/// -/// Key rotation test scenario -/// -public class KeyRotationScenario -{ - public List MessageBatches { get; set; } = new(); - public RotationType RotationType { get; set; } - public int ConcurrentOperations { get; set; } - public string ScenarioId { get; set; } = ""; -} - -/// -/// Message batch for testing -/// -public class MessageBatch -{ - public List Messages { get; set; } = new(); - public string BatchId { get; set; } = ""; -} - -/// -/// Rotation type enumeration -/// -public enum RotationType -{ - Automatic, - Manual, - OnDemand -} - -/// -/// Record of an encrypted message -/// -public class EncryptedMessageRecord -{ - public string Plaintext { get; set; } = ""; - public string Ciphertext { get; set; } = ""; - public string KeyVersion { get; set; } = ""; - public DateTime EncryptedAt { get; set; } -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/Integration/KmsSecurityAndPerformancePropertyTests.cs b/tests/SourceFlow.Cloud.AWS.Tests/Integration/KmsSecurityAndPerformancePropertyTests.cs deleted file mode 100644 index e69de29b..00000000 diff --git a/tests/SourceFlow.Cloud.AWS.Tests/Integration/KmsSecurityAndPerformanceTests.cs b/tests/SourceFlow.Cloud.AWS.Tests/Integration/KmsSecurityAndPerformanceTests.cs deleted file mode 100644 index f98c1c3a..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/Integration/KmsSecurityAndPerformanceTests.cs +++ /dev/null @@ -1,360 +0,0 @@ -using Amazon.KeyManagementService; -using Amazon.KeyManagementService.Model; -using Microsoft.Extensions.Caching.Memory; -using Microsoft.Extensions.Logging; -using SourceFlow.Cloud.AWS.Security; -using SourceFlow.Cloud.AWS.Tests.TestHelpers; -using SourceFlow.Cloud.Security; -using System.Diagnostics; -using System.Text.Json; - -namespace SourceFlow.Cloud.AWS.Tests.Integration; - -/// -/// Integration tests for KMS security and performance -/// Tests sensitive data masking, IAM permissions, performance under load, and audit logging -/// **Validates: Requirements 3.3, 3.4, 3.5** -/// -[Collection("AWS Integration Tests")] -[Trait("Category", "Integration")] -[Trait("Category", "RequiresLocalStack")] -public class KmsSecurityAndPerformanceTests : IClassFixture, IAsyncDisposable -{ - private readonly LocalStackTestFixture _localStack; - private readonly List _createdKeyIds = new(); - private readonly ILogger _logger; - private readonly IMemoryCache _memoryCache; - - public KmsSecurityAndPerformanceTests(LocalStackTestFixture localStack) - { - _localStack = localStack; - - // Create logger for tests - var loggerFactory = LoggerFactory.Create(builder => builder.AddConsole().SetMinimumLevel(LogLevel.Debug)); - _logger = loggerFactory.CreateLogger(); - - // Create memory cache for encryption tests - _memoryCache = new MemoryCache(new MemoryCacheOptions()); - } - - #region Sensitive Data Masking Tests - - [Fact] - public async Task SensitiveDataMasking_WithCreditCardAttribute_ShouldMaskInLogs() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.KmsClient == null) - { - return; - } - - // Arrange - var keyId = await CreateKmsKeyAsync("test-sensitive-cc"); - var encryption = CreateEncryptionService(keyId); - - var testData = new SensitiveTestData - { - CreditCardNumber = "4532-1234-5678-9010", - Email = "user@example.com", - PhoneNumber = "555-123-4567", - SSN = "123-45-6789", - ApiKey = "sk_test_1234567890abcdef", - Password = "SuperSecret123!" - }; - - // Act - Encrypt the sensitive data - var json = JsonSerializer.Serialize(testData); - var encrypted = await encryption.EncryptAsync(json); - - // Assert - Encrypted data should not contain sensitive information - Assert.DoesNotContain("4532-1234-5678-9010", encrypted); - Assert.DoesNotContain("user@example.com", encrypted); - Assert.DoesNotContain("555-123-4567", encrypted); - Assert.DoesNotContain("123-45-6789", encrypted); - Assert.DoesNotContain("sk_test_1234567890abcdef", encrypted); - Assert.DoesNotContain("SuperSecret123!", encrypted); - - // Verify masking works correctly - var masker = new SensitiveDataMasker(); - var masked = masker.Mask(testData); - - _logger.LogInformation("Masked data: {MaskedData}", masked); - - // Verify masked output doesn't contain full sensitive values - Assert.DoesNotContain("4532-1234-5678-9010", masked); - Assert.DoesNotContain("SuperSecret123!", masked); - Assert.Contains("********", masked); // Password should be fully masked - } - - [Fact] - public async Task SensitiveDataMasking_WithMultipleTypes_ShouldMaskAllCorrectly() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.KmsClient == null) - { - return; - } - - // Arrange - var masker = new SensitiveDataMasker(); - var testData = new ComprehensiveSensitiveData - { - UserName = "John Doe", - CreditCard = "5555-4444-3333-2222", - Email = "john.doe@company.com", - Phone = "1-800-555-0199", - SSN = "987-65-4321", - IPAddress = "192.168.1.100", - Password = "MyP@ssw0rd!", - ApiKey = "pk_live_abcdefghijklmnopqrstuvwxyz123456" - }; - - // Act - var masked = masker.Mask(testData); - - // Assert - Verify each type is masked correctly - Assert.DoesNotContain("John Doe", masked); - Assert.DoesNotContain("5555-4444-3333-2222", masked); - Assert.DoesNotContain("john.doe@company.com", masked); - Assert.DoesNotContain("1-800-555-0199", masked); - Assert.DoesNotContain("987-65-4321", masked); - Assert.DoesNotContain("192.168.1.100", masked); - Assert.DoesNotContain("MyP@ssw0rd!", masked); - Assert.DoesNotContain("pk_live_abcdefghijklmnopqrstuvwxyz123456", masked); - - _logger.LogInformation("Comprehensive masked data: {MaskedData}", masked); - } - - #endregion - - #region IAM Permission Tests - - [Fact] - public async Task IamPermissions_WithValidKey_ShouldAllowEncryption() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.KmsClient == null) - { - return; - } - - // Arrange - var keyId = await CreateKmsKeyAsync("test-iam-valid"); - var encryption = CreateEncryptionService(keyId); - var plaintext = "Test message for IAM validation"; - - // Act & Assert - Should succeed with valid permissions - var ciphertext = await encryption.EncryptAsync(plaintext); - Assert.NotNull(ciphertext); - Assert.NotEmpty(ciphertext); - - var decrypted = await encryption.DecryptAsync(ciphertext); - Assert.Equal(plaintext, decrypted); - - _logger.LogInformation("Successfully encrypted/decrypted with valid IAM permissions"); - } - - [Fact] - public async Task IamPermissions_WithInvalidKey_ShouldThrowException() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.KmsClient == null) - { - return; - } - - // Arrange - Use a non-existent key ID - var invalidKeyId = "arn:aws:kms:us-east-1:123456789012:key/00000000-0000-0000-0000-000000000000"; - var encryption = CreateEncryptionService(invalidKeyId); - var plaintext = "Test message"; - - // Act & Assert - Should fail with invalid key - await Assert.ThrowsAnyAsync(async () => - { - await encryption.EncryptAsync(plaintext); - }); - - _logger.LogInformation("Correctly rejected encryption with invalid key ID"); - } - - #endregion - - #region Performance Tests - - [Fact] - public async Task Performance_EncryptionThroughput_ShouldMeetThresholds() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.KmsClient == null) - { - return; - } - - // Arrange - var keyId = await CreateKmsKeyAsync("test-perf-throughput"); - var encryption = CreateEncryptionService(keyId); - var messageCount = 50; - var plaintext = "Performance test message for throughput measurement"; - - // Act - Measure encryption throughput - var stopwatch = Stopwatch.StartNew(); - var encryptTasks = Enumerable.Range(0, messageCount) - .Select(_ => encryption.EncryptAsync(plaintext)) - .ToList(); - - var ciphertexts = await Task.WhenAll(encryptTasks); - stopwatch.Stop(); - - // Calculate metrics - var throughput = messageCount / stopwatch.Elapsed.TotalSeconds; - var avgLatency = stopwatch.Elapsed.TotalMilliseconds / messageCount; - - // Assert - Performance should be reasonable - Assert.True(throughput > 1, $"Throughput {throughput:F2} msg/s should be > 1 msg/s"); - Assert.True(avgLatency < 5000, $"Average latency {avgLatency:F2}ms should be < 5000ms"); - - _logger.LogInformation( - "Encryption throughput: {Throughput:F2} msg/s, Average latency: {Latency:F2}ms", - throughput, avgLatency); - } - - #endregion - - - #region Helper Methods - - /// - /// Create a KMS key for testing - /// - private async Task CreateKmsKeyAsync(string keyAlias) - { - try - { - var createKeyResponse = await _localStack.KmsClient!.CreateKeyAsync(new CreateKeyRequest - { - Description = $"Security and performance test key: {keyAlias}", - KeyUsage = KeyUsageType.ENCRYPT_DECRYPT, - Origin = OriginType.AWS_KMS - }); - - var keyId = createKeyResponse.KeyMetadata.KeyId; - _createdKeyIds.Add(keyId); - - return keyId; - } - catch (Exception ex) - { - _logger.LogError(ex, "Failed to create KMS key: {KeyAlias}", keyAlias); - throw; - } - } - - /// - /// Create encryption service for testing - /// - private AwsKmsMessageEncryption CreateEncryptionService(string keyId, int cacheSeconds = 0) - { - var options = new AwsKmsOptions - { - MasterKeyId = keyId, - CacheDataKeySeconds = cacheSeconds - }; - - var loggerFactory = LoggerFactory.Create(builder => builder.AddConsole().SetMinimumLevel(LogLevel.Debug)); - var encryptionLogger = loggerFactory.CreateLogger(); - - return new AwsKmsMessageEncryption( - _localStack.KmsClient!, - encryptionLogger, - _memoryCache, - options); - } - - /// - /// Clean up created KMS keys - /// - public async ValueTask DisposeAsync() - { - if (_localStack.KmsClient != null) - { - foreach (var keyId in _createdKeyIds) - { - try - { - await _localStack.KmsClient.ScheduleKeyDeletionAsync(new ScheduleKeyDeletionRequest - { - KeyId = keyId, - PendingWindowInDays = 7 - }); - } - catch (Exception) - { - // Ignore cleanup errors - } - } - } - - _createdKeyIds.Clear(); - _memoryCache?.Dispose(); - } - - #endregion -} - -#region Test Data Models - -/// -/// Test data with sensitive fields -/// -public class SensitiveTestData -{ - [SensitiveData(SensitiveDataType.CreditCard)] - public string CreditCardNumber { get; set; } = ""; - - [SensitiveData(SensitiveDataType.Email)] - public string Email { get; set; } = ""; - - [SensitiveData(SensitiveDataType.PhoneNumber)] - public string PhoneNumber { get; set; } = ""; - - [SensitiveData(SensitiveDataType.SSN)] - public string SSN { get; set; } = ""; - - [SensitiveData(SensitiveDataType.ApiKey)] - public string ApiKey { get; set; } = ""; - - [SensitiveData(SensitiveDataType.Password)] - public string Password { get; set; } = ""; -} - -/// -/// Comprehensive sensitive data test model -/// -public class ComprehensiveSensitiveData -{ - [SensitiveData(SensitiveDataType.PersonalName)] - public string UserName { get; set; } = ""; - - [SensitiveData(SensitiveDataType.CreditCard)] - public string CreditCard { get; set; } = ""; - - [SensitiveData(SensitiveDataType.Email)] - public string Email { get; set; } = ""; - - [SensitiveData(SensitiveDataType.PhoneNumber)] - public string Phone { get; set; } = ""; - - [SensitiveData(SensitiveDataType.SSN)] - public string SSN { get; set; } = ""; - - [SensitiveData(SensitiveDataType.IPAddress)] - public string IPAddress { get; set; } = ""; - - [SensitiveData(SensitiveDataType.Password)] - public string Password { get; set; } = ""; - - [SensitiveData(SensitiveDataType.ApiKey)] - public string ApiKey { get; set; } = ""; -} - -#endregion diff --git a/tests/SourceFlow.Cloud.AWS.Tests/Integration/LocalStackCITimeoutExplorationTests.cs b/tests/SourceFlow.Cloud.AWS.Tests/Integration/LocalStackCITimeoutExplorationTests.cs deleted file mode 100644 index 309f9e02..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/Integration/LocalStackCITimeoutExplorationTests.cs +++ /dev/null @@ -1,413 +0,0 @@ -using SourceFlow.Cloud.AWS.Tests.TestHelpers; -using Microsoft.Extensions.Logging; -using System.Diagnostics; -using FsCheck; -using FsCheck.Xunit; - -namespace SourceFlow.Cloud.AWS.Tests.Integration; - -/// -/// Bug condition exploration tests for LocalStack timeout and port conflicts in GitHub Actions CI -/// -/// **CRITICAL**: These tests are EXPECTED TO FAIL on unfixed code - failure confirms the bug exists -/// **DO NOT attempt to fix the test or the code when it fails** -/// **NOTE**: These tests encode the expected behavior - they will validate the fix when they pass after implementation -/// **GOAL**: Surface counterexamples that demonstrate the bug exists in GitHub Actions CI -/// -/// Bug Condition: LocalStack containers in GitHub Actions CI do not report all services "available" -/// within 30-second timeout, and parallel test execution causes port conflicts. -/// -/// Expected Outcome: Tests FAIL with timeout after 30 seconds or port conflicts (this proves the bug exists) -/// -/// Validates: Requirements 1.1, 1.2, 1.3, 1.4, 1.5 from bugfix.md -/// -[Trait("Category", "Integration")] -[Trait("Category", "RequiresLocalStack")] -[Trait("Category", "BugExploration")] -[Collection("AWS Integration Tests")] -public class LocalStackCITimeoutExplorationTests : IAsyncLifetime -{ - private readonly ILogger _logger; - private LocalStackManager? _localStackManager; - private readonly List _counterexamples = new(); - private readonly Stopwatch _stopwatch = new(); - - public LocalStackCITimeoutExplorationTests() - { - var loggerFactory = LoggerFactory.Create(builder => - builder.AddConsole().SetMinimumLevel(LogLevel.Debug)); - _logger = loggerFactory.CreateLogger(); - } - - public Task InitializeAsync() - { - _localStackManager = new LocalStackManager( - LoggerFactory.Create(builder => - builder.AddConsole().SetMinimumLevel(LogLevel.Debug)) - .CreateLogger()); - return Task.CompletedTask; - } - - public async Task DisposeAsync() - { - if (_localStackManager != null) - { - await _localStackManager.DisposeAsync(); - } - - // Log all counterexamples found during test execution - if (_counterexamples.Any()) - { - _logger.LogWarning("=== COUNTEREXAMPLES FOUND ==="); - foreach (var counterexample in _counterexamples) - { - _logger.LogWarning(counterexample); - } - _logger.LogWarning("=== END COUNTEREXAMPLES ==="); - } - } - - /// - /// **Validates: Requirements 1.1, 1.3, 1.5** - /// - /// Property 1: Fault Condition - LocalStack Services Ready in CI - /// - /// Tests that LocalStack containers in GitHub Actions CI report all services "available" within 90 seconds. - /// - /// **EXPECTED OUTCOME ON UNFIXED CODE**: - /// - Test FAILS with TimeoutException after 30 seconds - /// - Services still report "initializing" status when timeout occurs - /// - Counterexample documents actual time required for services to become "available" in CI - /// - /// **EXPECTED OUTCOME AFTER FIX**: - /// - Test PASSES with all services reporting "available" within 90 seconds - /// - Enhanced retry logic and CI-specific timeouts allow sufficient initialization time - /// - [Fact] - public async Task LocalStack_ServicesReady_WithinCITimeout() - { - // Scoped PBT: Focus on the concrete failing case in CI environment - // This property is scoped to test the specific bug condition - - // Detect if we're running in GitHub Actions CI - var isGitHubActions = Environment.GetEnvironmentVariable("GITHUB_ACTIONS") == "true"; - - if (!isGitHubActions) - { - // Skip this test in local development - it's designed for CI - _logger.LogInformation("Skipping CI-specific test in local environment"); - return; - } - - _logger.LogInformation("=== BUG EXPLORATION TEST: LocalStack CI Timeout ==="); - // Only check services we actually enable — IAM/STS/cloudformation are disabled in LocalStack Community - var services = new[] { "sqs", "sns", "kms" }; - _logger.LogInformation("Testing services: {Services}", string.Join(", ", services)); - - // Use UNFIXED configuration (30-second timeout from current code) - var config = TestHelpers.LocalStackConfiguration.CreateForIntegrationTesting(); - - // Document the current timeout configuration - _logger.LogInformation("Current configuration:"); - _logger.LogInformation(" HealthCheckTimeout: {Timeout}", config.HealthCheckTimeout); - _logger.LogInformation(" MaxHealthCheckRetries: {Retries}", config.MaxHealthCheckRetries); - _logger.LogInformation(" HealthCheckRetryDelay: {Delay}", config.HealthCheckRetryDelay); - - _stopwatch.Restart(); - - try - { - // Attempt to start LocalStack with current (unfixed) configuration - await _localStackManager!.StartAsync(config); - - _stopwatch.Stop(); - var elapsedTime = _stopwatch.Elapsed; - - // If we get here, services became ready - _logger.LogInformation("Services became ready after {ElapsedTime}", elapsedTime); - - // Check individual service ready times - var healthStatus = await _localStackManager.GetServicesHealthAsync(); - foreach (var service in services) - { - if (healthStatus.TryGetValue(service, out var health)) - { - _logger.LogInformation("Service {Service}: Status={Status}, ResponseTime={ResponseTime}ms", - service, health.Status, health.ResponseTime.TotalMilliseconds); - } - } - - // Expected behavior: All enabled services should be available within 90 seconds - // On unfixed code, this will likely timeout at 30 seconds - var allAvailable = services.All(s => - healthStatus.TryGetValue(s, out var h) && h.IsAvailable); - - if (!allAvailable) - { - var counterexample = $"COUNTEREXAMPLE: Services not all available after {elapsedTime}. " + - $"Status: {string.Join(", ", services.Select(s => $"{s}={(healthStatus.TryGetValue(s, out var h) ? h.Status : "missing")}"))}"; - _counterexamples.Add(counterexample); - _logger.LogWarning(counterexample); - } - - Assert.True(allAvailable, - $"Expected all services to be available. " + - $"Status: {string.Join(", ", services.Select(s => $"{s}={(healthStatus.TryGetValue(s, out var h) ? h.Status : "missing")}"))}"); - } - catch (TimeoutException ex) - { - _stopwatch.Stop(); - var elapsedTime = _stopwatch.Elapsed; - - // This is the EXPECTED outcome on unfixed code - var counterexample = $"COUNTEREXAMPLE: Timeout after {elapsedTime}. " + - $"Message: {ex.Message}. " + - $"This confirms the bug - services need more than {config.HealthCheckTimeout} to become ready in CI."; - _counterexamples.Add(counterexample); - _logger.LogWarning(counterexample); - - // Try to get service status at time of failure - try - { - var healthStatus = await _localStackManager!.GetServicesHealthAsync(); - var statusDetails = string.Join(", ", - healthStatus.Select(kvp => $"{kvp.Key}={kvp.Value.Status}")); - _logger.LogWarning("Service status at timeout: {Status}", statusDetails); - _counterexamples.Add($"Service status at timeout: {statusDetails}"); - } - catch (Exception healthEx) - { - _logger.LogWarning("Could not retrieve service status: {Error}", healthEx.Message); - } - - // Throw to fail the test (this confirms the bug exists) - throw new Exception(counterexample, ex); - } - catch (Exception ex) - { - _stopwatch.Stop(); - var counterexample = $"COUNTEREXAMPLE: Unexpected error after {_stopwatch.Elapsed}: {ex.Message}"; - _counterexamples.Add(counterexample); - _logger.LogError(ex, counterexample); - throw new Exception(counterexample, ex); - } - } - - /// - /// **Validates: Requirements 1.2, 1.4** - /// - /// Property 2: Fault Condition - External Instance Detection - /// - /// Tests that external LocalStack instances are detected within 10 seconds with retry logic. - /// - /// **EXPECTED OUTCOME ON UNFIXED CODE**: - /// - Test FAILS because external instance detection timeout is only 3 seconds - /// - No retry logic exists for detection - /// - Counterexample documents detection failures within 3-second timeout - /// - /// **EXPECTED OUTCOME AFTER FIX**: - /// - Test PASSES with external instances detected within 10 seconds - /// - Retry logic (3 attempts with 2-second delays) improves detection reliability - /// - [Fact] - public async Task LocalStack_ExternalInstanceDetection_WithinTimeout() - { - var isGitHubActions = Environment.GetEnvironmentVariable("GITHUB_ACTIONS") == "true"; - - if (!isGitHubActions) - { - _logger.LogInformation("Skipping CI-specific test in local environment"); - return; - } - - _logger.LogInformation("=== BUG EXPLORATION TEST: External Instance Detection ==="); - - // Check if there's an external LocalStack instance (e.g., pre-started in GitHub Actions) - var config = TestHelpers.LocalStackConfiguration.CreateForIntegrationTesting(); - // Only check services we actually enable - var enabledServices = new[] { "sqs", "sns", "kms" }; - - _stopwatch.Restart(); - - try - { - // This will use the current (unfixed) 3-second timeout for external detection - await _localStackManager!.StartAsync(config); - - _stopwatch.Stop(); - - _logger.LogInformation("LocalStack started/detected after {ElapsedTime}", _stopwatch.Elapsed); - - // Check if it detected an external instance or started a new one - var healthStatus = await _localStackManager.GetServicesHealthAsync(); - var allAvailable = enabledServices.All(s => - healthStatus.TryGetValue(s, out var h) && h.IsAvailable); - - Assert.True(allAvailable, - "Expected all enabled services to be available. " + - $"Status: {string.Join(", ", enabledServices.Select(s => $"{s}={(healthStatus.TryGetValue(s, out var h) ? h.Status : "missing")}"))}"); - } - catch (TimeoutException ex) - { - _stopwatch.Stop(); - - var counterexample = $"COUNTEREXAMPLE: External instance detection failed after {_stopwatch.Elapsed}. " + - $"Message: {ex.Message}. " + - $"Current timeout is 3 seconds, which may be insufficient for CI environments."; - _counterexamples.Add(counterexample); - _logger.LogWarning(counterexample); - - // This failure confirms the bug exists - throw new Exception(counterexample, ex); - } - catch (InvalidOperationException ex) when (ex.Message.Contains("port is already allocated")) - { - _stopwatch.Stop(); - - var counterexample = $"COUNTEREXAMPLE: Port conflict detected after {_stopwatch.Elapsed}. " + - $"Message: {ex.Message}. " + - $"This indicates external instance detection failed and a new container was attempted."; - _counterexamples.Add(counterexample); - _logger.LogWarning(counterexample); - - // This failure confirms the bug exists - throw new Exception(counterexample, ex); - } - } - - /// - /// **Validates: Requirements 1.1, 1.3, 1.5** - /// - /// Property 3: Fault Condition - Individual Service Timing - /// - /// Tests and documents the actual time required for each service to become "available" in CI. - /// This is a diagnostic test to gather data about service initialization times. - /// - /// **EXPECTED OUTCOME ON UNFIXED CODE**: - /// - Test FAILS with timeout after 30 seconds - /// - Logs show which services became ready and which didn't - /// - Counterexample documents actual timing for each service (e.g., SQS: 25s, KMS: 45s) - /// - /// **EXPECTED OUTCOME AFTER FIX**: - /// - Test PASSES with all services ready within 90 seconds - /// - Logs show actual initialization times for each service - /// - [Fact] - public async Task LocalStack_ServiceTiming_DocumentActualInitializationTimes() - { - var isGitHubActions = Environment.GetEnvironmentVariable("GITHUB_ACTIONS") == "true"; - - if (!isGitHubActions) - { - _logger.LogInformation("Skipping CI-specific test in local environment"); - return; - } - - _logger.LogInformation("=== BUG EXPLORATION TEST: Service Timing Analysis ==="); - - var config = TestHelpers.LocalStackConfiguration.CreateForIntegrationTesting(); - // Only monitor services we actually enable — IAM/STS/cloudformation are disabled in LocalStack Community - var services = new[] { "sqs", "sns", "kms" }; - - _logger.LogInformation("Monitoring initialization times for services: {Services}", - string.Join(", ", services)); - - var serviceTimings = new Dictionary(); - foreach (var service in services) - { - serviceTimings[service] = null; - } - - _stopwatch.Restart(); - var startTime = DateTime.UtcNow; - - try - { - await _localStackManager!.StartAsync(config); - - _stopwatch.Stop(); - - // Get final health status - var healthStatus = await _localStackManager.GetServicesHealthAsync(); - - _logger.LogInformation("=== SERVICE TIMING RESULTS ==="); - _logger.LogInformation("Total startup time: {TotalTime}", _stopwatch.Elapsed); - - foreach (var service in services) - { - if (healthStatus.TryGetValue(service, out var health)) - { - var timing = health.LastChecked - startTime; - serviceTimings[service] = timing; - - _logger.LogInformation("Service {Service}: Status={Status}, Time={Time}, ResponseTime={ResponseTime}ms", - service, health.Status, timing, health.ResponseTime.TotalMilliseconds); - } - else - { - _logger.LogWarning("Service {Service}: NOT FOUND in health status", service); - } - } - - // Check if all enabled services are available - var allAvailable = services.All(s => - healthStatus.TryGetValue(s, out var h) && h.IsAvailable); - - if (!allAvailable) - { - var notAvailable = services - .Where(s => !healthStatus.TryGetValue(s, out var h) || !h.IsAvailable) - .Select(s => $"{s}={(healthStatus.TryGetValue(s, out var h) ? h.Status : "missing")}"); - var counterexample = $"COUNTEREXAMPLE: Not all services available after {_stopwatch.Elapsed}. " + - $"Not available: {string.Join(", ", notAvailable)}"; - _counterexamples.Add(counterexample); - _logger.LogWarning(counterexample); - } - - Assert.True(allAvailable, - $"Expected all services to be available within timeout. " + - $"Timings: {string.Join(", ", serviceTimings.Select(kvp => $"{kvp.Key}={kvp.Value?.TotalSeconds:F1}s"))}"); - } - catch (TimeoutException ex) - { - _stopwatch.Stop(); - - // Document which services became ready and which didn't - try - { - var healthStatus = await _localStackManager!.GetServicesHealthAsync(); - - _logger.LogWarning("=== SERVICE TIMING AT TIMEOUT ==="); - _logger.LogWarning("Timeout occurred after: {ElapsedTime}", _stopwatch.Elapsed); - - foreach (var service in services) - { - if (healthStatus.TryGetValue(service, out var health)) - { - var timing = health.LastChecked - startTime; - serviceTimings[service] = timing; - - _logger.LogWarning("Service {Service}: Status={Status}, Time={Time}", - service, health.Status, timing); - } - else - { - _logger.LogWarning("Service {Service}: NO STATUS AVAILABLE", service); - } - } - } - catch (Exception healthEx) - { - _logger.LogWarning("Could not retrieve service status: {Error}", healthEx.Message); - } - - var counterexample = $"COUNTEREXAMPLE: Timeout after {_stopwatch.Elapsed}. " + - $"Message: {ex.Message}. " + - $"Service timings: {string.Join(", ", serviceTimings.Select(kvp => $"{kvp.Key}={kvp.Value?.TotalSeconds.ToString("F1") ?? "N/A"}s"))}"; - _counterexamples.Add(counterexample); - _logger.LogWarning(counterexample); - - throw new Exception(counterexample, ex); - } - } -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/Integration/LocalStackIntegrationTests.cs b/tests/SourceFlow.Cloud.AWS.Tests/Integration/LocalStackIntegrationTests.cs deleted file mode 100644 index 858b2238..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/Integration/LocalStackIntegrationTests.cs +++ /dev/null @@ -1,184 +0,0 @@ -using Amazon.SQS.Model; -using Amazon.SimpleNotificationService.Model; -using SourceFlow.Cloud.AWS.Tests.TestHelpers; -using SqsMessageAttributeValue = Amazon.SQS.Model.MessageAttributeValue; -using SnsMessageAttributeValue = Amazon.SimpleNotificationService.Model.MessageAttributeValue; - -namespace SourceFlow.Cloud.AWS.Tests.Integration; - -/// -/// Integration tests using LocalStack emulator -/// -[Collection("AWS Integration Tests")] -[Trait("Category", "Integration")] -[Trait("Category", "RequiresLocalStack")] -public class LocalStackIntegrationTests : IClassFixture -{ - private readonly LocalStackTestFixture _localStack; - - public LocalStackIntegrationTests(LocalStackTestFixture localStack) - { - _localStack = localStack; - } - - [Fact] - public async Task LocalStack_ShouldBeAvailable() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests) - { - return; - } - - // Verify LocalStack is running and accessible - var isAvailable = await _localStack.IsAvailableAsync(); - Assert.True(isAvailable, "LocalStack should be available for integration tests"); - } - - [Fact] - public async Task SQS_ShouldCreateAndListQueues() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.SqsClient == null) - { - return; - } - - // Create a test queue - var queueName = $"test-queue-{Guid.NewGuid():N}"; - var createResponse = await _localStack.SqsClient.CreateQueueAsync(queueName); - - Assert.NotNull(createResponse.QueueUrl); - Assert.Contains(queueName, createResponse.QueueUrl); - - // List queues and verify our queue exists - var listResponse = await _localStack.SqsClient.ListQueuesAsync(new ListQueuesRequest()); - Assert.Contains(createResponse.QueueUrl, listResponse.QueueUrls); - - // Clean up - await _localStack.SqsClient.DeleteQueueAsync(createResponse.QueueUrl); - } - - [Fact] - public async Task SNS_ShouldCreateAndListTopics() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.SnsClient == null) - { - return; - } - - // Create a test topic - var topicName = $"test-topic-{Guid.NewGuid():N}"; - var createResponse = await _localStack.SnsClient.CreateTopicAsync(topicName); - - Assert.NotNull(createResponse.TopicArn); - Assert.Contains(topicName, createResponse.TopicArn); - - // List topics and verify our topic exists - var listResponse = await _localStack.SnsClient.ListTopicsAsync(); - Assert.Contains(createResponse.TopicArn, listResponse.Topics.Select(t => t.TopicArn)); - - // Clean up - await _localStack.SnsClient.DeleteTopicAsync(createResponse.TopicArn); - } - - [Fact] - public async Task SQS_ShouldSendAndReceiveMessages() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.SqsClient == null) - { - return; - } - - // Create a test queue - var queueName = $"test-message-queue-{Guid.NewGuid():N}"; - var createResponse = await _localStack.SqsClient.CreateQueueAsync(queueName); - var queueUrl = createResponse.QueueUrl; - - try - { - // Send a test message - var messageBody = $"Test message {Guid.NewGuid()}"; - var sendResponse = await _localStack.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = queueUrl, - MessageBody = messageBody, - MessageAttributes = new Dictionary - { - ["TestAttribute"] = new SqsMessageAttributeValue - { - DataType = "String", - StringValue = "TestValue" - } - } - }); - - Assert.NotNull(sendResponse.MessageId); - - // Receive the message - var receiveResponse = await _localStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = queueUrl, - MaxNumberOfMessages = 1, - MessageAttributeNames = new List { "All" }, - WaitTimeSeconds = 1 - }); - - Assert.Single(receiveResponse.Messages); - var receivedMessage = receiveResponse.Messages[0]; - - Assert.Equal(messageBody, receivedMessage.Body); - Assert.Contains("TestAttribute", receivedMessage.MessageAttributes.Keys); - Assert.Equal("TestValue", receivedMessage.MessageAttributes["TestAttribute"].StringValue); - } - finally - { - // Clean up - await _localStack.SqsClient.DeleteQueueAsync(queueUrl); - } - } - - [Fact] - public async Task SNS_ShouldPublishMessages() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.SnsClient == null) - { - return; - } - - // Create a test topic - var topicName = $"test-publish-topic-{Guid.NewGuid():N}"; - var createResponse = await _localStack.SnsClient.CreateTopicAsync(topicName); - var topicArn = createResponse.TopicArn; - - try - { - // Publish a test message - var messageBody = $"Test SNS message {Guid.NewGuid()}"; - var publishResponse = await _localStack.SnsClient.PublishAsync(new PublishRequest - { - TopicArn = topicArn, - Message = messageBody, - Subject = "Test Subject", - MessageAttributes = new Dictionary - { - ["TestAttribute"] = new SnsMessageAttributeValue - { - DataType = "String", - StringValue = "TestValue" - } - } - }); - - Assert.NotNull(publishResponse.MessageId); - } - finally - { - // Clean up - await _localStack.SnsClient.DeleteTopicAsync(topicArn); - } - } -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/Integration/LocalStackPreservationPropertyTests.cs b/tests/SourceFlow.Cloud.AWS.Tests/Integration/LocalStackPreservationPropertyTests.cs deleted file mode 100644 index 00be312c..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/Integration/LocalStackPreservationPropertyTests.cs +++ /dev/null @@ -1,511 +0,0 @@ -using System.Linq; -using SourceFlow.Cloud.AWS.Tests.TestHelpers; -using Microsoft.Extensions.Logging; -using System.Diagnostics; -using Amazon.SQS.Model; -using Amazon.SimpleNotificationService.Model; -using Amazon.KeyManagementService.Model; -using Amazon.IdentityManagement.Model; -using LocalStackConfig = SourceFlow.Cloud.AWS.Tests.TestHelpers.LocalStackConfiguration; - -namespace SourceFlow.Cloud.AWS.Tests.Integration; - -/// -/// Property-based tests for preservation of local development behavior -/// These tests verify that existing local development functionality remains unchanged -/// **Validates: Requirements 3.1, 3.2, 3.3, 3.4, 3.5, 3.6** -/// -[Trait("Category", "Integration")] -[Trait("Category", "RequiresLocalStack")] -[Trait("Category", "Preservation")] -[Collection("AWS Integration Tests")] -public class LocalStackPreservationPropertyTests : IAsyncLifetime -{ - private ILocalStackManager? _localStackManager; - private ILogger? _logger; - private LocalStackConfig? _configuration; - - public async Task InitializeAsync() - { - // Set up logging - var loggerFactory = LoggerFactory.Create(builder => - { - builder.AddConsole(); - builder.SetMinimumLevel(LogLevel.Debug); - }); - - _logger = loggerFactory.CreateLogger(); - _localStackManager = new LocalStackManager(_logger); - - // Use default configuration for local development - _configuration = LocalStackConfig.CreateDefault(); - - // Start LocalStack for preservation tests - await _localStackManager.StartAsync(_configuration); - } - - public async Task DisposeAsync() - { - if (_localStackManager != null) - { - await _localStackManager.DisposeAsync(); - } - } - - /// - /// Property 1: Local development tests complete within 35 seconds - /// **Validates: Requirement 3.1 - Local development tests pass with existing timeout configurations** - /// - [Fact] - public async Task LocalDevelopment_TestsCompleteWithin35Seconds() - { - // Property: For all test iterations (1-5), execution time should be <= 35 seconds - for (int testIterations = 1; testIterations <= 5; testIterations++) - { - var stopwatch = Stopwatch.StartNew(); - - // Simulate typical local development test execution - for (int i = 0; i < testIterations; i++) - { - // Verify LocalStack is running - Assert.True(_localStackManager!.IsRunning); - - // Perform basic health check - var health = await _localStackManager.GetServicesHealthAsync(); - Assert.NotEmpty(health); - - // Small delay between iterations - await Task.Delay(100); - } - - stopwatch.Stop(); - - // Property: Execution time should be <= 35 seconds for local development - var executionTime = stopwatch.Elapsed.TotalSeconds; - Assert.True(executionTime <= 35.0, - $"Execution time {executionTime:F2}s should be <= 35s for {testIterations} iterations"); - - _logger?.LogInformation("Test completed in {ExecutionTime:F2}s for {Iterations} iterations", - executionTime, testIterations); - } - } - - /// - /// Property 2: SQS service validation works correctly - /// **Validates: Requirement 3.2 - Service validation (SQS ListQueues) continues to work correctly** - /// - [Fact] - public async Task LocalDevelopment_SqsServiceValidationWorks() - { - // Property: For all queue counts (1-3), all created queues should be found via ListQueues - var queuePrefix = $"test-sqs-{Guid.NewGuid():N}"; - - for (int queueCount = 1; queueCount <= 3; queueCount++) - { - var sqsClient = CreateSqsClient(); - var createdQueues = new List(); - - try - { - // Create test queues - for (int i = 0; i < queueCount; i++) - { - var queueName = $"{queuePrefix}-{i}"; - var createResponse = await sqsClient.CreateQueueAsync(queueName); - createdQueues.Add(createResponse.QueueUrl); - } - - // Validate: ListQueues should return all created queues - var listResponse = await sqsClient.ListQueuesAsync(new ListQueuesRequest - { - QueueNamePrefix = queuePrefix - }); - - // Property: All created queues should be in the list - var allQueuesFound = createdQueues.All(queueUrl => - listResponse.QueueUrls.Any(url => url.Contains(queueUrl.Split('/').Last()))); - - Assert.True(allQueuesFound, - $"All {queueCount} queues should be found via ListQueues"); - - _logger?.LogInformation("SQS validation passed for {QueueCount} queues", queueCount); - } - finally - { - // Clean up - foreach (var queueUrl in createdQueues) - { - try - { - await sqsClient.DeleteQueueAsync(queueUrl); - } - catch - { - // Ignore cleanup errors - } - } - } - } - } - - /// - /// Property 3: SNS service validation works correctly - /// **Validates: Requirement 3.2 - Service validation (SNS ListTopics) continues to work correctly** - /// - [Fact] - public async Task LocalDevelopment_SnsServiceValidationWorks() - { - // Property: For all topic counts (1-3), all created topics should be found via ListTopics - var topicPrefix = $"test-sns-{Guid.NewGuid():N}"; - - for (int topicCount = 1; topicCount <= 3; topicCount++) - { - var snsClient = CreateSnsClient(); - var createdTopics = new List(); - - try - { - // Create test topics - for (int i = 0; i < topicCount; i++) - { - var topicName = $"{topicPrefix}-{i}"; - var createResponse = await snsClient.CreateTopicAsync(topicName); - createdTopics.Add(createResponse.TopicArn); - } - - // Validate: ListTopics should return all created topics - var listResponse = await snsClient.ListTopicsAsync(); - - // Property: All created topics should be in the list - var allTopicsFound = createdTopics.All(topicArn => - listResponse.Topics.Any(t => t.TopicArn == topicArn)); - - Assert.True(allTopicsFound, - $"All {topicCount} topics should be found via ListTopics"); - - _logger?.LogInformation("SNS validation passed for {TopicCount} topics", topicCount); - } - finally - { - // Clean up - foreach (var topicArn in createdTopics) - { - try - { - await snsClient.DeleteTopicAsync(topicArn); - } - catch - { - // Ignore cleanup errors - } - } - } - } - } - - /// - /// Property 4: KMS service validation works correctly - /// **Validates: Requirement 3.2 - Service validation (KMS ListKeys) continues to work correctly** - /// - [Fact] - public async Task LocalDevelopment_KmsServiceValidationWorks() - { - // Property: KMS ListKeys should execute successfully (repeated 5 times) - for (int i = 0; i < 5; i++) - { - var kmsClient = CreateKmsClient(); - - try - { - // Validate: ListKeys should execute without errors - var listResponse = await kmsClient.ListKeysAsync(new ListKeysRequest - { - Limit = 10 - }); - - // Property: ListKeys should return a valid response (may be empty) - Assert.NotNull(listResponse); - Assert.NotNull(listResponse.Keys); - - _logger?.LogInformation("KMS ListKeys validation passed (iteration {Iteration})", i + 1); - } - catch (Exception ex) - { - // Log the error for diagnostics - _logger?.LogWarning(ex, "KMS ListKeys failed on iteration {Iteration}", i + 1); - throw; - } - } - } - - /// - /// Property 5: IAM service validation works correctly - /// **Validates: Requirement 3.2 - Service validation (IAM ListRoles) continues to work correctly** - /// - [Fact] - public async Task LocalDevelopment_IamServiceValidationWorks() - { - // IAM may be disabled in LocalStack Community Edition — skip if not available - var health = await _localStackManager.GetServicesHealthAsync(); - if (!health.ContainsKey("iam") || !health["iam"].IsAvailable) - { - _logger?.LogInformation("IAM service not available in this LocalStack edition — skipping test"); - return; - } - - // Property: IAM ListRoles should execute successfully (repeated 5 times) - for (int i = 0; i < 5; i++) - { - var iamClient = CreateIamClient(); - - try - { - // Validate: ListRoles should execute without errors - var listResponse = await iamClient.ListRolesAsync(new ListRolesRequest - { - MaxItems = 10 - }); - - // Property: ListRoles should return a valid response (may be empty) - Assert.NotNull(listResponse); - Assert.NotNull(listResponse.Roles); - - _logger?.LogInformation("IAM ListRoles validation passed (iteration {Iteration})", i + 1); - } - catch (Exception ex) - { - // Log the error for diagnostics - _logger?.LogWarning(ex, "IAM ListRoles failed on iteration {Iteration}", i + 1); - throw; - } - } - } - - /// - /// Property 6: Container cleanup with AutoRemove functions properly - /// **Validates: Requirement 3.3 - Container cleanup with AutoRemove = true continues to function** - /// - [Fact] - public async Task LocalDevelopment_ContainerCleanupWorks() - { - // Skip when LocalStack is already running externally (CI or local dev with pre-started instance) - // This test starts new Docker containers on different ports which is very slow - if (_localStackManager!.IsRunning) - { - _logger?.LogInformation("Skipping container cleanup test - external LocalStack already running"); - return; - } - - // Property: For all cleanup iterations (1-3), containers should be stopped after disposal - for (int cleanupIterations = 1; cleanupIterations <= 3; cleanupIterations++) - { - var loggerFactory = LoggerFactory.Create(builder => - { - builder.AddConsole(); - builder.SetMinimumLevel(LogLevel.Debug); - }); - - for (int i = 0; i < cleanupIterations; i++) - { - var logger = loggerFactory.CreateLogger(); - var manager = new LocalStackManager(logger); - var config = LocalStackConfig.CreateDefault(); - config.Port = 4566 + i + 10; // Use different ports to avoid conflicts - config.Endpoint = $"http://localhost:{config.Port}"; - config.AutoRemove = true; - - try - { - // Start container - await manager.StartAsync(config); - Assert.True(manager.IsRunning, "Container should be running after start"); - - // Stop and dispose (should auto-remove) - await manager.DisposeAsync(); - - // Property: Container should be stopped after disposal - Assert.False(manager.IsRunning, "Container should be stopped after disposal"); - - _logger?.LogInformation("Container cleanup validated for iteration {Iteration}", i + 1); - } - catch (Exception ex) - { - _logger?.LogWarning(ex, "Container cleanup test iteration {Iteration} failed", i); - throw; - } - } - } - } - - /// - /// Property 7: Port conflict detection finds alternative ports - /// **Validates: Requirement 3.4 - Port conflict detection via FindAvailablePortAsync continues to work** - /// - [Fact] - public async Task LocalDevelopment_PortConflictDetectionWorks() - { - // Property: For various start ports, FindAvailablePortAsync should find available ports - var startPorts = new[] { 5000, 5500, 6000, 6500, 7000 }; - - foreach (var startPort in startPorts) - { - // Use reflection to access private FindAvailablePortAsync method - var managerType = typeof(LocalStackManager); - var method = managerType.GetMethod("FindAvailablePortAsync", - System.Reflection.BindingFlags.NonPublic | System.Reflection.BindingFlags.Instance); - - if (method == null) - { - _logger?.LogWarning("FindAvailablePortAsync method not found via reflection"); - continue; // Skip test if method not accessible - } - - var loggerFactory = LoggerFactory.Create(builder => - { - builder.AddConsole(); - builder.SetMinimumLevel(LogLevel.Debug); - }); - - var logger = loggerFactory.CreateLogger(); - var manager = new LocalStackManager(logger); - - try - { - // Invoke FindAvailablePortAsync - var resultTask = method.Invoke(manager, new object[] { startPort }) as Task; - Assert.NotNull(resultTask); - - var availablePort = await resultTask; - - // Property: Available port should be >= start port and within reasonable range - Assert.True(availablePort >= startPort, - $"Available port {availablePort} should be >= start port {startPort}"); - Assert.True(availablePort < startPort + 100, - $"Available port {availablePort} should be within 100 of start port {startPort}"); - - _logger?.LogInformation("Port conflict detection found port {AvailablePort} starting from {StartPort}", - availablePort, startPort); - } - catch (Exception ex) - { - _logger?.LogWarning(ex, "Port conflict detection test failed for start port {StartPort}", startPort); - throw; - } - } - } - - /// - /// Property 8: Test lifecycle with IAsyncLifetime works correctly - /// **Validates: Requirement 3.5 - Test lifecycle with IAsyncLifetime continues to work** - /// - [Fact] - public async Task LocalDevelopment_AsyncLifetimeWorks() - { - // This test itself validates IAsyncLifetime by using InitializeAsync and DisposeAsync - // Property: LocalStack should be running after InitializeAsync - Assert.NotNull(_localStackManager); - Assert.True(_localStackManager.IsRunning); - - // Property: Configuration should be set - Assert.NotNull(_configuration); - - // Property: Services should be available - var health = await _localStackManager.GetServicesHealthAsync(); - Assert.NotEmpty(health); - - // Property: All configured services should be available (except iam which is lazily initialized) - foreach (var service in _configuration.EnabledServices.Where(s => s != "iam")) - { - Assert.True(health.ContainsKey(service), $"Service {service} should be in health check"); - Assert.True(health[service].IsAvailable, $"Service {service} should be available"); - } - } - - /// - /// Property 9: Health endpoint JSON deserialization works correctly - /// **Validates: Requirement 3.6 - Health endpoint JSON deserialization continues to work** - /// - [Fact] - public async Task LocalDevelopment_HealthEndpointDeserializationWorks() - { - // Property: Health endpoint should deserialize correctly (repeated 10 times) - for (int i = 0; i < 10; i++) - { - try - { - // Get health status (which internally deserializes JSON) - var health = await _localStackManager!.GetServicesHealthAsync(); - - // Property: Health response should be deserializable and contain expected data - Assert.NotEmpty(health); - - // Property: Each service should have valid health information - foreach (var service in health.Values) - { - Assert.False(string.IsNullOrEmpty(service.ServiceName), - "Service name should not be empty"); - Assert.False(string.IsNullOrEmpty(service.Status), - "Service status should not be empty"); - Assert.NotEqual(default, service.LastChecked); - } - - _logger?.LogInformation("Health endpoint deserialization validated (iteration {Iteration})", i + 1); - } - catch (Exception ex) - { - _logger?.LogWarning(ex, "Health endpoint deserialization test failed on iteration {Iteration}", i + 1); - throw; - } - } - } - - // Helper methods to create AWS clients - - private IAmazonSQS CreateSqsClient() - { - var config = new Amazon.SQS.AmazonSQSConfig - { - ServiceURL = _localStackManager!.Endpoint, - UseHttp = true, - AuthenticationRegion = "us-east-1" - }; - - return new Amazon.SQS.AmazonSQSClient("test", "test", config); - } - - private IAmazonSimpleNotificationService CreateSnsClient() - { - var config = new Amazon.SimpleNotificationService.AmazonSimpleNotificationServiceConfig - { - ServiceURL = _localStackManager!.Endpoint, - UseHttp = true, - AuthenticationRegion = "us-east-1" - }; - - return new Amazon.SimpleNotificationService.AmazonSimpleNotificationServiceClient("test", "test", config); - } - - private IAmazonKeyManagementService CreateKmsClient() - { - var config = new Amazon.KeyManagementService.AmazonKeyManagementServiceConfig - { - ServiceURL = _localStackManager!.Endpoint, - UseHttp = true, - AuthenticationRegion = "us-east-1" - }; - - return new Amazon.KeyManagementService.AmazonKeyManagementServiceClient("test", "test", config); - } - - private IAmazonIdentityManagementService CreateIamClient() - { - var config = new Amazon.IdentityManagement.AmazonIdentityManagementServiceConfig - { - ServiceURL = _localStackManager!.Endpoint, - UseHttp = true, - AuthenticationRegion = "us-east-1" - }; - - return new Amazon.IdentityManagement.AmazonIdentityManagementServiceClient("test", "test", config); - } -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/Integration/SnsCorrelationAndErrorHandlingTests.cs b/tests/SourceFlow.Cloud.AWS.Tests/Integration/SnsCorrelationAndErrorHandlingTests.cs deleted file mode 100644 index 362d4de7..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/Integration/SnsCorrelationAndErrorHandlingTests.cs +++ /dev/null @@ -1,781 +0,0 @@ -using Amazon.SimpleNotificationService; -using Amazon.SimpleNotificationService.Model; -using Amazon.SQS; -using Amazon.SQS.Model; -using Microsoft.Extensions.DependencyInjection; -using Microsoft.Extensions.Logging; -using SourceFlow.Cloud.AWS.Tests.TestHelpers; -using System.Text.Json; -using Xunit.Abstractions; -using SnsMessageAttributeValue = Amazon.SimpleNotificationService.Model.MessageAttributeValue; - -namespace SourceFlow.Cloud.AWS.Tests.Integration; - -/// -/// Integration tests for SNS correlation ID preservation and error handling -/// Tests correlation ID preservation across subscriptions, failed delivery handling, and dead letter queue integration -/// **Validates: Requirements 2.4, 2.5** -/// -[Collection("AWS Integration Tests")] -[Trait("Category", "Integration")] -[Trait("Category", "RequiresLocalStack")] -public class SnsCorrelationAndErrorHandlingTests : IAsyncLifetime -{ - private readonly ITestOutputHelper _output; - private readonly IAwsTestEnvironment _testEnvironment; - private readonly ILogger _logger; - private readonly List _createdTopics = new(); - private readonly List _createdQueues = new(); - private readonly List _createdSubscriptions = new(); - - public SnsCorrelationAndErrorHandlingTests(ITestOutputHelper output) - { - _output = output; - - var services = new ServiceCollection(); - services.AddLogging(builder => builder.AddConsole().SetMinimumLevel(LogLevel.Debug)); - - var serviceProvider = services.BuildServiceProvider(); - _logger = serviceProvider.GetRequiredService>(); - - _testEnvironment = AwsTestEnvironmentFactory.CreateLocalStackEnvironmentAsync().GetAwaiter().GetResult(); - } - - public async Task InitializeAsync() - { - await _testEnvironment.InitializeAsync(); - - if (!await _testEnvironment.IsAvailableAsync()) - { - throw new InvalidOperationException("AWS test environment is not available"); - } - - _logger.LogInformation("SNS correlation and error handling integration tests initialized"); - } - - public async Task DisposeAsync() - { - // Clean up subscriptions first - foreach (var subscriptionArn in _createdSubscriptions) - { - try - { - await _testEnvironment.SnsClient.UnsubscribeAsync(new UnsubscribeRequest - { - SubscriptionArn = subscriptionArn - }); - } - catch (Exception ex) - { - _logger.LogWarning("Failed to delete subscription {SubscriptionArn}: {Error}", subscriptionArn, ex.Message); - } - } - - // Clean up topics - foreach (var topicArn in _createdTopics) - { - try - { - await _testEnvironment.DeleteTopicAsync(topicArn); - } - catch (Exception ex) - { - _logger.LogWarning("Failed to delete topic {TopicArn}: {Error}", topicArn, ex.Message); - } - } - - // Clean up queues - foreach (var queueUrl in _createdQueues) - { - try - { - await _testEnvironment.DeleteQueueAsync(queueUrl); - } - catch (Exception ex) - { - _logger.LogWarning("Failed to delete queue {QueueUrl}: {Error}", queueUrl, ex.Message); - } - } - - await _testEnvironment.DisposeAsync(); - _logger.LogInformation("SNS correlation and error handling integration tests disposed"); - } - - [Fact] - public async Task CorrelationId_PreservationAcrossMultipleSubscriptions_ShouldMaintainTraceability() - { - // Arrange - var topicName = $"test-correlation-topic-{Guid.NewGuid():N}"; - var topicArn = await _testEnvironment.CreateTopicAsync(topicName); - _createdTopics.Add(topicArn); - - var correlationId = Guid.NewGuid().ToString(); - var requestId = Guid.NewGuid().ToString(); - var sessionId = "session-12345"; - - // Create multiple subscriber queues - var subscriberQueues = new List<(string QueueUrl, string QueueArn, string Name)>(); - var subscriberNames = new[] { "OrderProcessor", "PaymentProcessor", "NotificationService" }; - - foreach (var name in subscriberNames) - { - var queueName = $"test-{name.ToLower()}-{Guid.NewGuid():N}"; - var queueUrl = await _testEnvironment.CreateStandardQueueAsync(queueName); - _createdQueues.Add(queueUrl); - - var queueArn = await GetQueueArnAsync(queueUrl); - subscriberQueues.Add((queueUrl, queueArn, name)); - - var subscriptionResponse = await _testEnvironment.SnsClient.SubscribeAsync(new SubscribeRequest - { - TopicArn = topicArn, - Protocol = "sqs", - Endpoint = queueArn - }); - _createdSubscriptions.Add(subscriptionResponse.SubscriptionArn); - - await SetQueuePolicyForSns(queueUrl, queueArn, topicArn); - } - - var testEvent = new TestEvent(new TestEventData - { - Id = 123, - Message = "Correlation test event", - Value = 456 - }); - - // Act - Publish event with correlation metadata - await _testEnvironment.SnsClient.PublishAsync(new PublishRequest - { - TopicArn = topicArn, - Message = JsonSerializer.Serialize(testEvent), - Subject = testEvent.Name, - MessageAttributes = new Dictionary - { - ["CorrelationId"] = new SnsMessageAttributeValue - { - DataType = "String", - StringValue = correlationId - }, - ["RequestId"] = new SnsMessageAttributeValue - { - DataType = "String", - StringValue = requestId - }, - ["SessionId"] = new SnsMessageAttributeValue - { - DataType = "String", - StringValue = sessionId - }, - ["EventType"] = new SnsMessageAttributeValue - { - DataType = "String", - StringValue = testEvent.GetType().Name - }, - ["Timestamp"] = new SnsMessageAttributeValue - { - DataType = "String", - StringValue = DateTime.UtcNow.ToString("O") - } - } - }); - - // Wait for message delivery - await Task.Delay(3000); - - // Assert - Verify correlation ID is preserved across all subscriptions - var correlationResults = new List<(string SubscriberName, bool HasCorrelationId, string? ReceivedCorrelationId)>(); - - foreach (var (queueUrl, _, name) in subscriberQueues) - { - var receiveResponse = await _testEnvironment.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = queueUrl, - MaxNumberOfMessages = 1, - WaitTimeSeconds = 3, - MessageAttributeNames = new List { "All" } - }); - - Assert.Single(receiveResponse.Messages); - - var receivedMessage = receiveResponse.Messages[0]; - var snsMessage = JsonSerializer.Deserialize(receivedMessage.Body); - - var hasCorrelationId = snsMessage?.MessageAttributes?.ContainsKey("CorrelationId") == true; - var receivedCorrelationId = snsMessage?.MessageAttributes?["CorrelationId"]?.Value; - - correlationResults.Add((name, hasCorrelationId, receivedCorrelationId)); - - // Verify all correlation attributes are preserved - Assert.True(hasCorrelationId, $"CorrelationId missing for subscriber {name}"); - Assert.Equal(correlationId, receivedCorrelationId); - - Assert.True(snsMessage?.MessageAttributes?.ContainsKey("RequestId")); - Assert.Equal(requestId, snsMessage?.MessageAttributes?["RequestId"]?.Value); - - Assert.True(snsMessage?.MessageAttributes?.ContainsKey("SessionId")); - Assert.Equal(sessionId, snsMessage?.MessageAttributes?["SessionId"]?.Value); - } - - // All subscribers should have received the same correlation metadata - Assert.All(correlationResults, result => - { - Assert.True(result.HasCorrelationId); - Assert.Equal(correlationId, result.ReceivedCorrelationId); - }); - - _logger.LogInformation("Successfully preserved correlation ID {CorrelationId} across {SubscriberCount} subscribers: {Subscribers}", - correlationId, subscriberQueues.Count, string.Join(", ", subscriberQueues.Select(s => s.Name))); - } - - [Fact] - public async Task ErrorHandling_FailedDeliveryWithRetryMechanisms_ShouldHandleGracefully() - { - // Arrange - var topicName = $"test-error-handling-{Guid.NewGuid():N}"; - var topicArn = await _testEnvironment.CreateTopicAsync(topicName); - _createdTopics.Add(topicArn); - - // Create a valid SQS subscriber - var validQueueName = $"test-valid-subscriber-{Guid.NewGuid():N}"; - var validQueueUrl = await _testEnvironment.CreateStandardQueueAsync(validQueueName); - _createdQueues.Add(validQueueUrl); - var validQueueArn = await GetQueueArnAsync(validQueueUrl); - - var validSubscriptionResponse = await _testEnvironment.SnsClient.SubscribeAsync(new SubscribeRequest - { - TopicArn = topicArn, - Protocol = "sqs", - Endpoint = validQueueArn - }); - _createdSubscriptions.Add(validSubscriptionResponse.SubscriptionArn); - await SetQueuePolicyForSns(validQueueUrl, validQueueArn, topicArn); - - // Create invalid HTTP endpoint subscribers (will fail delivery) - var invalidEndpoints = new[] - { - "http://invalid-endpoint-1.example.com/webhook", - "http://invalid-endpoint-2.example.com/webhook", - "https://non-existent-service.com/api/events" - }; - - foreach (var endpoint in invalidEndpoints) - { - try - { - var invalidSubscriptionResponse = await _testEnvironment.SnsClient.SubscribeAsync(new SubscribeRequest - { - TopicArn = topicArn, - Protocol = "http", - Endpoint = endpoint - }); - _createdSubscriptions.Add(invalidSubscriptionResponse.SubscriptionArn); - } - catch (Exception ex) - { - _logger.LogWarning("Failed to create invalid HTTP subscription for {Endpoint}: {Error}", endpoint, ex.Message); - } - } - - var correlationId = Guid.NewGuid().ToString(); - var testEvent = new TestEvent(new TestEventData - { - Id = 999, - Message = "Error handling test event", - Value = 888 - }); - - // Act - Publish event that will succeed for SQS but fail for HTTP endpoints - var publishResponse = await _testEnvironment.SnsClient.PublishAsync(new PublishRequest - { - TopicArn = topicArn, - Message = JsonSerializer.Serialize(testEvent), - Subject = testEvent.Name, - MessageAttributes = new Dictionary - { - ["CorrelationId"] = new SnsMessageAttributeValue - { - DataType = "String", - StringValue = correlationId - }, - ["EventType"] = new SnsMessageAttributeValue - { - DataType = "String", - StringValue = testEvent.GetType().Name - }, - ["ErrorHandlingTest"] = new SnsMessageAttributeValue - { - DataType = "String", - StringValue = "true" - } - } - }); - - // Assert - Publish should succeed despite invalid subscribers - Assert.NotNull(publishResponse.MessageId); - - // Wait for delivery attempts - await Task.Delay(5000); - - // Valid SQS subscriber should receive the message - var receiveResponse = await _testEnvironment.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = validQueueUrl, - MaxNumberOfMessages = 1, - WaitTimeSeconds = 5, - MessageAttributeNames = new List { "All" } - }); - - Assert.Single(receiveResponse.Messages); - - var receivedMessage = receiveResponse.Messages[0]; - var snsMessage = JsonSerializer.Deserialize(receivedMessage.Body); - - // Verify correlation ID is preserved even with failed deliveries - Assert.True(snsMessage?.MessageAttributes?.ContainsKey("CorrelationId")); - Assert.Equal(correlationId, snsMessage?.MessageAttributes?["CorrelationId"]?.Value); - - // Check subscription attributes for delivery policy (if supported) - try - { - var subscriptionAttributes = await _testEnvironment.SnsClient.GetSubscriptionAttributesAsync( - new GetSubscriptionAttributesRequest - { - SubscriptionArn = validSubscriptionResponse.SubscriptionArn - }); - - Assert.NotNull(subscriptionAttributes.Attributes); - _logger.LogInformation("Retrieved subscription attributes for error handling validation"); - } - catch (Exception ex) - { - _logger.LogWarning("Could not retrieve subscription attributes (might not be supported in LocalStack): {Error}", ex.Message); - } - - _logger.LogInformation("Successfully handled mixed delivery scenario - valid subscriber received message with CorrelationId {CorrelationId}", - correlationId); - } - - [Fact] - public async Task DeadLetterQueue_IntegrationWithSns_ShouldCaptureFailedDeliveries() - { - // Arrange - var topicName = $"test-dlq-integration-{Guid.NewGuid():N}"; - var topicArn = await _testEnvironment.CreateTopicAsync(topicName); - _createdTopics.Add(topicArn); - - // Create main queue with dead letter queue - var mainQueueName = $"test-main-queue-{Guid.NewGuid():N}"; - var dlqName = $"test-dlq-{Guid.NewGuid():N}"; - - // Create DLQ first - var dlqUrl = await _testEnvironment.CreateStandardQueueAsync(dlqName); - _createdQueues.Add(dlqUrl); - var dlqArn = await GetQueueArnAsync(dlqUrl); - - // Create main queue with DLQ configuration - var mainQueueUrl = await _testEnvironment.CreateStandardQueueAsync(mainQueueName, new Dictionary - { - ["RedrivePolicy"] = $"{{\"deadLetterTargetArn\":\"{dlqArn}\",\"maxReceiveCount\":2}}" - }); - _createdQueues.Add(mainQueueUrl); - var mainQueueArn = await GetQueueArnAsync(mainQueueUrl); - - var subscriptionResponse = await _testEnvironment.SnsClient.SubscribeAsync(new SubscribeRequest - { - TopicArn = topicArn, - Protocol = "sqs", - Endpoint = mainQueueArn - }); - _createdSubscriptions.Add(subscriptionResponse.SubscriptionArn); - - await SetQueuePolicyForSns(mainQueueUrl, mainQueueArn, topicArn); - await SetQueuePolicyForSns(dlqUrl, dlqArn, topicArn); - - var correlationId = Guid.NewGuid().ToString(); - var testEvent = new TestEvent(new TestEventData - { - Id = 777, - Message = "DLQ integration test event", - Value = 555 - }); - - // Act - Publish event - await _testEnvironment.SnsClient.PublishAsync(new PublishRequest - { - TopicArn = topicArn, - Message = JsonSerializer.Serialize(testEvent), - Subject = testEvent.Name, - MessageAttributes = new Dictionary - { - ["CorrelationId"] = new SnsMessageAttributeValue - { - DataType = "String", - StringValue = correlationId - }, - ["EventType"] = new SnsMessageAttributeValue - { - DataType = "String", - StringValue = testEvent.GetType().Name - }, - ["DlqTest"] = new SnsMessageAttributeValue - { - DataType = "String", - StringValue = "true" - } - } - }); - - // Wait for delivery - await Task.Delay(2000); - - // Receive message from main queue - var mainReceiveResponse = await _testEnvironment.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = mainQueueUrl, - MaxNumberOfMessages = 1, - WaitTimeSeconds = 3, - MessageAttributeNames = new List { "All" } - }); - - Assert.Single(mainReceiveResponse.Messages); - var receivedMessage = mainReceiveResponse.Messages[0]; - - // Simulate processing failure by not deleting the message and letting it exceed maxReceiveCount - // In a real scenario, this would happen automatically when message processing fails - - // For testing purposes, we'll verify the DLQ setup is correct - var dlqReceiveResponse = await _testEnvironment.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = dlqUrl, - MaxNumberOfMessages = 1, - WaitTimeSeconds = 2, - MessageAttributeNames = new List { "All" } - }); - - // DLQ should be empty initially (message hasn't failed processing yet) - Assert.Empty(dlqReceiveResponse.Messages); - - // Verify main queue received the message with correlation ID - var snsMessage = JsonSerializer.Deserialize(receivedMessage.Body); - Assert.True(snsMessage?.MessageAttributes?.ContainsKey("CorrelationId")); - Assert.Equal(correlationId, snsMessage?.MessageAttributes?["CorrelationId"]?.Value); - - _logger.LogInformation("Successfully set up DLQ integration for SNS delivery - message received in main queue with CorrelationId {CorrelationId}", - correlationId); - } - - [Fact] - public async Task ErrorReporting_AndMonitoring_ShouldProvideDetailedErrorInformation() - { - // Arrange - var topicName = $"test-error-reporting-{Guid.NewGuid():N}"; - var topicArn = await _testEnvironment.CreateTopicAsync(topicName); - _createdTopics.Add(topicArn); - - var correlationId = Guid.NewGuid().ToString(); - var requestId = Guid.NewGuid().ToString(); - - // Create a valid subscriber for successful delivery tracking - var validQueueName = $"test-monitoring-queue-{Guid.NewGuid():N}"; - var validQueueUrl = await _testEnvironment.CreateStandardQueueAsync(validQueueName); - _createdQueues.Add(validQueueUrl); - var validQueueArn = await GetQueueArnAsync(validQueueUrl); - - var validSubscriptionResponse = await _testEnvironment.SnsClient.SubscribeAsync(new SubscribeRequest - { - TopicArn = topicArn, - Protocol = "sqs", - Endpoint = validQueueArn - }); - _createdSubscriptions.Add(validSubscriptionResponse.SubscriptionArn); - await SetQueuePolicyForSns(validQueueUrl, validQueueArn, topicArn); - - var testEvent = new TestEvent(new TestEventData - { - Id = 12345, - Message = "Error reporting test event", - Value = 67890 - }); - - // Act - Publish event with comprehensive metadata for monitoring - var publishStartTime = DateTime.UtcNow; - var publishResponse = await _testEnvironment.SnsClient.PublishAsync(new PublishRequest - { - TopicArn = topicArn, - Message = JsonSerializer.Serialize(testEvent), - Subject = testEvent.Name, - MessageAttributes = new Dictionary - { - ["CorrelationId"] = new SnsMessageAttributeValue - { - DataType = "String", - StringValue = correlationId - }, - ["RequestId"] = new SnsMessageAttributeValue - { - DataType = "String", - StringValue = requestId - }, - ["EventType"] = new SnsMessageAttributeValue - { - DataType = "String", - StringValue = testEvent.GetType().Name - }, - ["PublishTimestamp"] = new SnsMessageAttributeValue - { - DataType = "String", - StringValue = publishStartTime.ToString("O") - }, - ["Source"] = new SnsMessageAttributeValue - { - DataType = "String", - StringValue = "ErrorReportingTest" - }, - ["Environment"] = new SnsMessageAttributeValue - { - DataType = "String", - StringValue = _testEnvironment.IsLocalEmulator ? "LocalStack" : "AWS" - } - } - }); - - var publishEndTime = DateTime.UtcNow; - var publishLatency = publishEndTime - publishStartTime; - - // Assert - Verify successful publish with detailed monitoring data - Assert.NotNull(publishResponse.MessageId); - Assert.NotEmpty(publishResponse.MessageId); - - // Wait for delivery - await Task.Delay(2000); - - // Verify message delivery with all monitoring attributes - var receiveResponse = await _testEnvironment.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = validQueueUrl, - MaxNumberOfMessages = 1, - WaitTimeSeconds = 5, - MessageAttributeNames = new List { "All" } - }); - - Assert.Single(receiveResponse.Messages); - - var receivedMessage = receiveResponse.Messages[0]; - var snsMessage = JsonSerializer.Deserialize(receivedMessage.Body); - - // Verify all monitoring attributes are preserved - var monitoringAttributes = new[] - { - "CorrelationId", "RequestId", "EventType", "PublishTimestamp", "Source", "Environment" - }; - - foreach (var attribute in monitoringAttributes) - { - Assert.True(snsMessage?.MessageAttributes?.ContainsKey(attribute), - $"Monitoring attribute {attribute} is missing"); - } - - // Verify specific values - Assert.Equal(correlationId, snsMessage?.MessageAttributes?["CorrelationId"]?.Value); - Assert.Equal(requestId, snsMessage?.MessageAttributes?["RequestId"]?.Value); - Assert.Equal(testEvent.GetType().Name, snsMessage?.MessageAttributes?["EventType"]?.Value); - - // Log comprehensive monitoring information - _logger.LogInformation("Error reporting and monitoring test completed successfully. " + - "MessageId: {MessageId}, CorrelationId: {CorrelationId}, RequestId: {RequestId}, " + - "PublishLatency: {PublishLatency}ms, Environment: {Environment}", - publishResponse.MessageId, correlationId, requestId, publishLatency.TotalMilliseconds, - _testEnvironment.IsLocalEmulator ? "LocalStack" : "AWS"); - } - - [Fact] - public async Task CorrelationId_ChainedEventProcessing_ShouldMaintainTraceabilityAcrossEventChain() - { - // Arrange - Create a chain of topics to simulate event processing workflow - var topics = new List<(string Name, string Arn)>(); - var queues = new List<(string Name, string Url, string Arn)>(); - - // Create topic chain: OrderCreated -> PaymentProcessed -> OrderCompleted - var topicNames = new[] { "OrderCreated", "PaymentProcessed", "OrderCompleted" }; - - foreach (var topicName in topicNames) - { - var fullTopicName = $"test-chain-{topicName.ToLower()}-{Guid.NewGuid():N}"; - var topicArn = await _testEnvironment.CreateTopicAsync(fullTopicName); - _createdTopics.Add(topicArn); - topics.Add((topicName, topicArn)); - - // Create corresponding queue - var queueName = $"test-{topicName.ToLower()}-processor-{Guid.NewGuid():N}"; - var queueUrl = await _testEnvironment.CreateStandardQueueAsync(queueName); - _createdQueues.Add(queueUrl); - var queueArn = await GetQueueArnAsync(queueUrl); - queues.Add((topicName, queueUrl, queueArn)); - - // Subscribe queue to topic - var subscriptionResponse = await _testEnvironment.SnsClient.SubscribeAsync(new SubscribeRequest - { - TopicArn = topicArn, - Protocol = "sqs", - Endpoint = queueArn - }); - _createdSubscriptions.Add(subscriptionResponse.SubscriptionArn); - - await SetQueuePolicyForSns(queueUrl, queueArn, topicArn); - } - - var originalCorrelationId = Guid.NewGuid().ToString(); - var orderId = Guid.NewGuid().ToString(); - - // Act - Simulate event chain processing - var eventChain = new[] - { - new { TopicIndex = 0, EventType = "OrderCreatedEvent", Message = "Order created successfully", StepId = "step-1" }, - new { TopicIndex = 1, EventType = "PaymentProcessedEvent", Message = "Payment processed successfully", StepId = "step-2" }, - new { TopicIndex = 2, EventType = "OrderCompletedEvent", Message = "Order completed successfully", StepId = "step-3" } - }; - - foreach (var eventStep in eventChain) - { - var testEvent = new TestEvent(new TestEventData - { - Id = Array.IndexOf(eventChain, eventStep) + 1, - Message = eventStep.Message, - Value = 1000 + Array.IndexOf(eventChain, eventStep) * 100 - }); - - await _testEnvironment.SnsClient.PublishAsync(new PublishRequest - { - TopicArn = topics[eventStep.TopicIndex].Arn, - Message = JsonSerializer.Serialize(testEvent), - Subject = testEvent.Name, - MessageAttributes = new Dictionary - { - ["CorrelationId"] = new SnsMessageAttributeValue - { - DataType = "String", - StringValue = originalCorrelationId - }, - ["OrderId"] = new SnsMessageAttributeValue - { - DataType = "String", - StringValue = orderId - }, - ["EventType"] = new SnsMessageAttributeValue - { - DataType = "String", - StringValue = eventStep.EventType - }, - ["StepId"] = new SnsMessageAttributeValue - { - DataType = "String", - StringValue = eventStep.StepId - }, - ["ChainPosition"] = new SnsMessageAttributeValue - { - DataType = "Number", - StringValue = (Array.IndexOf(eventChain, eventStep) + 1).ToString() - }, - ["Timestamp"] = new SnsMessageAttributeValue - { - DataType = "String", - StringValue = DateTime.UtcNow.ToString("O") - } - } - }); - - // Small delay between events to simulate processing time - await Task.Delay(500); - } - - // Wait for all deliveries - await Task.Delay(3000); - - // Assert - Verify correlation ID is maintained across entire event chain - var chainResults = new List<(string EventType, string? CorrelationId, string? OrderId, string? StepId)>(); - - for (int i = 0; i < queues.Count; i++) - { - var (topicName, queueUrl, _) = queues[i]; - - var receiveResponse = await _testEnvironment.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = queueUrl, - MaxNumberOfMessages = 1, - WaitTimeSeconds = 3, - MessageAttributeNames = new List { "All" } - }); - - Assert.Single(receiveResponse.Messages); - - var receivedMessage = receiveResponse.Messages[0]; - var snsMessage = JsonSerializer.Deserialize(receivedMessage.Body); - - var receivedCorrelationId = snsMessage?.MessageAttributes?["CorrelationId"]?.Value; - var receivedOrderId = snsMessage?.MessageAttributes?["OrderId"]?.Value; - var receivedStepId = snsMessage?.MessageAttributes?["StepId"]?.Value; - var receivedEventType = snsMessage?.MessageAttributes?["EventType"]?.Value; - - chainResults.Add((receivedEventType ?? "", receivedCorrelationId, receivedOrderId, receivedStepId)); - - // Verify correlation ID and order ID are preserved - Assert.Equal(originalCorrelationId, receivedCorrelationId); - Assert.Equal(orderId, receivedOrderId); - Assert.NotNull(receivedStepId); - } - - // All events in the chain should have the same correlation ID and order ID - Assert.All(chainResults, result => - { - Assert.Equal(originalCorrelationId, result.CorrelationId); - Assert.Equal(orderId, result.OrderId); - Assert.NotNull(result.StepId); - }); - - _logger.LogInformation("Successfully maintained correlation ID {CorrelationId} and OrderId {OrderId} across event chain: {EventTypes}", - originalCorrelationId, orderId, string.Join(" -> ", chainResults.Select(r => r.EventType))); - } - - private async Task GetQueueArnAsync(string queueUrl) - { - var response = await _testEnvironment.SqsClient.GetQueueAttributesAsync(new GetQueueAttributesRequest - { - QueueUrl = queueUrl, - AttributeNames = new List { "QueueArn" } - }); - - return response.Attributes["QueueArn"]; - } - - private async Task SetQueuePolicyForSns(string queueUrl, string queueArn, string topicArn) - { - var policy = $@"{{ - ""Version"": ""2012-10-17"", - ""Statement"": [ - {{ - ""Effect"": ""Allow"", - ""Principal"": {{ - ""Service"": ""sns.amazonaws.com"" - }}, - ""Action"": ""sqs:SendMessage"", - ""Resource"": ""{queueArn}"", - ""Condition"": {{ - ""ArnEquals"": {{ - ""aws:SourceArn"": ""{topicArn}"" - }} - }} - }} - ] - }}"; - - await _testEnvironment.SqsClient.SetQueueAttributesAsync(new SetQueueAttributesRequest - { - QueueUrl = queueUrl, - Attributes = new Dictionary - { - ["Policy"] = policy - } - }); - } -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/Integration/SnsEventPublishingPropertyTests.cs b/tests/SourceFlow.Cloud.AWS.Tests/Integration/SnsEventPublishingPropertyTests.cs deleted file mode 100644 index c579bfb4..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/Integration/SnsEventPublishingPropertyTests.cs +++ /dev/null @@ -1,592 +0,0 @@ -using Amazon.SimpleNotificationService; -using Amazon.SimpleNotificationService.Model; -using Amazon.SQS; -using Amazon.SQS.Model; -using FsCheck; -using FsCheck.Xunit; -using Microsoft.Extensions.DependencyInjection; -using Microsoft.Extensions.Logging; -using SourceFlow.Cloud.AWS.Tests.TestHelpers; -using System.Text.Json; -using SnsMessageAttributeValue = Amazon.SimpleNotificationService.Model.MessageAttributeValue; - -namespace SourceFlow.Cloud.AWS.Tests.Integration; - -/// -/// Property-based tests for SNS event publishing correctness -/// **Property 3: SNS Event Publishing Correctness** -/// **Validates: Requirements 2.1, 2.2, 2.4** -/// -[Collection("AWS Integration Tests")] -[Trait("Category", "Integration")] -[Trait("Category", "RequiresLocalStack")] -public class SnsEventPublishingPropertyTests : IAsyncLifetime -{ - private readonly IAwsTestEnvironment _testEnvironment; - private readonly ILogger _logger; - private readonly List _createdTopics = new(); - private readonly List _createdQueues = new(); - private readonly List _createdSubscriptions = new(); - - // FsCheck [Property] tests require a constructor that FsCheck can invoke. - // ITestOutputHelper cannot be injected by FsCheck — use ILogger instead. - public SnsEventPublishingPropertyTests() - { - var services = new ServiceCollection(); - services.AddLogging(builder => builder.AddConsole().SetMinimumLevel(LogLevel.Debug)); - - var serviceProvider = services.BuildServiceProvider(); - _logger = serviceProvider.GetRequiredService>(); - - _testEnvironment = AwsTestEnvironmentFactory.CreateLocalStackEnvironmentAsync().GetAwaiter().GetResult(); - } - - public async Task InitializeAsync() - { - await _testEnvironment.InitializeAsync(); - - if (!await _testEnvironment.IsAvailableAsync()) - { - throw new InvalidOperationException("AWS test environment is not available"); - } - - _logger.LogInformation("SNS event publishing property tests initialized"); - } - - public async Task DisposeAsync() - { - // Clean up subscriptions first - foreach (var subscriptionArn in _createdSubscriptions) - { - try - { - await _testEnvironment.SnsClient.UnsubscribeAsync(new UnsubscribeRequest - { - SubscriptionArn = subscriptionArn - }); - } - catch (Exception ex) - { - _logger.LogWarning("Failed to delete subscription {SubscriptionArn}: {Error}", subscriptionArn, ex.Message); - } - } - - // Clean up topics - foreach (var topicArn in _createdTopics) - { - try - { - await _testEnvironment.DeleteTopicAsync(topicArn); - } - catch (Exception ex) - { - _logger.LogWarning("Failed to delete topic {TopicArn}: {Error}", topicArn, ex.Message); - } - } - - // Clean up queues - foreach (var queueUrl in _createdQueues) - { - try - { - await _testEnvironment.DeleteQueueAsync(queueUrl); - } - catch (Exception ex) - { - _logger.LogWarning("Failed to delete queue {QueueUrl}: {Error}", queueUrl, ex.Message); - } - } - - await _testEnvironment.DisposeAsync(); - _logger.LogInformation("SNS event publishing property tests disposed"); - } - - /// - /// Property 3: SNS Event Publishing Correctness - /// **Validates: Requirements 2.1, 2.2, 2.4** - /// - /// For any valid SourceFlow event and SNS topic configuration, when the event is published, - /// it should be delivered to all subscribers with proper message attributes, correlation ID preservation, - /// and fan-out messaging to multiple subscriber types (SQS, Lambda, HTTP). - /// - [Property(MaxTest = 5, Arbitrary = new[] { typeof(SnsEventPublishingGenerators) })] - public void SnsEventPublishingCorrectness(SnsEventPublishingScenario scenario) - { - try - { - _logger.LogInformation("Testing SNS event publishing correctness with scenario: {Scenario}", - JsonSerializer.Serialize(scenario, new JsonSerializerOptions { WriteIndented = true })); - - // Property 1: Event publishing should succeed with proper message attributes - var publishingValid = ValidateEventPublishing(scenario).GetAwaiter().GetResult(); - - // Property 2: Fan-out messaging should deliver to all subscribers - var fanOutValid = ValidateFanOutMessaging(scenario).GetAwaiter().GetResult(); - - // Property 3: Correlation ID should be preserved across subscriptions - var correlationValid = ValidateCorrelationIdPreservation(scenario).GetAwaiter().GetResult(); - - // Property 4: Message attributes should be preserved - var attributesValid = ValidateMessageAttributePreservation(scenario).GetAwaiter().GetResult(); - - var result = publishingValid && fanOutValid && correlationValid && attributesValid; - - if (!result) - { - _logger.LogWarning("SNS event publishing correctness failed for scenario: {Scenario}. " + - "Publishing: {Publishing}, FanOut: {FanOut}, Correlation: {Correlation}, Attributes: {Attributes}", - JsonSerializer.Serialize(scenario), publishingValid, fanOutValid, correlationValid, attributesValid); - } - - Assert.True(result, "SNS event publishing correctness validation failed"); - } - catch (Exception ex) - { - _logger.LogError(ex, "SNS event publishing correctness test failed with exception for scenario: {Scenario}", - JsonSerializer.Serialize(scenario)); - throw; - } - } - - private async Task ValidateEventPublishing(SnsEventPublishingScenario scenario) - { - try - { - // Create topic - var topicName = $"prop-test-topic-{Guid.NewGuid():N}"; - var topicArn = await _testEnvironment.CreateTopicAsync(topicName); - _createdTopics.Add(topicArn); - - // Create test event - var testEvent = new TestEvent(new TestEventData - { - Id = scenario.EventId, - Message = scenario.EventMessage, - Value = scenario.EventValue - }); - - // Publish event - var publishResponse = await _testEnvironment.SnsClient.PublishAsync(new PublishRequest - { - TopicArn = topicArn, - Message = JsonSerializer.Serialize(testEvent), - Subject = testEvent.Name, - MessageAttributes = CreateMessageAttributes(scenario, testEvent) - }); - - // Validate publish response - var publishValid = publishResponse?.MessageId != null && !string.IsNullOrEmpty(publishResponse.MessageId); - - if (!publishValid) - { - _logger.LogWarning("Event publishing validation failed: MessageId is null or empty"); - } - - return publishValid; - } - catch (Exception ex) - { - _logger.LogWarning("Event publishing validation failed with exception: {Error}", ex.Message); - return false; - } - } - - private async Task ValidateFanOutMessaging(SnsEventPublishingScenario scenario) - { - try - { - // Create topic - var topicName = $"prop-test-fanout-{Guid.NewGuid():N}"; - var topicArn = await _testEnvironment.CreateTopicAsync(topicName); - _createdTopics.Add(topicArn); - - // Create multiple SQS subscribers - var subscriberQueues = new List<(string QueueUrl, string QueueArn)>(); - for (int i = 0; i < scenario.SubscriberCount && i < 5; i++) // Limit to 5 for performance - { - var queueName = $"prop-test-sub-{i}-{Guid.NewGuid():N}"; - var queueUrl = await _testEnvironment.CreateStandardQueueAsync(queueName); - _createdQueues.Add(queueUrl); - - var queueArn = await GetQueueArnAsync(queueUrl); - subscriberQueues.Add((queueUrl, queueArn)); - - // Subscribe to topic - var subscriptionResponse = await _testEnvironment.SnsClient.SubscribeAsync(new SubscribeRequest - { - TopicArn = topicArn, - Protocol = "sqs", - Endpoint = queueArn - }); - _createdSubscriptions.Add(subscriptionResponse.SubscriptionArn); - - // Set queue policy - await SetQueuePolicyForSns(queueUrl, queueArn, topicArn); - } - - // Create test event - var testEvent = new TestEvent(new TestEventData - { - Id = scenario.EventId, - Message = scenario.EventMessage, - Value = scenario.EventValue - }); - - // Publish event - await _testEnvironment.SnsClient.PublishAsync(new PublishRequest - { - TopicArn = topicArn, - Message = JsonSerializer.Serialize(testEvent), - Subject = testEvent.Name, - MessageAttributes = CreateMessageAttributes(scenario, testEvent) - }); - - // Wait for delivery - await Task.Delay(2000); - - // Verify all subscribers received the message - var deliveredCount = 0; - foreach (var (queueUrl, _) in subscriberQueues) - { - var receiveResponse = await _testEnvironment.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = queueUrl, - MaxNumberOfMessages = 10, - WaitTimeSeconds = 2 - }); - - if (receiveResponse.Messages.Count > 0) - { - deliveredCount++; - } - } - - var fanOutValid = deliveredCount == subscriberQueues.Count; - - if (!fanOutValid) - { - _logger.LogWarning("Fan-out messaging validation failed: {DeliveredCount}/{ExpectedCount} subscribers received messages", - deliveredCount, subscriberQueues.Count); - } - - return fanOutValid; - } - catch (Exception ex) - { - _logger.LogWarning("Fan-out messaging validation failed with exception: {Error}", ex.Message); - return false; - } - } - - private async Task ValidateCorrelationIdPreservation(SnsEventPublishingScenario scenario) - { - try - { - // Create topic and subscriber - var topicName = $"prop-test-correlation-{Guid.NewGuid():N}"; - var topicArn = await _testEnvironment.CreateTopicAsync(topicName); - _createdTopics.Add(topicArn); - - var queueName = $"prop-test-corr-queue-{Guid.NewGuid():N}"; - var queueUrl = await _testEnvironment.CreateStandardQueueAsync(queueName); - _createdQueues.Add(queueUrl); - - var queueArn = await GetQueueArnAsync(queueUrl); - var subscriptionResponse = await _testEnvironment.SnsClient.SubscribeAsync(new SubscribeRequest - { - TopicArn = topicArn, - Protocol = "sqs", - Endpoint = queueArn - }); - _createdSubscriptions.Add(subscriptionResponse.SubscriptionArn); - - await SetQueuePolicyForSns(queueUrl, queueArn, topicArn); - - // Create test event with correlation ID - var testEvent = new TestEvent(new TestEventData - { - Id = scenario.EventId, - Message = scenario.EventMessage, - Value = scenario.EventValue - }); - - var correlationId = scenario.CorrelationId ?? Guid.NewGuid().ToString(); - var messageAttributes = CreateMessageAttributes(scenario, testEvent); - messageAttributes["CorrelationId"] = new SnsMessageAttributeValue - { - DataType = "String", - StringValue = correlationId - }; - - // Publish event - await _testEnvironment.SnsClient.PublishAsync(new PublishRequest - { - TopicArn = topicArn, - Message = JsonSerializer.Serialize(testEvent), - Subject = testEvent.Name, - MessageAttributes = messageAttributes - }); - - // Wait for delivery - await Task.Delay(1500); - - // Receive and verify correlation ID - var receiveResponse = await _testEnvironment.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = queueUrl, - MaxNumberOfMessages = 1, - WaitTimeSeconds = 3, - MessageAttributeNames = new List { "All" } - }); - - if (receiveResponse.Messages.Count == 0) - { - _logger.LogWarning("Correlation ID validation failed: No messages received"); - return false; - } - - var receivedMessage = receiveResponse.Messages[0]; - - // Parse SNS message (SQS receives SNS messages wrapped in JSON) - var snsMessage = JsonSerializer.Deserialize(receivedMessage.Body); - var snsMessageAttributes = snsMessage?.MessageAttributes; - - var correlationValid = snsMessageAttributes?.ContainsKey("CorrelationId") == true && - snsMessageAttributes["CorrelationId"]?.Value == correlationId; - - if (!correlationValid) - { - _logger.LogWarning("Correlation ID validation failed: Expected {ExpectedId}, but correlation ID not found or mismatched in received message", - correlationId); - } - - return correlationValid; - } - catch (Exception ex) - { - _logger.LogWarning("Correlation ID validation failed with exception: {Error}", ex.Message); - return false; - } - } - - private async Task ValidateMessageAttributePreservation(SnsEventPublishingScenario scenario) - { - try - { - // Create topic and subscriber - var topicName = $"prop-test-attrs-{Guid.NewGuid():N}"; - var topicArn = await _testEnvironment.CreateTopicAsync(topicName); - _createdTopics.Add(topicArn); - - var queueName = $"prop-test-attrs-queue-{Guid.NewGuid():N}"; - var queueUrl = await _testEnvironment.CreateStandardQueueAsync(queueName); - _createdQueues.Add(queueUrl); - - var queueArn = await GetQueueArnAsync(queueUrl); - var subscriptionResponse = await _testEnvironment.SnsClient.SubscribeAsync(new SubscribeRequest - { - TopicArn = topicArn, - Protocol = "sqs", - Endpoint = queueArn - }); - _createdSubscriptions.Add(subscriptionResponse.SubscriptionArn); - - await SetQueuePolicyForSns(queueUrl, queueArn, topicArn); - - // Create test event - var testEvent = new TestEvent(new TestEventData - { - Id = scenario.EventId, - Message = scenario.EventMessage, - Value = scenario.EventValue - }); - - var messageAttributes = CreateMessageAttributes(scenario, testEvent); - - // Publish event - await _testEnvironment.SnsClient.PublishAsync(new PublishRequest - { - TopicArn = topicArn, - Message = JsonSerializer.Serialize(testEvent), - Subject = testEvent.Name, - MessageAttributes = messageAttributes - }); - - // Wait for delivery - await Task.Delay(1500); - - // Receive and verify attributes - var receiveResponse = await _testEnvironment.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = queueUrl, - MaxNumberOfMessages = 1, - WaitTimeSeconds = 3, - MessageAttributeNames = new List { "All" } - }); - - if (receiveResponse.Messages.Count == 0) - { - _logger.LogWarning("Message attribute validation failed: No messages received"); - return false; - } - - var receivedMessage = receiveResponse.Messages[0]; - - // Parse SNS message - var snsMessage = JsonSerializer.Deserialize(receivedMessage.Body); - var snsMessageAttributes = snsMessage?.MessageAttributes; - - // Verify key attributes are preserved - var eventTypeValid = snsMessageAttributes?.ContainsKey("EventType") == true && - snsMessageAttributes["EventType"]?.Value == testEvent.GetType().Name; - - var eventNameValid = snsMessageAttributes?.ContainsKey("EventName") == true && - snsMessageAttributes["EventName"]?.Value == testEvent.Name; - - var entityIdValid = snsMessageAttributes?.ContainsKey("EntityId") == true && - snsMessageAttributes["EntityId"]?.Value == scenario.EventId.ToString(); - - var attributesValid = eventTypeValid && eventNameValid && entityIdValid; - - if (!attributesValid) - { - _logger.LogWarning("Message attribute validation failed: EventType={EventType}, EventName={EventName}, EntityId={EntityId}", - eventTypeValid, eventNameValid, entityIdValid); - } - - return attributesValid; - } - catch (Exception ex) - { - _logger.LogWarning("Message attribute validation failed with exception: {Error}", ex.Message); - return false; - } - } - - private Dictionary CreateMessageAttributes(SnsEventPublishingScenario scenario, TestEvent testEvent) - { - var attributes = new Dictionary - { - ["EventType"] = new SnsMessageAttributeValue - { - DataType = "String", - StringValue = testEvent.GetType().Name - }, - ["EventName"] = new SnsMessageAttributeValue - { - DataType = "String", - StringValue = testEvent.Name - }, - ["EntityId"] = new SnsMessageAttributeValue - { - DataType = "Number", - StringValue = scenario.EventId.ToString() - } - }; - - // Add custom attributes from scenario - foreach (var customAttr in scenario.CustomAttributes) - { - attributes[customAttr.Key] = new SnsMessageAttributeValue - { - DataType = "String", - StringValue = customAttr.Value - }; - } - - return attributes; - } - - private async Task GetQueueArnAsync(string queueUrl) - { - var response = await _testEnvironment.SqsClient.GetQueueAttributesAsync(new GetQueueAttributesRequest - { - QueueUrl = queueUrl, - AttributeNames = new List { "QueueArn" } - }); - - return response.Attributes["QueueArn"]; - } - - private async Task SetQueuePolicyForSns(string queueUrl, string queueArn, string topicArn) - { - var policy = $@"{{ - ""Version"": ""2012-10-17"", - ""Statement"": [ - {{ - ""Effect"": ""Allow"", - ""Principal"": {{ - ""Service"": ""sns.amazonaws.com"" - }}, - ""Action"": ""sqs:SendMessage"", - ""Resource"": ""{queueArn}"", - ""Condition"": {{ - ""ArnEquals"": {{ - ""aws:SourceArn"": ""{topicArn}"" - }} - }} - }} - ] - }}"; - - await _testEnvironment.SqsClient.SetQueueAttributesAsync(new SetQueueAttributesRequest - { - QueueUrl = queueUrl, - Attributes = new Dictionary - { - ["Policy"] = policy - } - }); - } -} - -/// -/// Generators for SNS event publishing property tests -/// -public static class SnsEventPublishingGenerators -{ - public static Arbitrary SnsEventPublishingScenario() - { - return Gen.Fresh(() => new SnsEventPublishingScenario - { - EventId = Gen.Choose(1, 10000).Sample(0, 1).First(), - EventMessage = Gen.Elements("Test message", "Property test event", "SNS publishing test", "Fan-out test message").Sample(0, 1).First(), - EventValue = Gen.Choose(1, 1000).Sample(0, 1).First(), - SubscriberCount = Gen.Choose(1, 3).Sample(0, 1).First(), // Keep small for performance - CorrelationId = Gen.Elements(null, Guid.NewGuid().ToString(), "test-correlation-id").Sample(0, 1).First(), - CustomAttributes = GenerateCustomAttributes() - }).ToArbitrary(); - } - - private static Dictionary GenerateCustomAttributes() - { - var attributeCount = Gen.Choose(0, 3).Sample(0, 1).First(); - var attributes = new Dictionary(); - - for (int i = 0; i < attributeCount; i++) - { - var key = Gen.Elements("Priority", "Source", "Category", "Environment").Sample(0, 1).First(); - var value = Gen.Elements("High", "Medium", "Low", "Test", "Production").Sample(0, 1).First(); - - if (!attributes.ContainsKey(key)) - { - attributes[key] = value; - } - } - - return attributes; - } -} - -/// -/// Test scenario for SNS event publishing property tests -/// -public class SnsEventPublishingScenario -{ - public int EventId { get; set; } - public string EventMessage { get; set; } = ""; - public int EventValue { get; set; } - public int SubscriberCount { get; set; } - public string? CorrelationId { get; set; } - public Dictionary CustomAttributes { get; set; } = new(); -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/Integration/SnsFanOutMessagingIntegrationTests.cs b/tests/SourceFlow.Cloud.AWS.Tests/Integration/SnsFanOutMessagingIntegrationTests.cs deleted file mode 100644 index 13250d1a..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/Integration/SnsFanOutMessagingIntegrationTests.cs +++ /dev/null @@ -1,611 +0,0 @@ -using Amazon.SimpleNotificationService; -using Amazon.SimpleNotificationService.Model; -using Amazon.SQS; -using Amazon.SQS.Model; -using Microsoft.Extensions.DependencyInjection; -using Microsoft.Extensions.Logging; -using SourceFlow.Cloud.AWS.Tests.TestHelpers; -using System.Text.Json; -using Xunit.Abstractions; -using SnsMessageAttributeValue = Amazon.SimpleNotificationService.Model.MessageAttributeValue; -using SqsMessageAttributeValue = Amazon.SQS.Model.MessageAttributeValue; - -namespace SourceFlow.Cloud.AWS.Tests.Integration; - -/// -/// Integration tests for SNS fan-out messaging functionality -/// Tests event delivery to multiple subscriber types (SQS, Lambda, HTTP) with subscription management -/// **Validates: Requirements 2.2** -/// -[Collection("AWS Integration Tests")] -[Trait("Category", "Integration")] -[Trait("Category", "RequiresLocalStack")] -public class SnsFanOutMessagingIntegrationTests : IAsyncLifetime -{ - private readonly ITestOutputHelper _output; - private readonly IAwsTestEnvironment _testEnvironment; - private readonly ILogger _logger; - private readonly List _createdTopics = new(); - private readonly List _createdQueues = new(); - private readonly List _createdSubscriptions = new(); - - public SnsFanOutMessagingIntegrationTests(ITestOutputHelper output) - { - _output = output; - - var services = new ServiceCollection(); - services.AddLogging(builder => builder.AddConsole().SetMinimumLevel(LogLevel.Debug)); - - var serviceProvider = services.BuildServiceProvider(); - _logger = serviceProvider.GetRequiredService>(); - - _testEnvironment = AwsTestEnvironmentFactory.CreateLocalStackEnvironmentAsync().GetAwaiter().GetResult(); - } - - public async Task InitializeAsync() - { - await _testEnvironment.InitializeAsync(); - - if (!await _testEnvironment.IsAvailableAsync()) - { - throw new InvalidOperationException("AWS test environment is not available"); - } - - _logger.LogInformation("SNS fan-out messaging integration tests initialized"); - } - - public async Task DisposeAsync() - { - // Clean up subscriptions first - foreach (var subscriptionArn in _createdSubscriptions) - { - try - { - await _testEnvironment.SnsClient.UnsubscribeAsync(new UnsubscribeRequest - { - SubscriptionArn = subscriptionArn - }); - } - catch (Exception ex) - { - _logger.LogWarning("Failed to delete subscription {SubscriptionArn}: {Error}", subscriptionArn, ex.Message); - } - } - - // Clean up topics - foreach (var topicArn in _createdTopics) - { - try - { - await _testEnvironment.DeleteTopicAsync(topicArn); - } - catch (Exception ex) - { - _logger.LogWarning("Failed to delete topic {TopicArn}: {Error}", topicArn, ex.Message); - } - } - - // Clean up queues - foreach (var queueUrl in _createdQueues) - { - try - { - await _testEnvironment.DeleteQueueAsync(queueUrl); - } - catch (Exception ex) - { - _logger.LogWarning("Failed to delete queue {QueueUrl}: {Error}", queueUrl, ex.Message); - } - } - - await _testEnvironment.DisposeAsync(); - _logger.LogInformation("SNS fan-out messaging integration tests disposed"); - } - - [Fact] - public async Task FanOutMessage_ToMultipleSqsSubscribers_ShouldDeliverToAll() - { - // Arrange - var topicName = $"test-fanout-topic-{Guid.NewGuid():N}"; - var topicArn = await _testEnvironment.CreateTopicAsync(topicName); - _createdTopics.Add(topicArn); - - // Create multiple SQS queues as subscribers - var subscriberQueues = new List<(string QueueUrl, string QueueArn)>(); - for (int i = 0; i < 3; i++) - { - var queueName = $"test-subscriber-queue-{i}-{Guid.NewGuid():N}"; - var queueUrl = await _testEnvironment.CreateStandardQueueAsync(queueName); - _createdQueues.Add(queueUrl); - - var queueArn = await GetQueueArnAsync(queueUrl); - subscriberQueues.Add((queueUrl, queueArn)); - - // Subscribe queue to topic - var subscriptionResponse = await _testEnvironment.SnsClient.SubscribeAsync(new SubscribeRequest - { - TopicArn = topicArn, - Protocol = "sqs", - Endpoint = queueArn - }); - _createdSubscriptions.Add(subscriptionResponse.SubscriptionArn); - - // Set queue policy to allow SNS to send messages - await SetQueuePolicyForSns(queueUrl, queueArn, topicArn); - } - - var testEvent = new TestEvent(new TestEventData - { - Id = 123, - Message = "Fan-out test message", - Value = 456 - }); - - // Act - var publishResponse = await _testEnvironment.SnsClient.PublishAsync(new PublishRequest - { - TopicArn = topicArn, - Message = JsonSerializer.Serialize(testEvent), - Subject = testEvent.Name, - MessageAttributes = new Dictionary - { - ["EventType"] = new SnsMessageAttributeValue - { - DataType = "String", - StringValue = testEvent.GetType().Name - }, - ["FanOutTest"] = new SnsMessageAttributeValue - { - DataType = "String", - StringValue = "true" - } - } - }); - - // Assert - Assert.NotNull(publishResponse.MessageId); - - // Wait a bit for message delivery - await Task.Delay(2000); - - // Verify each subscriber received the message - var receivedMessages = new List(); - foreach (var (queueUrl, _) in subscriberQueues) - { - var receiveResponse = await _testEnvironment.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = queueUrl, - MaxNumberOfMessages = 10, - WaitTimeSeconds = 5, - MessageAttributeNames = new List { "All" } - }); - - Assert.NotEmpty(receiveResponse.Messages); - receivedMessages.AddRange(receiveResponse.Messages); - - _logger.LogInformation("Queue {QueueUrl} received {MessageCount} messages", queueUrl, receiveResponse.Messages.Count); - } - - // All subscribers should have received the message - Assert.Equal(subscriberQueues.Count, receivedMessages.Count); - - _logger.LogInformation("Successfully delivered fan-out message to {SubscriberCount} SQS subscribers", subscriberQueues.Count); - } - - [Fact] - public async Task FanOutMessage_WithSubscriptionManagement_ShouldHandleSubscriptionChanges() - { - // Arrange - var topicName = $"test-subscription-mgmt-{Guid.NewGuid():N}"; - var topicArn = await _testEnvironment.CreateTopicAsync(topicName); - _createdTopics.Add(topicArn); - - // Create initial subscriber - var queueName1 = $"test-sub-queue-1-{Guid.NewGuid():N}"; - var queueUrl1 = await _testEnvironment.CreateStandardQueueAsync(queueName1); - _createdQueues.Add(queueUrl1); - var queueArn1 = await GetQueueArnAsync(queueUrl1); - - var subscription1Response = await _testEnvironment.SnsClient.SubscribeAsync(new SubscribeRequest - { - TopicArn = topicArn, - Protocol = "sqs", - Endpoint = queueArn1 - }); - _createdSubscriptions.Add(subscription1Response.SubscriptionArn); - await SetQueuePolicyForSns(queueUrl1, queueArn1, topicArn); - - // Publish first message - var testEvent1 = new TestEvent(new TestEventData - { - Id = 100, - Message = "First message", - Value = 200 - }); - - await _testEnvironment.SnsClient.PublishAsync(new PublishRequest - { - TopicArn = topicArn, - Message = JsonSerializer.Serialize(testEvent1), - Subject = testEvent1.Name - }); - - await Task.Delay(1000); - - // Verify first subscriber received message - var receiveResponse1 = await _testEnvironment.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = queueUrl1, - MaxNumberOfMessages = 10, - WaitTimeSeconds = 2 - }); - - Assert.Single(receiveResponse1.Messages); - - // Add second subscriber - var queueName2 = $"test-sub-queue-2-{Guid.NewGuid():N}"; - var queueUrl2 = await _testEnvironment.CreateStandardQueueAsync(queueName2); - _createdQueues.Add(queueUrl2); - var queueArn2 = await GetQueueArnAsync(queueUrl2); - - var subscription2Response = await _testEnvironment.SnsClient.SubscribeAsync(new SubscribeRequest - { - TopicArn = topicArn, - Protocol = "sqs", - Endpoint = queueArn2 - }); - _createdSubscriptions.Add(subscription2Response.SubscriptionArn); - await SetQueuePolicyForSns(queueUrl2, queueArn2, topicArn); - - // Publish second message - var testEvent2 = new TestEvent(new TestEventData - { - Id = 300, - Message = "Second message", - Value = 400 - }); - - await _testEnvironment.SnsClient.PublishAsync(new PublishRequest - { - TopicArn = topicArn, - Message = JsonSerializer.Serialize(testEvent2), - Subject = testEvent2.Name - }); - - await Task.Delay(1000); - - // Verify both subscribers received second message - var receiveResponse2a = await _testEnvironment.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = queueUrl1, - MaxNumberOfMessages = 10, - WaitTimeSeconds = 2 - }); - - var receiveResponse2b = await _testEnvironment.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = queueUrl2, - MaxNumberOfMessages = 10, - WaitTimeSeconds = 2 - }); - - Assert.NotEmpty(receiveResponse2a.Messages); - Assert.NotEmpty(receiveResponse2b.Messages); - - // Remove first subscriber - await _testEnvironment.SnsClient.UnsubscribeAsync(new UnsubscribeRequest - { - SubscriptionArn = subscription1Response.SubscriptionArn - }); - _createdSubscriptions.Remove(subscription1Response.SubscriptionArn); - - // Publish third message - var testEvent3 = new TestEvent(new TestEventData - { - Id = 500, - Message = "Third message", - Value = 600 - }); - - await _testEnvironment.SnsClient.PublishAsync(new PublishRequest - { - TopicArn = topicArn, - Message = JsonSerializer.Serialize(testEvent3), - Subject = testEvent3.Name - }); - - await Task.Delay(1000); - - // Verify only second subscriber received third message - var receiveResponse3a = await _testEnvironment.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = queueUrl1, - MaxNumberOfMessages = 10, - WaitTimeSeconds = 2 - }); - - var receiveResponse3b = await _testEnvironment.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = queueUrl2, - MaxNumberOfMessages = 10, - WaitTimeSeconds = 2 - }); - - // First queue should not receive third message (unsubscribed) - Assert.Empty(receiveResponse3a.Messages); - // Second queue should receive third message - Assert.NotEmpty(receiveResponse3b.Messages); - - _logger.LogInformation("Successfully tested subscription management with dynamic subscriber changes"); - } - - [Fact] - public async Task FanOutMessage_WithDeliveryRetryAndErrorHandling_ShouldHandleFailures() - { - // Arrange - var topicName = $"test-retry-topic-{Guid.NewGuid():N}"; - var topicArn = await _testEnvironment.CreateTopicAsync(topicName); - _createdTopics.Add(topicArn); - - // Create a valid subscriber queue - var validQueueName = $"test-valid-queue-{Guid.NewGuid():N}"; - var validQueueUrl = await _testEnvironment.CreateStandardQueueAsync(validQueueName); - _createdQueues.Add(validQueueUrl); - var validQueueArn = await GetQueueArnAsync(validQueueUrl); - - var validSubscriptionResponse = await _testEnvironment.SnsClient.SubscribeAsync(new SubscribeRequest - { - TopicArn = topicArn, - Protocol = "sqs", - Endpoint = validQueueArn - }); - _createdSubscriptions.Add(validSubscriptionResponse.SubscriptionArn); - await SetQueuePolicyForSns(validQueueUrl, validQueueArn, topicArn); - - // Create an invalid HTTP endpoint subscriber (will fail delivery) - var invalidHttpSubscriptionResponse = await _testEnvironment.SnsClient.SubscribeAsync(new SubscribeRequest - { - TopicArn = topicArn, - Protocol = "http", - Endpoint = "http://invalid-endpoint-that-does-not-exist.com/webhook" - }); - _createdSubscriptions.Add(invalidHttpSubscriptionResponse.SubscriptionArn); - - var testEvent = new TestEvent(new TestEventData - { - Id = 777, - Message = "Retry test message", - Value = 888 - }); - - // Act - var publishResponse = await _testEnvironment.SnsClient.PublishAsync(new PublishRequest - { - TopicArn = topicArn, - Message = JsonSerializer.Serialize(testEvent), - Subject = testEvent.Name, - MessageAttributes = new Dictionary - { - ["EventType"] = new SnsMessageAttributeValue - { - DataType = "String", - StringValue = testEvent.GetType().Name - }, - ["RetryTest"] = new SnsMessageAttributeValue - { - DataType = "String", - StringValue = "true" - } - } - }); - - // Assert - Assert.NotNull(publishResponse.MessageId); - - // Wait for delivery attempts - await Task.Delay(3000); - - // Valid subscriber should receive the message - var receiveResponse = await _testEnvironment.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = validQueueUrl, - MaxNumberOfMessages = 10, - WaitTimeSeconds = 5 - }); - - Assert.NotEmpty(receiveResponse.Messages); - - // Check subscription attributes for delivery policy (if supported) - try - { - var subscriptionAttributes = await _testEnvironment.SnsClient.GetSubscriptionAttributesAsync( - new GetSubscriptionAttributesRequest - { - SubscriptionArn = validSubscriptionResponse.SubscriptionArn - }); - - Assert.NotNull(subscriptionAttributes.Attributes); - _logger.LogInformation("Valid subscription attributes retrieved successfully"); - } - catch (Exception ex) - { - _logger.LogWarning("Could not retrieve subscription attributes (might not be supported in LocalStack): {Error}", ex.Message); - } - - _logger.LogInformation("Successfully tested delivery retry and error handling with mixed subscriber types"); - } - - [Fact] - public async Task FanOutMessage_PerformanceAndScalability_ShouldHandleMultipleSubscribers() - { - // Arrange - var topicName = $"test-perf-fanout-{Guid.NewGuid():N}"; - var topicArn = await _testEnvironment.CreateTopicAsync(topicName); - _createdTopics.Add(topicArn); - - const int subscriberCount = 10; - const int messageCount = 20; - var subscriberQueues = new List<(string QueueUrl, string QueueArn)>(); - - // Create multiple subscribers - for (int i = 0; i < subscriberCount; i++) - { - var queueName = $"test-perf-queue-{i}-{Guid.NewGuid():N}"; - var queueUrl = await _testEnvironment.CreateStandardQueueAsync(queueName); - _createdQueues.Add(queueUrl); - - var queueArn = await GetQueueArnAsync(queueUrl); - subscriberQueues.Add((queueUrl, queueArn)); - - var subscriptionResponse = await _testEnvironment.SnsClient.SubscribeAsync(new SubscribeRequest - { - TopicArn = topicArn, - Protocol = "sqs", - Endpoint = queueArn - }); - _createdSubscriptions.Add(subscriptionResponse.SubscriptionArn); - - await SetQueuePolicyForSns(queueUrl, queueArn, topicArn); - } - - var stopwatch = System.Diagnostics.Stopwatch.StartNew(); - - // Act - Publish multiple messages - var publishTasks = new List(); - for (int i = 0; i < messageCount; i++) - { - var messageIndex = i; - var task = PublishTestMessage(topicArn, messageIndex); - publishTasks.Add(task); - } - - await Task.WhenAll(publishTasks); - stopwatch.Stop(); - - var publishLatency = stopwatch.Elapsed; - - // Wait for message delivery - await Task.Delay(5000); - - // Assert - Verify all subscribers received all messages - var totalMessagesReceived = 0; - var deliveryLatencies = new List(); - - foreach (var (queueUrl, _) in subscriberQueues) - { - var queueStopwatch = System.Diagnostics.Stopwatch.StartNew(); - var queueMessageCount = 0; - - // SQS returns at most 10 per call; poll until we stop getting messages - for (int poll = 0; poll < 5; poll++) - { - var receiveResponse = await _testEnvironment.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = queueUrl, - MaxNumberOfMessages = 10, - WaitTimeSeconds = 1 - }); - if (receiveResponse.Messages.Count == 0) break; - queueMessageCount += receiveResponse.Messages.Count; - } - - queueStopwatch.Stop(); - deliveryLatencies.Add(queueStopwatch.Elapsed); - totalMessagesReceived += queueMessageCount; - - _logger.LogDebug("Queue {QueueUrl} received {MessageCount} messages", queueUrl, queueMessageCount); - } - - var expectedTotalMessages = subscriberCount * messageCount; - var deliverySuccessRate = (double)totalMessagesReceived / expectedTotalMessages; - var averageDeliveryLatency = TimeSpan.FromMilliseconds(deliveryLatencies.Average(l => l.TotalMilliseconds)); - - // Performance assertions - Assert.True(deliverySuccessRate >= 0.90, - $"Delivery success rate {deliverySuccessRate:P2} is below 90% threshold. " + - $"Received {totalMessagesReceived}/{expectedTotalMessages} messages"); - - var maxExpectedPublishLatency = _testEnvironment.IsLocalEmulator ? TimeSpan.FromSeconds(10) : TimeSpan.FromSeconds(30); - Assert.True(publishLatency < maxExpectedPublishLatency, - $"Publish latency {publishLatency.TotalSeconds}s exceeds threshold {maxExpectedPublishLatency.TotalSeconds}s"); - - _logger.LogInformation("Fan-out performance test completed: {SubscriberCount} subscribers, {MessageCount} messages. " + - "Publish latency: {PublishLatency}ms, Average delivery latency: {DeliveryLatency}ms, " + - "Success rate: {SuccessRate:P2}", - subscriberCount, messageCount, publishLatency.TotalMilliseconds, - averageDeliveryLatency.TotalMilliseconds, deliverySuccessRate); - } - - private async Task PublishTestMessage(string topicArn, int messageIndex) - { - var testEvent = new TestEvent(new TestEventData - { - Id = messageIndex, - Message = $"Performance test message {messageIndex}", - Value = messageIndex * 100 - }); - - await _testEnvironment.SnsClient.PublishAsync(new PublishRequest - { - TopicArn = topicArn, - Message = JsonSerializer.Serialize(testEvent), - Subject = testEvent.Name, - MessageAttributes = new Dictionary - { - ["EventType"] = new SnsMessageAttributeValue - { - DataType = "String", - StringValue = testEvent.GetType().Name - }, - ["MessageIndex"] = new SnsMessageAttributeValue - { - DataType = "Number", - StringValue = messageIndex.ToString() - } - } - }); - } - - private async Task GetQueueArnAsync(string queueUrl) - { - var response = await _testEnvironment.SqsClient.GetQueueAttributesAsync(new GetQueueAttributesRequest - { - QueueUrl = queueUrl, - AttributeNames = new List { "QueueArn" } - }); - - return response.Attributes["QueueArn"]; - } - - private async Task SetQueuePolicyForSns(string queueUrl, string queueArn, string topicArn) - { - // Set queue policy to allow SNS to send messages - var policy = $@"{{ - ""Version"": ""2012-10-17"", - ""Statement"": [ - {{ - ""Effect"": ""Allow"", - ""Principal"": {{ - ""Service"": ""sns.amazonaws.com"" - }}, - ""Action"": ""sqs:SendMessage"", - ""Resource"": ""{queueArn}"", - ""Condition"": {{ - ""ArnEquals"": {{ - ""aws:SourceArn"": ""{topicArn}"" - }} - }} - }} - ] - }}"; - - await _testEnvironment.SqsClient.SetQueueAttributesAsync(new SetQueueAttributesRequest - { - QueueUrl = queueUrl, - Attributes = new Dictionary - { - ["Policy"] = policy - } - }); - } -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/Integration/SnsMessageFilteringAndErrorHandlingPropertyTests.cs b/tests/SourceFlow.Cloud.AWS.Tests/Integration/SnsMessageFilteringAndErrorHandlingPropertyTests.cs deleted file mode 100644 index f1770f29..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/Integration/SnsMessageFilteringAndErrorHandlingPropertyTests.cs +++ /dev/null @@ -1,743 +0,0 @@ -using Amazon.SimpleNotificationService; -using Amazon.SimpleNotificationService.Model; -using Amazon.SQS; -using Amazon.SQS.Model; -using FsCheck; -using FsCheck.Xunit; -using Microsoft.Extensions.DependencyInjection; -using Microsoft.Extensions.Logging; -using SourceFlow.Cloud.AWS.Tests.TestHelpers; -using System.Text.Json; -using SnsMessageAttributeValue = Amazon.SimpleNotificationService.Model.MessageAttributeValue; - -namespace SourceFlow.Cloud.AWS.Tests.Integration; - -/// -/// Property-based tests for SNS message filtering and error handling -/// **Property 4: SNS Message Filtering and Error Handling** -/// **Validates: Requirements 2.3, 2.5** -/// -[Collection("AWS Integration Tests")] -[Trait("Category", "Integration")] -[Trait("Category", "RequiresLocalStack")] -public class SnsMessageFilteringAndErrorHandlingPropertyTests : IAsyncLifetime -{ - private readonly IAwsTestEnvironment _testEnvironment; - private readonly ILogger _logger; - private readonly List _createdTopics = new(); - private readonly List _createdQueues = new(); - private readonly List _createdSubscriptions = new(); - - // FsCheck [Property] tests require a constructor that FsCheck can invoke. - // ITestOutputHelper cannot be injected by FsCheck — use ILogger instead. - public SnsMessageFilteringAndErrorHandlingPropertyTests() - { - var services = new ServiceCollection(); - services.AddLogging(builder => builder.AddConsole().SetMinimumLevel(LogLevel.Debug)); - - var serviceProvider = services.BuildServiceProvider(); - _logger = serviceProvider.GetRequiredService>(); - - _testEnvironment = AwsTestEnvironmentFactory.CreateLocalStackEnvironmentAsync().GetAwaiter().GetResult(); - } - - public async Task InitializeAsync() - { - await _testEnvironment.InitializeAsync(); - - if (!await _testEnvironment.IsAvailableAsync()) - { - throw new InvalidOperationException("AWS test environment is not available"); - } - - _logger.LogInformation("SNS message filtering and error handling property tests initialized"); - } - - public async Task DisposeAsync() - { - // Clean up subscriptions first - foreach (var subscriptionArn in _createdSubscriptions) - { - try - { - await _testEnvironment.SnsClient.UnsubscribeAsync(new UnsubscribeRequest - { - SubscriptionArn = subscriptionArn - }); - } - catch (Exception ex) - { - _logger.LogWarning("Failed to delete subscription {SubscriptionArn}: {Error}", subscriptionArn, ex.Message); - } - } - - // Clean up topics - foreach (var topicArn in _createdTopics) - { - try - { - await _testEnvironment.DeleteTopicAsync(topicArn); - } - catch (Exception ex) - { - _logger.LogWarning("Failed to delete topic {TopicArn}: {Error}", topicArn, ex.Message); - } - } - - // Clean up queues - foreach (var queueUrl in _createdQueues) - { - try - { - await _testEnvironment.DeleteQueueAsync(queueUrl); - } - catch (Exception ex) - { - _logger.LogWarning("Failed to delete queue {QueueUrl}: {Error}", queueUrl, ex.Message); - } - } - - await _testEnvironment.DisposeAsync(); - _logger.LogInformation("SNS message filtering and error handling property tests disposed"); - } - - /// - /// Property 4: SNS Message Filtering and Error Handling - /// **Validates: Requirements 2.3, 2.5** - /// - /// For any SNS subscription with message filtering rules, only events matching the filter criteria - /// should be delivered to that subscriber, and failed deliveries should trigger appropriate retry - /// mechanisms and error handling. - /// - [Property(MaxTest = 5, Arbitrary = new[] { typeof(SnsFilteringAndErrorHandlingGenerators) })] - public void SnsMessageFilteringAndErrorHandling(SnsFilteringAndErrorHandlingScenario scenario) - { - try - { - _logger.LogInformation("Testing SNS message filtering and error handling with scenario: {Scenario}", - JsonSerializer.Serialize(scenario, new JsonSerializerOptions { WriteIndented = true })); - - // Property 1: Message filtering should deliver only matching messages - var filteringValid = ValidateMessageFiltering(scenario).GetAwaiter().GetResult(); - - // Property 2: Error handling should gracefully handle failed deliveries - var errorHandlingValid = ValidateErrorHandling(scenario).GetAwaiter().GetResult(); - - // Property 3: Correlation IDs should be preserved even with filtering and errors - var correlationValid = ValidateCorrelationPreservation(scenario).GetAwaiter().GetResult(); - - // Property 4: Filter policy validation should reject invalid policies - var filterValidationValid = ValidateFilterPolicyValidation(scenario).GetAwaiter().GetResult(); - - var result = filteringValid && errorHandlingValid && correlationValid && filterValidationValid; - - if (!result) - { - _logger.LogWarning("SNS message filtering and error handling failed for scenario: {Scenario}. " + - "Filtering: {Filtering}, ErrorHandling: {ErrorHandling}, Correlation: {Correlation}, FilterValidation: {FilterValidation}", - JsonSerializer.Serialize(scenario), filteringValid, errorHandlingValid, correlationValid, filterValidationValid); - } - - Assert.True(result, "SNS message filtering and error handling validation failed"); - } - catch (Exception ex) - { - _logger.LogError(ex, "SNS message filtering and error handling test failed with exception for scenario: {Scenario}", - JsonSerializer.Serialize(scenario)); - throw; - } - } - - private async Task ValidateMessageFiltering(SnsFilteringAndErrorHandlingScenario scenario) - { - try - { - // Create topic - var topicName = $"prop-test-filtering-{Guid.NewGuid():N}"; - var topicArn = await _testEnvironment.CreateTopicAsync(topicName); - _createdTopics.Add(topicArn); - - // Create filtered subscriber - var filteredQueueName = $"prop-test-filtered-{Guid.NewGuid():N}"; - var filteredQueueUrl = await _testEnvironment.CreateStandardQueueAsync(filteredQueueName); - _createdQueues.Add(filteredQueueUrl); - var filteredQueueArn = await GetQueueArnAsync(filteredQueueUrl); - - // Create filter policy based on scenario - var filterPolicy = CreateFilterPolicy(scenario.FilterCriteria); - - var filteredSubscriptionResponse = await _testEnvironment.SnsClient.SubscribeAsync(new SubscribeRequest - { - TopicArn = topicArn, - Protocol = "sqs", - Endpoint = filteredQueueArn, - Attributes = new Dictionary - { - ["FilterPolicy"] = filterPolicy - } - }); - _createdSubscriptions.Add(filteredSubscriptionResponse.SubscriptionArn); - - await SetQueuePolicyForSns(filteredQueueUrl, filteredQueueArn, topicArn); - - // Create unfiltered subscriber for comparison - var unfilteredQueueName = $"prop-test-unfiltered-{Guid.NewGuid():N}"; - var unfilteredQueueUrl = await _testEnvironment.CreateStandardQueueAsync(unfilteredQueueName); - _createdQueues.Add(unfilteredQueueUrl); - var unfilteredQueueArn = await GetQueueArnAsync(unfilteredQueueUrl); - - var unfilteredSubscriptionResponse = await _testEnvironment.SnsClient.SubscribeAsync(new SubscribeRequest - { - TopicArn = topicArn, - Protocol = "sqs", - Endpoint = unfilteredQueueArn - }); - _createdSubscriptions.Add(unfilteredSubscriptionResponse.SubscriptionArn); - - await SetQueuePolicyForSns(unfilteredQueueUrl, unfilteredQueueArn, topicArn); - - // Publish test messages - var publishedMessages = new List<(bool ShouldMatch, Dictionary Attributes)>(); - - foreach (var testMessage in scenario.TestMessages) - { - var testEvent = new TestEvent(new TestEventData - { - Id = testMessage.EventId, - Message = testMessage.Message, - Value = testMessage.Value - }); - - var messageAttributes = CreateMessageAttributes(testMessage); - var shouldMatch = ShouldMessageMatchFilter(testMessage, scenario.FilterCriteria); - - await _testEnvironment.SnsClient.PublishAsync(new PublishRequest - { - TopicArn = topicArn, - Message = JsonSerializer.Serialize(testEvent), - Subject = testEvent.Name, - MessageAttributes = messageAttributes - }); - - publishedMessages.Add((shouldMatch, messageAttributes)); - } - - // Wait for delivery - await Task.Delay(3000); - - // Verify filtering results - var filteredReceiveResponse = await _testEnvironment.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = filteredQueueUrl, - MaxNumberOfMessages = 10, - WaitTimeSeconds = 3 - }); - - var unfilteredReceiveResponse = await _testEnvironment.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = unfilteredQueueUrl, - MaxNumberOfMessages = 10, - WaitTimeSeconds = 3 - }); - - var expectedFilteredCount = publishedMessages.Count(m => m.ShouldMatch); - var actualFilteredCount = filteredReceiveResponse.Messages.Count; - var actualUnfilteredCount = unfilteredReceiveResponse.Messages.Count; - - // Filtered queue should receive only matching messages - var filteringValid = actualFilteredCount <= expectedFilteredCount + 1; // Allow slight variance - - // Unfiltered queue should receive all messages - var unfilteredValid = actualUnfilteredCount >= publishedMessages.Count * 0.8; // Allow 80% delivery rate - - var result = filteringValid && unfilteredValid; - - if (!result) - { - _logger.LogWarning("Message filtering validation failed: Expected filtered {ExpectedFiltered}, got {ActualFiltered}. " + - "Expected unfiltered {ExpectedUnfiltered}, got {ActualUnfiltered}", - expectedFilteredCount, actualFilteredCount, publishedMessages.Count, actualUnfilteredCount); - } - - return result; - } - catch (Exception ex) - { - _logger.LogWarning("Message filtering validation failed with exception: {Error}", ex.Message); - return false; - } - } - - private async Task ValidateErrorHandling(SnsFilteringAndErrorHandlingScenario scenario) - { - try - { - // Create topic - var topicName = $"prop-test-error-{Guid.NewGuid():N}"; - var topicArn = await _testEnvironment.CreateTopicAsync(topicName); - _createdTopics.Add(topicArn); - - // Create valid SQS subscriber - var validQueueName = $"prop-test-valid-{Guid.NewGuid():N}"; - var validQueueUrl = await _testEnvironment.CreateStandardQueueAsync(validQueueName); - _createdQueues.Add(validQueueUrl); - var validQueueArn = await GetQueueArnAsync(validQueueUrl); - - var validSubscriptionResponse = await _testEnvironment.SnsClient.SubscribeAsync(new SubscribeRequest - { - TopicArn = topicArn, - Protocol = "sqs", - Endpoint = validQueueArn - }); - _createdSubscriptions.Add(validSubscriptionResponse.SubscriptionArn); - - await SetQueuePolicyForSns(validQueueUrl, validQueueArn, topicArn); - - // Create invalid HTTP subscribers (will fail delivery) - foreach (var invalidEndpoint in scenario.InvalidEndpoints.Take(2)) // Limit to 2 for performance - { - try - { - var invalidSubscriptionResponse = await _testEnvironment.SnsClient.SubscribeAsync(new SubscribeRequest - { - TopicArn = topicArn, - Protocol = "http", - Endpoint = invalidEndpoint - }); - _createdSubscriptions.Add(invalidSubscriptionResponse.SubscriptionArn); - } - catch (Exception ex) - { - _logger.LogDebug("Expected failure creating invalid HTTP subscription for {Endpoint}: {Error}", - invalidEndpoint, ex.Message); - } - } - - // Publish test message - var testMessage = scenario.TestMessages.FirstOrDefault() ?? new SnsTestMessage - { - EventId = 1, - Message = "Error handling test", - Value = 100, - Priority = "High", - Source = "Test" - }; - - var testEvent = new TestEvent(new TestEventData - { - Id = testMessage.EventId, - Message = testMessage.Message, - Value = testMessage.Value - }); - - var publishResponse = await _testEnvironment.SnsClient.PublishAsync(new PublishRequest - { - TopicArn = topicArn, - Message = JsonSerializer.Serialize(testEvent), - Subject = testEvent.Name, - MessageAttributes = CreateMessageAttributes(testMessage) - }); - - // Publish should succeed despite invalid subscribers - var publishValid = publishResponse?.MessageId != null; - - // Wait for delivery attempts - await Task.Delay(2000); - - // Valid subscriber should receive the message - var receiveResponse = await _testEnvironment.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = validQueueUrl, - MaxNumberOfMessages = 1, - WaitTimeSeconds = 3 - }); - - var deliveryValid = receiveResponse.Messages.Count > 0; - - var result = publishValid && deliveryValid; - - if (!result) - { - _logger.LogWarning("Error handling validation failed: Publish valid: {PublishValid}, Delivery valid: {DeliveryValid}", - publishValid, deliveryValid); - } - - return result; - } - catch (Exception ex) - { - _logger.LogWarning("Error handling validation failed with exception: {Error}", ex.Message); - return false; - } - } - - private async Task ValidateCorrelationPreservation(SnsFilteringAndErrorHandlingScenario scenario) - { - try - { - // Create topic - var topicName = $"prop-test-correlation-{Guid.NewGuid():N}"; - var topicArn = await _testEnvironment.CreateTopicAsync(topicName); - _createdTopics.Add(topicArn); - - // Create subscriber - var queueName = $"prop-test-corr-queue-{Guid.NewGuid():N}"; - var queueUrl = await _testEnvironment.CreateStandardQueueAsync(queueName); - _createdQueues.Add(queueUrl); - var queueArn = await GetQueueArnAsync(queueUrl); - - var subscriptionResponse = await _testEnvironment.SnsClient.SubscribeAsync(new SubscribeRequest - { - TopicArn = topicArn, - Protocol = "sqs", - Endpoint = queueArn - }); - _createdSubscriptions.Add(subscriptionResponse.SubscriptionArn); - - await SetQueuePolicyForSns(queueUrl, queueArn, topicArn); - - // Publish message with correlation ID - var correlationId = scenario.CorrelationId ?? Guid.NewGuid().ToString(); - var testMessage = scenario.TestMessages.FirstOrDefault() ?? new SnsTestMessage - { - EventId = 1, - Message = "Correlation test", - Value = 100, - Priority = "High", - Source = "Test" - }; - - var testEvent = new TestEvent(new TestEventData - { - Id = testMessage.EventId, - Message = testMessage.Message, - Value = testMessage.Value - }); - - var messageAttributes = CreateMessageAttributes(testMessage); - messageAttributes["CorrelationId"] = new SnsMessageAttributeValue - { - DataType = "String", - StringValue = correlationId - }; - - await _testEnvironment.SnsClient.PublishAsync(new PublishRequest - { - TopicArn = topicArn, - Message = JsonSerializer.Serialize(testEvent), - Subject = testEvent.Name, - MessageAttributes = messageAttributes - }); - - // Wait for delivery - await Task.Delay(1500); - - // Verify correlation ID preservation - var receiveResponse = await _testEnvironment.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = queueUrl, - MaxNumberOfMessages = 1, - WaitTimeSeconds = 3, - MessageAttributeNames = new List { "All" } - }); - - if (receiveResponse.Messages.Count == 0) - { - _logger.LogWarning("Correlation preservation validation failed: No messages received"); - return false; - } - - var receivedMessage = receiveResponse.Messages[0]; - var snsMessage = JsonSerializer.Deserialize(receivedMessage.Body); - - var correlationValid = snsMessage?.MessageAttributes?.ContainsKey("CorrelationId") == true && - snsMessage?.MessageAttributes?["CorrelationId"]?.Value == correlationId; - - if (!correlationValid) - { - _logger.LogWarning("Correlation preservation validation failed: Expected {ExpectedId}, but correlation ID not found or mismatched", - correlationId); - } - - return correlationValid; - } - catch (Exception ex) - { - _logger.LogWarning("Correlation preservation validation failed with exception: {Error}", ex.Message); - return false; - } - } - - private async Task ValidateFilterPolicyValidation(SnsFilteringAndErrorHandlingScenario scenario) - { - try - { - // Create topic - var topicName = $"prop-test-filter-validation-{Guid.NewGuid():N}"; - var topicArn = await _testEnvironment.CreateTopicAsync(topicName); - _createdTopics.Add(topicArn); - - var queueName = $"prop-test-validation-queue-{Guid.NewGuid():N}"; - var queueUrl = await _testEnvironment.CreateStandardQueueAsync(queueName); - _createdQueues.Add(queueUrl); - var queueArn = await GetQueueArnAsync(queueUrl); - - // Test valid filter policy - var validFilterPolicy = CreateFilterPolicy(scenario.FilterCriteria); - - try - { - var validSubscriptionResponse = await _testEnvironment.SnsClient.SubscribeAsync(new SubscribeRequest - { - TopicArn = topicArn, - Protocol = "sqs", - Endpoint = queueArn, - Attributes = new Dictionary - { - ["FilterPolicy"] = validFilterPolicy - } - }); - _createdSubscriptions.Add(validSubscriptionResponse.SubscriptionArn); - - // Valid filter policy should succeed - var validPolicyValid = !string.IsNullOrEmpty(validSubscriptionResponse.SubscriptionArn); - - // Test invalid filter policy if provided in scenario - if (!string.IsNullOrEmpty(scenario.InvalidFilterPolicy)) - { - try - { - await _testEnvironment.SnsClient.SubscribeAsync(new SubscribeRequest - { - TopicArn = topicArn, - Protocol = "sqs", - Endpoint = queueArn, - Attributes = new Dictionary - { - ["FilterPolicy"] = scenario.InvalidFilterPolicy - } - }); - - // Invalid filter policy should have failed, but didn't - _logger.LogWarning("Invalid filter policy was accepted when it should have been rejected"); - return false; - } - catch (Exception) - { - // Expected exception for invalid filter policy - return validPolicyValid; - } - } - - return validPolicyValid; - } - catch (Exception ex) - { - _logger.LogWarning("Filter policy validation failed: {Error}", ex.Message); - return false; - } - } - catch (Exception ex) - { - _logger.LogWarning("Filter policy validation failed with exception: {Error}", ex.Message); - return false; - } - } - - private string CreateFilterPolicy(SnsFilterCriteria criteria) - { - var policy = new Dictionary(); - - if (!string.IsNullOrEmpty(criteria.Priority)) - { - policy["Priority"] = new[] { criteria.Priority }; - } - - if (!string.IsNullOrEmpty(criteria.Source)) - { - policy["Source"] = new[] { criteria.Source }; - } - - if (criteria.MinValue.HasValue) - { - policy["Value"] = new object[] { new { numeric = new object[] { ">=", criteria.MinValue.Value } } }; - } - - return JsonSerializer.Serialize(policy); - } - - private bool ShouldMessageMatchFilter(SnsTestMessage message, SnsFilterCriteria criteria) - { - var priorityMatch = string.IsNullOrEmpty(criteria.Priority) || message.Priority == criteria.Priority; - var sourceMatch = string.IsNullOrEmpty(criteria.Source) || message.Source == criteria.Source; - var valueMatch = !criteria.MinValue.HasValue || message.Value >= criteria.MinValue.Value; - - return priorityMatch && sourceMatch && valueMatch; - } - - private Dictionary CreateMessageAttributes(SnsTestMessage message) - { - var attributes = new Dictionary - { - ["EventType"] = new SnsMessageAttributeValue - { - DataType = "String", - StringValue = "TestEvent" - }, - ["Priority"] = new SnsMessageAttributeValue - { - DataType = "String", - StringValue = message.Priority - }, - ["Source"] = new SnsMessageAttributeValue - { - DataType = "String", - StringValue = message.Source - }, - ["Value"] = new SnsMessageAttributeValue - { - DataType = "Number", - StringValue = message.Value.ToString() - } - }; - - return attributes; - } - - private async Task GetQueueArnAsync(string queueUrl) - { - var response = await _testEnvironment.SqsClient.GetQueueAttributesAsync(new GetQueueAttributesRequest - { - QueueUrl = queueUrl, - AttributeNames = new List { "QueueArn" } - }); - - return response.Attributes["QueueArn"]; - } - - private async Task SetQueuePolicyForSns(string queueUrl, string queueArn, string topicArn) - { - var policy = $@"{{ - ""Version"": ""2012-10-17"", - ""Statement"": [ - {{ - ""Effect"": ""Allow"", - ""Principal"": {{ - ""Service"": ""sns.amazonaws.com"" - }}, - ""Action"": ""sqs:SendMessage"", - ""Resource"": ""{queueArn}"", - ""Condition"": {{ - ""ArnEquals"": {{ - ""aws:SourceArn"": ""{topicArn}"" - }} - }} - }} - ] - }}"; - - await _testEnvironment.SqsClient.SetQueueAttributesAsync(new SetQueueAttributesRequest - { - QueueUrl = queueUrl, - Attributes = new Dictionary - { - ["Policy"] = policy - } - }); - } -} - -/// -/// Generators for SNS message filtering and error handling property tests -/// -public static class SnsFilteringAndErrorHandlingGenerators -{ - public static Arbitrary SnsFilteringAndErrorHandlingScenario() - { - return Gen.Fresh(() => new SnsFilteringAndErrorHandlingScenario - { - FilterCriteria = GenerateFilterCriteria(), - TestMessages = GenerateTestMessages(), - InvalidEndpoints = GenerateInvalidEndpoints(), - CorrelationId = Gen.Elements(null, Guid.NewGuid().ToString(), "test-correlation").Sample(0, 1).First(), - InvalidFilterPolicy = Gen.Elements(null, @"{""Priority"":[""High""", @"{invalid:json}").Sample(0, 1).First() - }).ToArbitrary(); - } - - private static SnsFilterCriteria GenerateFilterCriteria() - { - return new SnsFilterCriteria - { - Priority = Gen.Elements(null, "High", "Medium", "Low").Sample(0, 1).First(), - Source = Gen.Elements(null, "OrderService", "PaymentService", "UserService").Sample(0, 1).First(), - MinValue = Gen.Elements(null, 100, 500, 1000).Sample(0, 1).First() - }; - } - - private static List GenerateTestMessages() - { - var messageCount = Gen.Choose(2, 5).Sample(0, 1).First(); - var messages = new List(); - - var priorities = new[] { "High", "Medium", "Low" }; - var sources = new[] { "OrderService", "PaymentService", "UserService", "NotificationService" }; - - for (int i = 0; i < messageCount; i++) - { - messages.Add(new SnsTestMessage - { - EventId = i + 1, - Message = $"Test message {i + 1}", - Value = Gen.Choose(50, 2000).Sample(0, 1).First(), - Priority = Gen.Elements(priorities).Sample(0, 1).First(), - Source = Gen.Elements(sources).Sample(0, 1).First() - }); - } - - return messages; - } - - private static List GenerateInvalidEndpoints() - { - return new List - { - "http://invalid-endpoint-1.example.com/webhook", - "http://invalid-endpoint-2.example.com/webhook", - "https://non-existent-service.com/api/events" - }; - } -} - -/// -/// Test scenario for SNS message filtering and error handling property tests -/// -public class SnsFilteringAndErrorHandlingScenario -{ - public SnsFilterCriteria FilterCriteria { get; set; } = new(); - public List TestMessages { get; set; } = new(); - public List InvalidEndpoints { get; set; } = new(); - public string? CorrelationId { get; set; } - public string? InvalidFilterPolicy { get; set; } -} - -/// -/// Filter criteria for SNS message filtering tests -/// -public class SnsFilterCriteria -{ - public string? Priority { get; set; } - public string? Source { get; set; } - public int? MinValue { get; set; } -} - -/// -/// Test message for SNS filtering tests -/// -public class SnsTestMessage -{ - public int EventId { get; set; } - public string Message { get; set; } = ""; - public int Value { get; set; } - public string Priority { get; set; } = ""; - public string Source { get; set; } = ""; -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/Integration/SnsMessageFilteringIntegrationTests.cs b/tests/SourceFlow.Cloud.AWS.Tests/Integration/SnsMessageFilteringIntegrationTests.cs deleted file mode 100644 index e63b52e9..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/Integration/SnsMessageFilteringIntegrationTests.cs +++ /dev/null @@ -1,626 +0,0 @@ -using Amazon.SimpleNotificationService; -using Amazon.SimpleNotificationService.Model; -using Amazon.SQS; -using Amazon.SQS.Model; -using Microsoft.Extensions.DependencyInjection; -using Microsoft.Extensions.Logging; -using SourceFlow.Cloud.AWS.Tests.TestHelpers; -using System.Text.Json; -using Xunit.Abstractions; -using SnsMessageAttributeValue = Amazon.SimpleNotificationService.Model.MessageAttributeValue; - -namespace SourceFlow.Cloud.AWS.Tests.Integration; - -/// -/// Integration tests for SNS message filtering functionality -/// Tests subscription filter policies and selective message delivery based on attributes -/// **Validates: Requirements 2.3** -/// -[Collection("AWS Integration Tests")] -[Trait("Category", "Integration")] -[Trait("Category", "RequiresLocalStack")] -public class SnsMessageFilteringIntegrationTests : IAsyncLifetime -{ - private readonly ITestOutputHelper _output; - private readonly IAwsTestEnvironment _testEnvironment; - private readonly ILogger _logger; - private readonly List _createdTopics = new(); - private readonly List _createdQueues = new(); - private readonly List _createdSubscriptions = new(); - - public SnsMessageFilteringIntegrationTests(ITestOutputHelper output) - { - _output = output; - - var services = new ServiceCollection(); - services.AddLogging(builder => builder.AddConsole().SetMinimumLevel(LogLevel.Debug)); - - var serviceProvider = services.BuildServiceProvider(); - _logger = serviceProvider.GetRequiredService>(); - - _testEnvironment = AwsTestEnvironmentFactory.CreateLocalStackEnvironmentAsync().GetAwaiter().GetResult(); - } - - public async Task InitializeAsync() - { - await _testEnvironment.InitializeAsync(); - - if (!await _testEnvironment.IsAvailableAsync()) - { - throw new InvalidOperationException("AWS test environment is not available"); - } - - _logger.LogInformation("SNS message filtering integration tests initialized"); - } - - public async Task DisposeAsync() - { - // Clean up subscriptions first - foreach (var subscriptionArn in _createdSubscriptions) - { - try - { - await _testEnvironment.SnsClient.UnsubscribeAsync(new UnsubscribeRequest - { - SubscriptionArn = subscriptionArn - }); - } - catch (Exception ex) - { - _logger.LogWarning("Failed to delete subscription {SubscriptionArn}: {Error}", subscriptionArn, ex.Message); - } - } - - // Clean up topics - foreach (var topicArn in _createdTopics) - { - try - { - await _testEnvironment.DeleteTopicAsync(topicArn); - } - catch (Exception ex) - { - _logger.LogWarning("Failed to delete topic {TopicArn}: {Error}", topicArn, ex.Message); - } - } - - // Clean up queues - foreach (var queueUrl in _createdQueues) - { - try - { - await _testEnvironment.DeleteQueueAsync(queueUrl); - } - catch (Exception ex) - { - _logger.LogWarning("Failed to delete queue {QueueUrl}: {Error}", queueUrl, ex.Message); - } - } - - await _testEnvironment.DisposeAsync(); - _logger.LogInformation("SNS message filtering integration tests disposed"); - } - - [Fact] - public async Task MessageFiltering_WithSimpleAttributeFilter_ShouldDeliverSelectiveMessages() - { - // Arrange - var topicName = $"test-filter-topic-{Guid.NewGuid():N}"; - var topicArn = await _testEnvironment.CreateTopicAsync(topicName); - _createdTopics.Add(topicArn); - - // Create subscriber queue with filter policy - var queueName = $"test-filter-queue-{Guid.NewGuid():N}"; - var queueUrl = await _testEnvironment.CreateStandardQueueAsync(queueName); - _createdQueues.Add(queueUrl); - var queueArn = await GetQueueArnAsync(queueUrl); - - // Subscribe with filter policy for high priority messages only - var filterPolicy = @"{ - ""Priority"": [""High""] - }"; - - var subscriptionResponse = await _testEnvironment.SnsClient.SubscribeAsync(new SubscribeRequest - { - TopicArn = topicArn, - Protocol = "sqs", - Endpoint = queueArn, - Attributes = new Dictionary - { - ["FilterPolicy"] = filterPolicy - } - }); - _createdSubscriptions.Add(subscriptionResponse.SubscriptionArn); - - await SetQueuePolicyForSns(queueUrl, queueArn, topicArn); - - // Act - Publish messages with different priorities - var highPriorityEvent = new TestEvent(new TestEventData - { - Id = 1, - Message = "High priority message", - Value = 100 - }); - - var lowPriorityEvent = new TestEvent(new TestEventData - { - Id = 2, - Message = "Low priority message", - Value = 200 - }); - - // Publish high priority message (should be delivered) - await _testEnvironment.SnsClient.PublishAsync(new PublishRequest - { - TopicArn = topicArn, - Message = JsonSerializer.Serialize(highPriorityEvent), - Subject = highPriorityEvent.Name, - MessageAttributes = new Dictionary - { - ["Priority"] = new SnsMessageAttributeValue - { - DataType = "String", - StringValue = "High" - }, - ["EventType"] = new SnsMessageAttributeValue - { - DataType = "String", - StringValue = highPriorityEvent.GetType().Name - } - } - }); - - // Publish low priority message (should be filtered out) - await _testEnvironment.SnsClient.PublishAsync(new PublishRequest - { - TopicArn = topicArn, - Message = JsonSerializer.Serialize(lowPriorityEvent), - Subject = lowPriorityEvent.Name, - MessageAttributes = new Dictionary - { - ["Priority"] = new SnsMessageAttributeValue - { - DataType = "String", - StringValue = "Low" - }, - ["EventType"] = new SnsMessageAttributeValue - { - DataType = "String", - StringValue = lowPriorityEvent.GetType().Name - } - } - }); - - // Wait for message delivery - await Task.Delay(3000); - - // Assert - Only high priority message should be received - var receiveResponse = await _testEnvironment.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = queueUrl, - MaxNumberOfMessages = 10, - WaitTimeSeconds = 5, - MessageAttributeNames = new List { "All" } - }); - - Assert.Single(receiveResponse.Messages); - - var receivedMessage = receiveResponse.Messages[0]; - var snsMessage = JsonSerializer.Deserialize(receivedMessage.Body); - - // Verify it's the high priority message - Assert.Contains("High priority message", snsMessage?.Message ?? ""); - Assert.True(snsMessage?.MessageAttributes?.ContainsKey("Priority")); - Assert.Equal("High", snsMessage?.MessageAttributes?["Priority"]?.Value); - - _logger.LogInformation("Successfully filtered messages based on Priority attribute - only High priority message delivered"); - } - - [Fact] - public async Task MessageFiltering_WithComplexFilter_ShouldHandleMultipleConditions() - { - // Arrange - var topicName = $"test-complex-filter-{Guid.NewGuid():N}"; - var topicArn = await _testEnvironment.CreateTopicAsync(topicName); - _createdTopics.Add(topicArn); - - // Create subscriber queue with complex filter policy - var queueName = $"test-complex-queue-{Guid.NewGuid():N}"; - var queueUrl = await _testEnvironment.CreateStandardQueueAsync(queueName); - _createdQueues.Add(queueUrl); - var queueArn = await GetQueueArnAsync(queueUrl); - - // Filter for high priority messages from specific sources - var filterPolicy = @"{ - ""Priority"": [""High"", ""Critical""], - ""Source"": [""OrderService"", ""PaymentService""] - }"; - - var subscriptionResponse = await _testEnvironment.SnsClient.SubscribeAsync(new SubscribeRequest - { - TopicArn = topicArn, - Protocol = "sqs", - Endpoint = queueArn, - Attributes = new Dictionary - { - ["FilterPolicy"] = filterPolicy - } - }); - _createdSubscriptions.Add(subscriptionResponse.SubscriptionArn); - - await SetQueuePolicyForSns(queueUrl, queueArn, topicArn); - - // Act - Publish various messages - var testMessages = new[] - { - new { Priority = "High", Source = "OrderService", ShouldDeliver = true, Message = "High priority order event" }, - new { Priority = "Critical", Source = "PaymentService", ShouldDeliver = true, Message = "Critical payment event" }, - new { Priority = "High", Source = "UserService", ShouldDeliver = false, Message = "High priority user event" }, - new { Priority = "Low", Source = "OrderService", ShouldDeliver = false, Message = "Low priority order event" }, - new { Priority = "Medium", Source = "PaymentService", ShouldDeliver = false, Message = "Medium priority payment event" } - }; - - foreach (var testMsg in testMessages) - { - var testEvent = new TestEvent(new TestEventData - { - Id = Array.IndexOf(testMessages, testMsg) + 1, - Message = testMsg.Message, - Value = 100 - }); - - await _testEnvironment.SnsClient.PublishAsync(new PublishRequest - { - TopicArn = topicArn, - Message = JsonSerializer.Serialize(testEvent), - Subject = testEvent.Name, - MessageAttributes = new Dictionary - { - ["Priority"] = new SnsMessageAttributeValue - { - DataType = "String", - StringValue = testMsg.Priority - }, - ["Source"] = new SnsMessageAttributeValue - { - DataType = "String", - StringValue = testMsg.Source - }, - ["EventType"] = new SnsMessageAttributeValue - { - DataType = "String", - StringValue = testEvent.GetType().Name - } - } - }); - } - - // Wait for message delivery - await Task.Delay(4000); - - // Assert - Only messages matching both conditions should be received - var receiveResponse = await _testEnvironment.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = queueUrl, - MaxNumberOfMessages = 10, - WaitTimeSeconds = 5, - MessageAttributeNames = new List { "All" } - }); - - var expectedDeliveredCount = testMessages.Count(m => m.ShouldDeliver); - Assert.Equal(expectedDeliveredCount, receiveResponse.Messages.Count); - - // Verify received messages match filter criteria - foreach (var receivedMessage in receiveResponse.Messages) - { - var snsMessage = JsonSerializer.Deserialize(receivedMessage.Body); - var priority = snsMessage?.MessageAttributes?["Priority"]?.Value; - var source = snsMessage?.MessageAttributes?["Source"]?.Value; - - Assert.True(priority == "High" || priority == "Critical"); - Assert.True(source == "OrderService" || source == "PaymentService"); - } - - _logger.LogInformation("Successfully filtered {ReceivedCount}/{TotalCount} messages using complex filter policy", - receiveResponse.Messages.Count, testMessages.Length); - } - - [Fact] - public async Task MessageFiltering_WithNumericFilter_ShouldFilterByNumericValues() - { - // Arrange - var topicName = $"test-numeric-filter-{Guid.NewGuid():N}"; - var topicArn = await _testEnvironment.CreateTopicAsync(topicName); - _createdTopics.Add(topicArn); - - var queueName = $"test-numeric-queue-{Guid.NewGuid():N}"; - var queueUrl = await _testEnvironment.CreateStandardQueueAsync(queueName); - _createdQueues.Add(queueUrl); - var queueArn = await GetQueueArnAsync(queueUrl); - - // Filter for messages with Amount >= 1000 - var filterPolicy = @"{ - ""Amount"": [{""numeric"": ["">="", 1000]}] - }"; - - var subscriptionResponse = await _testEnvironment.SnsClient.SubscribeAsync(new SubscribeRequest - { - TopicArn = topicArn, - Protocol = "sqs", - Endpoint = queueArn, - Attributes = new Dictionary - { - ["FilterPolicy"] = filterPolicy - } - }); - _createdSubscriptions.Add(subscriptionResponse.SubscriptionArn); - - await SetQueuePolicyForSns(queueUrl, queueArn, topicArn); - - // Act - Publish messages with different amounts - var testAmounts = new[] { 500, 1000, 1500, 750, 2000 }; - - foreach (var amount in testAmounts) - { - var testEvent = new TestEvent(new TestEventData - { - Id = amount, - Message = $"Transaction for ${amount}", - Value = amount - }); - - await _testEnvironment.SnsClient.PublishAsync(new PublishRequest - { - TopicArn = topicArn, - Message = JsonSerializer.Serialize(testEvent), - Subject = testEvent.Name, - MessageAttributes = new Dictionary - { - ["Amount"] = new SnsMessageAttributeValue - { - DataType = "Number", - StringValue = amount.ToString() - }, - ["EventType"] = new SnsMessageAttributeValue - { - DataType = "String", - StringValue = testEvent.GetType().Name - } - } - }); - } - - // Wait for message delivery - await Task.Delay(3000); - - // Assert - Only messages with Amount >= 1000 should be received - var receiveResponse = await _testEnvironment.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = queueUrl, - MaxNumberOfMessages = 10, - WaitTimeSeconds = 5, - MessageAttributeNames = new List { "All" } - }); - - var expectedCount = testAmounts.Count(a => a >= 1000); - Assert.Equal(expectedCount, receiveResponse.Messages.Count); - - // Verify all received messages have Amount >= 1000 - foreach (var receivedMessage in receiveResponse.Messages) - { - var snsMessage = JsonSerializer.Deserialize(receivedMessage.Body); - var amountStr = snsMessage?.MessageAttributes?["Amount"]?.Value; - - Assert.True(int.TryParse(amountStr, out var amount)); - Assert.True(amount >= 1000); - } - - _logger.LogInformation("Successfully filtered {ReceivedCount}/{TotalCount} messages using numeric filter (Amount >= 1000)", - receiveResponse.Messages.Count, testAmounts.Length); - } - - [Fact] - public async Task MessageFiltering_WithInvalidFilterPolicy_ShouldHandleValidationErrors() - { - // Arrange - var topicName = $"test-invalid-filter-{Guid.NewGuid():N}"; - var topicArn = await _testEnvironment.CreateTopicAsync(topicName); - _createdTopics.Add(topicArn); - - var queueName = $"test-invalid-queue-{Guid.NewGuid():N}"; - var queueUrl = await _testEnvironment.CreateStandardQueueAsync(queueName); - _createdQueues.Add(queueUrl); - var queueArn = await GetQueueArnAsync(queueUrl); - - // Invalid filter policy (malformed JSON) - var invalidFilterPolicy = @"{ - ""Priority"": [""High"" - }"; // Missing closing bracket - - // Act & Assert - Should throw exception for invalid filter policy - var exception = await Assert.ThrowsAnyAsync(async () => - { - await _testEnvironment.SnsClient.SubscribeAsync(new SubscribeRequest - { - TopicArn = topicArn, - Protocol = "sqs", - Endpoint = queueArn, - Attributes = new Dictionary - { - ["FilterPolicy"] = invalidFilterPolicy - } - }); - }); - - Assert.NotNull(exception); - _logger.LogInformation("Expected exception thrown for invalid filter policy: {Exception}", exception.Message); - } - - [Fact] - public async Task MessageFiltering_PerformanceImpact_ShouldMeasureFilteringOverhead() - { - // Arrange - var topicName = $"test-perf-filter-{Guid.NewGuid():N}"; - var topicArn = await _testEnvironment.CreateTopicAsync(topicName); - _createdTopics.Add(topicArn); - - // Create two queues - one with filter, one without - var filteredQueueName = $"test-filtered-queue-{Guid.NewGuid():N}"; - var filteredQueueUrl = await _testEnvironment.CreateStandardQueueAsync(filteredQueueName); - _createdQueues.Add(filteredQueueUrl); - var filteredQueueArn = await GetQueueArnAsync(filteredQueueUrl); - - var unfilteredQueueName = $"test-unfiltered-queue-{Guid.NewGuid():N}"; - var unfilteredQueueUrl = await _testEnvironment.CreateStandardQueueAsync(unfilteredQueueName); - _createdQueues.Add(unfilteredQueueUrl); - var unfilteredQueueArn = await GetQueueArnAsync(unfilteredQueueUrl); - - // Subscribe with filter - var filterPolicy = @"{ - ""Priority"": [""High""] - }"; - - var filteredSubscriptionResponse = await _testEnvironment.SnsClient.SubscribeAsync(new SubscribeRequest - { - TopicArn = topicArn, - Protocol = "sqs", - Endpoint = filteredQueueArn, - Attributes = new Dictionary - { - ["FilterPolicy"] = filterPolicy - } - }); - _createdSubscriptions.Add(filteredSubscriptionResponse.SubscriptionArn); - - // Subscribe without filter - var unfilteredSubscriptionResponse = await _testEnvironment.SnsClient.SubscribeAsync(new SubscribeRequest - { - TopicArn = topicArn, - Protocol = "sqs", - Endpoint = unfilteredQueueArn - }); - _createdSubscriptions.Add(unfilteredSubscriptionResponse.SubscriptionArn); - - await SetQueuePolicyForSns(filteredQueueUrl, filteredQueueArn, topicArn); - await SetQueuePolicyForSns(unfilteredQueueUrl, unfilteredQueueArn, topicArn); - - // Act - Publish messages with different priorities - const int messageCount = 20; - var publishStopwatch = System.Diagnostics.Stopwatch.StartNew(); - - for (int i = 0; i < messageCount; i++) - { - var priority = i % 2 == 0 ? "High" : "Low"; - var testEvent = new TestEvent(new TestEventData - { - Id = i, - Message = $"Performance test message {i}", - Value = i * 10 - }); - - await _testEnvironment.SnsClient.PublishAsync(new PublishRequest - { - TopicArn = topicArn, - Message = JsonSerializer.Serialize(testEvent), - Subject = testEvent.Name, - MessageAttributes = new Dictionary - { - ["Priority"] = new SnsMessageAttributeValue - { - DataType = "String", - StringValue = priority - }, - ["MessageIndex"] = new SnsMessageAttributeValue - { - DataType = "Number", - StringValue = i.ToString() - } - } - }); - } - - publishStopwatch.Stop(); - - // Wait for message delivery - await Task.Delay(4000); - - // Assert - Measure filtering performance impact - var filteredReceiveResponse = await _testEnvironment.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = filteredQueueUrl, - MaxNumberOfMessages = 10, - WaitTimeSeconds = 3 - }); - - var unfilteredReceiveResponse = await _testEnvironment.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = unfilteredQueueUrl, - MaxNumberOfMessages = 10, - WaitTimeSeconds = 3 - }); - - var expectedFilteredCount = messageCount / 2; // Half should be High priority - var filteredCount = filteredReceiveResponse.Messages.Count; - var unfilteredCount = unfilteredReceiveResponse.Messages.Count; - - // Filtered queue should receive only High priority messages - Assert.True(filteredCount <= expectedFilteredCount + 1); // Allow for slight variance - - // Unfiltered queue should receive messages (single poll may not get all due to MaxNumberOfMessages=10 cap) - Assert.True(unfilteredCount >= 1); // At least some messages should arrive - - // Performance should be reasonable - var publishLatency = publishStopwatch.Elapsed; - var maxExpectedLatency = _testEnvironment.IsLocalEmulator ? TimeSpan.FromSeconds(10) : TimeSpan.FromSeconds(30); - Assert.True(publishLatency < maxExpectedLatency, - $"Publish latency {publishLatency.TotalSeconds}s exceeds threshold {maxExpectedLatency.TotalSeconds}s"); - - _logger.LogInformation("Message filtering performance test completed: " + - "Published {MessageCount} messages in {PublishLatency}ms. " + - "Filtered queue received {FilteredCount} messages, " + - "Unfiltered queue received {UnfilteredCount} messages", - messageCount, publishLatency.TotalMilliseconds, filteredCount, unfilteredCount); - } - - private async Task GetQueueArnAsync(string queueUrl) - { - var response = await _testEnvironment.SqsClient.GetQueueAttributesAsync(new GetQueueAttributesRequest - { - QueueUrl = queueUrl, - AttributeNames = new List { "QueueArn" } - }); - - return response.Attributes["QueueArn"]; - } - - private async Task SetQueuePolicyForSns(string queueUrl, string queueArn, string topicArn) - { - var policy = $@"{{ - ""Version"": ""2012-10-17"", - ""Statement"": [ - {{ - ""Effect"": ""Allow"", - ""Principal"": {{ - ""Service"": ""sns.amazonaws.com"" - }}, - ""Action"": ""sqs:SendMessage"", - ""Resource"": ""{queueArn}"", - ""Condition"": {{ - ""ArnEquals"": {{ - ""aws:SourceArn"": ""{topicArn}"" - }} - }} - }} - ] - }}"; - - await _testEnvironment.SqsClient.SetQueueAttributesAsync(new SetQueueAttributesRequest - { - QueueUrl = queueUrl, - Attributes = new Dictionary - { - ["Policy"] = policy - } - }); - } -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/Integration/SnsTopicPublishingIntegrationTests.cs b/tests/SourceFlow.Cloud.AWS.Tests/Integration/SnsTopicPublishingIntegrationTests.cs deleted file mode 100644 index bfcaeba0..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/Integration/SnsTopicPublishingIntegrationTests.cs +++ /dev/null @@ -1,465 +0,0 @@ -using Amazon.SimpleNotificationService; -using Amazon.SimpleNotificationService.Model; -using Microsoft.Extensions.DependencyInjection; -using Microsoft.Extensions.Logging; -using SourceFlow.Cloud.AWS.Tests.TestHelpers; -using System.Text.Json; -using Xunit.Abstractions; - -namespace SourceFlow.Cloud.AWS.Tests.Integration; - -/// -/// Integration tests for SNS topic publishing functionality -/// Tests event publishing to SNS topics with message attributes, encryption, and access control -/// **Validates: Requirements 2.1** -/// -[Collection("AWS Integration Tests")] -[Trait("Category", "Integration")] -[Trait("Category", "RequiresLocalStack")] -public class SnsTopicPublishingIntegrationTests : IAsyncLifetime -{ - private readonly ITestOutputHelper _output; - private IAwsTestEnvironment _testEnvironment = null!; - private readonly ILogger _logger; - private readonly List _createdTopics = new(); - private readonly List _createdQueues = new(); - - public SnsTopicPublishingIntegrationTests(ITestOutputHelper output) - { - _output = output; - - var services = new ServiceCollection(); - services.AddLogging(builder => builder.AddConsole().SetMinimumLevel(LogLevel.Debug)); - - var serviceProvider = services.BuildServiceProvider(); - _logger = serviceProvider.GetRequiredService>(); - } - - public async Task InitializeAsync() - { - _testEnvironment = await AwsTestEnvironmentFactory.CreateLocalStackEnvironmentAsync(); - - if (!await _testEnvironment.IsAvailableAsync()) - { - throw new InvalidOperationException("AWS test environment is not available"); - } - - _logger.LogInformation("SNS topic publishing integration tests initialized"); - } - - public async Task DisposeAsync() - { - // Clean up created resources - foreach (var topicArn in _createdTopics) - { - try - { - await _testEnvironment.DeleteTopicAsync(topicArn); - } - catch (Exception ex) - { - _logger.LogWarning("Failed to delete topic {TopicArn}: {Error}", topicArn, ex.Message); - } - } - - foreach (var queueUrl in _createdQueues) - { - try - { - await _testEnvironment.DeleteQueueAsync(queueUrl); - } - catch (Exception ex) - { - _logger.LogWarning("Failed to delete queue {QueueUrl}: {Error}", queueUrl, ex.Message); - } - } - - await _testEnvironment.DisposeAsync(); - _logger.LogInformation("SNS topic publishing integration tests disposed"); - } - - [Fact] - public async Task PublishEvent_ToStandardTopic_ShouldSucceed() - { - // Arrange - var topicName = $"test-topic-{Guid.NewGuid():N}"; - var topicArn = await _testEnvironment.CreateTopicAsync(topicName); - _createdTopics.Add(topicArn); - - var testEvent = new TestEvent(new TestEventData - { - Id = 123, - Message = "Test message for SNS publishing", - Value = 456 - }); - - // Act - var publishResponse = await _testEnvironment.SnsClient.PublishAsync(new PublishRequest - { - TopicArn = topicArn, - Message = JsonSerializer.Serialize(testEvent), - Subject = testEvent.Name, - MessageAttributes = new Dictionary - { - ["EventType"] = new MessageAttributeValue - { - DataType = "String", - StringValue = testEvent.GetType().Name - }, - ["EventName"] = new MessageAttributeValue - { - DataType = "String", - StringValue = testEvent.Name - }, - ["EntityId"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = testEvent.Payload.Id.ToString() - } - } - }); - - // Assert - Assert.NotNull(publishResponse); - Assert.NotNull(publishResponse.MessageId); - Assert.NotEmpty(publishResponse.MessageId); - - _logger.LogInformation("Successfully published event to topic {TopicArn} with MessageId {MessageId}", - topicArn, publishResponse.MessageId); - } - - [Fact] - public async Task PublishEvent_WithMessageAttributes_ShouldPreserveAttributes() - { - // Arrange - var topicName = $"test-topic-attrs-{Guid.NewGuid():N}"; - var topicArn = await _testEnvironment.CreateTopicAsync(topicName); - _createdTopics.Add(topicArn); - - var testEvent = new TestEvent(new TestEventData - { - Id = 789, - Message = "Test message with attributes", - Value = 101112 - }); - - var customAttributes = new Dictionary - { - ["EventType"] = new MessageAttributeValue - { - DataType = "String", - StringValue = testEvent.GetType().Name - }, - ["EventName"] = new MessageAttributeValue - { - DataType = "String", - StringValue = testEvent.Name - }, - ["EntityId"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = testEvent.Payload.Id.ToString() - }, - ["Priority"] = new MessageAttributeValue - { - DataType = "String", - StringValue = "High" - }, - ["Source"] = new MessageAttributeValue - { - DataType = "String", - StringValue = "IntegrationTest" - }, - ["Timestamp"] = new MessageAttributeValue - { - DataType = "String", - StringValue = DateTime.UtcNow.ToString("O") - } - }; - - // Act - var publishResponse = await _testEnvironment.SnsClient.PublishAsync(new PublishRequest - { - TopicArn = topicArn, - Message = JsonSerializer.Serialize(testEvent), - Subject = testEvent.Name, - MessageAttributes = customAttributes - }); - - // Assert - Assert.NotNull(publishResponse); - Assert.NotNull(publishResponse.MessageId); - Assert.NotEmpty(publishResponse.MessageId); - - _logger.LogInformation("Successfully published event with {AttributeCount} attributes to topic {TopicArn}", - customAttributes.Count, topicArn); - } - - [Fact] - public async Task PublishEvent_WithTopicEncryption_ShouldSucceed() - { - // Arrange - var topicName = $"test-topic-encrypted-{Guid.NewGuid():N}"; - - // Create topic with server-side encryption (if supported) - var topicAttributes = new Dictionary(); - - // Note: KMS encryption for SNS topics might not be fully supported in LocalStack free tier - // We'll test with basic encryption settings - if (!_testEnvironment.IsLocalEmulator) - { - topicAttributes["KmsMasterKeyId"] = "alias/aws/sns"; - } - - var topicArn = await _testEnvironment.CreateTopicAsync(topicName, topicAttributes); - _createdTopics.Add(topicArn); - - var testEvent = new TestEvent(new TestEventData - { - Id = 999, - Message = "Encrypted test message", - Value = 888 - }); - - // Act - var publishResponse = await _testEnvironment.SnsClient.PublishAsync(new PublishRequest - { - TopicArn = topicArn, - Message = JsonSerializer.Serialize(testEvent), - Subject = testEvent.Name, - MessageAttributes = new Dictionary - { - ["EventType"] = new MessageAttributeValue - { - DataType = "String", - StringValue = testEvent.GetType().Name - }, - ["Encrypted"] = new MessageAttributeValue - { - DataType = "String", - StringValue = "true" - } - } - }); - - // Assert - Assert.NotNull(publishResponse); - Assert.NotNull(publishResponse.MessageId); - Assert.NotEmpty(publishResponse.MessageId); - - _logger.LogInformation("Successfully published encrypted event to topic {TopicArn}", topicArn); - } - - [Fact] - public async Task PublishEvent_WithAccessControl_ShouldRespectPermissions() - { - // Arrange - var topicName = $"test-topic-access-{Guid.NewGuid():N}"; - var topicArn = await _testEnvironment.CreateTopicAsync(topicName); - _createdTopics.Add(topicArn); - - // Verify we have publish permissions - var hasPublishPermission = await _testEnvironment.ValidateIamPermissionsAsync("sns:Publish", topicArn); - - if (!hasPublishPermission && !_testEnvironment.IsLocalEmulator) - { - _logger.LogWarning("Skipping access control test - insufficient permissions"); - return; - } - - var testEvent = new TestEvent(new TestEventData - { - Id = 555, - Message = "Access control test message", - Value = 777 - }); - - // Act & Assert - Should succeed with proper permissions - var publishResponse = await _testEnvironment.SnsClient.PublishAsync(new PublishRequest - { - TopicArn = topicArn, - Message = JsonSerializer.Serialize(testEvent), - Subject = testEvent.Name, - MessageAttributes = new Dictionary - { - ["EventType"] = new MessageAttributeValue - { - DataType = "String", - StringValue = testEvent.GetType().Name - }, - ["AccessTest"] = new MessageAttributeValue - { - DataType = "String", - StringValue = "true" - } - } - }); - - Assert.NotNull(publishResponse); - Assert.NotNull(publishResponse.MessageId); - - _logger.LogInformation("Successfully published event with access control validation to topic {TopicArn}", topicArn); - } - - [Fact] - public async Task PublishEvent_PerformanceTest_ShouldMeetReliabilityThresholds() - { - // Arrange - var topicName = $"test-topic-perf-{Guid.NewGuid():N}"; - var topicArn = await _testEnvironment.CreateTopicAsync(topicName); - _createdTopics.Add(topicArn); - - const int messageCount = 50; - const int maxLatencyMs = 5000; // 5 seconds max per publish - var publishTasks = new List>(); - - // Act - for (int i = 0; i < messageCount; i++) - { - var messageIndex = i; - var task = PublishEventWithLatencyMeasurement(topicArn, messageIndex, maxLatencyMs); - publishTasks.Add(task); - } - - var results = await Task.WhenAll(publishTasks); - - // Assert - var successfulPublishes = results.Count(r => r.Success); - var averageLatency = TimeSpan.FromMilliseconds(results.Where(r => r.Success).Average(r => r.Latency.TotalMilliseconds)); - var maxLatency = results.Where(r => r.Success).Max(r => r.Latency); - var reliabilityRate = (double)successfulPublishes / messageCount; - - // Reliability should be at least 95% - Assert.True(reliabilityRate >= 0.95, - $"Reliability rate {reliabilityRate:P2} is below 95% threshold. {successfulPublishes}/{messageCount} messages published successfully"); - - // Average latency should be reasonable (under 1 second for LocalStack, under 2 seconds for real AWS) - var maxExpectedLatency = _testEnvironment.IsLocalEmulator ? TimeSpan.FromSeconds(1) : TimeSpan.FromSeconds(2); - Assert.True(averageLatency < maxExpectedLatency, - $"Average latency {averageLatency.TotalMilliseconds}ms exceeds threshold {maxExpectedLatency.TotalMilliseconds}ms"); - - _logger.LogInformation("Performance test completed: {SuccessCount}/{TotalCount} messages published successfully. " + - "Average latency: {AvgLatency}ms, Max latency: {MaxLatency}ms, Reliability: {Reliability:P2}", - successfulPublishes, messageCount, averageLatency.TotalMilliseconds, maxLatency.TotalMilliseconds, reliabilityRate); - } - - [Fact] - public async Task PublishEvent_ToNonExistentTopic_ShouldThrowException() - { - // Arrange - var nonExistentTopicArn = "arn:aws:sns:us-east-1:123456789012:non-existent-topic"; - var testEvent = new TestEvent(new TestEventData - { - Id = 404, - Message = "This should fail", - Value = 0 - }); - - // Act & Assert - var exception = await Assert.ThrowsAnyAsync(async () => - { - await _testEnvironment.SnsClient.PublishAsync(new PublishRequest - { - TopicArn = nonExistentTopicArn, - Message = JsonSerializer.Serialize(testEvent), - Subject = testEvent.Name - }); - }); - - Assert.NotNull(exception); - _logger.LogInformation("Expected exception thrown when publishing to non-existent topic: {Exception}", exception.Message); - } - - [Fact] - public async Task PublishEvent_WithLargeMessage_ShouldHandleCorrectly() - { - // Arrange - var topicName = $"test-topic-large-{Guid.NewGuid():N}"; - var topicArn = await _testEnvironment.CreateTopicAsync(topicName); - _createdTopics.Add(topicArn); - - // Create a large message (close to SNS limit of 256KB) - var largeMessage = new string('A', 200 * 1024); // 200KB message - var testEvent = new TestEvent(new TestEventData - { - Id = 1000, - Message = largeMessage, - Value = 2000 - }); - - // Act - var publishResponse = await _testEnvironment.SnsClient.PublishAsync(new PublishRequest - { - TopicArn = topicArn, - Message = JsonSerializer.Serialize(testEvent), - Subject = testEvent.Name, - MessageAttributes = new Dictionary - { - ["EventType"] = new MessageAttributeValue - { - DataType = "String", - StringValue = testEvent.GetType().Name - }, - ["MessageSize"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = largeMessage.Length.ToString() - } - } - }); - - // Assert - Assert.NotNull(publishResponse); - Assert.NotNull(publishResponse.MessageId); - - _logger.LogInformation("Successfully published large message ({Size} bytes) to topic {TopicArn}", - largeMessage.Length, topicArn); - } - - private async Task<(bool Success, TimeSpan Latency, string? MessageId)> PublishEventWithLatencyMeasurement( - string topicArn, int messageIndex, int maxLatencyMs) - { - var stopwatch = System.Diagnostics.Stopwatch.StartNew(); - - try - { - var testEvent = new TestEvent(new TestEventData - { - Id = messageIndex, - Message = $"Performance test message {messageIndex}", - Value = messageIndex * 10 - }); - - var publishResponse = await _testEnvironment.SnsClient.PublishAsync(new PublishRequest - { - TopicArn = topicArn, - Message = JsonSerializer.Serialize(testEvent), - Subject = testEvent.Name, - MessageAttributes = new Dictionary - { - ["EventType"] = new MessageAttributeValue - { - DataType = "String", - StringValue = testEvent.GetType().Name - }, - ["MessageIndex"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = messageIndex.ToString() - } - } - }); - - stopwatch.Stop(); - - var success = publishResponse?.MessageId != null && stopwatch.ElapsedMilliseconds <= maxLatencyMs; - return (success, stopwatch.Elapsed, publishResponse?.MessageId); - } - catch (Exception ex) - { - stopwatch.Stop(); - _logger.LogWarning("Failed to publish message {MessageIndex}: {Error}", messageIndex, ex.Message); - return (false, stopwatch.Elapsed, null); - } - } -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/Integration/SqsBatchOperationsIntegrationTests.cs b/tests/SourceFlow.Cloud.AWS.Tests/Integration/SqsBatchOperationsIntegrationTests.cs deleted file mode 100644 index 075da4d5..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/Integration/SqsBatchOperationsIntegrationTests.cs +++ /dev/null @@ -1,874 +0,0 @@ -using Amazon.SQS.Model; -using SourceFlow.Cloud.AWS.Tests.TestHelpers; -using System.Diagnostics; -using System.Text.Json; - -namespace SourceFlow.Cloud.AWS.Tests.Integration; - -/// -/// Comprehensive integration tests for SQS batch operations -/// Tests batch sending up to AWS limits, efficiency, resource utilization, and partial failure handling -/// -[Collection("AWS Integration Tests")] -[Trait("Category", "Integration")] -[Trait("Category", "RequiresLocalStack")] -public class SqsBatchOperationsIntegrationTests : IClassFixture, IAsyncDisposable -{ - private readonly LocalStackTestFixture _localStack; - private readonly List _createdQueues = new(); - - public SqsBatchOperationsIntegrationTests(LocalStackTestFixture localStack) - { - _localStack = localStack; - } - - [Fact] - public async Task BatchSend_ShouldRespectAwsTenMessageLimit() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.SqsClient == null) - { - return; - } - - // Arrange - var queueName = $"test-batch-limit-{Guid.NewGuid():N}"; - var queueUrl = await CreateStandardQueueAsync(queueName); - - // Test exactly 10 messages (AWS limit) - var maxBatchSize = 10; - var batchEntries = new List(); - - for (int i = 0; i < maxBatchSize; i++) - { - batchEntries.Add(new SendMessageBatchRequestEntry - { - Id = i.ToString(), - MessageBody = $"Batch message {i} - {DateTime.UtcNow:HH:mm:ss.fff}", - MessageAttributes = new Dictionary - { - ["MessageIndex"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = i.ToString() - }, - ["BatchId"] = new MessageAttributeValue - { - DataType = "String", - StringValue = Guid.NewGuid().ToString() - }, - ["EntityId"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = (1000 + i).ToString() - }, - ["CommandType"] = new MessageAttributeValue - { - DataType = "String", - StringValue = "BatchTestCommand" - } - } - }); - } - - // Act - Send batch of exactly 10 messages - var batchResponse = await _localStack.SqsClient.SendMessageBatchAsync(new SendMessageBatchRequest - { - QueueUrl = queueUrl, - Entries = batchEntries - }); - - // Assert - All messages should be sent successfully - Assert.Equal(maxBatchSize, batchResponse.Successful.Count); - Assert.Empty(batchResponse.Failed); - - // Verify each successful response - foreach (var successful in batchResponse.Successful) - { - Assert.NotNull(successful.MessageId); - Assert.True(int.Parse(successful.Id) >= 0 && int.Parse(successful.Id) < maxBatchSize); - } - - // Act - Receive all messages - var receivedMessages = new List(); - var maxAttempts = 10; - var attempts = 0; - - while (receivedMessages.Count < maxBatchSize && attempts < maxAttempts) - { - var receiveResponse = await _localStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = queueUrl, - MaxNumberOfMessages = 10, - MessageAttributeNames = new List { "All" }, - WaitTimeSeconds = 1 - }); - - receivedMessages.AddRange(receiveResponse.Messages); - attempts++; - } - - // Assert - All messages should be received - Assert.Equal(maxBatchSize, receivedMessages.Count); - - // Verify message content and attributes - var receivedIndices = receivedMessages - .Select(m => int.Parse(m.MessageAttributes["MessageIndex"].StringValue)) - .OrderBy(i => i) - .ToList(); - - var expectedIndices = Enumerable.Range(0, maxBatchSize).ToList(); - Assert.Equal(expectedIndices, receivedIndices); - - // Clean up - await CleanupMessages(queueUrl, receivedMessages); - } - - [Fact] - public async Task BatchSend_ShouldRejectMoreThanTenMessages() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.SqsClient == null) - { - return; - } - - // Arrange - var queueName = $"test-batch-over-limit-{Guid.NewGuid():N}"; - var queueUrl = await CreateStandardQueueAsync(queueName); - - // Try to send 11 messages (over AWS limit) - var overLimitBatchSize = 11; - var batchEntries = new List(); - - for (int i = 0; i < overLimitBatchSize; i++) - { - batchEntries.Add(new SendMessageBatchRequestEntry - { - Id = i.ToString(), - MessageBody = $"Over limit message {i}", - MessageAttributes = new Dictionary - { - ["MessageIndex"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = i.ToString() - } - } - }); - } - - // Act & Assert - Should throw exception for too many messages - var exception = await Assert.ThrowsAnyAsync(async () => - { - await _localStack.SqsClient.SendMessageBatchAsync(new SendMessageBatchRequest - { - QueueUrl = queueUrl, - Entries = batchEntries - }); - }); - - // Verify error is related to batch size limit (message varies by SDK/LocalStack version) - Assert.True( - exception.Message.Contains("batch", StringComparison.OrdinalIgnoreCase) || - exception.Message.Contains("entries", StringComparison.OrdinalIgnoreCase), - $"Expected batch size error but got: {exception.Message}"); - } - - [Fact] - public async Task BatchSend_ShouldBeMoreEfficientThanIndividualSends() - { - // Skip if not configured for integration tests or performance tests - if (!_localStack.Configuration.RunIntegrationTests || - !_localStack.Configuration.RunPerformanceTests || - _localStack.SqsClient == null) - { - return; - } - - // Arrange - var queueName = $"test-batch-efficiency-{Guid.NewGuid():N}"; - var queueUrl = await CreateStandardQueueAsync(queueName); - - var messageCount = 30; // Test with multiple batches - var testMessages = Enumerable.Range(0, messageCount) - .Select(i => new - { - Index = i, - Body = $"Efficiency test message {i} - {DateTime.UtcNow:HH:mm:ss.fff}", - EntityId = 2000 + i, - CommandType = "EfficiencyTestCommand" - }) - .ToList(); - - // Act - Send messages individually - var individualStopwatch = Stopwatch.StartNew(); - var individualTasks = testMessages.Select(async msg => - { - return await _localStack.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = queueUrl, - MessageBody = msg.Body, - MessageAttributes = new Dictionary - { - ["MessageIndex"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = msg.Index.ToString() - }, - ["SendMethod"] = new MessageAttributeValue - { - DataType = "String", - StringValue = "Individual" - }, - ["EntityId"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = msg.EntityId.ToString() - }, - ["CommandType"] = new MessageAttributeValue - { - DataType = "String", - StringValue = msg.CommandType - } - } - }); - }); - - var individualResults = await Task.WhenAll(individualTasks); - individualStopwatch.Stop(); - - // Clear the queue - await DrainQueue(queueUrl); - - // Act - Send messages in batches - var batchStopwatch = Stopwatch.StartNew(); - var batches = testMessages - .Select((msg, index) => new { Message = msg, Index = index }) - .GroupBy(x => x.Index / 10) // Group into batches of 10 - .Select(g => g.ToList()) - .ToList(); - - var batchTasks = batches.Select(async batch => - { - var entries = batch.Select(item => new SendMessageBatchRequestEntry - { - Id = item.Message.Index.ToString(), - MessageBody = item.Message.Body, - MessageAttributes = new Dictionary - { - ["MessageIndex"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = item.Message.Index.ToString() - }, - ["SendMethod"] = new MessageAttributeValue - { - DataType = "String", - StringValue = "Batch" - }, - ["EntityId"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = item.Message.EntityId.ToString() - }, - ["CommandType"] = new MessageAttributeValue - { - DataType = "String", - StringValue = item.Message.CommandType - } - } - }).ToList(); - - return await _localStack.SqsClient.SendMessageBatchAsync(new SendMessageBatchRequest - { - QueueUrl = queueUrl, - Entries = entries - }); - }); - - var batchResults = await Task.WhenAll(batchTasks); - batchStopwatch.Stop(); - - // Assert - Both methods should send all messages successfully - Assert.Equal(messageCount, individualResults.Length); - Assert.All(individualResults, result => Assert.NotNull(result.MessageId)); - - var totalBatchSuccessful = batchResults.Sum(r => r.Successful.Count); - var totalBatchFailed = batchResults.Sum(r => r.Failed.Count); - - Assert.Equal(messageCount, totalBatchSuccessful); - Assert.Equal(0, totalBatchFailed); - - // Calculate performance metrics - var individualThroughput = messageCount / individualStopwatch.Elapsed.TotalSeconds; - var batchThroughput = messageCount / batchStopwatch.Elapsed.TotalSeconds; - var individualLatency = individualStopwatch.Elapsed.TotalMilliseconds / messageCount; - var batchLatency = batchStopwatch.Elapsed.TotalMilliseconds / messageCount; - - // Log performance results - Console.WriteLine($"Individual sends: {individualThroughput:F2} msg/sec, {individualLatency:F2}ms avg latency"); - Console.WriteLine($"Batch sends: {batchThroughput:F2} msg/sec, {batchLatency:F2}ms avg latency"); - Console.WriteLine($"Batch efficiency gain: {(batchThroughput / individualThroughput):F2}x throughput, {(individualLatency / batchLatency):F2}x latency improvement"); - - // Assert - Batch should be more efficient (this is informational for LocalStack) - Assert.True(batchThroughput > 0 && individualThroughput > 0, - "Both batch and individual throughput should be positive"); - - // In real AWS, batch operations are typically more efficient - // For LocalStack, we just verify both methods work correctly - - // Verify all messages are in the queue - var finalReceiveResponse = await _localStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = queueUrl, - MaxNumberOfMessages = 10, - MessageAttributeNames = new List { "All" }, - WaitTimeSeconds = 2 - }); - - Assert.True(finalReceiveResponse.Messages.Count > 0, "Should have messages from batch sends"); - - // Clean up - await DrainQueue(queueUrl); - } - - [Fact] - public async Task BatchSend_ShouldHandlePartialFailures() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.SqsClient == null) - { - return; - } - - // Arrange - var queueName = $"test-batch-partial-failure-{Guid.NewGuid():N}"; - var queueUrl = await CreateStandardQueueAsync(queueName); - - // Create a batch with some potentially problematic messages - var batchEntries = new List - { - // Valid messages - new SendMessageBatchRequestEntry - { - Id = "valid-1", - MessageBody = "Valid message 1", - MessageAttributes = new Dictionary - { - ["MessageType"] = new MessageAttributeValue { DataType = "String", StringValue = "Valid" } - } - }, - new SendMessageBatchRequestEntry - { - Id = "valid-2", - MessageBody = "Valid message 2", - MessageAttributes = new Dictionary - { - ["MessageType"] = new MessageAttributeValue { DataType = "String", StringValue = "Valid" } - } - }, - // Potentially problematic message (unique ID) - new SendMessageBatchRequestEntry - { - Id = "problematic-1", - MessageBody = "Duplicate ID message", - MessageAttributes = new Dictionary - { - ["MessageType"] = new MessageAttributeValue { DataType = "String", StringValue = "Duplicate" } - } - }, - // Valid message - new SendMessageBatchRequestEntry - { - Id = "valid-3", - MessageBody = "Valid message 3", - MessageAttributes = new Dictionary - { - ["MessageType"] = new MessageAttributeValue { DataType = "String", StringValue = "Valid" } - } - } - }; - - // Act - Send batch with potential failures - var batchResponse = await _localStack.SqsClient.SendMessageBatchAsync(new SendMessageBatchRequest - { - QueueUrl = queueUrl, - Entries = batchEntries - }); - - // Assert - Should have both successful and failed messages - Assert.True(batchResponse.Successful.Count > 0, "Should have some successful messages"); - - // In LocalStack, duplicate IDs might be handled differently than real AWS - // The key is that the operation completes and provides clear success/failure information - var totalProcessed = batchResponse.Successful.Count + batchResponse.Failed.Count; - Assert.Equal(batchEntries.Count, totalProcessed); - - // Verify successful messages have valid response data - foreach (var successful in batchResponse.Successful) - { - Assert.NotNull(successful.MessageId); - Assert.Contains(successful.Id, batchEntries.Select(e => e.Id)); - } - - // Verify failed messages have error information - foreach (var failed in batchResponse.Failed) - { - Assert.NotNull(failed.Id); - Assert.NotNull(failed.Code); - Assert.NotNull(failed.Message); - Assert.True(failed.SenderFault); // Client-side errors should be marked as sender fault - } - - // Act - Receive successful messages - var receiveResponse = await _localStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = queueUrl, - MaxNumberOfMessages = 10, - MessageAttributeNames = new List { "All" }, - WaitTimeSeconds = 2 - }); - - // Assert - Should receive only the successful messages - Assert.Equal(batchResponse.Successful.Count, receiveResponse.Messages.Count); - - foreach (var message in receiveResponse.Messages) - { - Assert.True(message.MessageAttributes.ContainsKey("MessageType")); - var messageType = message.MessageAttributes["MessageType"].StringValue; - Assert.True(messageType == "Valid" || messageType == "Duplicate"); // Depending on LocalStack behavior - } - - // Clean up - await CleanupMessages(queueUrl, receiveResponse.Messages); - } - - [Fact] - public async Task BatchSend_ShouldSupportFifoQueues() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.SqsClient == null) - { - return; - } - - // Arrange - var queueName = $"test-batch-fifo-{Guid.NewGuid():N}.fifo"; - var queueUrl = await CreateFifoQueueAsync(queueName); - - var entityId = 3000; - var messageGroupId = $"entity-{entityId}"; - var batchSize = 8; // Less than 10 for easier testing - - // Create FIFO batch entries - var batchEntries = new List(); - - for (int i = 0; i < batchSize; i++) - { - batchEntries.Add(new SendMessageBatchRequestEntry - { - Id = i.ToString(), - MessageBody = $"FIFO batch message {i} - Entity {entityId}", - MessageGroupId = messageGroupId, - MessageDeduplicationId = $"batch-{entityId}-{i}-{Guid.NewGuid():N}", - MessageAttributes = new Dictionary - { - ["EntityId"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = entityId.ToString() - }, - ["SequenceNo"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = i.ToString() - }, - ["CommandType"] = new MessageAttributeValue - { - DataType = "String", - StringValue = "FifoBatchCommand" - }, - ["BatchIndex"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = i.ToString() - } - } - }); - } - - // Act - Send FIFO batch - var batchResponse = await _localStack.SqsClient.SendMessageBatchAsync(new SendMessageBatchRequest - { - QueueUrl = queueUrl, - Entries = batchEntries - }); - - // Assert - All messages should be sent successfully - Assert.Equal(batchSize, batchResponse.Successful.Count); - Assert.Empty(batchResponse.Failed); - - // Act - Receive messages in order - var receivedMessages = new List(); - var maxAttempts = 10; - var attempts = 0; - - while (receivedMessages.Count < batchSize && attempts < maxAttempts) - { - var receiveResponse = await _localStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = queueUrl, - MaxNumberOfMessages = 10, - MessageAttributeNames = new List { "All" }, - WaitTimeSeconds = 1 - }); - - receivedMessages.AddRange(receiveResponse.Messages); - attempts++; - } - - // Assert - All messages should be received - Assert.Equal(batchSize, receivedMessages.Count); - - // Verify FIFO ordering is maintained - var orderedMessages = receivedMessages - .OrderBy(m => int.Parse(m.MessageAttributes["BatchIndex"].StringValue)) - .ToList(); - - for (int i = 0; i < batchSize; i++) - { - var message = orderedMessages[i]; - Assert.Equal(i.ToString(), message.MessageAttributes["BatchIndex"].StringValue); - Assert.Equal(entityId.ToString(), message.MessageAttributes["EntityId"].StringValue); - Assert.Equal("FifoBatchCommand", message.MessageAttributes["CommandType"].StringValue); - Assert.Contains($"FIFO batch message {i}", message.Body); - } - - // Verify message group ID is preserved - foreach (var message in receivedMessages) - { - if (message.Attributes.ContainsKey("MessageGroupId")) - { - Assert.Equal(messageGroupId, message.Attributes["MessageGroupId"]); - } - } - - // Clean up - await CleanupMessages(queueUrl, receivedMessages); - } - - [Fact] - public async Task BatchReceive_ShouldReceiveMultipleMessages() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.SqsClient == null) - { - return; - } - - // Arrange - var queueName = $"test-batch-receive-{Guid.NewGuid():N}"; - var queueUrl = await CreateStandardQueueAsync(queueName); - - var messageCount = 15; - - // Send individual messages first - var sendTasks = Enumerable.Range(0, messageCount).Select(async i => - { - return await _localStack.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = queueUrl, - MessageBody = $"Batch receive test message {i}", - MessageAttributes = new Dictionary - { - ["MessageIndex"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = i.ToString() - }, - ["EntityId"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = (4000 + i).ToString() - }, - ["CommandType"] = new MessageAttributeValue - { - DataType = "String", - StringValue = "BatchReceiveTestCommand" - } - } - }); - }); - - await Task.WhenAll(sendTasks); - - // Act - Receive messages in batches - var allReceivedMessages = new List(); - var maxBatchReceiveAttempts = 5; - var attempts = 0; - - while (allReceivedMessages.Count < messageCount && attempts < maxBatchReceiveAttempts) - { - var receiveResponse = await _localStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = queueUrl, - MaxNumberOfMessages = 10, // AWS maximum for batch receive - MessageAttributeNames = new List { "All" }, - WaitTimeSeconds = 2 - }); - - allReceivedMessages.AddRange(receiveResponse.Messages); - attempts++; - - if (receiveResponse.Messages.Count == 0) - { - break; // No more messages - } - } - - // Assert - Should receive all messages - Assert.True(allReceivedMessages.Count >= messageCount * 0.9, // Allow some variance - $"Expected at least {messageCount * 0.9} messages, received {allReceivedMessages.Count}"); - - // Verify message content - var receivedIndices = allReceivedMessages - .Select(m => int.Parse(m.MessageAttributes["MessageIndex"].StringValue)) - .OrderBy(i => i) - .ToList(); - - Assert.True(receivedIndices.Count > 0, "Should have received messages with indices"); - - // Verify all messages have required attributes - foreach (var message in allReceivedMessages) - { - Assert.True(message.MessageAttributes.ContainsKey("MessageIndex")); - Assert.True(message.MessageAttributes.ContainsKey("EntityId")); - Assert.True(message.MessageAttributes.ContainsKey("CommandType")); - Assert.Equal("BatchReceiveTestCommand", message.MessageAttributes["CommandType"].StringValue); - } - - // Clean up - await CleanupMessages(queueUrl, allReceivedMessages); - } - - [Fact] - public async Task BatchDelete_ShouldDeleteMultipleMessages() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.SqsClient == null) - { - return; - } - - // Arrange - var queueName = $"test-batch-delete-{Guid.NewGuid():N}"; - var queueUrl = await CreateStandardQueueAsync(queueName); - - var messageCount = 8; - - // Send messages - var sendTasks = Enumerable.Range(0, messageCount).Select(async i => - { - return await _localStack.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = queueUrl, - MessageBody = $"Batch delete test message {i}", - MessageAttributes = new Dictionary - { - ["MessageIndex"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = i.ToString() - } - } - }); - }); - - await Task.WhenAll(sendTasks); - - // Receive messages - var receiveResponse = await _localStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = queueUrl, - MaxNumberOfMessages = 10, - MessageAttributeNames = new List { "All" }, - WaitTimeSeconds = 2 - }); - - Assert.True(receiveResponse.Messages.Count >= messageCount * 0.8, - $"Should receive at least {messageCount * 0.8} messages for batch delete test"); - - // Act - Delete messages in batch - var deleteEntries = receiveResponse.Messages.Select((message, index) => new DeleteMessageBatchRequestEntry - { - Id = index.ToString(), - ReceiptHandle = message.ReceiptHandle - }).ToList(); - - var batchDeleteResponse = await _localStack.SqsClient.DeleteMessageBatchAsync(new DeleteMessageBatchRequest - { - QueueUrl = queueUrl, - Entries = deleteEntries - }); - - // Assert - All deletes should be successful - Assert.Equal(deleteEntries.Count, batchDeleteResponse.Successful.Count); - Assert.Empty(batchDeleteResponse.Failed); - - // Verify each successful delete - foreach (var successful in batchDeleteResponse.Successful) - { - Assert.Contains(successful.Id, deleteEntries.Select(e => e.Id)); - } - - // Act - Verify queue is empty - var finalReceiveResponse = await _localStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = queueUrl, - MaxNumberOfMessages = 10, - WaitTimeSeconds = 1 - }); - - // Assert - Queue should be empty after batch delete - Assert.Empty(finalReceiveResponse.Messages); - } - - /// - /// Create a standard queue with the specified name and attributes - /// - private async Task CreateStandardQueueAsync(string queueName, Dictionary? additionalAttributes = null) - { - var attributes = new Dictionary - { - ["MessageRetentionPeriod"] = "1209600", // 14 days - ["VisibilityTimeout"] = "30" - }; - - if (additionalAttributes != null) - { - foreach (var attr in additionalAttributes) - { - attributes[attr.Key] = attr.Value; - } - } - - var response = await _localStack.SqsClient.CreateQueueAsync(new CreateQueueRequest - { - QueueName = queueName, - Attributes = attributes - }); - - _createdQueues.Add(response.QueueUrl); - return response.QueueUrl; - } - - /// - /// Create a FIFO queue with the specified name and attributes - /// - private async Task CreateFifoQueueAsync(string queueName, Dictionary? additionalAttributes = null) - { - var attributes = new Dictionary - { - ["FifoQueue"] = "true", - ["ContentBasedDeduplication"] = "true", - ["MessageRetentionPeriod"] = "1209600", - ["VisibilityTimeout"] = "30" - }; - - if (additionalAttributes != null) - { - foreach (var attr in additionalAttributes) - { - attributes[attr.Key] = attr.Value; - } - } - - var response = await _localStack.SqsClient.CreateQueueAsync(new CreateQueueRequest - { - QueueName = queueName, - Attributes = attributes - }); - - _createdQueues.Add(response.QueueUrl); - return response.QueueUrl; - } - - /// - /// Clean up messages from a queue - /// - private async Task CleanupMessages(string queueUrl, List messages) - { - if (!messages.Any()) return; - - var deleteTasks = messages.Select(message => - _localStack.SqsClient.DeleteMessageAsync(new DeleteMessageRequest - { - QueueUrl = queueUrl, - ReceiptHandle = message.ReceiptHandle - })); - - try - { - await Task.WhenAll(deleteTasks); - } - catch (Exception) - { - // Ignore cleanup errors - } - } - - /// - /// Drain all messages from a queue - /// - private async Task DrainQueue(string queueUrl) - { - var maxAttempts = 10; - var attempts = 0; - - while (attempts < maxAttempts) - { - var receiveResponse = await _localStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = queueUrl, - MaxNumberOfMessages = 10, - WaitTimeSeconds = 1 - }); - - if (receiveResponse.Messages.Count == 0) - { - break; // Queue is empty - } - - // Delete all received messages - await CleanupMessages(queueUrl, receiveResponse.Messages); - attempts++; - } - } - - /// - /// Clean up created queues - /// - public async ValueTask DisposeAsync() - { - if (_localStack.SqsClient != null) - { - foreach (var queueUrl in _createdQueues) - { - try - { - await _localStack.SqsClient.DeleteQueueAsync(new DeleteQueueRequest - { - QueueUrl = queueUrl - }); - } - catch (Exception) - { - // Ignore cleanup errors - } - } - } - - _createdQueues.Clear(); - } -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/Integration/SqsDeadLetterQueueIntegrationTests.cs b/tests/SourceFlow.Cloud.AWS.Tests/Integration/SqsDeadLetterQueueIntegrationTests.cs deleted file mode 100644 index b38051dd..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/Integration/SqsDeadLetterQueueIntegrationTests.cs +++ /dev/null @@ -1,174 +0,0 @@ -using Amazon.SQS.Model; -using SourceFlow.Cloud.AWS.Tests.TestHelpers; -using System.Text.Json; - -namespace SourceFlow.Cloud.AWS.Tests.Integration; - -/// -/// Comprehensive integration tests for SQS dead letter queue functionality -/// Tests failed message capture, retry policies, poison message handling, and reprocessing capabilities -/// -/// -/// Integration tests for SQS dead letter queue functionality -/// -[Collection("AWS Integration Tests")] -[Trait("Category", "Integration")] -[Trait("Category", "RequiresLocalStack")] -public class SqsDeadLetterQueueIntegrationTests : IClassFixture, IAsyncDisposable -{ - private readonly LocalStackTestFixture _localStack; - private readonly List _createdQueues = new(); - - public SqsDeadLetterQueueIntegrationTests(LocalStackTestFixture localStack) - { - _localStack = localStack; - } - - public async ValueTask DisposeAsync() - { - if (!_localStack.Configuration.RunIntegrationTests || _localStack.SqsClient == null) - { - return; - } - - // Clean up all created queues - foreach (var queueUrl in _createdQueues) - { - try - { - await _localStack.SqsClient.DeleteQueueAsync(queueUrl); - } - catch - { - // Ignore cleanup errors - } - } - } - - [Fact] - public async Task DeadLetterQueue_ShouldReceiveFailedMessages() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.SqsClient == null) - { - return; - } - - // Create DLQ - var dlqName = $"test-dlq-{Guid.NewGuid():N}"; - var dlqResponse = await _localStack.SqsClient.CreateQueueAsync(dlqName); - var dlqUrl = dlqResponse.QueueUrl; - _createdQueues.Add(dlqUrl); - - // Get DLQ ARN - var dlqAttributes = await _localStack.SqsClient.GetQueueAttributesAsync(new GetQueueAttributesRequest - { - QueueUrl = dlqUrl, - AttributeNames = new List { "QueueArn" } - }); - var dlqArn = dlqAttributes.QueueARN; - - // Create main queue with DLQ configuration - var queueName = $"test-queue-{Guid.NewGuid():N}"; - var createResponse = await _localStack.SqsClient.CreateQueueAsync(new CreateQueueRequest - { - QueueName = queueName, - Attributes = new Dictionary - { - ["RedrivePolicy"] = $"{{\"deadLetterTargetArn\":\"{dlqArn}\",\"maxReceiveCount\":\"2\"}}" - } - }); - var queueUrl = createResponse.QueueUrl; - _createdQueues.Add(queueUrl); - - // Send a test message - var messageBody = $"Test message {Guid.NewGuid()}"; - await _localStack.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = queueUrl, - MessageBody = messageBody - }); - - // Receive and don't delete (simulate failure) - do this 3 times to exceed maxReceiveCount - for (int i = 0; i < 3; i++) - { - var receiveResponse = await _localStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = queueUrl, - MaxNumberOfMessages = 1, - VisibilityTimeout = 1, - WaitTimeSeconds = 1 - }); - - if (receiveResponse.Messages.Count > 0) - { - // Don't delete - let visibility timeout expire - await Task.Delay(TimeSpan.FromSeconds(2)); - } - } - - // Check DLQ for the failed message - await Task.Delay(TimeSpan.FromSeconds(2)); // Give time for message to move to DLQ - - var dlqReceiveResponse = await _localStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = dlqUrl, - MaxNumberOfMessages = 1, - WaitTimeSeconds = 5 - }); - - Assert.Single(dlqReceiveResponse.Messages); - Assert.Equal(messageBody, dlqReceiveResponse.Messages[0].Body); - } - - [Fact] - public async Task DeadLetterQueue_ShouldHaveCorrectConfiguration() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.SqsClient == null) - { - return; - } - - // Create DLQ - var dlqName = $"test-dlq-config-{Guid.NewGuid():N}"; - var dlqResponse = await _localStack.SqsClient.CreateQueueAsync(dlqName); - var dlqUrl = dlqResponse.QueueUrl; - _createdQueues.Add(dlqUrl); - - // Get DLQ ARN - var dlqAttributes = await _localStack.SqsClient.GetQueueAttributesAsync(new GetQueueAttributesRequest - { - QueueUrl = dlqUrl, - AttributeNames = new List { "QueueArn" } - }); - var dlqArn = dlqAttributes.QueueARN; - - // Create main queue with DLQ configuration - var queueName = $"test-queue-config-{Guid.NewGuid():N}"; - var maxReceiveCount = 5; - var createResponse = await _localStack.SqsClient.CreateQueueAsync(new CreateQueueRequest - { - QueueName = queueName, - Attributes = new Dictionary - { - ["RedrivePolicy"] = $"{{\"deadLetterTargetArn\":\"{dlqArn}\",\"maxReceiveCount\":\"{maxReceiveCount}\"}}" - } - }); - var queueUrl = createResponse.QueueUrl; - _createdQueues.Add(queueUrl); - - // Verify configuration - var attributes = await _localStack.SqsClient.GetQueueAttributesAsync(new GetQueueAttributesRequest - { - QueueUrl = queueUrl, - AttributeNames = new List { "RedrivePolicy" } - }); - - Assert.Contains("RedrivePolicy", attributes.Attributes.Keys); - var redrivePolicy = attributes.Attributes["RedrivePolicy"]; - Assert.Contains(dlqArn, redrivePolicy); - Assert.Contains($"\"maxReceiveCount\":\"{maxReceiveCount}\"", redrivePolicy); - } -} - diff --git a/tests/SourceFlow.Cloud.AWS.Tests/Integration/SqsDeadLetterQueuePropertyTests.cs b/tests/SourceFlow.Cloud.AWS.Tests/Integration/SqsDeadLetterQueuePropertyTests.cs deleted file mode 100644 index 7347f4fe..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/Integration/SqsDeadLetterQueuePropertyTests.cs +++ /dev/null @@ -1,746 +0,0 @@ -using Amazon.SQS.Model; -using FsCheck; -using FsCheck.Xunit; -using SourceFlow.Cloud.AWS.Tests.TestHelpers; -using System.Text.Json; - -namespace SourceFlow.Cloud.AWS.Tests.Integration; - -/// -/// Property-based tests for SQS dead letter queue handling -/// Validates universal properties that should hold for all dead letter queue scenarios -/// -[Collection("AWS Integration Tests")] -[Trait("Category", "Integration")] -[Trait("Category", "RequiresLocalStack")] -public class SqsDeadLetterQueuePropertyTests : IClassFixture, IAsyncDisposable -{ - private readonly LocalStackTestFixture _localStack; - private readonly List _createdQueues = new(); - - public SqsDeadLetterQueuePropertyTests(LocalStackTestFixture localStack) - { - _localStack = localStack; - } - - /// - /// Property 2: SQS Dead Letter Queue Handling - /// For any command that fails processing beyond the maximum retry count, - /// it should be automatically moved to the configured dead letter queue with - /// complete failure metadata, retry history, and be available for analysis and reprocessing. - /// Validates: Requirements 1.3 - /// - [Property(MaxTest = 15, Arbitrary = new[] { typeof(DeadLetterQueueGenerators) })] - // FsCheck 2.x does not support async Task properties — method must be void - public void Property_SqsDeadLetterQueueHandling(DeadLetterQueueScenario scenario) => - Property_SqsDeadLetterQueueHandlingAsync(scenario).GetAwaiter().GetResult(); - - private async Task Property_SqsDeadLetterQueueHandlingAsync(DeadLetterQueueScenario scenario) - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.SqsClient == null) - { - return; - } - - // Arrange - Create main queue with dead letter queue - var dlqUrl = scenario.QueueType == QueueType.Fifo - ? await CreateFifoQueueAsync($"prop-test-dlq-{Guid.NewGuid():N}.fifo") - : await CreateStandardQueueAsync($"prop-test-dlq-{Guid.NewGuid():N}"); - - var dlqArn = await GetQueueArnAsync(dlqUrl); - - var mainQueueUrl = scenario.QueueType == QueueType.Fifo - ? await CreateFifoQueueAsync($"prop-test-main-{Guid.NewGuid():N}.fifo", new Dictionary - { - ["VisibilityTimeout"] = scenario.VisibilityTimeout.ToString(), - ["RedrivePolicy"] = JsonSerializer.Serialize(new - { - deadLetterTargetArn = dlqArn, - maxReceiveCount = scenario.MaxReceiveCount - }) - }) - : await CreateStandardQueueAsync($"prop-test-main-{Guid.NewGuid():N}", new Dictionary - { - ["VisibilityTimeout"] = scenario.VisibilityTimeout.ToString(), - ["RedrivePolicy"] = JsonSerializer.Serialize(new - { - deadLetterTargetArn = dlqArn, - maxReceiveCount = scenario.MaxReceiveCount - }) - }); - - var sentMessages = new List(); - var dlqMessages = new List(); - - try - { - // Act - Send messages that will fail processing - await SendFailingMessages(mainQueueUrl, scenario, sentMessages); - - // Act - Simulate processing failures up to maxReceiveCount - await SimulateProcessingFailures(mainQueueUrl, scenario); - - // Act - Wait for messages to be moved to DLQ - await Task.Delay(TimeSpan.FromSeconds(scenario.VisibilityTimeout + 2)); - - // Act - Retrieve messages from dead letter queue - await RetrieveDeadLetterMessages(dlqUrl, scenario.Messages.Count, dlqMessages); - - // Assert - Dead letter queue correctness - AssertDeadLetterQueueCorrectness(sentMessages, dlqMessages, scenario); - - // Assert - Message metadata preservation - AssertMessageMetadataPreservation(sentMessages, dlqMessages); - - // Assert - Failure information completeness - AssertFailureInformationCompleteness(dlqMessages, scenario); - - // Assert - Reprocessing capability - await AssertReprocessingCapability(dlqUrl, dlqMessages, scenario); - } - finally - { - // Clean up messages - await CleanupMessages(dlqUrl, dlqMessages); - } - } - - /// - /// Send messages that will fail processing to the main queue - /// - private async Task SendFailingMessages(string queueUrl, DeadLetterQueueScenario scenario, List sentMessages) - { - var sendTasks = scenario.Messages.Select(async (message, index) => - { - var request = CreateSendMessageRequest(queueUrl, message, scenario.QueueType, index); - var startTime = DateTime.UtcNow; - - var response = await _localStack.SqsClient.SendMessageAsync(request); - var endTime = DateTime.UtcNow; - - var sentMessage = new DeadLetterTestMessage - { - OriginalMessage = message, - MessageId = response.MessageId, - SendTime = startTime, - SendDuration = endTime - startTime, - MessageGroupId = request.MessageGroupId, - MessageDeduplicationId = request.MessageDeduplicationId, - ExpectedFailureType = message.FailureType, - MessageAttributes = request.MessageAttributes.ToDictionary( - kvp => kvp.Key, - kvp => kvp.Value.StringValue ?? kvp.Value.BinaryValue?.ToString() ?? "") - }; - - lock (sentMessages) - { - sentMessages.Add(sentMessage); - } - }); - - await Task.WhenAll(sendTasks); - } - - /// - /// Simulate processing failures by receiving messages without deleting them - /// - private async Task SimulateProcessingFailures(string queueUrl, DeadLetterQueueScenario scenario) - { - var maxAttempts = scenario.MaxReceiveCount + 2; // Try a bit more than max to ensure DLQ triggering - var visibilityTimeout = TimeSpan.FromSeconds(scenario.VisibilityTimeout); - - for (int attempt = 1; attempt <= maxAttempts; attempt++) - { - var receiveResponse = await _localStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = queueUrl, - MaxNumberOfMessages = 10, - MessageAttributeNames = new List { "All" }, - WaitTimeSeconds = 1 - }); - - if (receiveResponse.Messages.Any()) - { - // Don't delete messages - simulate processing failure - // Wait for visibility timeout to expire - await Task.Delay(visibilityTimeout.Add(TimeSpan.FromMilliseconds(500))); - } - else - { - // No more messages in main queue - they might have been moved to DLQ - break; - } - } - } - - /// - /// Retrieve messages from the dead letter queue - /// - private async Task RetrieveDeadLetterMessages(string dlqUrl, int expectedCount, List dlqMessages) - { - var maxAttempts = 10; - var attempts = 0; - - while (dlqMessages.Count < expectedCount && attempts < maxAttempts) - { - var receiveResponse = await _localStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = dlqUrl, - MaxNumberOfMessages = 10, - MessageAttributeNames = new List { "All" }, - WaitTimeSeconds = 1 - }); - - dlqMessages.AddRange(receiveResponse.Messages); - attempts++; - - if (receiveResponse.Messages.Count == 0) - { - await Task.Delay(500); - } - } - } - - /// - /// Assert that dead letter queue handling is correct - /// - private static void AssertDeadLetterQueueCorrectness(List sentMessages, List dlqMessages, DeadLetterQueueScenario scenario) - { - // Messages should be moved to DLQ after exceeding maxReceiveCount - Assert.True(dlqMessages.Count >= sentMessages.Count * 0.8, // Allow some variance for LocalStack - $"Expected at least {sentMessages.Count * 0.8} messages in DLQ, found {dlqMessages.Count}"); - - // Each DLQ message should correspond to a sent message - foreach (var dlqMessage in dlqMessages) - { - var messageBody = dlqMessage.Body; - var matchingSent = sentMessages.FirstOrDefault(s => - JsonSerializer.Serialize(s.OriginalMessage.Payload) == messageBody); - - Assert.NotNull(matchingSent); - } - - // Messages should not be in main queue anymore (this would require additional verification) - // For property tests, we assume the SQS service correctly implements the redrive policy - } - - /// - /// Assert that message metadata is preserved in the dead letter queue - /// - private static void AssertMessageMetadataPreservation(List sentMessages, List dlqMessages) - { - foreach (var dlqMessage in dlqMessages) - { - // Find corresponding sent message - var messageBody = dlqMessage.Body; - var matchingSent = sentMessages.FirstOrDefault(s => - JsonSerializer.Serialize(s.OriginalMessage.Payload) == messageBody); - - if (matchingSent == null) continue; - - // Verify SourceFlow attributes are preserved - var requiredAttributes = new[] { "EntityId", "SequenceNo", "CommandType", "PayloadType" }; - - foreach (var attrName in requiredAttributes) - { - Assert.True(dlqMessage.MessageAttributes.ContainsKey(attrName), - $"Missing required attribute in DLQ: {attrName}"); - - if (matchingSent.MessageAttributes.ContainsKey(attrName)) - { - Assert.Equal(matchingSent.MessageAttributes[attrName], - dlqMessage.MessageAttributes[attrName].StringValue); - } - } - - // Verify failure-related attributes are present - Assert.True(dlqMessage.MessageAttributes.ContainsKey("FailureType"), - "FailureType should be preserved in DLQ"); - - // Verify original message structure is intact - var originalPayload = JsonSerializer.Deserialize>(messageBody); - Assert.NotNull(originalPayload); - Assert.True(originalPayload.ContainsKey("CommandId")); - Assert.True(originalPayload.ContainsKey("Data")); - } - } - - /// - /// Assert that failure information is complete and useful for analysis - /// - private static void AssertFailureInformationCompleteness(List dlqMessages, DeadLetterQueueScenario scenario) - { - foreach (var dlqMessage in dlqMessages) - { - // Verify failure metadata is available - Assert.True(dlqMessage.MessageAttributes.ContainsKey("FailureType"), - "Failure type should be available for analysis"); - - var failureType = dlqMessage.MessageAttributes["FailureType"].StringValue; - Assert.True(Enum.IsDefined(typeof(MessageFailureType), failureType), - "Failure type should be a valid enum value"); - - // Verify timestamp information is preserved - Assert.True(dlqMessage.MessageAttributes.ContainsKey("Timestamp"), - "Original timestamp should be preserved"); - - // Verify entity information is preserved for correlation - Assert.True(dlqMessage.MessageAttributes.ContainsKey("EntityId"), - "EntityId should be preserved for correlation"); - - // Verify command type is preserved for reprocessing logic - Assert.True(dlqMessage.MessageAttributes.ContainsKey("CommandType"), - "CommandType should be preserved for reprocessing"); - - // Message body should be intact for reprocessing - Assert.False(string.IsNullOrEmpty(dlqMessage.Body), - "Message body should be preserved for reprocessing"); - - // Verify message can be deserialized - var messagePayload = JsonSerializer.Deserialize>(dlqMessage.Body); - Assert.NotNull(messagePayload); - } - } - - /// - /// Assert that messages in DLQ can be reprocessed - /// - private async Task AssertReprocessingCapability(string dlqUrl, List dlqMessages, DeadLetterQueueScenario scenario) - { - if (!dlqMessages.Any()) return; - - // Create a reprocessing queue - var reprocessQueueUrl = scenario.QueueType == QueueType.Fifo - ? await CreateFifoQueueAsync($"prop-test-reprocess-{Guid.NewGuid():N}.fifo") - : await CreateStandardQueueAsync($"prop-test-reprocess-{Guid.NewGuid():N}"); - - try - { - // Take a sample of messages for reprocessing test - var samplesToReprocess = dlqMessages.Take(Math.Min(3, dlqMessages.Count)).ToList(); - - // Reprocess messages - var reprocessTasks = samplesToReprocess.Select(async dlqMessage => - { - var originalBody = JsonSerializer.Deserialize>(dlqMessage.Body); - Assert.NotNull(originalBody); - - // Add reprocessing metadata - var reprocessedBody = new Dictionary(originalBody) - { - ["ReprocessedAt"] = DateTime.UtcNow.ToString("O"), - ["ReprocessedFromDLQ"] = true, - ["OriginalFailureType"] = dlqMessage.MessageAttributes["FailureType"].StringValue - }; - - var reprocessRequest = new SendMessageRequest - { - QueueUrl = reprocessQueueUrl, - MessageBody = JsonSerializer.Serialize(reprocessedBody), - MessageAttributes = new Dictionary - { - ["ReprocessedFrom"] = new MessageAttributeValue - { - DataType = "String", - StringValue = "DeadLetterQueue" - }, - ["OriginalEntityId"] = new MessageAttributeValue - { - DataType = "String", - StringValue = dlqMessage.MessageAttributes["EntityId"].StringValue - }, - ["OriginalCommandType"] = new MessageAttributeValue - { - DataType = "String", - StringValue = dlqMessage.MessageAttributes["CommandType"].StringValue - }, - ["ReprocessAttempt"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = "1" - } - } - }; - - // Add FIFO-specific attributes if needed - if (scenario.QueueType == QueueType.Fifo) - { - var entityId = dlqMessage.MessageAttributes["EntityId"].StringValue; - reprocessRequest.MessageGroupId = $"reprocess-entity-{entityId}"; - reprocessRequest.MessageDeduplicationId = $"reprocess-{Guid.NewGuid():N}"; - } - - return await _localStack.SqsClient.SendMessageAsync(reprocessRequest); - }); - - var reprocessResults = await Task.WhenAll(reprocessTasks); - - // Assert all reprocessing attempts succeeded - Assert.All(reprocessResults, result => Assert.NotNull(result.MessageId)); - - // Verify reprocessed messages are available - var reprocessedReceiveResponse = await _localStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = reprocessQueueUrl, - MaxNumberOfMessages = 10, - MessageAttributeNames = new List { "All" }, - WaitTimeSeconds = 2 - }); - - Assert.Equal(samplesToReprocess.Count, reprocessedReceiveResponse.Messages.Count); - - // Verify reprocessed message structure - foreach (var reprocessedMessage in reprocessedReceiveResponse.Messages) - { - Assert.Equal("DeadLetterQueue", reprocessedMessage.MessageAttributes["ReprocessedFrom"].StringValue); - Assert.True(reprocessedMessage.MessageAttributes.ContainsKey("OriginalEntityId")); - Assert.True(reprocessedMessage.MessageAttributes.ContainsKey("OriginalCommandType")); - - var messageBody = JsonSerializer.Deserialize>(reprocessedMessage.Body); - Assert.NotNull(messageBody); - Assert.True(messageBody.ContainsKey("ReprocessedAt")); - Assert.True(messageBody.ContainsKey("ReprocessedFromDLQ")); - Assert.True(messageBody.ContainsKey("OriginalFailureType")); - } - - // Clean up reprocessed messages - var cleanupTasks = reprocessedReceiveResponse.Messages.Select(message => - _localStack.SqsClient.DeleteMessageAsync(new DeleteMessageRequest - { - QueueUrl = reprocessQueueUrl, - ReceiptHandle = message.ReceiptHandle - })); - - await Task.WhenAll(cleanupTasks); - } - finally - { - // Clean up reprocess queue - try - { - await _localStack.SqsClient.DeleteQueueAsync(new DeleteQueueRequest - { - QueueUrl = reprocessQueueUrl - }); - } - catch (Exception) - { - // Ignore cleanup errors - } - } - } - - /// - /// Create a send message request for the given test message - /// - private static SendMessageRequest CreateSendMessageRequest(string queueUrl, FailingTestMessage message, QueueType queueType, int index) - { - var request = new SendMessageRequest - { - QueueUrl = queueUrl, - MessageBody = JsonSerializer.Serialize(message.Payload), - MessageAttributes = new Dictionary - { - ["EntityId"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = message.EntityId.ToString() - }, - ["SequenceNo"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = message.SequenceNo.ToString() - }, - ["CommandType"] = new MessageAttributeValue - { - DataType = "String", - StringValue = message.CommandType - }, - ["PayloadType"] = new MessageAttributeValue - { - DataType = "String", - StringValue = message.PayloadType - }, - ["FailureType"] = new MessageAttributeValue - { - DataType = "String", - StringValue = message.FailureType.ToString() - }, - ["Timestamp"] = new MessageAttributeValue - { - DataType = "String", - StringValue = DateTime.UtcNow.ToString("O") - } - } - }; - - // Add FIFO-specific attributes - if (queueType == QueueType.Fifo) - { - request.MessageGroupId = $"entity-{message.EntityId}"; - request.MessageDeduplicationId = $"msg-{message.EntityId}-{message.SequenceNo}-{index}-{Guid.NewGuid():N}"; - } - - return request; - } - - /// - /// Clean up messages from the dead letter queue - /// - private async Task CleanupMessages(string dlqUrl, List dlqMessages) - { - var deleteTasks = dlqMessages.Select(message => - _localStack.SqsClient.DeleteMessageAsync(new DeleteMessageRequest - { - QueueUrl = dlqUrl, - ReceiptHandle = message.ReceiptHandle - })); - - try - { - await Task.WhenAll(deleteTasks); - } - catch (Exception) - { - // Ignore cleanup errors - } - } - - /// - /// Get the ARN for a queue - /// - private async Task GetQueueArnAsync(string queueUrl) - { - var response = await _localStack.SqsClient.GetQueueAttributesAsync(new GetQueueAttributesRequest - { - QueueUrl = queueUrl, - AttributeNames = new List { "QueueArn" } - }); - - return response.Attributes["QueueArn"]; - } - - /// - /// Create a standard queue for testing - /// - private async Task CreateStandardQueueAsync(string queueName, Dictionary? additionalAttributes = null) - { - var attributes = new Dictionary - { - ["MessageRetentionPeriod"] = "1209600", - ["VisibilityTimeout"] = "30" - }; - - if (additionalAttributes != null) - { - foreach (var attr in additionalAttributes) - { - attributes[attr.Key] = attr.Value; - } - } - - var response = await _localStack.SqsClient.CreateQueueAsync(new CreateQueueRequest - { - QueueName = queueName, - Attributes = attributes - }); - - _createdQueues.Add(response.QueueUrl); - return response.QueueUrl; - } - - /// - /// Create a FIFO queue for testing - /// - private async Task CreateFifoQueueAsync(string queueName, Dictionary? additionalAttributes = null) - { - var attributes = new Dictionary - { - ["FifoQueue"] = "true", - ["ContentBasedDeduplication"] = "true", - ["MessageRetentionPeriod"] = "1209600", - ["VisibilityTimeout"] = "30" - }; - - if (additionalAttributes != null) - { - foreach (var attr in additionalAttributes) - { - attributes[attr.Key] = attr.Value; - } - } - - var response = await _localStack.SqsClient.CreateQueueAsync(new CreateQueueRequest - { - QueueName = queueName, - Attributes = attributes - }); - - _createdQueues.Add(response.QueueUrl); - return response.QueueUrl; - } - - /// - /// Clean up created queues - /// - public async ValueTask DisposeAsync() - { - if (_localStack.SqsClient != null) - { - foreach (var queueUrl in _createdQueues) - { - try - { - await _localStack.SqsClient.DeleteQueueAsync(new DeleteQueueRequest - { - QueueUrl = queueUrl - }); - } - catch (Exception) - { - // Ignore cleanup errors - } - } - } - - _createdQueues.Clear(); - } -} - -/// -/// FsCheck generators for dead letter queue property tests -/// -public static class DeadLetterQueueGenerators -{ - /// - /// Generate test scenarios for dead letter queue handling - /// - public static Arbitrary DeadLetterQueueScenario() - { - var queueTypeGen = Gen.Elements(QueueType.Standard, QueueType.Fifo); - var maxReceiveCountGen = Gen.Choose(2, 5); // Reasonable range for testing - var visibilityTimeoutGen = Gen.Choose(1, 5); // Short timeouts for faster testing - var messageCountGen = Gen.Choose(1, 10); // Reasonable number for property testing - - var scenarioGen = from queueType in queueTypeGen - from maxReceiveCount in maxReceiveCountGen - from visibilityTimeout in visibilityTimeoutGen - from messageCount in messageCountGen - from messages in Gen.ListOf(messageCount, FailingTestMessage()) - select new DeadLetterQueueScenario - { - QueueType = queueType, - MaxReceiveCount = maxReceiveCount, - VisibilityTimeout = visibilityTimeout, - Messages = messages.ToList() - }; - - return Arb.From(scenarioGen); - } - - /// - /// Generate test messages that will fail processing - /// - public static Gen FailingTestMessage() - { - var entityIdGen = Gen.Choose(1, 1000); - var sequenceNoGen = Gen.Choose(1, 100); - var commandTypeGen = Gen.Elements( - "ProcessOrderCommand", - "ValidatePaymentCommand", - "UpdateInventoryCommand", - "SendNotificationCommand", - "CalculateShippingCommand"); - var payloadTypeGen = Gen.Elements( - "ProcessOrderPayload", - "ValidatePaymentPayload", - "UpdateInventoryPayload", - "SendNotificationPayload", - "CalculateShippingPayload"); - var failureTypeGen = Gen.Elements( - MessageFailureType.ValidationError, - MessageFailureType.TimeoutError, - MessageFailureType.ExternalServiceError, - MessageFailureType.DataCorruption, - MessageFailureType.InsufficientResources); - - var payloadGen = from commandId in Gen.Fresh(() => Guid.NewGuid()) - from data in Gen.Elements("test-data-1", "test-data-2", "corrupted-data", "timeout-data") - from priority in Gen.Choose(1, 10) - select new Dictionary - { - ["CommandId"] = commandId, - ["Data"] = data, - ["Priority"] = priority, - ["CreatedAt"] = DateTime.UtcNow.ToString("O") - }; - - return from entityId in entityIdGen - from sequenceNo in sequenceNoGen - from commandType in commandTypeGen - from payloadType in payloadTypeGen - from failureType in failureTypeGen - from payload in payloadGen - select new FailingTestMessage - { - EntityId = entityId, - SequenceNo = sequenceNo, - CommandType = commandType, - PayloadType = payloadType, - FailureType = failureType, - Payload = payload - }; - } -} - -/// -/// Test scenario for dead letter queue handling -/// -public class DeadLetterQueueScenario -{ - public QueueType QueueType { get; set; } - public int MaxReceiveCount { get; set; } - public int VisibilityTimeout { get; set; } - public List Messages { get; set; } = new(); -} - -/// -/// Test message that will fail processing -/// -public class FailingTestMessage -{ - public int EntityId { get; set; } - public int SequenceNo { get; set; } - public string CommandType { get; set; } = ""; - public string PayloadType { get; set; } = ""; - public MessageFailureType FailureType { get; set; } - public Dictionary Payload { get; set; } = new(); -} - -/// -/// Sent message tracking information for dead letter queue tests -/// -public class DeadLetterTestMessage -{ - public FailingTestMessage OriginalMessage { get; set; } = new(); - public string MessageId { get; set; } = ""; - public DateTime SendTime { get; set; } - public TimeSpan SendDuration { get; set; } - public string? MessageGroupId { get; set; } - public string? MessageDeduplicationId { get; set; } - public MessageFailureType ExpectedFailureType { get; set; } - public Dictionary MessageAttributes { get; set; } = new(); -} - -/// -/// Types of message processing failures -/// -public enum MessageFailureType -{ - ValidationError, - TimeoutError, - ExternalServiceError, - DataCorruption, - InsufficientResources -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/Integration/SqsFifoIntegrationTests.cs b/tests/SourceFlow.Cloud.AWS.Tests/Integration/SqsFifoIntegrationTests.cs deleted file mode 100644 index db3f3a3d..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/Integration/SqsFifoIntegrationTests.cs +++ /dev/null @@ -1,602 +0,0 @@ -using Amazon.SQS.Model; -using SourceFlow.Cloud.AWS.Tests.TestHelpers; -using SourceFlow.Messaging.Commands; -using System.Text.Json; - -namespace SourceFlow.Cloud.AWS.Tests.Integration; - -/// -/// Comprehensive integration tests for SQS FIFO queue functionality -/// Tests message ordering, deduplication, EntityId-based grouping, and FIFO-specific behaviors -/// -[Collection("AWS Integration Tests")] -[Trait("Category", "Integration")] -[Trait("Category", "RequiresLocalStack")] -public class SqsFifoIntegrationTests : IClassFixture, IAsyncDisposable -{ - private readonly LocalStackTestFixture _localStack; - private readonly List _createdQueues = new(); - - public SqsFifoIntegrationTests(LocalStackTestFixture localStack) - { - _localStack = localStack; - } - - [Fact] - public async Task FifoQueue_ShouldMaintainMessageOrderingWithinMessageGroups() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.SqsClient == null) - { - return; - } - - // Arrange - var queueName = $"test-fifo-ordering-{Guid.NewGuid():N}.fifo"; - var queueUrl = await CreateFifoQueueAsync(queueName); - - var messageGroupId = "test-group-1"; - var messages = new List(); - - // Act - Send multiple messages in sequence to the same message group - for (int i = 0; i < 5; i++) - { - var messageBody = $"Message {i:D2} - {DateTime.UtcNow:yyyy-MM-dd HH:mm:ss.fff}"; - messages.Add(messageBody); - - await _localStack.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = queueUrl, - MessageBody = messageBody, - MessageGroupId = messageGroupId, - MessageDeduplicationId = $"dedup-{i}-{Guid.NewGuid():N}" - }); - - // Small delay to ensure ordering - await Task.Delay(10); - } - - // Act - Receive messages - var receivedMessages = new List(); - var maxAttempts = 10; - var attempts = 0; - - while (receivedMessages.Count < messages.Count && attempts < maxAttempts) - { - var receiveResponse = await _localStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = queueUrl, - MaxNumberOfMessages = 10, - WaitTimeSeconds = 1, - AttributeNames = new List { "All" } - }); - - foreach (var message in receiveResponse.Messages) - { - receivedMessages.Add(message.Body); - - // Delete message to acknowledge processing - await _localStack.SqsClient.DeleteMessageAsync(new DeleteMessageRequest - { - QueueUrl = queueUrl, - ReceiptHandle = message.ReceiptHandle - }); - } - - attempts++; - } - - // Assert - Messages should be received in the same order they were sent - Assert.Equal(messages.Count, receivedMessages.Count); - for (int i = 0; i < messages.Count; i++) - { - Assert.Equal(messages[i], receivedMessages[i]); - } - } - - [Fact] - public async Task FifoQueue_ShouldHandleContentBasedDeduplication() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.SqsClient == null) - { - return; - } - - // Arrange - var queueName = $"test-fifo-dedup-{Guid.NewGuid():N}.fifo"; - var queueUrl = await CreateFifoQueueAsync(queueName, new Dictionary - { - ["ContentBasedDeduplication"] = "true" - }); - - var messageGroupId = "dedup-test-group"; - var duplicateMessageBody = $"Duplicate message content - {DateTime.UtcNow:yyyy-MM-dd}"; - - // Act - Send the same message multiple times (should be deduplicated) - var sendTasks = new List>(); - for (int i = 0; i < 3; i++) - { - sendTasks.Add(_localStack.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = queueUrl, - MessageBody = duplicateMessageBody, - MessageGroupId = messageGroupId - // No MessageDeduplicationId - using content-based deduplication - })); - } - - var sendResponses = await Task.WhenAll(sendTasks); - - // Wait a moment for deduplication to take effect - await Task.Delay(1000); - - // Act - Receive messages - var receiveResponse = await _localStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = queueUrl, - MaxNumberOfMessages = 10, - WaitTimeSeconds = 2 - }); - - // Assert - Only one message should be received due to deduplication - Assert.Single(receiveResponse.Messages); - Assert.Equal(duplicateMessageBody, receiveResponse.Messages[0].Body); - - // All send operations should have succeeded (deduplication happens server-side) - Assert.All(sendResponses, response => Assert.NotNull(response.MessageId)); - } - - [Fact] - public async Task FifoQueue_ShouldSupportEntityIdBasedMessageGrouping() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.SqsClient == null) - { - return; - } - - // Arrange - var queueName = $"test-fifo-entity-grouping-{Guid.NewGuid():N}.fifo"; - var queueUrl = await CreateFifoQueueAsync(queueName); - - var entity1Id = 1001; - var entity2Id = 1002; - var messagesPerEntity = 3; - - // Act - Send messages for different entities (should be processed in parallel) - var sendTasks = new List(); - - for (int i = 0; i < messagesPerEntity; i++) - { - // Messages for Entity 1 - sendTasks.Add(_localStack.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = queueUrl, - MessageBody = $"Entity {entity1Id} - Message {i}", - MessageGroupId = $"entity-{entity1Id}", - MessageDeduplicationId = $"entity-{entity1Id}-msg-{i}-{Guid.NewGuid():N}", - MessageAttributes = new Dictionary - { - ["EntityId"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = entity1Id.ToString() - }, - ["SequenceNo"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = i.ToString() - } - } - })); - - // Messages for Entity 2 - sendTasks.Add(_localStack.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = queueUrl, - MessageBody = $"Entity {entity2Id} - Message {i}", - MessageGroupId = $"entity-{entity2Id}", - MessageDeduplicationId = $"entity-{entity2Id}-msg-{i}-{Guid.NewGuid():N}", - MessageAttributes = new Dictionary - { - ["EntityId"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = entity2Id.ToString() - }, - ["SequenceNo"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = i.ToString() - } - } - })); - } - - await Task.WhenAll(sendTasks); - - // Act - Receive all messages - var allMessages = new List(); - var maxAttempts = 10; - var attempts = 0; - - while (allMessages.Count < messagesPerEntity * 2 && attempts < maxAttempts) - { - var receiveResponse = await _localStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = queueUrl, - MaxNumberOfMessages = 10, - MessageAttributeNames = new List { "All" }, - WaitTimeSeconds = 1 - }); - - allMessages.AddRange(receiveResponse.Messages); - - // Delete received messages - foreach (var message in receiveResponse.Messages) - { - await _localStack.SqsClient.DeleteMessageAsync(new DeleteMessageRequest - { - QueueUrl = queueUrl, - ReceiptHandle = message.ReceiptHandle - }); - } - - attempts++; - } - - // Assert - Should receive all messages - Assert.Equal(messagesPerEntity * 2, allMessages.Count); - - // Group messages by EntityId - var entity1Messages = allMessages - .Where(m => m.MessageAttributes.ContainsKey("EntityId") && - m.MessageAttributes["EntityId"].StringValue == entity1Id.ToString()) - .OrderBy(m => int.Parse(m.MessageAttributes["SequenceNo"].StringValue)) - .ToList(); - - var entity2Messages = allMessages - .Where(m => m.MessageAttributes.ContainsKey("EntityId") && - m.MessageAttributes["EntityId"].StringValue == entity2Id.ToString()) - .OrderBy(m => int.Parse(m.MessageAttributes["SequenceNo"].StringValue)) - .ToList(); - - // Assert - Each entity should have received all its messages in order - Assert.Equal(messagesPerEntity, entity1Messages.Count); - Assert.Equal(messagesPerEntity, entity2Messages.Count); - - for (int i = 0; i < messagesPerEntity; i++) - { - Assert.Contains($"Entity {entity1Id} - Message {i}", entity1Messages[i].Body); - Assert.Contains($"Entity {entity2Id} - Message {i}", entity2Messages[i].Body); - } - } - - [Fact] - public async Task FifoQueue_ShouldValidateFifoSpecificAttributes() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.SqsClient == null) - { - return; - } - - // Arrange - var queueName = $"test-fifo-attributes-{Guid.NewGuid():N}.fifo"; - var queueUrl = await CreateFifoQueueAsync(queueName, new Dictionary - { - ["ContentBasedDeduplication"] = "true", - ["DeduplicationScope"] = "messageGroup", - ["FifoThroughputLimit"] = "perMessageGroupId" - }); - - // Act - Get queue attributes - var attributesResponse = await _localStack.SqsClient.GetQueueAttributesAsync(new GetQueueAttributesRequest - { - QueueUrl = queueUrl, - AttributeNames = new List { "All" } - }); - - // Assert - FIFO-specific attributes should be set correctly - Assert.True(attributesResponse.Attributes.ContainsKey("FifoQueue")); - Assert.Equal("true", attributesResponse.Attributes["FifoQueue"]); - - Assert.True(attributesResponse.Attributes.ContainsKey("ContentBasedDeduplication")); - Assert.Equal("true", attributesResponse.Attributes["ContentBasedDeduplication"]); - - // Test that MessageGroupId is required for FIFO queues - var exception = await Assert.ThrowsAsync(async () => - { - await _localStack.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = queueUrl, - MessageBody = "Test message without MessageGroupId" - // Missing MessageGroupId - should fail - }); - }); - - Assert.Contains("MessageGroupId", exception.Message); - } - - [Fact] - public async Task FifoQueue_ShouldHandleSourceFlowCommandMetadata() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.SqsClient == null) - { - return; - } - - // Arrange - var queueName = $"test-fifo-sourceflow-{Guid.NewGuid():N}.fifo"; - var queueUrl = await CreateFifoQueueAsync(queueName); - - var entityId = 12345; - var sequenceNo = 42; - var commandType = "CreateOrderCommand"; - var payloadType = "CreateOrderPayload"; - - var commandPayload = new - { - OrderId = Guid.NewGuid(), - CustomerId = 67890, - Amount = 99.99m, - Currency = "USD" - }; - - var commandMetadata = new Dictionary - { - ["CorrelationId"] = Guid.NewGuid().ToString(), - ["UserId"] = "test-user-123", - ["Timestamp"] = DateTime.UtcNow.ToString("O") - }; - - // Act - Send message with SourceFlow command metadata - var sendResponse = await _localStack.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = queueUrl, - MessageBody = JsonSerializer.Serialize(commandPayload), - MessageGroupId = $"entity-{entityId}", - MessageDeduplicationId = $"cmd-{entityId}-{sequenceNo}-{Guid.NewGuid():N}", - MessageAttributes = new Dictionary - { - ["EntityId"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = entityId.ToString() - }, - ["SequenceNo"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = sequenceNo.ToString() - }, - ["CommandType"] = new MessageAttributeValue - { - DataType = "String", - StringValue = commandType - }, - ["PayloadType"] = new MessageAttributeValue - { - DataType = "String", - StringValue = payloadType - }, - ["Metadata"] = new MessageAttributeValue - { - DataType = "String", - StringValue = JsonSerializer.Serialize(commandMetadata) - } - } - }); - - Assert.NotNull(sendResponse.MessageId); - - // Act - Receive and validate message - var receiveResponse = await _localStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = queueUrl, - MaxNumberOfMessages = 1, - MessageAttributeNames = new List { "All" }, - WaitTimeSeconds = 2 - }); - - // Assert - Message should contain all SourceFlow metadata - Assert.Single(receiveResponse.Messages); - var message = receiveResponse.Messages[0]; - - Assert.Equal(entityId.ToString(), message.MessageAttributes["EntityId"].StringValue); - Assert.Equal(sequenceNo.ToString(), message.MessageAttributes["SequenceNo"].StringValue); - Assert.Equal(commandType, message.MessageAttributes["CommandType"].StringValue); - Assert.Equal(payloadType, message.MessageAttributes["PayloadType"].StringValue); - - var receivedMetadata = JsonSerializer.Deserialize>( - message.MessageAttributes["Metadata"].StringValue); - Assert.NotNull(receivedMetadata); - Assert.True(receivedMetadata.ContainsKey("CorrelationId")); - Assert.True(receivedMetadata.ContainsKey("UserId")); - Assert.True(receivedMetadata.ContainsKey("Timestamp")); - - var receivedPayload = JsonSerializer.Deserialize>(message.Body); - Assert.NotNull(receivedPayload); - Assert.True(receivedPayload.ContainsKey("OrderId")); - Assert.True(receivedPayload.ContainsKey("CustomerId")); - Assert.True(receivedPayload.ContainsKey("Amount")); - } - - [Fact] - public async Task FifoQueue_ShouldHandleHighThroughputScenario() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.SqsClient == null) - { - return; - } - - // Arrange - var queueName = $"test-fifo-throughput-{Guid.NewGuid():N}.fifo"; - var queueUrl = await CreateFifoQueueAsync(queueName, new Dictionary - { - ["FifoThroughputLimit"] = "perMessageGroupId", - ["DeduplicationScope"] = "messageGroup" - }); - - var messageGroups = 5; - var messagesPerGroup = 20; - var totalMessages = messageGroups * messagesPerGroup; - - // Act - Send messages across multiple message groups for higher throughput - var sendTasks = new List>(); - - for (int groupId = 0; groupId < messageGroups; groupId++) - { - for (int msgId = 0; msgId < messagesPerGroup; msgId++) - { - sendTasks.Add(_localStack.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = queueUrl, - MessageBody = $"Group {groupId} - Message {msgId} - {DateTime.UtcNow:HH:mm:ss.fff}", - MessageGroupId = $"group-{groupId}", - MessageDeduplicationId = $"group-{groupId}-msg-{msgId}-{Guid.NewGuid():N}", - MessageAttributes = new Dictionary - { - ["GroupId"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = groupId.ToString() - }, - ["MessageId"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = msgId.ToString() - } - } - })); - } - } - - var startTime = DateTime.UtcNow; - var sendResponses = await Task.WhenAll(sendTasks); - var sendDuration = DateTime.UtcNow - startTime; - - // Assert - All messages should be sent successfully - Assert.Equal(totalMessages, sendResponses.Length); - Assert.All(sendResponses, response => Assert.NotNull(response.MessageId)); - - // Act - Receive all messages - var receivedMessages = new List(); - var maxAttempts = 20; - var attempts = 0; - - startTime = DateTime.UtcNow; - while (receivedMessages.Count < totalMessages && attempts < maxAttempts) - { - var receiveResponse = await _localStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = queueUrl, - MaxNumberOfMessages = 10, - MessageAttributeNames = new List { "All" }, - WaitTimeSeconds = 1 - }); - - receivedMessages.AddRange(receiveResponse.Messages); - - // Delete received messages - foreach (var message in receiveResponse.Messages) - { - await _localStack.SqsClient.DeleteMessageAsync(new DeleteMessageRequest - { - QueueUrl = queueUrl, - ReceiptHandle = message.ReceiptHandle - }); - } - - attempts++; - } - var receiveDuration = DateTime.UtcNow - startTime; - - // Assert - All messages should be received - Assert.Equal(totalMessages, receivedMessages.Count); - - // Verify ordering within each message group - var messagesByGroup = receivedMessages - .GroupBy(m => m.MessageAttributes["GroupId"].StringValue) - .ToDictionary(g => int.Parse(g.Key), g => g.OrderBy(m => int.Parse(m.MessageAttributes["MessageId"].StringValue)).ToList()); - - Assert.Equal(messageGroups, messagesByGroup.Count); - - foreach (var group in messagesByGroup) - { - Assert.Equal(messagesPerGroup, group.Value.Count); - - for (int i = 0; i < messagesPerGroup; i++) - { - Assert.Contains($"Group {group.Key} - Message {i}", group.Value[i].Body); - } - } - - // Log performance metrics - var sendThroughput = totalMessages / sendDuration.TotalSeconds; - var receiveThroughput = totalMessages / receiveDuration.TotalSeconds; - - // These are informational - actual thresholds would depend on LocalStack vs real AWS - Assert.True(sendThroughput > 0, $"Send throughput: {sendThroughput:F2} messages/second"); - Assert.True(receiveThroughput > 0, $"Receive throughput: {receiveThroughput:F2} messages/second"); - } - - /// - /// Create a FIFO queue with the specified name and attributes - /// - private async Task CreateFifoQueueAsync(string queueName, Dictionary? additionalAttributes = null) - { - var attributes = new Dictionary - { - ["FifoQueue"] = "true", - ["ContentBasedDeduplication"] = "true", - ["MessageRetentionPeriod"] = "1209600", // 14 days - ["VisibilityTimeout"] = "30" - }; - - if (additionalAttributes != null) - { - foreach (var attr in additionalAttributes) - { - attributes[attr.Key] = attr.Value; - } - } - - var response = await _localStack.SqsClient.CreateQueueAsync(new CreateQueueRequest - { - QueueName = queueName, - Attributes = attributes - }); - - _createdQueues.Add(response.QueueUrl); - return response.QueueUrl; - } - - /// - /// Clean up created queues - /// - public async ValueTask DisposeAsync() - { - if (_localStack.SqsClient != null) - { - foreach (var queueUrl in _createdQueues) - { - try - { - await _localStack.SqsClient.DeleteQueueAsync(new DeleteQueueRequest - { - QueueUrl = queueUrl - }); - } - catch (Exception) - { - // Ignore cleanup errors - } - } - } - - _createdQueues.Clear(); - } -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/Integration/SqsMessageAttributesIntegrationTests.cs b/tests/SourceFlow.Cloud.AWS.Tests/Integration/SqsMessageAttributesIntegrationTests.cs deleted file mode 100644 index df78e09c..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/Integration/SqsMessageAttributesIntegrationTests.cs +++ /dev/null @@ -1,955 +0,0 @@ -using Amazon.SQS.Model; -using SourceFlow.Cloud.AWS.Tests.TestHelpers; -using System.Text; -using System.Text.Json; - -namespace SourceFlow.Cloud.AWS.Tests.Integration; - -/// -/// Comprehensive integration tests for SQS message attributes -/// Tests SourceFlow command metadata preservation, custom attributes handling, routing/filtering, and size limits -/// -[Collection("AWS Integration Tests")] -[Trait("Category", "Integration")] -[Trait("Category", "RequiresLocalStack")] -public class SqsMessageAttributesIntegrationTests : IClassFixture, IAsyncDisposable -{ - private readonly LocalStackTestFixture _localStack; - private readonly List _createdQueues = new(); - - public SqsMessageAttributesIntegrationTests(LocalStackTestFixture localStack) - { - _localStack = localStack; - } - - [Fact] - public async Task MessageAttributes_ShouldPreserveSourceFlowCommandMetadata() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.SqsClient == null) - { - return; - } - - // Arrange - var queueName = $"test-sourceflow-metadata-{Guid.NewGuid():N}"; - var queueUrl = await CreateStandardQueueAsync(queueName); - - var entityId = 12345; - var sequenceNo = 42; - var commandType = "CreateOrderCommand"; - var payloadType = "CreateOrderPayload"; - var correlationId = Guid.NewGuid().ToString(); - var userId = "user-123"; - var tenantId = "tenant-456"; - - var commandPayload = new - { - OrderId = Guid.NewGuid(), - CustomerId = 67890, - Amount = 199.99m, - Currency = "USD", - Items = new[] - { - new { ProductId = "PROD-001", Quantity = 2, Price = 99.99m }, - new { ProductId = "PROD-002", Quantity = 1, Price = 99.99m } - } - }; - - var commandMetadata = new Dictionary - { - ["CorrelationId"] = correlationId, - ["UserId"] = userId, - ["TenantId"] = tenantId, - ["RequestId"] = Guid.NewGuid().ToString(), - ["ClientVersion"] = "1.2.3", - ["Timestamp"] = DateTime.UtcNow.ToString("O"), - ["Source"] = "OrderService", - ["TraceId"] = "trace-" + Guid.NewGuid().ToString("N")[..16] - }; - - // Act - Send message with comprehensive SourceFlow metadata - var sendResponse = await _localStack.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = queueUrl, - MessageBody = JsonSerializer.Serialize(commandPayload), - MessageAttributes = new Dictionary - { - // Core SourceFlow attributes - ["EntityId"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = entityId.ToString() - }, - ["SequenceNo"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = sequenceNo.ToString() - }, - ["CommandType"] = new MessageAttributeValue - { - DataType = "String", - StringValue = commandType - }, - ["PayloadType"] = new MessageAttributeValue - { - DataType = "String", - StringValue = payloadType - }, - ["Metadata"] = new MessageAttributeValue - { - DataType = "String", - StringValue = JsonSerializer.Serialize(commandMetadata) - }, - // Additional SourceFlow attributes - ["Version"] = new MessageAttributeValue - { - DataType = "String", - StringValue = "1.0" - }, - ["Priority"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = "5" - }, - ["RetryCount"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = "0" - }, - ["TimeToLive"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = "3600" // 1 hour in seconds - } - } - }); - - Assert.NotNull(sendResponse.MessageId); - - // Act - Receive and validate message - var receiveResponse = await _localStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = queueUrl, - MaxNumberOfMessages = 1, - MessageAttributeNames = new List { "All" }, - WaitTimeSeconds = 2 - }); - - // Assert - Message should contain all SourceFlow metadata - Assert.Single(receiveResponse.Messages); - var message = receiveResponse.Messages[0]; - - // Verify core SourceFlow attributes - Assert.Equal(entityId.ToString(), message.MessageAttributes["EntityId"].StringValue); - Assert.Equal(sequenceNo.ToString(), message.MessageAttributes["SequenceNo"].StringValue); - Assert.Equal(commandType, message.MessageAttributes["CommandType"].StringValue); - Assert.Equal(payloadType, message.MessageAttributes["PayloadType"].StringValue); - Assert.Equal("1.0", message.MessageAttributes["Version"].StringValue); - Assert.Equal("5", message.MessageAttributes["Priority"].StringValue); - Assert.Equal("0", message.MessageAttributes["RetryCount"].StringValue); - Assert.Equal("3600", message.MessageAttributes["TimeToLive"].StringValue); - - // Verify metadata preservation - var receivedMetadata = JsonSerializer.Deserialize>( - message.MessageAttributes["Metadata"].StringValue); - Assert.NotNull(receivedMetadata); - Assert.Equal(correlationId, receivedMetadata["CorrelationId"].ToString()); - Assert.Equal(userId, receivedMetadata["UserId"].ToString()); - Assert.Equal(tenantId, receivedMetadata["TenantId"].ToString()); - Assert.True(receivedMetadata.ContainsKey("RequestId")); - Assert.True(receivedMetadata.ContainsKey("ClientVersion")); - Assert.True(receivedMetadata.ContainsKey("Timestamp")); - Assert.True(receivedMetadata.ContainsKey("Source")); - Assert.True(receivedMetadata.ContainsKey("TraceId")); - - // Verify payload preservation - var receivedPayload = JsonSerializer.Deserialize>(message.Body); - Assert.NotNull(receivedPayload); - Assert.True(receivedPayload.ContainsKey("OrderId")); - Assert.True(receivedPayload.ContainsKey("CustomerId")); - Assert.True(receivedPayload.ContainsKey("Amount")); - Assert.True(receivedPayload.ContainsKey("Currency")); - Assert.True(receivedPayload.ContainsKey("Items")); - - // Clean up - await _localStack.SqsClient.DeleteMessageAsync(new DeleteMessageRequest - { - QueueUrl = queueUrl, - ReceiptHandle = message.ReceiptHandle - }); - } - - [Fact] - public async Task MessageAttributes_ShouldSupportAllDataTypes() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.SqsClient == null) - { - return; - } - - // Arrange - var queueName = $"test-attribute-data-types-{Guid.NewGuid():N}"; - var queueUrl = await CreateStandardQueueAsync(queueName); - - var binaryData = Encoding.UTF8.GetBytes("Binary test data with special chars: àáâãäå"); - - // Act - Send message with various data types - var sendResponse = await _localStack.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = queueUrl, - MessageBody = "Message with various attribute data types", - MessageAttributes = new Dictionary - { - // String attributes - ["StringAttribute"] = new MessageAttributeValue - { - DataType = "String", - StringValue = "Test string value with unicode: 你好世界" - }, - // Note: SQS rejects empty string attribute values — omitting EmptyString test - ["ShortString"] = new MessageAttributeValue - { - DataType = "String", - StringValue = "x" - }, - // Number attributes - ["IntegerAttribute"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = "42" - }, - ["NegativeNumber"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = "-123" - }, - ["DecimalNumber"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = "3.14159" - }, - ["LargeNumber"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = "9223372036854775807" // Long.MaxValue - }, - // Binary attribute - ["BinaryAttribute"] = new MessageAttributeValue - { - DataType = "Binary", - BinaryValue = new MemoryStream(binaryData) - }, - // Custom data types - ["CustomType.DateTime"] = new MessageAttributeValue - { - DataType = "String.DateTime", - StringValue = DateTime.UtcNow.ToString("O") - }, - ["CustomType.Boolean"] = new MessageAttributeValue - { - DataType = "String.Boolean", - StringValue = "true" - }, - ["CustomType.Guid"] = new MessageAttributeValue - { - DataType = "String.Guid", - StringValue = Guid.NewGuid().ToString() - } - } - }); - - Assert.NotNull(sendResponse.MessageId); - - // Act - Receive and validate message - var receiveResponse = await _localStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = queueUrl, - MaxNumberOfMessages = 1, - MessageAttributeNames = new List { "All" }, - WaitTimeSeconds = 2 - }); - - // Assert - All attributes should be preserved with correct data types - Assert.Single(receiveResponse.Messages); - var message = receiveResponse.Messages[0]; - - // Verify string attributes - Assert.Equal("String", message.MessageAttributes["StringAttribute"].DataType); - Assert.Equal("Test string value with unicode: 你好世界", message.MessageAttributes["StringAttribute"].StringValue); - // Note: SQS rejects empty string attribute values, so EmptyString is not tested here - - // Verify number attributes - Assert.Equal("Number", message.MessageAttributes["IntegerAttribute"].DataType); - Assert.Equal("42", message.MessageAttributes["IntegerAttribute"].StringValue); - Assert.Equal("Number", message.MessageAttributes["NegativeNumber"].DataType); - Assert.Equal("-123", message.MessageAttributes["NegativeNumber"].StringValue); - Assert.Equal("Number", message.MessageAttributes["DecimalNumber"].DataType); - Assert.Equal("3.14159", message.MessageAttributes["DecimalNumber"].StringValue); - Assert.Equal("Number", message.MessageAttributes["LargeNumber"].DataType); - Assert.Equal("9223372036854775807", message.MessageAttributes["LargeNumber"].StringValue); - - // Verify binary attribute - Assert.Equal("Binary", message.MessageAttributes["BinaryAttribute"].DataType); - var receivedBinaryData = new byte[message.MessageAttributes["BinaryAttribute"].BinaryValue.Length]; - message.MessageAttributes["BinaryAttribute"].BinaryValue.Read(receivedBinaryData, 0, receivedBinaryData.Length); - Assert.Equal(binaryData, receivedBinaryData); - - // Verify custom data types - Assert.Equal("String.DateTime", message.MessageAttributes["CustomType.DateTime"].DataType); - Assert.True(DateTime.TryParse(message.MessageAttributes["CustomType.DateTime"].StringValue, out _)); - Assert.Equal("String.Boolean", message.MessageAttributes["CustomType.Boolean"].DataType); - Assert.Equal("true", message.MessageAttributes["CustomType.Boolean"].StringValue); - Assert.Equal("String.Guid", message.MessageAttributes["CustomType.Guid"].DataType); - Assert.True(Guid.TryParse(message.MessageAttributes["CustomType.Guid"].StringValue, out _)); - - // Clean up - await _localStack.SqsClient.DeleteMessageAsync(new DeleteMessageRequest - { - QueueUrl = queueUrl, - ReceiptHandle = message.ReceiptHandle - }); - } - - [Fact] - public async Task MessageAttributes_ShouldSupportAttributeBasedFiltering() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.SqsClient == null) - { - return; - } - - // Arrange - var queueName = $"test-attribute-filtering-{Guid.NewGuid():N}"; - var queueUrl = await CreateStandardQueueAsync(queueName); - - // Send messages with different attributes for filtering - var messages = new[] - { - new { Priority = "High", Category = "Order", EntityId = 1001, MessageBody = "High priority order message" }, - new { Priority = "Low", Category = "Order", EntityId = 1002, MessageBody = "Low priority order message" }, - new { Priority = "High", Category = "Payment", EntityId = 1003, MessageBody = "High priority payment message" }, - new { Priority = "Medium", Category = "Notification", EntityId = 1004, MessageBody = "Medium priority notification message" }, - new { Priority = "High", Category = "Order", EntityId = 1005, MessageBody = "Another high priority order message" } - }; - - var sendTasks = messages.Select(async msg => - { - return await _localStack.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = queueUrl, - MessageBody = msg.MessageBody, - MessageAttributes = new Dictionary - { - ["Priority"] = new MessageAttributeValue - { - DataType = "String", - StringValue = msg.Priority - }, - ["Category"] = new MessageAttributeValue - { - DataType = "String", - StringValue = msg.Category - }, - ["EntityId"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = msg.EntityId.ToString() - }, - ["CommandType"] = new MessageAttributeValue - { - DataType = "String", - StringValue = $"{msg.Category}Command" - } - } - }); - }); - - await Task.WhenAll(sendTasks); - - // Act - Receive messages with attribute filtering (receive all first) - var allMessages = new List(); - var maxAttempts = 10; - var attempts = 0; - - while (allMessages.Count < messages.Length && attempts < maxAttempts) - { - var receiveResponse = await _localStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = queueUrl, - MaxNumberOfMessages = 10, - MessageAttributeNames = new List { "All" }, - WaitTimeSeconds = 1 - }); - - allMessages.AddRange(receiveResponse.Messages); - attempts++; - } - - // Assert - Should receive all messages - Assert.Equal(messages.Length, allMessages.Count); - - // Filter messages by attributes (client-side filtering for demonstration) - var highPriorityMessages = allMessages - .Where(m => m.MessageAttributes.ContainsKey("Priority") && - m.MessageAttributes["Priority"].StringValue == "High") - .ToList(); - - var orderMessages = allMessages - .Where(m => m.MessageAttributes.ContainsKey("Category") && - m.MessageAttributes["Category"].StringValue == "Order") - .ToList(); - - var highPriorityOrderMessages = allMessages - .Where(m => m.MessageAttributes.ContainsKey("Priority") && - m.MessageAttributes["Priority"].StringValue == "High" && - m.MessageAttributes.ContainsKey("Category") && - m.MessageAttributes["Category"].StringValue == "Order") - .ToList(); - - // Assert - Filtering should work correctly - Assert.Equal(3, highPriorityMessages.Count); // 3 high priority messages - Assert.Equal(3, orderMessages.Count); // 3 order messages - Assert.Equal(2, highPriorityOrderMessages.Count); // 2 high priority order messages - - // Verify attribute values in filtered messages - foreach (var message in highPriorityMessages) - { - Assert.Equal("High", message.MessageAttributes["Priority"].StringValue); - } - - foreach (var message in orderMessages) - { - Assert.Equal("Order", message.MessageAttributes["Category"].StringValue); - Assert.Equal("OrderCommand", message.MessageAttributes["CommandType"].StringValue); - } - - foreach (var message in highPriorityOrderMessages) - { - Assert.Equal("High", message.MessageAttributes["Priority"].StringValue); - Assert.Equal("Order", message.MessageAttributes["Category"].StringValue); - Assert.Contains("order message", message.Body.ToLower()); - } - - // Clean up - await CleanupMessages(queueUrl, allMessages); - } - - [Fact] - public async Task MessageAttributes_ShouldRespectSizeLimits() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.SqsClient == null) - { - return; - } - - // Arrange - var queueName = $"test-attribute-size-limits-{Guid.NewGuid():N}"; - var queueUrl = await CreateStandardQueueAsync(queueName); - - // Test with attributes approaching AWS limits - // AWS SQS limits: 10 attributes per message, 256KB total message size, 256 bytes per attribute name, 256KB per attribute value - - var largeAttributeValue = new string('A', 1024); // 1KB value (well within 256KB limit) - var mediumAttributeValue = new string('B', 256); // 256 bytes - - // Act - Send message with multiple attributes of various sizes - var sendResponse = await _localStack.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = queueUrl, - MessageBody = "Message with size limit testing", - MessageAttributes = new Dictionary - { - ["Attribute1"] = new MessageAttributeValue - { - DataType = "String", - StringValue = largeAttributeValue - }, - ["Attribute2"] = new MessageAttributeValue - { - DataType = "String", - StringValue = mediumAttributeValue - }, - ["Attribute3"] = new MessageAttributeValue - { - DataType = "String", - StringValue = "Small value" - }, - ["EntityId"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = "12345" - }, - ["CommandType"] = new MessageAttributeValue - { - DataType = "String", - StringValue = "SizeLimitTestCommand" - }, - ["LongAttributeName123456789012345678901234567890"] = new MessageAttributeValue - { - DataType = "String", - StringValue = "Testing long attribute name" - }, - ["JsonAttribute"] = new MessageAttributeValue - { - DataType = "String", - StringValue = JsonSerializer.Serialize(new - { - ComplexObject = new - { - Id = Guid.NewGuid(), - Name = "Complex object in attribute", - Values = new[] { 1, 2, 3, 4, 5 }, - Metadata = new Dictionary - { - ["Key1"] = "Value1", - ["Key2"] = "Value2" - } - } - }) - }, - ["BinaryAttribute"] = new MessageAttributeValue - { - DataType = "Binary", - BinaryValue = new MemoryStream(Encoding.UTF8.GetBytes(new string('C', 512))) // 512 bytes binary - }, - ["UnicodeAttribute"] = new MessageAttributeValue - { - DataType = "String", - StringValue = "Unicode test: 🚀🌟💫⭐🎯🔥💎🎨🎪🎭" + string.Concat(Enumerable.Repeat("🎵", 50)) // Unicode with emojis - }, - ["NumericAttribute"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = "123456789012345678901234567890.123456789" // Large decimal number - } - } - }); - - Assert.NotNull(sendResponse.MessageId); - - // Act - Receive and validate message - var receiveResponse = await _localStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = queueUrl, - MaxNumberOfMessages = 1, - MessageAttributeNames = new List { "All" }, - WaitTimeSeconds = 2 - }); - - // Assert - All attributes should be preserved despite their size - Assert.Single(receiveResponse.Messages); - var message = receiveResponse.Messages[0]; - - // Verify large attributes are preserved - Assert.Equal(largeAttributeValue, message.MessageAttributes["Attribute1"].StringValue); - Assert.Equal(mediumAttributeValue, message.MessageAttributes["Attribute2"].StringValue); - Assert.Equal("Small value", message.MessageAttributes["Attribute3"].StringValue); - - // Verify long attribute name is preserved - Assert.True(message.MessageAttributes.ContainsKey("LongAttributeName123456789012345678901234567890")); - Assert.Equal("Testing long attribute name", - message.MessageAttributes["LongAttributeName123456789012345678901234567890"].StringValue); - - // Verify JSON attribute is preserved - var jsonAttribute = message.MessageAttributes["JsonAttribute"].StringValue; - var deserializedJson = JsonSerializer.Deserialize>(jsonAttribute); - Assert.NotNull(deserializedJson); - Assert.True(deserializedJson.ContainsKey("ComplexObject")); - - // Verify binary attribute is preserved - var binaryAttribute = message.MessageAttributes["BinaryAttribute"]; - Assert.Equal("Binary", binaryAttribute.DataType); - var binaryData = new byte[binaryAttribute.BinaryValue.Length]; - binaryAttribute.BinaryValue.Read(binaryData, 0, binaryData.Length); - Assert.Equal(512, binaryData.Length); - - // Verify unicode attribute is preserved - var unicodeAttribute = message.MessageAttributes["UnicodeAttribute"].StringValue; - Assert.Contains("🚀🌟💫⭐🎯🔥💎🎨🎪🎭", unicodeAttribute); - Assert.Contains("🎵", unicodeAttribute); - - // Verify numeric attribute is preserved - Assert.Equal("123456789012345678901234567890.123456789", - message.MessageAttributes["NumericAttribute"].StringValue); - - // Clean up - await _localStack.SqsClient.DeleteMessageAsync(new DeleteMessageRequest - { - QueueUrl = queueUrl, - ReceiptHandle = message.ReceiptHandle - }); - } - - [Fact] - public async Task MessageAttributes_ShouldHandleAttributeEncoding() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.SqsClient == null) - { - return; - } - - // Arrange - var queueName = $"test-attribute-encoding-{Guid.NewGuid():N}"; - var queueUrl = await CreateStandardQueueAsync(queueName); - - // Test various encoding scenarios - var specialCharacters = "Special chars: !@#$%^&*()_+-=[]{}|;':\",./<>?`~"; - var xmlContent = "Value & more"; - var jsonContent = "{\"key\": \"value with \\\"quotes\\\" and \\n newlines\"}"; - var base64Content = Convert.ToBase64String(Encoding.UTF8.GetBytes("Base64 encoded content")); - var urlEncodedContent = "param1=value%201¶m2=value%202"; - - // Act - Send message with various encoded content - var sendResponse = await _localStack.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = queueUrl, - MessageBody = "Message with encoding test attributes", - MessageAttributes = new Dictionary - { - ["SpecialChars"] = new MessageAttributeValue - { - DataType = "String", - StringValue = specialCharacters - }, - ["XmlContent"] = new MessageAttributeValue - { - DataType = "String", - StringValue = xmlContent - }, - ["JsonContent"] = new MessageAttributeValue - { - DataType = "String", - StringValue = jsonContent - }, - ["Base64Content"] = new MessageAttributeValue - { - DataType = "String", - StringValue = base64Content - }, - ["UrlEncodedContent"] = new MessageAttributeValue - { - DataType = "String", - StringValue = urlEncodedContent - }, - ["MultilineContent"] = new MessageAttributeValue - { - DataType = "String", - StringValue = "Line 1\nLine 2\r\nLine 3\tTabbed\r\n\tIndented" - }, - ["UnicodeContent"] = new MessageAttributeValue - { - DataType = "String", - StringValue = "Multilingual: English, Español, Français, Deutsch, 中文, 日本語, العربية, Русский" - }, - ["EscapedContent"] = new MessageAttributeValue - { - DataType = "String", - StringValue = "Escaped: \\n \\t \\r \\\\ \\\" \\'" - }, - ["EntityId"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = "99999" - }, - ["CommandType"] = new MessageAttributeValue - { - DataType = "String", - StringValue = "EncodingTestCommand" - } - } - }); - - Assert.NotNull(sendResponse.MessageId); - - // Act - Receive and validate message - var receiveResponse = await _localStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = queueUrl, - MaxNumberOfMessages = 1, - MessageAttributeNames = new List { "All" }, - WaitTimeSeconds = 2 - }); - - // Assert - All encoded content should be preserved exactly - Assert.Single(receiveResponse.Messages); - var message = receiveResponse.Messages[0]; - - // Verify special characters are preserved - Assert.Equal(specialCharacters, message.MessageAttributes["SpecialChars"].StringValue); - - // Verify XML content is preserved - Assert.Equal(xmlContent, message.MessageAttributes["XmlContent"].StringValue); - - // Verify JSON content is preserved - Assert.Equal(jsonContent, message.MessageAttributes["JsonContent"].StringValue); - - // Verify Base64 content is preserved - Assert.Equal(base64Content, message.MessageAttributes["Base64Content"].StringValue); - var decodedBase64 = Encoding.UTF8.GetString(Convert.FromBase64String( - message.MessageAttributes["Base64Content"].StringValue)); - Assert.Equal("Base64 encoded content", decodedBase64); - - // Verify URL encoded content is preserved - Assert.Equal(urlEncodedContent, message.MessageAttributes["UrlEncodedContent"].StringValue); - - // Verify multiline content is preserved - var multilineContent = message.MessageAttributes["MultilineContent"].StringValue; - Assert.Contains("Line 1\nLine 2", multilineContent); - Assert.Contains("\tTabbed", multilineContent); - Assert.Contains("\tIndented", multilineContent); - - // Verify Unicode content is preserved - var unicodeContent = message.MessageAttributes["UnicodeContent"].StringValue; - Assert.Contains("English", unicodeContent); - Assert.Contains("中文", unicodeContent); - Assert.Contains("العربية", unicodeContent); - Assert.Contains("Русский", unicodeContent); - - // Verify escaped content is preserved - Assert.Equal("Escaped: \\n \\t \\r \\\\ \\\" \\'", - message.MessageAttributes["EscapedContent"].StringValue); - - // Clean up - await _localStack.SqsClient.DeleteMessageAsync(new DeleteMessageRequest - { - QueueUrl = queueUrl, - ReceiptHandle = message.ReceiptHandle - }); - } - - [Fact] - public async Task MessageAttributes_ShouldSupportFifoQueueAttributes() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.SqsClient == null) - { - return; - } - - // Arrange - var queueName = $"test-fifo-attributes-{Guid.NewGuid():N}.fifo"; - var queueUrl = await CreateFifoQueueAsync(queueName); - - var entityId = 54321; - var messageGroupId = $"entity-{entityId}"; - - // Send multiple messages with attributes to FIFO queue - var messages = new[] - { - new { SequenceNo = 1, Priority = "High", Action = "Create" }, - new { SequenceNo = 2, Priority = "Medium", Action = "Update" }, - new { SequenceNo = 3, Priority = "High", Action = "Delete" } - }; - - var sendTasks = messages.Select(async (msg, index) => - { - return await _localStack.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = queueUrl, - MessageBody = $"FIFO message {msg.SequenceNo} - {msg.Action}", - MessageGroupId = messageGroupId, - MessageDeduplicationId = $"msg-{entityId}-{msg.SequenceNo}-{Guid.NewGuid():N}", - MessageAttributes = new Dictionary - { - ["EntityId"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = entityId.ToString() - }, - ["SequenceNo"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = msg.SequenceNo.ToString() - }, - ["Priority"] = new MessageAttributeValue - { - DataType = "String", - StringValue = msg.Priority - }, - ["Action"] = new MessageAttributeValue - { - DataType = "String", - StringValue = msg.Action - }, - ["CommandType"] = new MessageAttributeValue - { - DataType = "String", - StringValue = $"{msg.Action}Command" - }, - ["Timestamp"] = new MessageAttributeValue - { - DataType = "String", - StringValue = DateTime.UtcNow.ToString("O") - } - } - }); - }); - - await Task.WhenAll(sendTasks); - - // Act - Receive messages in order - var receivedMessages = new List(); - var maxAttempts = 10; - var attempts = 0; - - while (receivedMessages.Count < messages.Length && attempts < maxAttempts) - { - var receiveResponse = await _localStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = queueUrl, - MaxNumberOfMessages = 10, - MessageAttributeNames = new List { "All" }, - WaitTimeSeconds = 1 - }); - - receivedMessages.AddRange(receiveResponse.Messages); - attempts++; - } - - // Assert - All messages should be received with attributes preserved - Assert.Equal(messages.Length, receivedMessages.Count); - - // Verify FIFO ordering is maintained based on SequenceNo - var orderedMessages = receivedMessages - .OrderBy(m => int.Parse(m.MessageAttributes["SequenceNo"].StringValue)) - .ToList(); - - for (int i = 0; i < messages.Length; i++) - { - var message = orderedMessages[i]; - var expectedMsg = messages[i]; - - // Verify attributes are preserved - Assert.Equal(entityId.ToString(), message.MessageAttributes["EntityId"].StringValue); - Assert.Equal(expectedMsg.SequenceNo.ToString(), message.MessageAttributes["SequenceNo"].StringValue); - Assert.Equal(expectedMsg.Priority, message.MessageAttributes["Priority"].StringValue); - Assert.Equal(expectedMsg.Action, message.MessageAttributes["Action"].StringValue); - Assert.Equal($"{expectedMsg.Action}Command", message.MessageAttributes["CommandType"].StringValue); - - // Verify message body - Assert.Contains($"FIFO message {expectedMsg.SequenceNo}", message.Body); - Assert.Contains(expectedMsg.Action, message.Body); - - // Verify timestamp is valid - Assert.True(DateTime.TryParse(message.MessageAttributes["Timestamp"].StringValue, out _)); - } - - // Clean up - await CleanupMessages(queueUrl, receivedMessages); - } - - /// - /// Create a standard queue with the specified name and attributes - /// - private async Task CreateStandardQueueAsync(string queueName, Dictionary? additionalAttributes = null) - { - var attributes = new Dictionary - { - ["MessageRetentionPeriod"] = "1209600", // 14 days - ["VisibilityTimeout"] = "30" - }; - - if (additionalAttributes != null) - { - foreach (var attr in additionalAttributes) - { - attributes[attr.Key] = attr.Value; - } - } - - var response = await _localStack.SqsClient.CreateQueueAsync(new CreateQueueRequest - { - QueueName = queueName, - Attributes = attributes - }); - - _createdQueues.Add(response.QueueUrl); - return response.QueueUrl; - } - - /// - /// Create a FIFO queue with the specified name and attributes - /// - private async Task CreateFifoQueueAsync(string queueName, Dictionary? additionalAttributes = null) - { - var attributes = new Dictionary - { - ["FifoQueue"] = "true", - ["ContentBasedDeduplication"] = "true", - ["MessageRetentionPeriod"] = "1209600", - ["VisibilityTimeout"] = "30" - }; - - if (additionalAttributes != null) - { - foreach (var attr in additionalAttributes) - { - attributes[attr.Key] = attr.Value; - } - } - - var response = await _localStack.SqsClient.CreateQueueAsync(new CreateQueueRequest - { - QueueName = queueName, - Attributes = attributes - }); - - _createdQueues.Add(response.QueueUrl); - return response.QueueUrl; - } - - /// - /// Clean up messages from a queue - /// - private async Task CleanupMessages(string queueUrl, List messages) - { - if (!messages.Any()) return; - - var deleteTasks = messages.Select(message => - _localStack.SqsClient.DeleteMessageAsync(new DeleteMessageRequest - { - QueueUrl = queueUrl, - ReceiptHandle = message.ReceiptHandle - })); - - try - { - await Task.WhenAll(deleteTasks); - } - catch (Exception) - { - // Ignore cleanup errors - } - } - - /// - /// Clean up created queues - /// - public async ValueTask DisposeAsync() - { - if (_localStack.SqsClient != null) - { - foreach (var queueUrl in _createdQueues) - { - try - { - await _localStack.SqsClient.DeleteQueueAsync(new DeleteQueueRequest - { - QueueUrl = queueUrl - }); - } - catch (Exception) - { - // Ignore cleanup errors - } - } - } - - _createdQueues.Clear(); - } -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/Integration/SqsMessageProcessingPropertyTests.cs b/tests/SourceFlow.Cloud.AWS.Tests/Integration/SqsMessageProcessingPropertyTests.cs deleted file mode 100644 index cd72db1e..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/Integration/SqsMessageProcessingPropertyTests.cs +++ /dev/null @@ -1,639 +0,0 @@ -using Amazon.SQS.Model; -using FsCheck; -using FsCheck.Xunit; -using SourceFlow.Cloud.AWS.Tests.TestHelpers; -using System.Text.Json; - -namespace SourceFlow.Cloud.AWS.Tests.Integration; - -/// -/// Property-based tests for SQS message processing correctness -/// Validates universal properties that should hold across all valid SQS operations -/// -[Collection("AWS Integration Tests")] -[Trait("Category", "Integration")] -[Trait("Category", "RequiresLocalStack")] -public class SqsMessageProcessingPropertyTests : IClassFixture, IAsyncDisposable -{ - private readonly LocalStackTestFixture _localStack; - private readonly List _createdQueues = new(); - - public SqsMessageProcessingPropertyTests(LocalStackTestFixture localStack) - { - _localStack = localStack; - } - - /// - /// Property 1: SQS Message Processing Correctness - /// For any valid SourceFlow command and SQS queue configuration (standard or FIFO), - /// when the command is dispatched through SQS, it should be delivered correctly with - /// proper message attributes (EntityId, SequenceNo, CommandType), maintain FIFO ordering - /// within message groups when applicable, support batch operations up to AWS limits, - /// and achieve consistent throughput performance. - /// Validates: Requirements 1.1, 1.2, 1.4, 1.5 - /// - // FsCheck 2.x does not support async Task properties — method must be void - [Property(MaxTest = 20, Arbitrary = new[] { typeof(SqsMessageGenerators) })] - public void Property_SqsMessageProcessingCorrectness(SqsTestScenario scenario) => - Property_SqsMessageProcessingCorrectnessAsync(scenario).GetAwaiter().GetResult(); - - private async Task Property_SqsMessageProcessingCorrectnessAsync(SqsTestScenario scenario) - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.SqsClient == null) - { - return; - } - - // Arrange - Create appropriate queue type - var queueUrl = scenario.QueueType == QueueType.Fifo - ? await CreateFifoQueueAsync($"prop-test-fifo-{Guid.NewGuid():N}.fifo") - : await CreateStandardQueueAsync($"prop-test-standard-{Guid.NewGuid():N}"); - - var sentMessages = new List(); - var receivedMessages = new List(); - - try - { - // Act - Send messages according to scenario - if (scenario.UseBatchSending && scenario.Messages.Count > 1) - { - await SendMessagesBatch(queueUrl, scenario, sentMessages); - } - else - { - await SendMessagesIndividually(queueUrl, scenario, sentMessages); - } - - // Act - Receive all messages - await ReceiveAllMessages(queueUrl, scenario.Messages.Count, receivedMessages); - - // Assert - Message delivery correctness - AssertMessageDeliveryCorrectness(sentMessages, receivedMessages); - - // Assert - Message attributes preservation - AssertMessageAttributesPreservation(sentMessages, receivedMessages); - - // Assert - FIFO ordering (if applicable) - if (scenario.QueueType == QueueType.Fifo) - { - AssertFifoOrdering(sentMessages, receivedMessages); - } - - // Assert - Batch operation efficiency (if applicable) - if (scenario.UseBatchSending) - { - AssertBatchOperationEfficiency(scenario, sentMessages); - } - - // Assert - Performance consistency - AssertPerformanceConsistency(scenario, sentMessages, receivedMessages); - } - finally - { - // Clean up messages - await CleanupMessages(queueUrl, receivedMessages); - } - } - - /// - /// Send messages individually to the queue - /// - private async Task SendMessagesIndividually(string queueUrl, SqsTestScenario scenario, List sentMessages) - { - var sendTasks = scenario.Messages.Select(async (message, index) => - { - var request = CreateSendMessageRequest(queueUrl, message, scenario.QueueType, index); - var startTime = DateTime.UtcNow; - - var response = await _localStack.SqsClient.SendMessageAsync(request); - var endTime = DateTime.UtcNow; - - var sentMessage = new SqsTestMessage - { - OriginalMessage = message, - MessageId = response.MessageId, - SendTime = startTime, - SendDuration = endTime - startTime, - MessageGroupId = request.MessageGroupId, - MessageDeduplicationId = request.MessageDeduplicationId, - MessageAttributes = request.MessageAttributes.ToDictionary( - kvp => kvp.Key, - kvp => kvp.Value.StringValue ?? kvp.Value.BinaryValue?.ToString() ?? "") - }; - - lock (sentMessages) - { - sentMessages.Add(sentMessage); - } - }); - - await Task.WhenAll(sendTasks); - } - - /// - /// Send messages using batch operations - /// - private async Task SendMessagesBatch(string queueUrl, SqsTestScenario scenario, List sentMessages) - { - const int maxBatchSize = 10; // AWS SQS limit - var batches = scenario.Messages - .Select((message, index) => new { Message = message, Index = index }) - .GroupBy(x => x.Index / maxBatchSize) - .Select(g => g.ToList()) - .ToList(); - - foreach (var batch in batches) - { - var entries = batch.Select(item => - { - var request = CreateSendMessageRequest(queueUrl, item.Message, scenario.QueueType, item.Index); - return new SendMessageBatchRequestEntry - { - Id = item.Index.ToString(), - MessageBody = request.MessageBody, - MessageGroupId = request.MessageGroupId, - MessageDeduplicationId = request.MessageDeduplicationId, - MessageAttributes = request.MessageAttributes - }; - }).ToList(); - - var startTime = DateTime.UtcNow; - var response = await _localStack.SqsClient.SendMessageBatchAsync(new SendMessageBatchRequest - { - QueueUrl = queueUrl, - Entries = entries - }); - var endTime = DateTime.UtcNow; - - // Record successful sends - foreach (var successful in response.Successful) - { - var originalIndex = int.Parse(successful.Id); - var originalMessage = batch.First(b => b.Index == originalIndex).Message; - var originalEntry = entries.First(e => e.Id == successful.Id); - - var sentMessage = new SqsTestMessage - { - OriginalMessage = originalMessage, - MessageId = successful.MessageId, - SendTime = startTime, - SendDuration = endTime - startTime, - MessageGroupId = originalEntry.MessageGroupId, - MessageDeduplicationId = originalEntry.MessageDeduplicationId, - MessageAttributes = originalEntry.MessageAttributes.ToDictionary( - kvp => kvp.Key, - kvp => kvp.Value.StringValue ?? kvp.Value.BinaryValue?.ToString() ?? ""), - WasBatchSent = true - }; - - sentMessages.Add(sentMessage); - } - - // Assert no failed sends in property test - if (response.Failed.Any()) - { - throw new InvalidOperationException($"Batch send failed for {response.Failed.Count} messages: " + - string.Join(", ", response.Failed.Select(f => f.Code + ": " + f.Message))); - } - } - } - - /// - /// Receive all messages from the queue - /// - private async Task ReceiveAllMessages(string queueUrl, int expectedCount, List receivedMessages) - { - var maxAttempts = 30; - var attempts = 0; - - while (receivedMessages.Count < expectedCount && attempts < maxAttempts) - { - var receiveResponse = await _localStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = queueUrl, - MaxNumberOfMessages = 10, - MessageAttributeNames = new List { "All" }, - WaitTimeSeconds = 1 - }); - - receivedMessages.AddRange(receiveResponse.Messages); - attempts++; - - if (receiveResponse.Messages.Count == 0) - { - await Task.Delay(100); - } - } - } - - /// - /// Assert that all sent messages are delivered correctly - /// - private static void AssertMessageDeliveryCorrectness(List sentMessages, List receivedMessages) - { - // All sent messages should be received - Assert.True(receivedMessages.Count >= sentMessages.Count * 0.95, // Allow 5% variance for LocalStack - $"Expected at least {sentMessages.Count * 0.95} messages, received {receivedMessages.Count}"); - - // Each received message should correspond to a sent message - foreach (var receivedMessage in receivedMessages) - { - var messageBody = receivedMessage.Body; - var matchingSent = sentMessages.FirstOrDefault(s => - JsonSerializer.Serialize(s.OriginalMessage.Payload) == messageBody); - - Assert.NotNull(matchingSent); - } - } - - /// - /// Assert that message attributes are preserved correctly - /// - private static void AssertMessageAttributesPreservation(List sentMessages, List receivedMessages) - { - foreach (var receivedMessage in receivedMessages) - { - // Find corresponding sent message - var messageBody = receivedMessage.Body; - var matchingSent = sentMessages.FirstOrDefault(s => - JsonSerializer.Serialize(s.OriginalMessage.Payload) == messageBody); - - if (matchingSent == null) continue; - - // Verify SourceFlow attributes are preserved - var requiredAttributes = new[] { "EntityId", "SequenceNo", "CommandType", "PayloadType" }; - - foreach (var attrName in requiredAttributes) - { - Assert.True(receivedMessage.MessageAttributes.ContainsKey(attrName), - $"Missing required attribute: {attrName}"); - - if (matchingSent.MessageAttributes.ContainsKey(attrName)) - { - Assert.Equal(matchingSent.MessageAttributes[attrName], - receivedMessage.MessageAttributes[attrName].StringValue); - } - } - - // Verify EntityId is numeric - Assert.True(int.TryParse(receivedMessage.MessageAttributes["EntityId"].StringValue, out _), - "EntityId should be numeric"); - - // Verify SequenceNo is numeric - Assert.True(int.TryParse(receivedMessage.MessageAttributes["SequenceNo"].StringValue, out _), - "SequenceNo should be numeric"); - } - } - - /// - /// Assert FIFO ordering is maintained within message groups - /// - private static void AssertFifoOrdering(List sentMessages, List receivedMessages) - { - // Group messages by MessageGroupId - var sentByGroup = sentMessages - .Where(s => !string.IsNullOrEmpty(s.MessageGroupId)) - .GroupBy(s => s.MessageGroupId) - .ToDictionary(g => g.Key, g => g.OrderBy(s => s.SendTime).ToList()); - - var receivedByGroup = receivedMessages - .Where(r => r.Attributes.ContainsKey("MessageGroupId")) - .GroupBy(r => r.Attributes["MessageGroupId"]) - .ToDictionary(g => g.Key, g => g.ToList()); - - foreach (var groupId in sentByGroup.Keys) - { - if (!receivedByGroup.ContainsKey(groupId)) continue; - - var sentInGroup = sentByGroup[groupId]; - var receivedInGroup = receivedByGroup[groupId]; - - // Within each group, messages should maintain order based on SequenceNo - var receivedSequenceNos = receivedInGroup - .Where(r => r.MessageAttributes.ContainsKey("SequenceNo")) - .Select(r => int.Parse(r.MessageAttributes["SequenceNo"].StringValue)) - .ToList(); - - var sortedSequenceNos = receivedSequenceNos.OrderBy(x => x).ToList(); - - Assert.Equal(sortedSequenceNos, receivedSequenceNos); - } - } - - /// - /// Assert batch operation efficiency - /// - private static void AssertBatchOperationEfficiency(SqsTestScenario scenario, List sentMessages) - { - if (!scenario.UseBatchSending) return; - - // Batch operations should be more efficient than individual sends - var batchSentMessages = sentMessages.Where(s => s.WasBatchSent).ToList(); - var individualSentMessages = sentMessages.Where(s => !s.WasBatchSent).ToList(); - - if (batchSentMessages.Any() && individualSentMessages.Any()) - { - var avgBatchDuration = batchSentMessages.Average(s => s.SendDuration.TotalMilliseconds); - var avgIndividualDuration = individualSentMessages.Average(s => s.SendDuration.TotalMilliseconds); - - // This is informational - actual efficiency depends on LocalStack vs real AWS - Assert.True(avgBatchDuration >= 0 && avgIndividualDuration >= 0, - "Both batch and individual send durations should be non-negative"); - } - - // Batch sends should respect AWS limits (max 10 messages per batch) - var maxBatchSize = 10; - Assert.True(batchSentMessages.Count <= scenario.Messages.Count, - "Batch sent messages should not exceed total messages"); - } - - /// - /// Assert performance consistency - /// - private static void AssertPerformanceConsistency(SqsTestScenario scenario, List sentMessages, List receivedMessages) - { - // Send performance should be consistent - var sendDurations = sentMessages.Select(s => s.SendDuration.TotalMilliseconds).ToList(); - if (sendDurations.Count > 1) - { - var avgSendDuration = sendDurations.Average(); - var maxSendDuration = sendDurations.Max(); - - // Performance should be reasonable (this is informational for LocalStack) - Assert.True(avgSendDuration >= 0, "Average send duration should be non-negative"); - Assert.True(maxSendDuration < 30000, "Maximum send duration should be less than 30 seconds"); - } - - // Message throughput should be positive - if (sentMessages.Any()) - { - var totalSendTime = sentMessages.Max(s => s.SendTime.Add(s.SendDuration)) - sentMessages.Min(s => s.SendTime); - if (totalSendTime.TotalSeconds > 0) - { - var throughput = sentMessages.Count / totalSendTime.TotalSeconds; - Assert.True(throughput > 0, "Message throughput should be positive"); - } - } - } - - /// - /// Create a send message request for the given test message - /// - private static SendMessageRequest CreateSendMessageRequest(string queueUrl, TestMessage message, QueueType queueType, int index) - { - var request = new SendMessageRequest - { - QueueUrl = queueUrl, - MessageBody = JsonSerializer.Serialize(message.Payload), - MessageAttributes = new Dictionary - { - ["EntityId"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = message.EntityId.ToString() - }, - ["SequenceNo"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = message.SequenceNo.ToString() - }, - ["CommandType"] = new MessageAttributeValue - { - DataType = "String", - StringValue = message.CommandType - }, - ["PayloadType"] = new MessageAttributeValue - { - DataType = "String", - StringValue = message.PayloadType - }, - ["Timestamp"] = new MessageAttributeValue - { - DataType = "String", - StringValue = DateTime.UtcNow.ToString("O") - } - } - }; - - // Add FIFO-specific attributes - if (queueType == QueueType.Fifo) - { - request.MessageGroupId = $"entity-{message.EntityId}"; - request.MessageDeduplicationId = $"msg-{message.EntityId}-{message.SequenceNo}-{index}-{Guid.NewGuid():N}"; - } - - return request; - } - - /// - /// Clean up received messages - /// - private async Task CleanupMessages(string queueUrl, List receivedMessages) - { - var deleteTasks = receivedMessages.Select(message => - _localStack.SqsClient.DeleteMessageAsync(new DeleteMessageRequest - { - QueueUrl = queueUrl, - ReceiptHandle = message.ReceiptHandle - })); - - try - { - await Task.WhenAll(deleteTasks); - } - catch (Exception) - { - // Ignore cleanup errors - } - } - - /// - /// Create a FIFO queue for testing - /// - private async Task CreateFifoQueueAsync(string queueName) - { - var response = await _localStack.SqsClient.CreateQueueAsync(new CreateQueueRequest - { - QueueName = queueName, - Attributes = new Dictionary - { - ["FifoQueue"] = "true", - ["ContentBasedDeduplication"] = "true", - ["MessageRetentionPeriod"] = "1209600", - ["VisibilityTimeout"] = "30" - } - }); - - _createdQueues.Add(response.QueueUrl); - return response.QueueUrl; - } - - /// - /// Create a standard queue for testing - /// - private async Task CreateStandardQueueAsync(string queueName) - { - var response = await _localStack.SqsClient.CreateQueueAsync(new CreateQueueRequest - { - QueueName = queueName, - Attributes = new Dictionary - { - ["MessageRetentionPeriod"] = "1209600", - ["VisibilityTimeout"] = "30" - } - }); - - _createdQueues.Add(response.QueueUrl); - return response.QueueUrl; - } - - /// - /// Clean up created queues - /// - public async ValueTask DisposeAsync() - { - if (_localStack.SqsClient != null) - { - foreach (var queueUrl in _createdQueues) - { - try - { - await _localStack.SqsClient.DeleteQueueAsync(new DeleteQueueRequest - { - QueueUrl = queueUrl - }); - } - catch (Exception) - { - // Ignore cleanup errors - } - } - } - - _createdQueues.Clear(); - } -} - -/// -/// FsCheck generators for SQS message processing property tests -/// -public static class SqsMessageGenerators -{ - /// - /// Generate test scenarios for SQS message processing - /// - public static Arbitrary SqsTestScenario() - { - var queueTypeGen = Gen.Elements(QueueType.Standard, QueueType.Fifo); - var useBatchGen = Gen.Elements(true, false); - var messageCountGen = Gen.Choose(1, 20); - - var scenarioGen = from queueType in queueTypeGen - from useBatch in useBatchGen - from messageCount in messageCountGen - from messages in Gen.ListOf(messageCount, TestMessage()) - select new SqsTestScenario - { - QueueType = queueType, - UseBatchSending = useBatch, - Messages = messages.ToList() - }; - - return Arb.From(scenarioGen); - } - - /// - /// Generate test messages with realistic SourceFlow command structure - /// - public static Gen TestMessage() - { - var entityIdGen = Gen.Choose(1, 10000); - var sequenceNoGen = Gen.Choose(1, 1000); - var commandTypeGen = Gen.Elements( - "CreateOrderCommand", - "UpdateOrderCommand", - "CancelOrderCommand", - "ProcessPaymentCommand", - "ShipOrderCommand"); - var payloadTypeGen = Gen.Elements( - "CreateOrderPayload", - "UpdateOrderPayload", - "CancelOrderPayload", - "ProcessPaymentPayload", - "ShipOrderPayload"); - - var payloadGen = from orderId in Gen.Fresh(() => Guid.NewGuid()) - from customerId in Gen.Choose(1, 100000) - from amountCents in Gen.Choose(100, 1000000) - from currency in Gen.Elements("USD", "EUR", "GBP", "CAD") - select new Dictionary - { - ["OrderId"] = orderId, - ["CustomerId"] = customerId, - ["Amount"] = Math.Round(amountCents / 100.0, 2), - ["Currency"] = currency, - ["Timestamp"] = DateTime.UtcNow.ToString("O") - }; - - return from entityId in entityIdGen - from sequenceNo in sequenceNoGen - from commandType in commandTypeGen - from payloadType in payloadTypeGen - from payload in payloadGen - select new TestMessage - { - EntityId = entityId, - SequenceNo = sequenceNo, - CommandType = commandType, - PayloadType = payloadType, - Payload = payload - }; - } -} - -/// -/// Test scenario for SQS message processing -/// -public class SqsTestScenario -{ - public QueueType QueueType { get; set; } - public bool UseBatchSending { get; set; } - public List Messages { get; set; } = new(); -} - -/// -/// Test message representing a SourceFlow command -/// -public class TestMessage -{ - public int EntityId { get; set; } - public int SequenceNo { get; set; } - public string CommandType { get; set; } = ""; - public string PayloadType { get; set; } = ""; - public Dictionary Payload { get; set; } = new(); -} - -/// -/// Sent message tracking information -/// -public class SqsTestMessage -{ - public TestMessage OriginalMessage { get; set; } = new(); - public string MessageId { get; set; } = ""; - public DateTime SendTime { get; set; } - public TimeSpan SendDuration { get; set; } - public string? MessageGroupId { get; set; } - public string? MessageDeduplicationId { get; set; } - public Dictionary MessageAttributes { get; set; } = new(); - public bool WasBatchSent { get; set; } -} - -/// -/// Queue type enumeration -/// -public enum QueueType -{ - Standard, - Fifo -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/Integration/SqsStandardIntegrationTests.cs b/tests/SourceFlow.Cloud.AWS.Tests/Integration/SqsStandardIntegrationTests.cs deleted file mode 100644 index 5d5c7127..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/Integration/SqsStandardIntegrationTests.cs +++ /dev/null @@ -1,751 +0,0 @@ -using Amazon.SQS.Model; -using SourceFlow.Cloud.AWS.Tests.TestHelpers; -using System.Collections.Concurrent; -using System.Diagnostics; -using System.Text.Json; - -namespace SourceFlow.Cloud.AWS.Tests.Integration; - -/// -/// Comprehensive integration tests for SQS standard queue functionality -/// Tests high-throughput delivery, at-least-once guarantees, concurrent processing, and performance characteristics -/// -[Collection("AWS Integration Tests")] -[Trait("Category", "Integration")] -[Trait("Category", "RequiresLocalStack")] -public class SqsStandardIntegrationTests : IClassFixture, IAsyncDisposable -{ - private readonly LocalStackTestFixture _localStack; - private readonly List _createdQueues = new(); - - public SqsStandardIntegrationTests(LocalStackTestFixture localStack) - { - _localStack = localStack; - } - - [Fact] - public async Task StandardQueue_ShouldSupportHighThroughputMessageDelivery() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.SqsClient == null) - { - return; - } - - // Arrange - var queueName = $"test-standard-throughput-{Guid.NewGuid():N}"; - var queueUrl = await CreateStandardQueueAsync(queueName); - - var messageCount = 100; - var concurrentSenders = 5; - var messagesPerSender = messageCount / concurrentSenders; - - // Act - Send messages concurrently for high throughput - var sendTasks = new List>>(); - var stopwatch = Stopwatch.StartNew(); - - for (int senderId = 0; senderId < concurrentSenders; senderId++) - { - var currentSenderId = senderId; // Capture for closure - sendTasks.Add(Task.Run(async () => - { - var responses = new List(); - for (int msgId = 0; msgId < messagesPerSender; msgId++) - { - var response = await _localStack.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = queueUrl, - MessageBody = $"Sender {currentSenderId} - Message {msgId} - {DateTime.UtcNow:HH:mm:ss.fff}", - MessageAttributes = new Dictionary - { - ["SenderId"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = currentSenderId.ToString() - }, - ["MessageId"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = msgId.ToString() - }, - ["Timestamp"] = new MessageAttributeValue - { - DataType = "String", - StringValue = DateTime.UtcNow.ToString("O") - } - } - }); - responses.Add(response); - } - return responses; - })); - } - - var allSendResponses = await Task.WhenAll(sendTasks); - var sendDuration = stopwatch.Elapsed; - - var totalSent = allSendResponses.SelectMany(responses => responses).ToList(); - - // Assert - All messages should be sent successfully - Assert.Equal(messageCount, totalSent.Count); - Assert.All(totalSent, response => Assert.NotNull(response.MessageId)); - - // Calculate and verify throughput - var sendThroughput = messageCount / sendDuration.TotalSeconds; - Assert.True(sendThroughput > 0, $"Send throughput: {sendThroughput:F2} messages/second"); - - // Act - Receive all messages with concurrent consumers - var receivedMessages = new ConcurrentBag(); - var concurrentReceivers = 3; - var maxReceiveAttempts = 20; - - stopwatch.Restart(); - var receiveTasks = new List(); - - for (int receiverId = 0; receiverId < concurrentReceivers; receiverId++) - { - receiveTasks.Add(Task.Run(async () => - { - var attempts = 0; - while (receivedMessages.Count < messageCount && attempts < maxReceiveAttempts) - { - var receiveResponse = await _localStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = queueUrl, - MaxNumberOfMessages = 10, - MessageAttributeNames = new List { "All" }, - WaitTimeSeconds = 1 - }); - - foreach (var message in receiveResponse.Messages) - { - receivedMessages.Add(message); - - // Delete message to acknowledge processing - await _localStack.SqsClient.DeleteMessageAsync(new DeleteMessageRequest - { - QueueUrl = queueUrl, - ReceiptHandle = message.ReceiptHandle - }); - } - - attempts++; - - if (receiveResponse.Messages.Count == 0) - { - await Task.Delay(100); // Brief pause if no messages - } - } - })); - } - - await Task.WhenAll(receiveTasks); - var receiveDuration = stopwatch.Elapsed; - - // Assert - All messages should be received - Assert.True(receivedMessages.Count >= messageCount * 0.95, // Allow for some variance in LocalStack - $"Expected at least {messageCount * 0.95} messages, received {receivedMessages.Count}"); - - var receiveThroughput = receivedMessages.Count / receiveDuration.TotalSeconds; - Assert.True(receiveThroughput > 0, $"Receive throughput: {receiveThroughput:F2} messages/second"); - - // Verify message distribution across senders - var messagesBySender = receivedMessages - .Where(m => m.MessageAttributes.ContainsKey("SenderId")) - .GroupBy(m => m.MessageAttributes["SenderId"].StringValue) - .ToDictionary(g => int.Parse(g.Key), g => g.Count()); - - Assert.True(messagesBySender.Count > 0, "Should receive messages from multiple senders"); - } - - [Fact] - public async Task StandardQueue_ShouldGuaranteeAtLeastOnceDelivery() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.SqsClient == null) - { - return; - } - - // Arrange - var queueName = $"test-standard-at-least-once-{Guid.NewGuid():N}"; - var queueUrl = await CreateStandardQueueAsync(queueName, new Dictionary - { - ["VisibilityTimeout"] = "5" // Short visibility timeout for testing - }); - - var messageBody = $"At-least-once test message - {Guid.NewGuid()}"; - var messageId = Guid.NewGuid().ToString(); - - // Act - Send a message - var sendResponse = await _localStack.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = queueUrl, - MessageBody = messageBody, - MessageAttributes = new Dictionary - { - ["MessageId"] = new MessageAttributeValue - { - DataType = "String", - StringValue = messageId - }, - ["SendTime"] = new MessageAttributeValue - { - DataType = "String", - StringValue = DateTime.UtcNow.ToString("O") - } - } - }); - - Assert.NotNull(sendResponse.MessageId); - - // Act - Receive message but don't delete it (simulate processing failure) - var firstReceive = await _localStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = queueUrl, - MaxNumberOfMessages = 1, - MessageAttributeNames = new List { "All" }, - WaitTimeSeconds = 2 - }); - - Assert.Single(firstReceive.Messages); - var firstMessage = firstReceive.Messages[0]; - Assert.Equal(messageBody, firstMessage.Body); - Assert.Equal(messageId, firstMessage.MessageAttributes["MessageId"].StringValue); - - // Don't delete the message - it should become visible again after visibility timeout - - // Act - Wait for visibility timeout and receive again - await Task.Delay(TimeSpan.FromSeconds(6)); // Wait longer than visibility timeout - - var secondReceive = await _localStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = queueUrl, - MaxNumberOfMessages = 1, - MessageAttributeNames = new List { "All" }, - WaitTimeSeconds = 2 - }); - - // Assert - Message should be available again (at-least-once delivery) - Assert.Single(secondReceive.Messages); - var secondMessage = secondReceive.Messages[0]; - Assert.Equal(messageBody, secondMessage.Body); - Assert.Equal(messageId, secondMessage.MessageAttributes["MessageId"].StringValue); - - // The receipt handles should be different (message was re-delivered) - Assert.NotEqual(firstMessage.ReceiptHandle, secondMessage.ReceiptHandle); - - // Clean up - delete the message - await _localStack.SqsClient.DeleteMessageAsync(new DeleteMessageRequest - { - QueueUrl = queueUrl, - ReceiptHandle = secondMessage.ReceiptHandle - }); - - // Verify message is gone - var finalReceive = await _localStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = queueUrl, - MaxNumberOfMessages = 1, - WaitTimeSeconds = 1 - }); - - Assert.Empty(finalReceive.Messages); - } - - [Fact] - public async Task StandardQueue_ShouldSupportConcurrentMessageProcessing() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.SqsClient == null) - { - return; - } - - // Arrange - var queueName = $"test-standard-concurrent-{Guid.NewGuid():N}"; - var queueUrl = await CreateStandardQueueAsync(queueName); - - var messageCount = 50; - var concurrentProcessors = 5; - - // Act - Send messages - var sendTasks = new List>(); - for (int i = 0; i < messageCount; i++) - { - sendTasks.Add(_localStack.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = queueUrl, - MessageBody = $"Concurrent processing test message {i}", - MessageAttributes = new Dictionary - { - ["MessageIndex"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = i.ToString() - }, - ["SendTime"] = new MessageAttributeValue - { - DataType = "String", - StringValue = DateTime.UtcNow.ToString("O") - } - } - })); - } - - await Task.WhenAll(sendTasks); - - // Act - Process messages concurrently - var processedMessages = new ConcurrentBag<(int ProcessorId, string MessageBody, int MessageIndex)>(); - var processingTasks = new List(); - var stopwatch = Stopwatch.StartNew(); - - for (int processorId = 0; processorId < concurrentProcessors; processorId++) - { - var currentProcessorId = processorId; - processingTasks.Add(Task.Run(async () => - { - var maxAttempts = 20; - var attempts = 0; - - while (processedMessages.Count < messageCount && attempts < maxAttempts) - { - var receiveResponse = await _localStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = queueUrl, - MaxNumberOfMessages = 5, // Process multiple messages per call - MessageAttributeNames = new List { "All" }, - WaitTimeSeconds = 1 - }); - - var processingSubTasks = receiveResponse.Messages.Select(async message => - { - // Simulate processing time - await Task.Delay(System.Random.Shared.Next(10, 50)); - - var messageIndex = int.Parse(message.MessageAttributes["MessageIndex"].StringValue); - processedMessages.Add((currentProcessorId, message.Body, messageIndex)); - - // Delete message after processing - await _localStack.SqsClient.DeleteMessageAsync(new DeleteMessageRequest - { - QueueUrl = queueUrl, - ReceiptHandle = message.ReceiptHandle - }); - }); - - await Task.WhenAll(processingSubTasks); - attempts++; - - if (receiveResponse.Messages.Count == 0) - { - await Task.Delay(100); - } - } - })); - } - - await Task.WhenAll(processingTasks); - var processingDuration = stopwatch.Elapsed; - - // Assert - All messages should be processed - Assert.True(processedMessages.Count >= messageCount * 0.95, // Allow for some variance - $"Expected at least {messageCount * 0.95} processed messages, got {processedMessages.Count}"); - - // Verify concurrent processing occurred - var messagesByProcessor = processedMessages - .GroupBy(m => m.ProcessorId) - .ToDictionary(g => g.Key, g => g.Count()); - - Assert.True(messagesByProcessor.Count > 1, "Messages should be processed by multiple processors"); - - // Verify no duplicate processing (each message index should appear only once) - var messageIndices = processedMessages.Select(m => m.MessageIndex).ToList(); - var uniqueIndices = messageIndices.Distinct().ToList(); - Assert.Equal(uniqueIndices.Count, messageIndices.Count); - - var processingThroughput = processedMessages.Count / processingDuration.TotalSeconds; - Assert.True(processingThroughput > 0, $"Processing throughput: {processingThroughput:F2} messages/second"); - } - - [Fact] - public async Task StandardQueue_ShouldValidatePerformanceCharacteristics() - { - // Skip if not configured for integration tests or performance tests - if (!_localStack.Configuration.RunIntegrationTests || - !_localStack.Configuration.RunPerformanceTests || - _localStack.SqsClient == null) - { - return; - } - - // Arrange - var queueName = $"test-standard-performance-{Guid.NewGuid():N}"; - var queueUrl = await CreateStandardQueueAsync(queueName); - - var messageSizes = new[] { 1024, 4096, 16384, 65536 }; // 1KB, 4KB, 16KB, 64KB - var messagesPerSize = 20; - - var performanceResults = new List<(int MessageSize, double SendLatency, double ReceiveLatency, double Throughput)>(); - - foreach (var messageSize in messageSizes) - { - // Generate test message of specified size - var messageBody = new string('A', messageSize); - var messageIds = new List(); - - // Measure send performance - var sendStopwatch = Stopwatch.StartNew(); - var sendTasks = new List>(); - - for (int i = 0; i < messagesPerSize; i++) - { - var messageId = Guid.NewGuid().ToString(); - messageIds.Add(messageId); - - sendTasks.Add(_localStack.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = queueUrl, - MessageBody = messageBody, - MessageAttributes = new Dictionary - { - ["MessageId"] = new MessageAttributeValue - { - DataType = "String", - StringValue = messageId - }, - ["MessageSize"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = messageSize.ToString() - }, - ["SendTime"] = new MessageAttributeValue - { - DataType = "String", - StringValue = DateTime.UtcNow.ToString("O") - } - } - })); - } - - await Task.WhenAll(sendTasks); - var sendDuration = sendStopwatch.Elapsed; - var avgSendLatency = sendDuration.TotalMilliseconds / messagesPerSize; - - // Measure receive performance - var receivedMessages = new List(); - var receiveStopwatch = Stopwatch.StartNew(); - var maxAttempts = 15; - var attempts = 0; - - while (receivedMessages.Count < messagesPerSize && attempts < maxAttempts) - { - var receiveResponse = await _localStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = queueUrl, - MaxNumberOfMessages = 10, - MessageAttributeNames = new List { "All" }, - WaitTimeSeconds = 1 - }); - - foreach (var message in receiveResponse.Messages) - { - if (message.MessageAttributes.ContainsKey("MessageSize") && - message.MessageAttributes["MessageSize"].StringValue == messageSize.ToString()) - { - receivedMessages.Add(message); - - // Delete message - await _localStack.SqsClient.DeleteMessageAsync(new DeleteMessageRequest - { - QueueUrl = queueUrl, - ReceiptHandle = message.ReceiptHandle - }); - } - } - - attempts++; - } - - var receiveDuration = receiveStopwatch.Elapsed; - var avgReceiveLatency = receiveDuration.TotalMilliseconds / receivedMessages.Count; - var throughput = receivedMessages.Count / receiveDuration.TotalSeconds; - - performanceResults.Add((messageSize, avgSendLatency, avgReceiveLatency, throughput)); - - // Assert - Should receive all messages - Assert.True(receivedMessages.Count >= messagesPerSize * 0.9, - $"Expected at least {messagesPerSize * 0.9} messages for size {messageSize}, got {receivedMessages.Count}"); - } - - // Assert - Performance should be reasonable and consistent - foreach (var result in performanceResults) - { - Assert.True(result.SendLatency > 0, $"Send latency should be positive for {result.MessageSize} byte messages"); - Assert.True(result.ReceiveLatency > 0, $"Receive latency should be positive for {result.MessageSize} byte messages"); - Assert.True(result.Throughput > 0, $"Throughput should be positive for {result.MessageSize} byte messages"); - - // Log performance metrics for analysis - Console.WriteLine($"Message Size: {result.MessageSize} bytes, " + - $"Send Latency: {result.SendLatency:F2}ms, " + - $"Receive Latency: {result.ReceiveLatency:F2}ms, " + - $"Throughput: {result.Throughput:F2} msg/sec"); - } - - // Performance should generally degrade with larger message sizes (but this is informational) - var smallMessageThroughput = performanceResults.First().Throughput; - var largeMessageThroughput = performanceResults.Last().Throughput; - - // This is informational - actual performance depends on LocalStack vs real AWS - Assert.True(smallMessageThroughput > 0 && largeMessageThroughput > 0, - "Both small and large message throughput should be positive"); - } - - [Fact] - public async Task StandardQueue_ShouldHandleMessageAttributesCorrectly() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.SqsClient == null) - { - return; - } - - // Arrange - var queueName = $"test-standard-attributes-{Guid.NewGuid():N}"; - var queueUrl = await CreateStandardQueueAsync(queueName); - - var testData = new - { - OrderId = Guid.NewGuid(), - CustomerId = 12345, - Amount = 99.99m, - Items = new[] { "Item1", "Item2", "Item3" } - }; - - var messageAttributes = new Dictionary - { - ["EntityId"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = "12345" - }, - ["SequenceNo"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = "42" - }, - ["CommandType"] = new MessageAttributeValue - { - DataType = "String", - StringValue = "CreateOrderCommand" - }, - ["PayloadType"] = new MessageAttributeValue - { - DataType = "String", - StringValue = "CreateOrderPayload" - }, - ["CorrelationId"] = new MessageAttributeValue - { - DataType = "String", - StringValue = Guid.NewGuid().ToString() - }, - ["Priority"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = "5" - }, - ["IsUrgent"] = new MessageAttributeValue - { - DataType = "String", - StringValue = "true" - }, - ["ProcessingHints"] = new MessageAttributeValue - { - DataType = "String", - StringValue = JsonSerializer.Serialize(new { Timeout = 30, RetryCount = 3 }) - } - }; - - // Act - Send message with comprehensive attributes - var sendResponse = await _localStack.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = queueUrl, - MessageBody = JsonSerializer.Serialize(testData), - MessageAttributes = messageAttributes - }); - - Assert.NotNull(sendResponse.MessageId); - - // Act - Receive message and validate attributes - var receiveResponse = await _localStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = queueUrl, - MaxNumberOfMessages = 1, - MessageAttributeNames = new List { "All" }, - WaitTimeSeconds = 2 - }); - - // Assert - Message and all attributes should be preserved - Assert.Single(receiveResponse.Messages); - var message = receiveResponse.Messages[0]; - - // Validate message body - var receivedData = JsonSerializer.Deserialize>(message.Body); - Assert.NotNull(receivedData); - Assert.True(receivedData.ContainsKey("OrderId")); - Assert.True(receivedData.ContainsKey("CustomerId")); - Assert.True(receivedData.ContainsKey("Amount")); - - // Validate all message attributes - Assert.Equal(messageAttributes.Count, message.MessageAttributes.Count); - - foreach (var expectedAttr in messageAttributes) - { - Assert.True(message.MessageAttributes.ContainsKey(expectedAttr.Key), - $"Missing attribute: {expectedAttr.Key}"); - - var receivedAttr = message.MessageAttributes[expectedAttr.Key]; - Assert.Equal(expectedAttr.Value.DataType, receivedAttr.DataType); - Assert.Equal(expectedAttr.Value.StringValue, receivedAttr.StringValue); - } - - // Validate specific SourceFlow attributes - Assert.Equal("12345", message.MessageAttributes["EntityId"].StringValue); - Assert.Equal("42", message.MessageAttributes["SequenceNo"].StringValue); - Assert.Equal("CreateOrderCommand", message.MessageAttributes["CommandType"].StringValue); - Assert.Equal("CreateOrderPayload", message.MessageAttributes["PayloadType"].StringValue); - - // Clean up - await _localStack.SqsClient.DeleteMessageAsync(new DeleteMessageRequest - { - QueueUrl = queueUrl, - ReceiptHandle = message.ReceiptHandle - }); - } - - [Fact] - public async Task StandardQueue_ShouldSupportLongPolling() - { - // Skip if not configured for integration tests - if (!_localStack.Configuration.RunIntegrationTests || _localStack.SqsClient == null) - { - return; - } - - // Arrange - var queueName = $"test-standard-long-polling-{Guid.NewGuid():N}"; - var queueUrl = await CreateStandardQueueAsync(queueName, new Dictionary - { - ["ReceiveMessageWaitTimeSeconds"] = "10" // Enable long polling - }); - - var messageBody = $"Long polling test message - {Guid.NewGuid()}"; - - // Act - Start long polling receive (should wait for message) - var receiveTask = Task.Run(async () => - { - var stopwatch = Stopwatch.StartNew(); - var receiveResponse = await _localStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = queueUrl, - MaxNumberOfMessages = 1, - WaitTimeSeconds = 5, // Long poll for 5 seconds - MessageAttributeNames = new List { "All" } - }); - stopwatch.Stop(); - - return (Messages: receiveResponse.Messages, WaitTime: stopwatch.Elapsed); - }); - - // Wait a moment, then send a message - await Task.Delay(2000); - - var sendResponse = await _localStack.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = queueUrl, - MessageBody = messageBody, - MessageAttributes = new Dictionary - { - ["SendTime"] = new MessageAttributeValue - { - DataType = "String", - StringValue = DateTime.UtcNow.ToString("O") - } - } - }); - - // Wait for receive to complete - var result = await receiveTask; - - // Assert - Should receive the message - Assert.Single(result.Messages); - Assert.Equal(messageBody, result.Messages[0].Body); - - // Long polling should have waited at least 2 seconds (when we sent the message) - Assert.True(result.WaitTime.TotalSeconds >= 1.5, - $"Long polling should have waited, actual wait time: {result.WaitTime.TotalSeconds:F2} seconds"); - - // Clean up - await _localStack.SqsClient.DeleteMessageAsync(new DeleteMessageRequest - { - QueueUrl = queueUrl, - ReceiptHandle = result.Messages[0].ReceiptHandle - }); - } - - /// - /// Create a standard queue with the specified name and attributes - /// - private async Task CreateStandardQueueAsync(string queueName, Dictionary? additionalAttributes = null) - { - var attributes = new Dictionary - { - ["MessageRetentionPeriod"] = "1209600", // 14 days - ["VisibilityTimeout"] = "30", - ["ReceiveMessageWaitTimeSeconds"] = "0" // Short polling by default - }; - - if (additionalAttributes != null) - { - foreach (var attr in additionalAttributes) - { - attributes[attr.Key] = attr.Value; - } - } - - var response = await _localStack.SqsClient.CreateQueueAsync(new CreateQueueRequest - { - QueueName = queueName, - Attributes = attributes - }); - - _createdQueues.Add(response.QueueUrl); - return response.QueueUrl; - } - - /// - /// Clean up created queues - /// - public async ValueTask DisposeAsync() - { - if (_localStack.SqsClient != null) - { - foreach (var queueUrl in _createdQueues) - { - try - { - await _localStack.SqsClient.DeleteQueueAsync(new DeleteQueueRequest - { - QueueUrl = queueUrl - }); - } - catch (Exception) - { - // Ignore cleanup errors - } - } - } - - _createdQueues.Clear(); - } -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/Performance/AwsScalabilityBenchmarks.cs b/tests/SourceFlow.Cloud.AWS.Tests/Performance/AwsScalabilityBenchmarks.cs deleted file mode 100644 index 4292aa2d..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/Performance/AwsScalabilityBenchmarks.cs +++ /dev/null @@ -1,795 +0,0 @@ -using System.Diagnostics; -using System.Text; -using Amazon.SQS.Model; -using Amazon.SimpleNotificationService.Model; -using BenchmarkDotNet.Attributes; -using SourceFlow.Cloud.AWS.Tests.TestHelpers; -using SnsMessageAttributeValue = Amazon.SimpleNotificationService.Model.MessageAttributeValue; -using SqsMessageAttributeValue = Amazon.SQS.Model.MessageAttributeValue; - -namespace SourceFlow.Cloud.AWS.Tests.Performance; - -/// -/// Comprehensive scalability benchmarks for AWS services -/// Validates Requirements 5.4, 5.5 - Resource utilization and scalability testing -/// -/// This benchmark suite provides comprehensive scalability testing for: -/// - Performance under increasing concurrent connections -/// - Resource utilization (memory, CPU, network) under load -/// - Performance scaling characteristics -/// - AWS service limit impact on performance -/// - Combined SQS and SNS scalability scenarios -/// -[MemoryDiagnoser] -[ThreadingDiagnoser] -[SimpleJob(warmupCount: 2, iterationCount: 3)] -[Trait("Category", "Integration")] -[Trait("Category", "RequiresLocalStack")] -public class AwsScalabilityBenchmarks : PerformanceBenchmarkBase -{ - private readonly List _standardQueueUrls = new(); - private readonly List _fifoQueueUrls = new(); - private readonly List _topicArns = new(); - private readonly List _subscriberQueueUrls = new(); - - // Scalability test parameters - [Params(1, 5, 10, 20)] - public int ConcurrentConnections { get; set; } - - [Params(100, 500, 1000)] - public int MessagesPerConnection { get; set; } - - [Params(256, 1024)] - public int MessageSizeBytes { get; set; } - - [Params(1, 3, 5)] - public int ResourceCount { get; set; } - - [GlobalSetup] - public override async Task GlobalSetup() - { - await base.GlobalSetup(); - - if (LocalStack?.SqsClient != null && LocalStack?.SnsClient != null && LocalStack.Configuration.RunPerformanceTests) - { - // Create multiple standard queues for scalability testing - for (int i = 0; i < ResourceCount; i++) - { - var standardQueueName = $"scale-test-standard-{i}-{Guid.NewGuid():N}"; - var standardResponse = await LocalStack.SqsClient.CreateQueueAsync(new CreateQueueRequest - { - QueueName = standardQueueName, - Attributes = new Dictionary - { - ["MessageRetentionPeriod"] = "3600", - ["VisibilityTimeout"] = "30" - } - }); - _standardQueueUrls.Add(standardResponse.QueueUrl); - - // Create FIFO queues - var fifoQueueName = $"scale-test-fifo-{i}-{Guid.NewGuid():N}.fifo"; - var fifoResponse = await LocalStack.SqsClient.CreateQueueAsync(new CreateQueueRequest - { - QueueName = fifoQueueName, - Attributes = new Dictionary - { - ["FifoQueue"] = "true", - ["ContentBasedDeduplication"] = "true", - ["MessageRetentionPeriod"] = "3600", - ["VisibilityTimeout"] = "30" - } - }); - _fifoQueueUrls.Add(fifoResponse.QueueUrl); - - // Create SNS topics - var topicName = $"scale-test-topic-{i}-{Guid.NewGuid():N}"; - var topicResponse = await LocalStack.SnsClient.CreateTopicAsync(new CreateTopicRequest - { - Name = topicName - }); - _topicArns.Add(topicResponse.TopicArn); - - // Create subscriber queues for each topic - var subscriberQueueName = $"scale-test-subscriber-{i}-{Guid.NewGuid():N}"; - var subscriberResponse = await LocalStack.SqsClient.CreateQueueAsync(new CreateQueueRequest - { - QueueName = subscriberQueueName, - Attributes = new Dictionary - { - ["MessageRetentionPeriod"] = "3600", - ["VisibilityTimeout"] = "30" - } - }); - _subscriberQueueUrls.Add(subscriberResponse.QueueUrl); - - // Subscribe queue to topic - var queueAttributes = await LocalStack.SqsClient.GetQueueAttributesAsync(new GetQueueAttributesRequest - { - QueueUrl = subscriberResponse.QueueUrl, - AttributeNames = new List { "QueueArn" } - }); - var queueArn = queueAttributes.Attributes["QueueArn"]; - - await LocalStack.SnsClient.SubscribeAsync(new SubscribeRequest - { - TopicArn = topicResponse.TopicArn, - Protocol = "sqs", - Endpoint = queueArn - }); - } - } - } - - [GlobalCleanup] - public override async Task GlobalCleanup() - { - if (LocalStack?.SqsClient != null && LocalStack?.SnsClient != null) - { - // Clean up all queues - foreach (var queueUrl in _standardQueueUrls.Concat(_fifoQueueUrls).Concat(_subscriberQueueUrls)) - { - try - { - await LocalStack.SqsClient.DeleteQueueAsync(queueUrl); - } - catch - { - // Ignore cleanup errors - } - } - - // Clean up all topics - foreach (var topicArn in _topicArns) - { - try - { - await LocalStack.SnsClient.DeleteTopicAsync(new DeleteTopicRequest - { - TopicArn = topicArn - }); - } - catch - { - // Ignore cleanup errors - } - } - } - - await base.GlobalCleanup(); - } - - /// - /// Benchmark: SQS scalability with increasing concurrent connections - /// Measures throughput and resource utilization as connections increase - /// - [Benchmark(Description = "SQS Scalability - Increasing Concurrent Connections")] - public async Task SqsScalabilityWithConcurrentConnections() - { - if (LocalStack?.SqsClient == null || _standardQueueUrls.Count == 0) - return; - - var messageBody = GenerateMessageBody(MessageSizeBytes); - var queueUrl = _standardQueueUrls[0]; - - // Create concurrent tasks that send messages - var tasks = Enumerable.Range(0, ConcurrentConnections) - .Select(async connectionId => - { - for (int i = 0; i < MessagesPerConnection; i++) - { - await LocalStack.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = queueUrl, - MessageBody = messageBody, - MessageAttributes = new Dictionary - { - ["ConnectionId"] = new SqsMessageAttributeValue - { - DataType = "Number", - StringValue = connectionId.ToString() - }, - ["MessageIndex"] = new SqsMessageAttributeValue - { - DataType = "Number", - StringValue = i.ToString() - } - } - }); - } - }); - - await Task.WhenAll(tasks); - } - - /// - /// Benchmark: SNS scalability with increasing concurrent connections - /// Measures publish throughput and fan-out performance as connections increase - /// - [Benchmark(Description = "SNS Scalability - Increasing Concurrent Connections")] - public async Task SnsScalabilityWithConcurrentConnections() - { - if (LocalStack?.SnsClient == null || _topicArns.Count == 0) - return; - - var messageBody = GenerateMessageBody(MessageSizeBytes); - var topicArn = _topicArns[0]; - - // Create concurrent tasks that publish messages - var tasks = Enumerable.Range(0, ConcurrentConnections) - .Select(async connectionId => - { - for (int i = 0; i < MessagesPerConnection; i++) - { - await LocalStack.SnsClient.PublishAsync(new PublishRequest - { - TopicArn = topicArn, - Message = messageBody, - MessageAttributes = new Dictionary - { - ["ConnectionId"] = new SnsMessageAttributeValue - { - DataType = "Number", - StringValue = connectionId.ToString() - }, - ["MessageIndex"] = new SnsMessageAttributeValue - { - DataType = "Number", - StringValue = i.ToString() - } - } - }); - } - }); - - await Task.WhenAll(tasks); - } - - /// - /// Benchmark: Multi-queue scalability with load distribution - /// Measures performance when distributing load across multiple queues - /// - [Benchmark(Description = "SQS Multi-Queue - Load Distribution Scalability")] - public async Task SqsMultiQueueLoadDistribution() - { - if (LocalStack?.SqsClient == null || _standardQueueUrls.Count == 0) - return; - - var messageBody = GenerateMessageBody(MessageSizeBytes); - - // Distribute connections across available queues - var tasks = Enumerable.Range(0, ConcurrentConnections) - .Select(async connectionId => - { - var queueUrl = _standardQueueUrls[connectionId % _standardQueueUrls.Count]; - - for (int i = 0; i < MessagesPerConnection; i++) - { - await LocalStack.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = queueUrl, - MessageBody = messageBody, - MessageAttributes = new Dictionary - { - ["ConnectionId"] = new SqsMessageAttributeValue - { - DataType = "Number", - StringValue = connectionId.ToString() - }, - ["QueueIndex"] = new SqsMessageAttributeValue - { - DataType = "Number", - StringValue = (connectionId % _standardQueueUrls.Count).ToString() - } - } - }); - } - }); - - await Task.WhenAll(tasks); - } - - /// - /// Benchmark: Multi-topic scalability with load distribution - /// Measures performance when distributing load across multiple topics - /// - [Benchmark(Description = "SNS Multi-Topic - Load Distribution Scalability")] - public async Task SnsMultiTopicLoadDistribution() - { - if (LocalStack?.SnsClient == null || _topicArns.Count == 0) - return; - - var messageBody = GenerateMessageBody(MessageSizeBytes); - - // Distribute connections across available topics - var tasks = Enumerable.Range(0, ConcurrentConnections) - .Select(async connectionId => - { - var topicArn = _topicArns[connectionId % _topicArns.Count]; - - for (int i = 0; i < MessagesPerConnection; i++) - { - await LocalStack.SnsClient.PublishAsync(new PublishRequest - { - TopicArn = topicArn, - Message = messageBody, - MessageAttributes = new Dictionary - { - ["ConnectionId"] = new SnsMessageAttributeValue - { - DataType = "Number", - StringValue = connectionId.ToString() - }, - ["TopicIndex"] = new SnsMessageAttributeValue - { - DataType = "Number", - StringValue = (connectionId % _topicArns.Count).ToString() - } - } - }); - } - }); - - await Task.WhenAll(tasks); - } - - /// - /// Benchmark: FIFO queue scalability with multiple message groups - /// Measures FIFO performance with parallel message groups - /// - [Benchmark(Description = "FIFO Queue - Message Group Scalability")] - public async Task FifoQueueMessageGroupScalability() - { - if (LocalStack?.SqsClient == null || _fifoQueueUrls.Count == 0) - return; - - var messageBody = GenerateMessageBody(MessageSizeBytes); - var queueUrl = _fifoQueueUrls[0]; - - // Each connection uses its own message group for parallel processing - var tasks = Enumerable.Range(0, ConcurrentConnections) - .Select(async connectionId => - { - var messageGroupId = $"group-{connectionId}"; - - for (int i = 0; i < MessagesPerConnection; i++) - { - await LocalStack.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = queueUrl, - MessageBody = messageBody, - MessageGroupId = messageGroupId, - MessageDeduplicationId = $"conn-{connectionId}-msg-{i}-{Guid.NewGuid():N}", - MessageAttributes = new Dictionary - { - ["ConnectionId"] = new SqsMessageAttributeValue - { - DataType = "Number", - StringValue = connectionId.ToString() - }, - ["MessageGroupId"] = new SqsMessageAttributeValue - { - DataType = "String", - StringValue = messageGroupId - } - } - }); - } - }); - - await Task.WhenAll(tasks); - } - - /// - /// Benchmark: Combined SQS and SNS scalability - /// Measures end-to-end scalability with SNS publishing and SQS consumption - /// - [Benchmark(Description = "Combined SQS+SNS - End-to-End Scalability")] - public async Task CombinedSqsSnsScalability() - { - if (LocalStack?.SnsClient == null || LocalStack?.SqsClient == null || - _topicArns.Count == 0 || _subscriberQueueUrls.Count == 0) - return; - - var messageBody = GenerateMessageBody(MessageSizeBytes); - var messagesPerConnection = Math.Min(MessagesPerConnection, 50); // Limit for combined test - - // Publish messages concurrently to topics - var publishTasks = Enumerable.Range(0, ConcurrentConnections) - .Select(async connectionId => - { - var topicArn = _topicArns[connectionId % _topicArns.Count]; - - for (int i = 0; i < messagesPerConnection; i++) - { - await LocalStack.SnsClient.PublishAsync(new PublishRequest - { - TopicArn = topicArn, - Message = messageBody, - MessageAttributes = new Dictionary - { - ["ConnectionId"] = new SnsMessageAttributeValue - { - DataType = "Number", - StringValue = connectionId.ToString() - }, - ["MessageIndex"] = new SnsMessageAttributeValue - { - DataType = "Number", - StringValue = i.ToString() - } - } - }); - } - }); - - await Task.WhenAll(publishTasks); - - // Wait for message propagation - await Task.Delay(1000); - - // Receive messages concurrently from subscriber queues - var receiveTasks = _subscriberQueueUrls.Select(async queueUrl => - { - var receivedCount = 0; - var maxAttempts = 10; - var attempts = 0; - - while (attempts < maxAttempts) - { - var response = await LocalStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = queueUrl, - MaxNumberOfMessages = 10, - WaitTimeSeconds = 1 - }); - - if (response.Messages.Count > 0) - { - // Delete received messages - var deleteTasks = response.Messages.Select(msg => - LocalStack.SqsClient.DeleteMessageAsync(new DeleteMessageRequest - { - QueueUrl = queueUrl, - ReceiptHandle = msg.ReceiptHandle - })); - - await Task.WhenAll(deleteTasks); - receivedCount += response.Messages.Count; - } - else if (receivedCount > 0) - { - break; - } - - attempts++; - } - - return receivedCount; - }); - - await Task.WhenAll(receiveTasks); - } - - /// - /// Benchmark: Batch operations scalability - /// Measures scalability of batch send operations with concurrent connections - /// - [Benchmark(Description = "SQS Batch - Concurrent Batch Operations Scalability")] - public async Task SqsBatchOperationsScalability() - { - if (LocalStack?.SqsClient == null || _standardQueueUrls.Count == 0) - return; - - var messageBody = GenerateMessageBody(MessageSizeBytes); - var queueUrl = _standardQueueUrls[0]; - var batchSize = 10; // AWS SQS batch limit - var batchesPerConnection = MessagesPerConnection / batchSize; - - // Create concurrent tasks that send batches - var tasks = Enumerable.Range(0, ConcurrentConnections) - .Select(async connectionId => - { - for (int batch = 0; batch < batchesPerConnection; batch++) - { - var entries = new List(); - - for (int i = 0; i < batchSize; i++) - { - entries.Add(new SendMessageBatchRequestEntry - { - Id = i.ToString(), - MessageBody = messageBody, - MessageAttributes = new Dictionary - { - ["ConnectionId"] = new SqsMessageAttributeValue - { - DataType = "Number", - StringValue = connectionId.ToString() - }, - ["BatchIndex"] = new SqsMessageAttributeValue - { - DataType = "Number", - StringValue = batch.ToString() - } - } - }); - } - - await LocalStack.SqsClient.SendMessageBatchAsync(new SendMessageBatchRequest - { - QueueUrl = queueUrl, - Entries = entries - }); - } - }); - - await Task.WhenAll(tasks); - } - - /// - /// Benchmark: Concurrent receive operations scalability - /// Measures scalability of message consumption with multiple concurrent receivers - /// - [Benchmark(Description = "SQS Receive - Concurrent Receivers Scalability")] - public async Task SqsConcurrentReceiversScalability() - { - if (LocalStack?.SqsClient == null || _standardQueueUrls.Count == 0) - return; - - var queueUrl = _standardQueueUrls[0]; - var messageBody = GenerateMessageBody(MessageSizeBytes); - var totalMessages = ConcurrentConnections * MessagesPerConnection; - - // First, populate the queue with messages - var populateTasks = Enumerable.Range(0, totalMessages) - .Select(i => LocalStack.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = queueUrl, - MessageBody = messageBody, - MessageAttributes = new Dictionary - { - ["MessageIndex"] = new SqsMessageAttributeValue - { - DataType = "Number", - StringValue = i.ToString() - } - } - })); - - await Task.WhenAll(populateTasks); - - // Now receive messages concurrently - var messagesPerReceiver = totalMessages / ConcurrentConnections; - var receiveTasks = Enumerable.Range(0, ConcurrentConnections) - .Select(async receiverId => - { - var receivedCount = 0; - - while (receivedCount < messagesPerReceiver) - { - var response = await LocalStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = queueUrl, - MaxNumberOfMessages = 10, - WaitTimeSeconds = 1 - }); - - if (response.Messages.Count > 0) - { - // Delete received messages - var deleteTasks = response.Messages.Select(msg => - LocalStack.SqsClient.DeleteMessageAsync(new DeleteMessageRequest - { - QueueUrl = queueUrl, - ReceiptHandle = msg.ReceiptHandle - })); - - await Task.WhenAll(deleteTasks); - receivedCount += response.Messages.Count; - } - else - { - break; // No more messages available - } - } - - return receivedCount; - }); - - await Task.WhenAll(receiveTasks); - } - - /// - /// Benchmark: Message size impact on scalability - /// Measures how message size affects throughput with concurrent connections - /// - [Benchmark(Description = "SQS Scalability - Message Size Impact")] - public async Task SqsMessageSizeScalabilityImpact() - { - if (LocalStack?.SqsClient == null || _standardQueueUrls.Count == 0) - return; - - var messageBody = GenerateMessageBody(MessageSizeBytes); - var queueUrl = _standardQueueUrls[0]; - - // Test with varying message sizes and concurrent connections - var tasks = Enumerable.Range(0, ConcurrentConnections) - .Select(async connectionId => - { - for (int i = 0; i < MessagesPerConnection; i++) - { - await LocalStack.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = queueUrl, - MessageBody = messageBody, - MessageAttributes = new Dictionary - { - ["ConnectionId"] = new SqsMessageAttributeValue - { - DataType = "Number", - StringValue = connectionId.ToString() - }, - ["MessageSize"] = new SqsMessageAttributeValue - { - DataType = "Number", - StringValue = MessageSizeBytes.ToString() - } - } - }); - } - }); - - await Task.WhenAll(tasks); - } - - /// - /// Benchmark: Resource count impact on scalability - /// Measures how the number of queues/topics affects overall throughput - /// - [Benchmark(Description = "Multi-Resource - Resource Count Scalability Impact")] - public async Task MultiResourceScalabilityImpact() - { - if (LocalStack?.SqsClient == null || _standardQueueUrls.Count == 0) - return; - - var messageBody = GenerateMessageBody(MessageSizeBytes); - - // Distribute connections evenly across all available queues - var tasks = Enumerable.Range(0, ConcurrentConnections) - .Select(async connectionId => - { - var queueIndex = connectionId % _standardQueueUrls.Count; - var queueUrl = _standardQueueUrls[queueIndex]; - - for (int i = 0; i < MessagesPerConnection; i++) - { - await LocalStack.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = queueUrl, - MessageBody = messageBody, - MessageAttributes = new Dictionary - { - ["ConnectionId"] = new SqsMessageAttributeValue - { - DataType = "Number", - StringValue = connectionId.ToString() - }, - ["QueueIndex"] = new SqsMessageAttributeValue - { - DataType = "Number", - StringValue = queueIndex.ToString() - }, - ["ResourceCount"] = new SqsMessageAttributeValue - { - DataType = "Number", - StringValue = _standardQueueUrls.Count.ToString() - } - } - }); - } - }); - - await Task.WhenAll(tasks); - } - - /// - /// Benchmark: Mixed workload scalability - /// Measures performance with mixed send/receive operations - /// - [Benchmark(Description = "SQS Mixed - Send and Receive Scalability")] - public async Task SqsMixedWorkloadScalability() - { - if (LocalStack?.SqsClient == null || _standardQueueUrls.Count == 0) - return; - - var messageBody = GenerateMessageBody(MessageSizeBytes); - var queueUrl = _standardQueueUrls[0]; - var halfConnections = ConcurrentConnections / 2; - - // Half connections send messages - var sendTasks = Enumerable.Range(0, halfConnections) - .Select(async connectionId => - { - for (int i = 0; i < MessagesPerConnection; i++) - { - await LocalStack.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = queueUrl, - MessageBody = messageBody, - MessageAttributes = new Dictionary - { - ["ConnectionId"] = new SqsMessageAttributeValue - { - DataType = "Number", - StringValue = connectionId.ToString() - }, - ["OperationType"] = new SqsMessageAttributeValue - { - DataType = "String", - StringValue = "Send" - } - } - }); - } - }); - - // Half connections receive messages - var receiveTasks = Enumerable.Range(halfConnections, halfConnections) - .Select(async connectionId => - { - var receivedCount = 0; - var targetCount = MessagesPerConnection; - - while (receivedCount < targetCount) - { - var response = await LocalStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = queueUrl, - MaxNumberOfMessages = 10, - WaitTimeSeconds = 1 - }); - - if (response.Messages.Count > 0) - { - // Delete received messages - var deleteTasks = response.Messages.Select(msg => - LocalStack.SqsClient.DeleteMessageAsync(new DeleteMessageRequest - { - QueueUrl = queueUrl, - ReceiptHandle = msg.ReceiptHandle - })); - - await Task.WhenAll(deleteTasks); - receivedCount += response.Messages.Count; - } - else - { - // Wait a bit for more messages - await Task.Delay(100); - } - } - - return receivedCount; - }); - - // Run send and receive operations concurrently - await Task.WhenAll(sendTasks.Concat(receiveTasks)); - } - - /// - /// Helper method to generate message body of specified size - /// - private string GenerateMessageBody(int sizeBytes) - { - var sb = new StringBuilder(sizeBytes); - var random = new System.Random(); - - while (sb.Length < sizeBytes) - { - sb.Append((char)('A' + random.Next(26))); - } - - return sb.ToString(0, sizeBytes); - } -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/Performance/SnsPerformanceBenchmarks.cs b/tests/SourceFlow.Cloud.AWS.Tests/Performance/SnsPerformanceBenchmarks.cs deleted file mode 100644 index 86d516ad..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/Performance/SnsPerformanceBenchmarks.cs +++ /dev/null @@ -1,736 +0,0 @@ -using System.Diagnostics; -using System.Text; -using Amazon.SimpleNotificationService.Model; -using Amazon.SQS.Model; -using BenchmarkDotNet.Attributes; -using SourceFlow.Cloud.AWS.Tests.TestHelpers; -using SnsMessageAttributeValue = Amazon.SimpleNotificationService.Model.MessageAttributeValue; -using SqsMessageAttributeValue = Amazon.SQS.Model.MessageAttributeValue; - -namespace SourceFlow.Cloud.AWS.Tests.Performance; - -/// -/// Enhanced performance benchmarks for SNS operations -/// Validates Requirements 5.2, 5.3 - SNS throughput and end-to-end latency testing -/// -/// This benchmark suite provides comprehensive performance testing for: -/// - Event publishing rate testing -/// - Fan-out delivery performance with multiple subscribers -/// - SNS-to-SQS delivery latency -/// - Performance impact of message filtering -/// - End-to-end latency including network overhead -/// -[MemoryDiagnoser] -[SimpleJob(warmupCount: 3, iterationCount: 5)] -[Trait("Category", "Integration")] -[Trait("Category", "RequiresLocalStack")] -public class SnsPerformanceBenchmarks : PerformanceBenchmarkBase -{ - private string? _topicArn; - private readonly List _subscriberQueueUrls = new(); - private readonly List _subscriptionArns = new(); - - // Benchmark parameters - [Params(1, 5, 10)] - public int ConcurrentPublishers { get; set; } - - [Params(100, 500, 1000)] - public int MessageCount { get; set; } - - [Params(256, 1024, 4096)] - public int MessageSizeBytes { get; set; } - - [Params(1, 3, 5)] - public int SubscriberCount { get; set; } - - [GlobalSetup] - public override async Task GlobalSetup() - { - await base.GlobalSetup(); - - if (LocalStack?.SnsClient != null && LocalStack?.SqsClient != null && LocalStack.Configuration.RunPerformanceTests) - { - // Create an SNS topic for performance testing - var topicName = $"perf-test-topic-{Guid.NewGuid():N}"; - var topicResponse = await LocalStack.SnsClient.CreateTopicAsync(new CreateTopicRequest - { - Name = topicName, - Attributes = new Dictionary - { - ["DisplayName"] = "Performance Test Topic" - } - }); - _topicArn = topicResponse.TopicArn; - - // Create SQS queues as subscribers - for (int i = 0; i < SubscriberCount; i++) - { - var queueName = $"perf-test-subscriber-{i}-{Guid.NewGuid():N}"; - var queueResponse = await LocalStack.SqsClient.CreateQueueAsync(new CreateQueueRequest - { - QueueName = queueName, - Attributes = new Dictionary - { - ["MessageRetentionPeriod"] = "3600", // 1 hour - ["VisibilityTimeout"] = "30" - } - }); - _subscriberQueueUrls.Add(queueResponse.QueueUrl); - - // Get queue ARN for subscription - var queueAttributes = await LocalStack.SqsClient.GetQueueAttributesAsync(new GetQueueAttributesRequest - { - QueueUrl = queueResponse.QueueUrl, - AttributeNames = new List { "QueueArn" } - }); - var queueArn = queueAttributes.Attributes["QueueArn"]; - - // Subscribe queue to topic - var subscriptionResponse = await LocalStack.SnsClient.SubscribeAsync(new SubscribeRequest - { - TopicArn = _topicArn, - Protocol = "sqs", - Endpoint = queueArn - }); - _subscriptionArns.Add(subscriptionResponse.SubscriptionArn); - } - } - } - - [GlobalCleanup] - public override async Task GlobalCleanup() - { - if (LocalStack?.SnsClient != null && LocalStack?.SqsClient != null) - { - // Unsubscribe all subscriptions - foreach (var subscriptionArn in _subscriptionArns) - { - try - { - await LocalStack.SnsClient.UnsubscribeAsync(new UnsubscribeRequest - { - SubscriptionArn = subscriptionArn - }); - } - catch - { - // Ignore cleanup errors - } - } - - // Delete all subscriber queues - foreach (var queueUrl in _subscriberQueueUrls) - { - try - { - await LocalStack.SqsClient.DeleteQueueAsync(queueUrl); - } - catch - { - // Ignore cleanup errors - } - } - - // Delete the topic - if (!string.IsNullOrEmpty(_topicArn)) - { - try - { - await LocalStack.SnsClient.DeleteTopicAsync(new DeleteTopicRequest - { - TopicArn = _topicArn - }); - } - catch - { - // Ignore cleanup errors - } - } - } - - await base.GlobalCleanup(); - } - - /// - /// Benchmark: Event publishing rate with single publisher - /// Measures messages per second for SNS topic publishing - /// - [Benchmark(Description = "SNS Topic - Single Publisher Throughput")] - public async Task SnsTopicSinglePublisherThroughput() - { - if (LocalStack?.SnsClient == null || string.IsNullOrEmpty(_topicArn)) - return; - - var messageBody = GenerateMessageBody(MessageSizeBytes); - - for (int i = 0; i < MessageCount; i++) - { - await LocalStack.SnsClient.PublishAsync(new PublishRequest - { - TopicArn = _topicArn, - Message = messageBody, - MessageAttributes = new Dictionary - { - ["MessageIndex"] = new SnsMessageAttributeValue - { - DataType = "Number", - StringValue = i.ToString() - } - } - }); - } - } - - /// - /// Benchmark: Event publishing rate with concurrent publishers - /// Measures messages per second with multiple concurrent publishers - /// - [Benchmark(Description = "SNS Topic - Concurrent Publishers Throughput")] - public async Task SnsTopicConcurrentPublishersThroughput() - { - if (LocalStack?.SnsClient == null || string.IsNullOrEmpty(_topicArn)) - return; - - var messageBody = GenerateMessageBody(MessageSizeBytes); - var messagesPerPublisher = MessageCount / ConcurrentPublishers; - - var tasks = Enumerable.Range(0, ConcurrentPublishers) - .Select(async publisherId => - { - for (int i = 0; i < messagesPerPublisher; i++) - { - await LocalStack.SnsClient.PublishAsync(new PublishRequest - { - TopicArn = _topicArn, - Message = messageBody, - MessageAttributes = new Dictionary - { - ["PublisherId"] = new SnsMessageAttributeValue - { - DataType = "Number", - StringValue = publisherId.ToString() - }, - ["MessageIndex"] = new SnsMessageAttributeValue - { - DataType = "Number", - StringValue = i.ToString() - } - } - }); - } - }); - - await Task.WhenAll(tasks); - } - - /// - /// Benchmark: Fan-out delivery performance with multiple subscribers - /// Measures SNS-to-SQS delivery latency and fan-out efficiency - /// - [Benchmark(Description = "SNS Fan-Out - Multiple Subscribers Delivery")] - public async Task SnsFanOutDeliveryPerformance() - { - if (LocalStack?.SnsClient == null || LocalStack?.SqsClient == null || - string.IsNullOrEmpty(_topicArn) || _subscriberQueueUrls.Count == 0) - return; - - var messageBody = GenerateMessageBody(MessageSizeBytes); - var publishCount = Math.Min(MessageCount, 100); // Limit for fan-out test - - // Publish messages to topic - for (int i = 0; i < publishCount; i++) - { - await LocalStack.SnsClient.PublishAsync(new PublishRequest - { - TopicArn = _topicArn, - Message = messageBody, - MessageAttributes = new Dictionary - { - ["MessageId"] = new SnsMessageAttributeValue - { - DataType = "String", - StringValue = Guid.NewGuid().ToString() - }, - ["Timestamp"] = new SnsMessageAttributeValue - { - DataType = "Number", - StringValue = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds().ToString() - } - } - }); - } - - // Wait a bit for message propagation - await Task.Delay(1000); - - // Verify delivery to all subscribers - var receiveTasks = _subscriberQueueUrls.Select(async queueUrl => - { - var receivedCount = 0; - var maxAttempts = 10; - var attempts = 0; - - while (receivedCount < publishCount && attempts < maxAttempts) - { - var response = await LocalStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = queueUrl, - MaxNumberOfMessages = 10, - WaitTimeSeconds = 1, - MessageAttributeNames = new List { "All" } - }); - - if (response.Messages.Count > 0) - { - // Delete received messages - var deleteTasks = response.Messages.Select(msg => - LocalStack.SqsClient.DeleteMessageAsync(new DeleteMessageRequest - { - QueueUrl = queueUrl, - ReceiptHandle = msg.ReceiptHandle - })); - - await Task.WhenAll(deleteTasks); - receivedCount += response.Messages.Count; - } - - attempts++; - } - - return receivedCount; - }); - - await Task.WhenAll(receiveTasks); - } - - /// - /// Benchmark: SNS-to-SQS delivery latency - /// Measures end-to-end latency from SNS publish to SQS receive - /// - [Benchmark(Description = "SNS-to-SQS - End-to-End Delivery Latency")] - public async Task SnsToSqsDeliveryLatency() - { - if (LocalStack?.SnsClient == null || LocalStack?.SqsClient == null || - string.IsNullOrEmpty(_topicArn) || _subscriberQueueUrls.Count == 0) - return; - - var messageBody = GenerateMessageBody(MessageSizeBytes); - var queueUrl = _subscriberQueueUrls[0]; // Use first subscriber - - // Publish message with timestamp - var publishTimestamp = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds(); - await LocalStack.SnsClient.PublishAsync(new PublishRequest - { - TopicArn = _topicArn, - Message = messageBody, - MessageAttributes = new Dictionary - { - ["PublishTimestamp"] = new SnsMessageAttributeValue - { - DataType = "Number", - StringValue = publishTimestamp.ToString() - }, - ["MessageId"] = new SnsMessageAttributeValue - { - DataType = "String", - StringValue = Guid.NewGuid().ToString() - } - } - }); - - // Receive message from subscriber queue - var maxAttempts = 10; - var attempts = 0; - - while (attempts < maxAttempts) - { - var response = await LocalStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = queueUrl, - MaxNumberOfMessages = 1, - WaitTimeSeconds = 2, - MessageAttributeNames = new List { "All" } - }); - - if (response.Messages.Count > 0) - { - var message = response.Messages[0]; - - // Delete message - await LocalStack.SqsClient.DeleteMessageAsync(new DeleteMessageRequest - { - QueueUrl = queueUrl, - ReceiptHandle = message.ReceiptHandle - }); - - break; - } - - attempts++; - } - } - - /// - /// Benchmark: Message filtering performance impact - /// Measures the performance overhead of SNS message filtering - /// - [Benchmark(Description = "SNS Filtering - Performance Impact")] - public async Task SnsMessageFilteringPerformanceImpact() - { - if (LocalStack?.SnsClient == null || LocalStack?.SqsClient == null || - string.IsNullOrEmpty(_topicArn)) - return; - - // Create a filtered subscription - var filterQueueName = $"perf-test-filtered-{Guid.NewGuid():N}"; - var filterQueueResponse = await LocalStack.SqsClient.CreateQueueAsync(new CreateQueueRequest - { - QueueName = filterQueueName, - Attributes = new Dictionary - { - ["MessageRetentionPeriod"] = "3600", - ["VisibilityTimeout"] = "30" - } - }); - var filterQueueUrl = filterQueueResponse.QueueUrl; - - try - { - // Get queue ARN - var queueAttributes = await LocalStack.SqsClient.GetQueueAttributesAsync(new GetQueueAttributesRequest - { - QueueUrl = filterQueueUrl, - AttributeNames = new List { "QueueArn" } - }); - var queueArn = queueAttributes.Attributes["QueueArn"]; - - // Subscribe with filter policy - var filterPolicy = @"{ - ""EventType"": [""OrderCreated"", ""OrderUpdated""], - ""Priority"": [{""numeric"": ["">="", 5]}] - }"; - - var subscriptionResponse = await LocalStack.SnsClient.SubscribeAsync(new SubscribeRequest - { - TopicArn = _topicArn, - Protocol = "sqs", - Endpoint = queueArn, - Attributes = new Dictionary - { - ["FilterPolicy"] = filterPolicy - } - }); - - var messageBody = GenerateMessageBody(MessageSizeBytes); - var publishCount = Math.Min(MessageCount, 100); // Limit for filtering test - - // Publish messages with varying attributes (some match filter, some don't) - for (int i = 0; i < publishCount; i++) - { - var eventType = i % 3 == 0 ? "OrderCreated" : (i % 3 == 1 ? "OrderUpdated" : "OrderDeleted"); - var priority = i % 10; - - await LocalStack.SnsClient.PublishAsync(new PublishRequest - { - TopicArn = _topicArn, - Message = messageBody, - MessageAttributes = new Dictionary - { - ["EventType"] = new SnsMessageAttributeValue - { - DataType = "String", - StringValue = eventType - }, - ["Priority"] = new SnsMessageAttributeValue - { - DataType = "Number", - StringValue = priority.ToString() - }, - ["MessageIndex"] = new SnsMessageAttributeValue - { - DataType = "Number", - StringValue = i.ToString() - } - } - }); - } - - // Wait for message propagation - await Task.Delay(1000); - - // Receive filtered messages - var receivedCount = 0; - var maxAttempts = 10; - var attempts = 0; - - while (attempts < maxAttempts) - { - var response = await LocalStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = filterQueueUrl, - MaxNumberOfMessages = 10, - WaitTimeSeconds = 1 - }); - - if (response.Messages.Count > 0) - { - // Delete received messages - var deleteTasks = response.Messages.Select(msg => - LocalStack.SqsClient.DeleteMessageAsync(new DeleteMessageRequest - { - QueueUrl = filterQueueUrl, - ReceiptHandle = msg.ReceiptHandle - })); - - await Task.WhenAll(deleteTasks); - receivedCount += response.Messages.Count; - } - else - { - break; - } - - attempts++; - } - - // Cleanup subscription - await LocalStack.SnsClient.UnsubscribeAsync(new UnsubscribeRequest - { - SubscriptionArn = subscriptionResponse.SubscriptionArn - }); - } - finally - { - // Cleanup filter queue - try - { - await LocalStack.SqsClient.DeleteQueueAsync(filterQueueUrl); - } - catch - { - // Ignore cleanup errors - } - } - } - - /// - /// Benchmark: Message attributes performance overhead for SNS - /// Measures the performance impact of including message attributes in SNS publish - /// - [Benchmark(Description = "SNS Topic - Message Attributes Overhead")] - public async Task SnsMessageAttributesOverhead() - { - if (LocalStack?.SnsClient == null || string.IsNullOrEmpty(_topicArn)) - return; - - var messageBody = GenerateMessageBody(MessageSizeBytes); - - for (int i = 0; i < MessageCount; i++) - { - await LocalStack.SnsClient.PublishAsync(new PublishRequest - { - TopicArn = _topicArn, - Message = messageBody, - MessageAttributes = new Dictionary - { - ["EventType"] = new SnsMessageAttributeValue - { - DataType = "String", - StringValue = "TestEvent" - }, - ["EntityId"] = new SnsMessageAttributeValue - { - DataType = "Number", - StringValue = "12345" - }, - ["SequenceNo"] = new SnsMessageAttributeValue - { - DataType = "Number", - StringValue = i.ToString() - }, - ["Timestamp"] = new SnsMessageAttributeValue - { - DataType = "Number", - StringValue = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds().ToString() - }, - ["CorrelationId"] = new SnsMessageAttributeValue - { - DataType = "String", - StringValue = Guid.NewGuid().ToString() - } - } - }); - } - } - - /// - /// Benchmark: Concurrent fan-out with high subscriber count - /// Measures scalability of SNS fan-out with multiple concurrent publishers and subscribers - /// - [Benchmark(Description = "SNS Fan-Out - Concurrent Publishers and Subscribers")] - public async Task SnsConcurrentFanOutScalability() - { - if (LocalStack?.SnsClient == null || LocalStack?.SqsClient == null || - string.IsNullOrEmpty(_topicArn) || _subscriberQueueUrls.Count == 0) - return; - - var messageBody = GenerateMessageBody(MessageSizeBytes); - var messagesPerPublisher = Math.Min(MessageCount / ConcurrentPublishers, 50); // Limit for scalability test - - // Publish messages concurrently - var publishTasks = Enumerable.Range(0, ConcurrentPublishers) - .Select(async publisherId => - { - for (int i = 0; i < messagesPerPublisher; i++) - { - await LocalStack.SnsClient.PublishAsync(new PublishRequest - { - TopicArn = _topicArn, - Message = messageBody, - MessageAttributes = new Dictionary - { - ["PublisherId"] = new SnsMessageAttributeValue - { - DataType = "Number", - StringValue = publisherId.ToString() - }, - ["MessageIndex"] = new SnsMessageAttributeValue - { - DataType = "Number", - StringValue = i.ToString() - } - } - }); - } - }); - - await Task.WhenAll(publishTasks); - - // Wait for message propagation - await Task.Delay(2000); - - // Receive messages from all subscribers concurrently - var receiveTasks = _subscriberQueueUrls.Select(async queueUrl => - { - var receivedCount = 0; - var maxAttempts = 15; - var attempts = 0; - - while (attempts < maxAttempts) - { - var response = await LocalStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = queueUrl, - MaxNumberOfMessages = 10, - WaitTimeSeconds = 1 - }); - - if (response.Messages.Count > 0) - { - // Delete received messages - var deleteTasks = response.Messages.Select(msg => - LocalStack.SqsClient.DeleteMessageAsync(new DeleteMessageRequest - { - QueueUrl = queueUrl, - ReceiptHandle = msg.ReceiptHandle - })); - - await Task.WhenAll(deleteTasks); - receivedCount += response.Messages.Count; - } - else if (receivedCount > 0) - { - break; // No more messages - } - - attempts++; - } - - return receivedCount; - }); - - await Task.WhenAll(receiveTasks); - } - - /// - /// Benchmark: SNS publish with subject line - /// Measures performance impact of including subject in SNS messages - /// - [Benchmark(Description = "SNS Topic - Publish with Subject")] - public async Task SnsPublishWithSubject() - { - if (LocalStack?.SnsClient == null || string.IsNullOrEmpty(_topicArn)) - return; - - var messageBody = GenerateMessageBody(MessageSizeBytes); - - for (int i = 0; i < MessageCount; i++) - { - await LocalStack.SnsClient.PublishAsync(new PublishRequest - { - TopicArn = _topicArn, - Message = messageBody, - Subject = $"Test Event {i}", - MessageAttributes = new Dictionary - { - ["MessageIndex"] = new SnsMessageAttributeValue - { - DataType = "Number", - StringValue = i.ToString() - } - } - }); - } - } - - /// - /// Benchmark: SNS message deduplication overhead - /// Measures performance with message deduplication IDs - /// - [Benchmark(Description = "SNS Topic - Message Deduplication")] - public async Task SnsMessageDeduplication() - { - if (LocalStack?.SnsClient == null || string.IsNullOrEmpty(_topicArn)) - return; - - var messageBody = GenerateMessageBody(MessageSizeBytes); - - for (int i = 0; i < MessageCount; i++) - { - await LocalStack.SnsClient.PublishAsync(new PublishRequest - { - TopicArn = _topicArn, - Message = messageBody, - MessageAttributes = new Dictionary - { - ["MessageDeduplicationId"] = new SnsMessageAttributeValue - { - DataType = "String", - StringValue = $"dedup-{i}-{Guid.NewGuid():N}" - }, - ["MessageIndex"] = new SnsMessageAttributeValue - { - DataType = "Number", - StringValue = i.ToString() - } - } - }); - } - } - - /// - /// Helper method to generate message body of specified size - /// - private string GenerateMessageBody(int sizeBytes) - { - var sb = new StringBuilder(sizeBytes); - var random = new System.Random(); - - while (sb.Length < sizeBytes) - { - sb.Append((char)('A' + random.Next(26))); - } - - return sb.ToString(0, sizeBytes); - } -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/Performance/SqsPerformanceBenchmarks.cs b/tests/SourceFlow.Cloud.AWS.Tests/Performance/SqsPerformanceBenchmarks.cs deleted file mode 100644 index ebb6c229..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/Performance/SqsPerformanceBenchmarks.cs +++ /dev/null @@ -1,159 +0,0 @@ -using Amazon.SQS.Model; -using BenchmarkDotNet.Attributes; -using SourceFlow.Cloud.AWS.Tests.TestHelpers; - -namespace SourceFlow.Cloud.AWS.Tests.Performance; - -/// -/// Performance benchmarks for SQS operations -/// -[MemoryDiagnoser] -[SimpleJob] -[Trait("Category", "Integration")] -[Trait("Category", "RequiresLocalStack")] -public class SqsPerformanceBenchmarks : PerformanceBenchmarkBase -{ - private string? _testQueueUrl; - - [GlobalSetup] - public override async Task GlobalSetup() - { - await base.GlobalSetup(); - - if (LocalStack?.SqsClient != null && LocalStack.Configuration.RunPerformanceTests) - { - // Create a dedicated queue for performance testing - var queueName = $"perf-test-queue-{Guid.NewGuid():N}"; - var response = await LocalStack.SqsClient.CreateQueueAsync(queueName); - _testQueueUrl = response.QueueUrl; - } - } - - [GlobalCleanup] - public override async Task GlobalCleanup() - { - if (LocalStack?.SqsClient != null && !string.IsNullOrEmpty(_testQueueUrl)) - { - try - { - await LocalStack.SqsClient.DeleteQueueAsync(_testQueueUrl); - } - catch - { - // Ignore cleanup errors - } - } - - await base.GlobalCleanup(); - } - - [Benchmark] - public async Task SendSingleMessage() - { - if (LocalStack?.SqsClient == null || string.IsNullOrEmpty(_testQueueUrl)) - return; - - var messageBody = $"Benchmark message {Guid.NewGuid()}"; - await LocalStack.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = _testQueueUrl, - MessageBody = messageBody - }); - } - - [Benchmark] - public async Task SendMessageWithAttributes() - { - if (LocalStack?.SqsClient == null || string.IsNullOrEmpty(_testQueueUrl)) - return; - - var messageBody = $"Benchmark message with attributes {Guid.NewGuid()}"; - await LocalStack.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = _testQueueUrl, - MessageBody = messageBody, - MessageAttributes = new Dictionary - { - ["CommandType"] = new MessageAttributeValue - { - DataType = "String", - StringValue = "TestCommand" - }, - ["EntityId"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = "123" - }, - ["SequenceNo"] = new MessageAttributeValue - { - DataType = "Number", - StringValue = "1" - } - } - }); - } - - [Benchmark] - [Arguments(10)] - [Arguments(50)] - [Arguments(100)] - public async Task SendBatchMessages(int batchSize) - { - if (LocalStack?.SqsClient == null || string.IsNullOrEmpty(_testQueueUrl)) - return; - - var entries = new List(); - - for (int i = 0; i < Math.Min(batchSize, 10); i++) // SQS batch limit is 10 - { - entries.Add(new SendMessageBatchRequestEntry - { - Id = i.ToString(), - MessageBody = $"Batch message {i} - {Guid.NewGuid()}" - }); - } - - // Send in batches of 10 if batchSize > 10 - for (int i = 0; i < entries.Count; i += 10) - { - var batch = entries.Skip(i).Take(10).ToList(); - await LocalStack.SqsClient.SendMessageBatchAsync(new SendMessageBatchRequest - { - QueueUrl = _testQueueUrl, - Entries = batch - }); - } - } - - [Benchmark] - public async Task ReceiveMessages() - { - if (LocalStack?.SqsClient == null || string.IsNullOrEmpty(_testQueueUrl)) - return; - - // First send a message to receive - await LocalStack.SqsClient.SendMessageAsync(new SendMessageRequest - { - QueueUrl = _testQueueUrl, - MessageBody = "Message to receive" - }); - - // Then receive it - var response = await LocalStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = _testQueueUrl, - MaxNumberOfMessages = 1, - WaitTimeSeconds = 1 - }); - - // Delete received messages - foreach (var message in response.Messages) - { - await LocalStack.SqsClient.DeleteMessageAsync(new DeleteMessageRequest - { - QueueUrl = _testQueueUrl, - ReceiptHandle = message.ReceiptHandle - }); - } - } -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/README.md b/tests/SourceFlow.Cloud.AWS.Tests/README.md deleted file mode 100644 index 55cb17bf..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/README.md +++ /dev/null @@ -1,600 +0,0 @@ -# SourceFlow AWS Cloud Integration Tests - -This test project provides comprehensive testing capabilities for the SourceFlow AWS cloud integration, including unit tests, property-based tests, integration tests, performance benchmarks, security validation, and resilience testing. The testing framework validates Amazon SQS command dispatching, SNS event publishing, KMS encryption, health monitoring, and performance characteristics to ensure SourceFlow applications work correctly in AWS environments. - -## 🎉 Implementation Complete - -**All phases of the AWS cloud integration testing framework have been successfully implemented and validated.** - -The comprehensive test suite includes: -- ✅ **16 Property-Based Tests** - Universal correctness properties validated with FsCheck -- ✅ **100+ Integration Tests** - End-to-end scenarios with LocalStack and real AWS -- ✅ **Performance Benchmarks** - Detailed throughput, latency, and scalability measurements -- ✅ **Security Validation** - IAM, KMS, encryption, and audit logging tests -- ✅ **Resilience Testing** - Circuit breakers, retry policies, and failure handling -- ✅ **CI/CD Integration** - Automated testing with resource provisioning and cleanup -- ✅ **Comprehensive Documentation** - Setup guides, troubleshooting, and best practices - -## Implementation Status - -### ✅ Phase 1-3: Enhanced Test Infrastructure (Complete) -- Enhanced test project with FsCheck, BenchmarkDotNet, and TestContainers -- LocalStack manager with full AWS service emulation (SQS, SNS, KMS, IAM) -- AWS resource manager for automated provisioning and cleanup -- AWS test environment abstraction for LocalStack and real AWS - -### ✅ Phase 4-5: SQS and SNS Integration Tests (Complete) -- SQS FIFO and standard queue integration tests -- SQS dead letter queue and batch operations tests -- SQS message attributes and processing tests -- SNS topic publishing and fan-out messaging tests -- SNS message filtering and correlation tests -- Property tests for SQS and SNS correctness - -### ✅ Phase 6: KMS Encryption Integration Tests (Complete) -- ✅ KMS encryption round-trip property tests -- ✅ KMS encryption integration tests (comprehensive test suite) - - End-to-end encryption/decryption tests - - Different encryption algorithms and key types - - Encryption context and AAD validation - - Performance and overhead measurements - - Error handling and edge cases -- ✅ KMS key rotation tests - - Seamless rotation without service interruption - - Backward compatibility with previous key versions - - Automatic key version management - - Rotation monitoring and alerting -- ✅ KMS security and performance tests - - Sensitive data masking with [SensitiveData] attribute - - IAM permission enforcement - - Performance under various load conditions - - Audit logging and compliance validation - -### ✅ Phase 7: AWS Health Check Integration Tests (Complete) -- ✅ Comprehensive health check tests for SQS, SNS, and KMS - - SQS: queue existence, accessibility, send/receive permissions - - SNS: topic availability, attributes, publish permissions, subscription status - - KMS: key accessibility, encryption/decryption permissions, key status -- ✅ Service connectivity validation with response time measurements -- ✅ Health check performance and reliability under load -- ✅ Property-based health check accuracy tests (Property 8) - - Validates health checks accurately reflect service availability - - Ensures health checks detect accessibility issues - - Verifies permission validation correctness - - Tests health check performance (< 5 seconds) - - Validates reliability under concurrent access (90%+ consistency) - -### ✅ Phase 9 Complete: AWS Performance Testing -- ✅ Enhanced SQS performance benchmarks with comprehensive scenarios - - Standard and FIFO queue throughput testing - - Concurrent sender/receiver performance testing - - Batch operation performance benefits - - End-to-end latency measurements - - Message attributes overhead testing -- ✅ SNS performance benchmarks with fan-out and filtering tests - - Event publishing rate testing - - Fan-out delivery performance with multiple subscribers - - SNS-to-SQS delivery latency measurements - - Message filtering performance impact -- ✅ Comprehensive scalability benchmarks with concurrent load testing - - Performance under increasing concurrent connections - - Resource utilization (memory, CPU, network) under load - - Performance scaling characteristics validation - - AWS service limit impact on performance -- ✅ Performance measurement consistency property tests (Property 9) - - Validates consistent throughput measurements - - Ensures reliable latency measurements across iterations - - Tests performance under various load conditions - - Validates resource utilization tracking accuracy - - **Implementation Change**: Test method signature changed from `async Task` to `void` with `[Fact]` attribute - - Uses manual scenario iteration instead of FsCheck automatic generation - - Contains async operations that may require `async Task` return type for proper execution - -### ✅ Phase 10: AWS Resilience Testing (Complete) -- ✅ Circuit breaker pattern tests for AWS service failures -- ✅ Retry policy tests with exponential backoff -- ✅ Service throttling and failure handling tests -- ✅ Dead letter queue processing tests -- ✅ Property tests for resilience patterns (Properties 11-12) - -### ✅ Phase 11: AWS Security Testing (Complete) -- ✅ IAM role and permission tests - - Proper IAM role assumption and credential management - - Least privilege access enforcement with flexible wildcard validation - - Cross-account access and permission boundaries -- ✅ Property test for IAM security enforcement (Property 13) - - Enhanced wildcard permission validation logic - - Supports scenarios with zero wildcards or controlled wildcard usage - - Validates least privilege principles with realistic constraints - - **Lenient required permission validation**: Handles test generation edge cases where required permissions may exceed available actions -- ✅ Encryption in transit validation - - TLS encryption for all AWS service communications - - Certificate validation and security protocols - - Encryption configuration and compliance -- ✅ Audit logging tests - - CloudTrail integration and event logging - - Security event capture and analysis - - Audit log completeness and integrity validation - - Compliance reporting and monitoring - -### ✅ Phase 12-15: CI/CD Integration and Final Validation (Complete) -- ✅ CI/CD test execution framework with LocalStack and real AWS support -- ✅ Automatic AWS resource provisioning using CloudFormation -- ✅ Test environment isolation and parallel execution -- ✅ Comprehensive test reporting and metrics collection -- ✅ Enhanced error reporting with AWS-specific troubleshooting guidance -- ✅ Unique resource naming and comprehensive cleanup -- ✅ Complete AWS test documentation (setup, execution, performance, security) -- ✅ Full test suite validation against LocalStack and real AWS services -- ✅ Property test for AWS CI/CD integration reliability (Property 16) -- 🔄 Audit logging tests (In Progress) - -### ⏳ Future Enhancements (Optional) -The core testing framework is complete. Future enhancements could include: -- Additional cloud provider integrations (GCP, etc.) -- Advanced chaos engineering scenarios -- Multi-region failover testing -- Cost optimization analysis tools - -## Test Categories - -All AWS integration tests are categorized using xUnit traits for flexible test execution: - -- **`[Trait("Category", "Unit")]`** - No external dependencies (50+ tests) -- **`[Trait("Category", "Integration")]`** - Requires external AWS services (100+ tests) -- **`[Trait("Category", "RequiresLocalStack")]`** - Tests specifically designed for LocalStack emulator -- **`[Trait("Category", "RequiresAWS")]`** - Tests requiring real AWS services - -### Running Tests by Category - -```bash -# Run only unit tests (fast, no infrastructure needed) -dotnet test --filter "Category=Unit" - -# Run all tests (requires AWS infrastructure) -dotnet test - -# Skip all integration tests -dotnet test --filter "Category!=Integration" - -# Skip LocalStack-dependent tests -dotnet test --filter "Category!=RequiresLocalStack" - -# Skip real AWS-dependent tests -dotnet test --filter "Category!=RequiresAWS" -``` - - - -## Test Structure - -``` -tests/SourceFlow.Cloud.AWS.Tests/ -├── Unit/ # Unit tests with mocks -│ ├── AwsSqsCommandDispatcherTests.cs ✅ -│ ├── AwsSnsEventDispatcherTests.cs ✅ -│ ├── IocExtensionsTests.cs ✅ -│ ├── RoutingConfigurationTests.cs ✅ -│ └── PropertyBasedTests.cs ✅ # FsCheck property-based tests -├── Integration/ # LocalStack integration tests -│ ├── SqsStandardIntegrationTests.cs ✅ -│ ├── SqsFifoIntegrationTests.cs ✅ -│ ├── SqsDeadLetterQueueIntegrationTests.cs ✅ -│ ├── SqsDeadLetterQueuePropertyTests.cs ✅ -│ ├── SqsBatchOperationsIntegrationTests.cs ✅ -│ ├── SqsMessageAttributesIntegrationTests.cs ✅ -│ ├── SqsMessageProcessingPropertyTests.cs ✅ -│ ├── SnsTopicPublishingIntegrationTests.cs ✅ -│ ├── SnsFanOutMessagingIntegrationTests.cs ✅ -│ ├── SnsEventPublishingPropertyTests.cs ✅ -│ ├── SnsMessageFilteringIntegrationTests.cs ✅ -│ ├── SnsCorrelationAndErrorHandlingTests.cs ✅ -│ ├── SnsMessageFilteringAndErrorHandlingPropertyTests.cs ✅ -│ ├── KmsEncryptionIntegrationTests.cs ✅ -│ ├── KmsEncryptionRoundTripPropertyTests.cs ✅ -│ ├── KmsKeyRotationIntegrationTests.cs ✅ -│ ├── KmsKeyRotationPropertyTests.cs ✅ -│ ├── KmsSecurityAndPerformanceTests.cs ✅ -│ ├── KmsSecurityAndPerformancePropertyTests.cs ✅ -│ ├── AwsHealthCheckIntegrationTests.cs ✅ -│ ├── AwsHealthCheckPropertyTests.cs ✅ -│ ├── EnhancedLocalStackManagerTests.cs ✅ -│ ├── EnhancedAwsTestEnvironmentTests.cs ✅ -│ ├── LocalStackIntegrationTests.cs ✅ -│ └── HealthCheckIntegrationTests.cs ⏳ -├── Performance/ # BenchmarkDotNet performance tests -│ ├── SqsPerformanceBenchmarks.cs ✅ -│ ├── SnsPerformanceBenchmarks.cs ⏳ -│ ├── KmsPerformanceBenchmarks.cs ⏳ -│ ├── EndToEndLatencyBenchmarks.cs ⏳ -│ └── ScalabilityBenchmarks.cs ⏳ -├── Security/ # AWS security and IAM tests -│ ├── IamRoleTests.cs ⏳ # Not Started -│ ├── KmsEncryptionTests.cs ⏳ -│ ├── AccessControlTests.cs ⏳ -│ └── AuditLoggingTests.cs ⏳ -├── Resilience/ # Circuit breaker and retry tests -│ ├── CircuitBreakerTests.cs ⏳ -│ ├── RetryPolicyTests.cs ⏳ -│ ├── ServiceFailureTests.cs ⏳ -│ └── ThrottlingTests.cs ⏳ -├── E2E/ # End-to-end scenario tests -│ ├── CommandToEventFlowTests.cs ⏳ -│ ├── SagaOrchestrationTests.cs ⏳ -│ └── MultiServiceIntegrationTests.cs ⏳ -└── TestHelpers/ # Test utilities and fixtures - ├── LocalStackManager.cs ✅ - ├── LocalStackConfiguration.cs ✅ - ├── ILocalStackManager.cs ✅ - ├── AwsTestEnvironment.cs ✅ - ├── IAwsTestEnvironment.cs ✅ - ├── AwsResourceManager.cs ✅ - ├── IAwsResourceManager.cs ✅ - ├── AwsTestConfiguration.cs ✅ - ├── AwsTestEnvironmentFactory.cs ✅ - ├── AwsTestScenario.cs ✅ - ├── CiCdTestScenario.cs ✅ - ├── LocalStackTestFixture.cs ✅ - ├── PerformanceTestHelpers.cs ✅ - └── README.md ✅ -``` - -Legend: ✅ Complete | 🔄 Queued/In Progress | ⏳ Planned - -## Testing Frameworks - -### xUnit -- **Primary testing framework** - Replaced NUnit for consistency -- **Fact/Theory attributes** - Standard unit test patterns -- **Class fixtures** - Shared test setup and teardown - -### FsCheck (Property-Based Testing) -- **Property validation** - Tests universal properties across randomized inputs -- **Automatic shrinking** - Finds minimal failing examples -- **Custom generators** - Tailored test data generation for SourceFlow types - -### BenchmarkDotNet (Performance Testing) -- **Micro-benchmarks** - Precise performance measurements -- **Memory diagnostics** - Allocation and GC pressure analysis -- **Statistical analysis** - Reliable performance comparisons - -### TestContainers (Integration Testing) -- **LocalStack integration** - AWS service emulation -- **Docker container management** - Automatic lifecycle handling -- **Isolated test environments** - Clean state for each test run - -## Key Features - -### Property-Based Tests (14 of 16 Implemented) -The project includes comprehensive property-based tests that validate universal correctness properties for AWS cloud integration: - -1. ✅ **SQS Message Processing Correctness** - Ensures commands are delivered correctly with proper message attributes, FIFO ordering, and batch operations -2. ✅ **SQS Dead Letter Queue Handling** - Validates failed message capture and recovery mechanisms -3. ✅ **SNS Event Publishing Correctness** - Verifies event delivery to all subscribers with proper fan-out messaging -4. ✅ **SNS Message Filtering and Error Handling** - Tests subscription filters and error handling mechanisms -5. ✅ **KMS Encryption Round-Trip Consistency** - Ensures message encryption and decryption correctness with the following validations: - - Round-trip consistency: decrypt(encrypt(plaintext)) == plaintext - - Encryption non-determinism: same plaintext produces different ciphertext each time - - Sensitive data protection: plaintext substrings not visible in ciphertext - - Performance characteristics: encryption/decryption within reasonable time bounds - - Unicode safety: proper handling of multi-byte characters - - Base64 encoding: ciphertext properly encoded for transmission -6. ✅ **KMS Key Rotation Seamlessness** - Validates seamless key rotation without service interruption - - Messages encrypted with old keys decrypt after rotation - - Backward compatibility with previous key versions - - Automatic key version management - - Rotation monitoring and alerting -7. ✅ **KMS Security and Performance** - Tests sensitive data masking and performance characteristics - - [SensitiveData] attributes properly masked in logs - - Encryption performance within acceptable bounds - - IAM permission enforcement - - Audit logging and compliance -8. ✅ **AWS Health Check Accuracy** - Verifies health checks accurately reflect service availability - - Health checks detect service availability, accessibility, and permissions - - Health checks complete within acceptable latency (< 5 seconds) - - Reliability under concurrent access (90%+ consistency) - - SQS queue existence, accessibility, send/receive permissions - - SNS topic availability, attributes, publish permissions, subscription status - - KMS key accessibility, encryption/decryption permissions, key status -9. ✅ **AWS Performance Measurement Consistency** - Tests performance measurement reliability across test runs - - Validates consistent throughput measurements within acceptable variance - - Ensures reliable latency measurements across iterations - - Tests performance under various load conditions - - Validates resource utilization tracking accuracy - - **Implementation Note**: The main property test method was recently changed from `async Task` to `void`. This may require review as the method contains async operations (`await` calls) which typically require an `async Task` return type. The test uses `[Fact]` attribute instead of `[Property]` and manually iterates through scenarios rather than using FsCheck's automatic test case generation. -10. ✅ **LocalStack AWS Service Equivalence** - Ensures LocalStack provides equivalent functionality to real AWS services -11. ✅ **AWS Resilience Pattern Compliance** - Validates circuit breakers, retry policies, and failure handling -12. ✅ **AWS Dead Letter Queue Processing** - Tests failed message analysis and reprocessing -13. ✅ **AWS IAM Security Enforcement** - Tests proper authentication and authorization enforcement - - Validates IAM role authentication with proper credential management - - Ensures least privilege principles with flexible wildcard permission validation - - Tests cross-account access with permission boundaries and external IDs - - Verifies role assumption with MFA and source IP restrictions - - **Enhanced validation logic**: Handles property-based test generation edge cases gracefully - - Lenient required permission validation when test generation produces more required permissions than available actions - - Validates that granted actions include required permissions up to the available action count - - Prevents false negatives from random test data generation -14. ✅ **AWS Encryption in Transit** - Validates TLS encryption for all communications - - TLS encryption for all AWS service communications (SQS, SNS, KMS) - - Certificate validation and security protocols - - Encryption configuration and compliance validation -15. 🔄 **AWS Audit Logging** - Tests CloudTrail integration and event logging (In Progress) -16. ✅ **AWS CI/CD Integration Reliability** - Validates test execution in CI/CD with proper resource isolation - -### Enhanced LocalStack Integration (Implemented) -Enhanced LocalStack-based integration tests provide comprehensive AWS service validation: - -- **SQS Integration** - Tests both FIFO and standard queues with full API compatibility -- **SNS Integration** - Validates topic publishing, subscriptions, and fan-out messaging -- **KMS Integration** - Tests encryption, decryption, and key rotation scenarios -- **Dead Letter Queue Integration** - Validates failed message handling and recovery -- **Health Check Integration** - Tests service availability and connectivity validation -- **Cross-Service Integration** - End-to-end message flows across multiple AWS services -- **Automated Resource Management** - `AwsResourceManager` for provisioning and cleanup - -### Performance Benchmarks (Implemented) -Comprehensive BenchmarkDotNet tests measure AWS service performance: - -- ✅ **SQS Throughput** - Messages per second for standard and FIFO queues with various scenarios - - Single sender and concurrent sender throughput testing - - Batch operation performance benefits - - Message attributes overhead measurements - - Concurrent receiver performance testing -- ✅ **SNS Publishing** - Event publishing rates and fan-out delivery performance - - Topic publishing throughput testing - - Fan-out delivery performance with multiple subscribers - - Message filtering performance impact - - Cross-service (SNS-to-SQS) delivery latency -- ✅ **End-to-End Latency** - Complete message processing times including network overhead - - Standard and FIFO queue end-to-end latency measurements - - Network overhead and AWS service processing time -- ✅ **Scalability** - Performance under increasing concurrent connections and load - - Concurrent connection scaling tests - - Resource utilization under various load conditions - - AWS service limit impact on performance -- ✅ **Batch Operation Efficiency** - Performance benefits of AWS batch operations -- ✅ **Memory allocation patterns** - GC pressure analysis and optimization - -### Security and Resilience Tests (Substantial Implementation) -Comprehensive validation of AWS security features and resilience patterns: - -- ✅ **Circuit Breaker Patterns** - Automatic failure detection and recovery for AWS services -- ✅ **Retry Policies** - Exponential backoff and maximum retry enforcement -- ✅ **IAM Role Authentication** - Proper role assumption and credential management -- ✅ **Access Control Validation** - Least privilege access and permission enforcement -- ✅ **Dead Letter Queue Processing** - Failed message analysis and reprocessing -- ✅ **Service Throttling Handling** - Graceful handling of AWS service limits -- ✅ **Encryption in Transit** - TLS encryption validation for all AWS communications -- 🔄 **KMS Encryption Security** - End-to-end encryption and key management (In Progress) -- 🔄 **Audit Logging** - CloudTrail integration and security event logging (In Progress) - -## AWS Resource Manager - -### Automated Resource Provisioning -The `AwsResourceManager` class provides comprehensive automated resource lifecycle management: - -```csharp -public interface IAwsResourceManager : IAsyncDisposable -{ - Task CreateTestResourcesAsync(string testPrefix, AwsResourceTypes resourceTypes = AwsResourceTypes.All); - Task CleanupResourcesAsync(AwsResourceSet resources, bool force = false); - Task ResourceExistsAsync(string resourceArn); - Task> ListTestResourcesAsync(string testPrefix); - Task CleanupOldResourcesAsync(TimeSpan maxAge, string? testPrefix = null); - Task EstimateCostAsync(AwsResourceSet resources, TimeSpan duration); - Task TagResourceAsync(string resourceArn, Dictionary tags); - Task CreateCloudFormationStackAsync(string stackName, string templateBody, Dictionary? parameters = null); - Task DeleteCloudFormationStackAsync(string stackName); -} -``` - -### Key Features -- **Resource Types** - SQS queues, SNS topics, KMS keys, IAM roles, CloudFormation stacks -- **Unique Naming** - Test prefix-based naming to prevent resource conflicts -- **Automatic Tagging** - Metadata tagging for identification and cost tracking -- **Cost Estimation** - Resource cost calculation and monitoring -- **CloudFormation Integration** - Stack-based resource provisioning for complex scenarios -- **Cleanup Management** - Comprehensive resource cleanup with force options -- **Multi-Account Support** - Cross-account resource management capabilities - -### Usage in Tests -```csharp -[Fact] -public async Task TestWithManagedResources() -{ - var resourceSet = await _resourceManager.CreateTestResourcesAsync("integration-test", - AwsResourceTypes.SqsQueues | AwsResourceTypes.SnsTopics); - - try - { - // Use resourceSet.QueueUrls and resourceSet.TopicArns for testing - // Test implementation here - } - finally - { - await _resourceManager.CleanupResourcesAsync(resourceSet); - } -} -``` - -## Configuration - -### Test Configuration -Tests are configured via enhanced `AwsTestConfiguration`: - -```csharp -public class AwsTestConfiguration -{ - public bool UseLocalStack { get; set; } = true; - public bool RunIntegrationTests { get; set; } = true; - public bool RunPerformanceTests { get; set; } = false; - public bool RunSecurityTests { get; set; } = true; - public string LocalStackEndpoint { get; set; } = "http://localhost:4566"; - public LocalStackConfiguration LocalStack { get; set; } = new(); - public AwsServiceConfiguration Services { get; set; } = new(); - public PerformanceTestConfiguration Performance { get; set; } = new(); - public SecurityTestConfiguration Security { get; set; } = new(); -} -``` - -### Environment Requirements - -#### Unit Tests -- **.NET 9.0 runtime** -- **No external dependencies** - -#### Integration Tests -- **Docker Desktop** - For LocalStack containers with SQS, SNS, KMS, and IAM services -- **LocalStack image** - AWS service emulation with full API compatibility -- **Network connectivity** - Container port access and health checking -- **AWS SDK compatibility** - Real AWS SDK calls against LocalStack endpoints - -#### Performance Tests -- **Release build configuration** - Accurate performance measurements -- **Stable environment** - Minimal background processes for consistent results -- **Sufficient resources** - CPU and memory for benchmarking AWS service operations -- **AWS service limits awareness** - Testing within AWS service constraints - -#### Security Tests -- **AWS credentials** - Proper IAM role configuration for security testing -- **KMS key access** - Permissions for encryption/decryption operations -- **CloudTrail access** - Audit logging validation capabilities -- **Cross-account testing** - Multi-account access validation (optional) - -## Running Tests - -### Quick Start - -```bash -# Run only unit tests (no infrastructure needed) -dotnet test --filter "Category=Unit" - -# Run all tests (requires LocalStack or AWS) -dotnet test - -# Skip integration tests -dotnet test --filter "Category!=Integration" -``` - -### Test Categories - -```bash -# Unit tests only (fast, no dependencies) -dotnet test --filter "Category=Unit" - -# Integration tests only (requires LocalStack or AWS) -dotnet test --filter "Category=Integration" - -# LocalStack-specific tests -dotnet test --filter "Category=RequiresLocalStack" - -# Real AWS-specific tests -dotnet test --filter "Category=RequiresAWS" - -# Security tests -dotnet test --filter "Category=Security" - -# Resilience tests -dotnet test --filter "Category=Resilience" - -# End-to-end tests -dotnet test --filter "Category=E2E" -``` - -### Performance Benchmarks -```bash -dotnet run --project tests/SourceFlow.Cloud.AWS.Tests/ --configuration Release -``` - -## Dependencies - -### Core Testing -- **xunit** (2.9.2) - Primary testing framework -- **xunit.runner.visualstudio** (2.8.2) - Visual Studio integration -- **Moq** (4.20.72) - Mocking framework - -### Property-Based Testing -- **FsCheck** (2.16.6) - Property-based testing library -- **FsCheck.Xunit** (2.16.6) - xUnit integration - -### Performance Testing -- **BenchmarkDotNet** (0.14.0) - Micro-benchmarking framework - -### Integration Testing -- **TestContainers** (4.0.0) - Container management -- **Testcontainers.LocalStack** (4.0.0) - LocalStack integration - -### AWS SDK -- **AWSSDK.Extensions.NETCore.Setup** (3.7.301) - AWS SDK configuration -- **Amazon.Lambda.TestUtilities** (2.0.0) - Lambda testing utilities - -## Property-Based Testing Enhancements - -### Robust Test Generation Handling -The property-based tests include sophisticated validation logic that handles edge cases from random test data generation: - -1. **Lenient Required Permission Validation**: When FsCheck generates test scenarios where required permissions exceed available actions, the validation logic gracefully handles this by only validating that the actions present include the required permissions (up to the action count). This prevents false negatives from random test generation. - -2. **Flexible Wildcard Permission Validation**: Supports scenarios with zero wildcards (when not generated) or controlled wildcard usage (up to 50% of actions), ensuring realistic validation without being overly strict. - -3. **Cross-Account Boundary Validation**: Ensures permission boundaries include all allowed actions or have appropriate wildcards, handling cases where test generation produces empty or minimal boundary configurations. - -4. **Account ID Validation**: Handles test generation edge cases where source and target account IDs might be identical, focusing on validating the structure rather than enforcing uniqueness in property tests. - -These enhancements ensure that property-based tests provide meaningful validation while accommodating the inherent randomness of property-based test generation. - -### Unit Tests -- **Mock external dependencies** - Use Moq for AWS SDK clients -- **Test specific scenarios** - Focus on concrete examples -- **Verify behavior** - Assert on method calls and state changes -- **Fast execution** - No network or file system dependencies - -### Property-Based Tests -- **Define clear properties** - Universal truths about the system -- **Use appropriate generators** - Constrain input space meaningfully -- **Handle edge cases** - Filter invalid inputs appropriately -- **Document properties** - Link to requirements and design - -### Integration Tests -- **Isolate test data** - Use unique identifiers per test -- **Clean up resources** - Ensure proper teardown -- **Handle failures gracefully** - Skip tests when Docker unavailable -- **Test realistic scenarios** - Mirror production usage patterns - -### Performance Tests -- **Use Release builds** - Accurate performance characteristics -- **Warm up operations** - Account for JIT compilation -- **Measure consistently** - Multiple iterations for reliability -- **Document baselines** - Track performance over time - -## Troubleshooting - -### Docker Issues -If integration tests fail with Docker errors: -1. Ensure Docker Desktop is running -2. Check Docker daemon accessibility -3. Verify LocalStack image availability -4. Review container port conflicts - -### Property Test Failures -When property tests find counterexamples: -1. Analyze the failing input -2. Determine if it's a valid edge case -3. Either fix the code or refine the property -4. Document the resolution - -### Performance Variations -If benchmark results are inconsistent: -1. Run in Release configuration -2. Close unnecessary applications -3. Use dedicated benchmarking environment -4. Increase iteration counts for stability - -## Contributing - -When adding new tests: -1. **Follow naming conventions** - Descriptive test names -2. **Add appropriate categories** - Unit/Integration/Performance -3. **Document test purpose** - Clear comments and descriptions -4. **Update this README** - Keep documentation current -5. **Verify all test types** - Ensure comprehensive coverage \ No newline at end of file diff --git a/tests/SourceFlow.Cloud.AWS.Tests/Security/IamRoleTests.cs b/tests/SourceFlow.Cloud.AWS.Tests/Security/IamRoleTests.cs deleted file mode 100644 index 380890ad..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/Security/IamRoleTests.cs +++ /dev/null @@ -1,427 +0,0 @@ -using Amazon.IdentityManagement; -using Amazon.IdentityManagement.Model; -using SourceFlow.Cloud.AWS.Tests.TestHelpers; -using Xunit; - -namespace SourceFlow.Cloud.AWS.Tests.Security; - -/// -/// Integration tests for AWS IAM role and permission validation -/// **Feature: aws-cloud-integration-testing** -/// **Validates: Requirements 8.1, 8.2, 8.3** -/// -[Trait("Category", "Integration")] -[Trait("Category", "RequiresAWS")] -public class IamRoleTests : IAsyncLifetime -{ - private IAwsTestEnvironment? _environment; - private IAmazonIdentityManagementService _iamClient = null!; - - public async Task InitializeAsync() - { - try - { - _environment = await AwsTestEnvironmentFactory.CreateSecurityTestEnvironmentAsync(); - _iamClient = _environment.IamClient; - } - catch (InvalidOperationException) - { - // LocalStack container startup may fail (e.g., port conflict with external instance) - // Tests will check _environment and skip if null - } - } - - public async Task DisposeAsync() - { - if (_environment != null) - { - await _environment.DisposeAsync(); - } - } - - /// - /// Test proper IAM role assumption and credential management - /// **Validates: Requirement 8.1** - /// - [Fact] - public async Task IamRoleAssumption_ShouldSucceed_WithValidRole() - { - // Skip if using LocalStack (IAM emulation is limited) - if (_environment == null || _environment.IsLocalEmulator) - { - return; - } - - // Arrange - var roleName = $"sourceflow-test-role-{Guid.NewGuid():N}"; - var assumeRolePolicyDocument = @"{ - ""Version"": ""2012-10-17"", - ""Statement"": [{ - ""Effect"": ""Allow"", - ""Principal"": { ""Service"": ""sqs.amazonaws.com"" }, - ""Action"": ""sts:AssumeRole"" - }] - }"; - - try - { - // Act - Create test role - var createRoleResponse = await _iamClient.CreateRoleAsync(new CreateRoleRequest - { - RoleName = roleName, - AssumeRolePolicyDocument = assumeRolePolicyDocument, - Description = "SourceFlow test role for IAM validation" - }); - - // Assert - Role should be created successfully - Assert.NotNull(createRoleResponse.Role); - Assert.Equal(roleName, createRoleResponse.Role.RoleName); - Assert.NotNull(createRoleResponse.Role.Arn); - - // Verify role can be retrieved - var getRoleResponse = await _iamClient.GetRoleAsync(new GetRoleRequest - { - RoleName = roleName - }); - - Assert.NotNull(getRoleResponse.Role); - Assert.Equal(roleName, getRoleResponse.Role.RoleName); - } - finally - { - // Cleanup - try - { - await _iamClient.DeleteRoleAsync(new DeleteRoleRequest { RoleName = roleName }); - } - catch - { - // Best effort cleanup - } - } - } - - /// - /// Test IAM credential management and token refresh - /// **Validates: Requirement 8.1** - /// - [Fact] - public async Task IamCredentials_ShouldRefresh_BeforeExpiration() - { - // Skip if using LocalStack - if (_environment == null || _environment.IsLocalEmulator) - { - return; - } - - // This test validates that credentials are properly managed - // In a real scenario, we would test credential refresh logic - // For now, we validate that the IAM client is properly configured - Assert.NotNull(_iamClient); - } - - /// - /// Test least privilege access enforcement - /// **Validates: Requirement 8.2** - /// - [Fact] - public async Task IamPermissions_ShouldEnforce_LeastPrivilege() - { - // Skip if using LocalStack - if (_environment == null || _environment.IsLocalEmulator) - { - return; - } - - // Arrange - var roleName = $"sourceflow-test-restricted-role-{Guid.NewGuid():N}"; - var policyName = "SourceFlowRestrictedPolicy"; - - // Policy with minimal SQS permissions - var policyDocument = @"{ - ""Version"": ""2012-10-17"", - ""Statement"": [{ - ""Effect"": ""Allow"", - ""Action"": [ - ""sqs:SendMessage"", - ""sqs:ReceiveMessage"" - ], - ""Resource"": ""*"" - }] - }"; - - var assumeRolePolicyDocument = @"{ - ""Version"": ""2012-10-17"", - ""Statement"": [{ - ""Effect"": ""Allow"", - ""Principal"": { ""Service"": ""sqs.amazonaws.com"" }, - ""Action"": ""sts:AssumeRole"" - }] - }"; - - try - { - // Act - Create role with restricted permissions - var createRoleResponse = await _iamClient.CreateRoleAsync(new CreateRoleRequest - { - RoleName = roleName, - AssumeRolePolicyDocument = assumeRolePolicyDocument - }); - - // Attach inline policy with minimal permissions - await _iamClient.PutRolePolicyAsync(new PutRolePolicyRequest - { - RoleName = roleName, - PolicyName = policyName, - PolicyDocument = policyDocument - }); - - // Assert - Policy should be attached - var getPolicyResponse = await _iamClient.GetRolePolicyAsync(new GetRolePolicyRequest - { - RoleName = roleName, - PolicyName = policyName - }); - - Assert.NotNull(getPolicyResponse); - Assert.Equal(policyName, getPolicyResponse.PolicyName); - Assert.Contains("sqs:SendMessage", getPolicyResponse.PolicyDocument); - Assert.Contains("sqs:ReceiveMessage", getPolicyResponse.PolicyDocument); - - // Verify no excessive permissions (should not contain DeleteQueue) - Assert.DoesNotContain("sqs:DeleteQueue", getPolicyResponse.PolicyDocument); - Assert.DoesNotContain("sqs:*", getPolicyResponse.PolicyDocument); - } - finally - { - // Cleanup - try - { - await _iamClient.DeleteRolePolicyAsync(new DeleteRolePolicyRequest - { - RoleName = roleName, - PolicyName = policyName - }); - await _iamClient.DeleteRoleAsync(new DeleteRoleRequest { RoleName = roleName }); - } - catch - { - // Best effort cleanup - } - } - } - - /// - /// Test cross-account access with permission boundaries - /// **Validates: Requirement 8.3** - /// - [Fact] - public async Task IamCrossAccountAccess_ShouldRespect_PermissionBoundaries() - { - // Skip if using LocalStack - if (_environment == null || _environment.IsLocalEmulator) - { - return; - } - - // Arrange - var roleName = $"sourceflow-test-boundary-role-{Guid.NewGuid():N}"; - var boundaryPolicyName = "SourceFlowPermissionBoundary"; - - // Permission boundary policy - var boundaryPolicyDocument = @"{ - ""Version"": ""2012-10-17"", - ""Statement"": [{ - ""Effect"": ""Allow"", - ""Action"": [ - ""sqs:*"", - ""sns:*"" - ], - ""Resource"": ""*"" - }] - }"; - - var assumeRolePolicyDocument = @"{ - ""Version"": ""2012-10-17"", - ""Statement"": [{ - ""Effect"": ""Allow"", - ""Principal"": { ""Service"": ""sqs.amazonaws.com"" }, - ""Action"": ""sts:AssumeRole"" - }] - }"; - - string? boundaryPolicyArn = null; - - try - { - // Act - Create permission boundary policy - var createPolicyResponse = await _iamClient.CreatePolicyAsync(new CreatePolicyRequest - { - PolicyName = boundaryPolicyName, - PolicyDocument = boundaryPolicyDocument, - Description = "Permission boundary for SourceFlow test role" - }); - - boundaryPolicyArn = createPolicyResponse.Policy.Arn; - - // Create role with permission boundary - var createRoleResponse = await _iamClient.CreateRoleAsync(new CreateRoleRequest - { - RoleName = roleName, - AssumeRolePolicyDocument = assumeRolePolicyDocument, - PermissionsBoundary = boundaryPolicyArn - }); - - // Assert - Role should have permission boundary - var getRoleResponse = await _iamClient.GetRoleAsync(new GetRoleRequest - { - RoleName = roleName - }); - - Assert.NotNull(getRoleResponse.Role); - Assert.Equal(boundaryPolicyArn, getRoleResponse.Role.PermissionsBoundary?.PermissionsBoundaryArn); - } - finally - { - // Cleanup - try - { - await _iamClient.DeleteRoleAsync(new DeleteRoleRequest { RoleName = roleName }); - - if (boundaryPolicyArn != null) - { - await _iamClient.DeletePolicyAsync(new DeletePolicyRequest { PolicyArn = boundaryPolicyArn }); - } - } - catch - { - // Best effort cleanup - } - } - } - - /// - /// Test IAM policy validation and syntax checking - /// **Validates: Requirement 8.2** - /// - [Fact] - public async Task IamPolicy_ShouldValidate_PolicySyntax() - { - // Skip if using LocalStack - if (_environment == null || _environment.IsLocalEmulator) - { - return; - } - - // Arrange - Valid policy document - var validPolicyDocument = @"{ - ""Version"": ""2012-10-17"", - ""Statement"": [{ - ""Effect"": ""Allow"", - ""Action"": ""sqs:SendMessage"", - ""Resource"": ""*"" - }] - }"; - - // Act - Simulate policy validation - var policyName = $"sourceflow-test-policy-{Guid.NewGuid():N}"; - - try - { - var createPolicyResponse = await _iamClient.CreatePolicyAsync(new CreatePolicyRequest - { - PolicyName = policyName, - PolicyDocument = validPolicyDocument - }); - - // Assert - Policy should be created successfully - Assert.NotNull(createPolicyResponse.Policy); - Assert.Equal(policyName, createPolicyResponse.Policy.PolicyName); - } - finally - { - // Cleanup - try - { - var listPoliciesResponse = await _iamClient.ListPoliciesAsync(new ListPoliciesRequest - { - Scope = PolicyScopeType.Local - }); - - var policy = listPoliciesResponse.Policies.FirstOrDefault(p => p.PolicyName == policyName); - if (policy != null) - { - await _iamClient.DeletePolicyAsync(new DeletePolicyRequest { PolicyArn = policy.Arn }); - } - } - catch - { - // Best effort cleanup - } - } - } - - /// - /// Test IAM role tagging for resource management - /// **Validates: Requirement 8.2** - /// - [Fact] - public async Task IamRole_ShouldSupport_ResourceTagging() - { - // Skip if environment unavailable or using LocalStack - if (_environment == null || _environment.IsLocalEmulator) - { - return; - } - - // Arrange - var roleName = $"sourceflow-test-tagged-role-{Guid.NewGuid():N}"; - var assumeRolePolicyDocument = @"{ - ""Version"": ""2012-10-17"", - ""Statement"": [{ - ""Effect"": ""Allow"", - ""Principal"": { ""Service"": ""sqs.amazonaws.com"" }, - ""Action"": ""sts:AssumeRole"" - }] - }"; - - try - { - // Act - Create role with tags - var createRoleResponse = await _iamClient.CreateRoleAsync(new CreateRoleRequest - { - RoleName = roleName, - AssumeRolePolicyDocument = assumeRolePolicyDocument, - Tags = new List - { - new Tag { Key = "Environment", Value = "Test" }, - new Tag { Key = "Project", Value = "SourceFlow" }, - new Tag { Key = "ManagedBy", Value = "IntegrationTests" } - } - }); - - // Assert - Tags should be applied - var listTagsResponse = await _iamClient.ListRoleTagsAsync(new ListRoleTagsRequest - { - RoleName = roleName - }); - - Assert.NotNull(listTagsResponse.Tags); - Assert.Contains(listTagsResponse.Tags, t => t.Key == "Environment" && t.Value == "Test"); - Assert.Contains(listTagsResponse.Tags, t => t.Key == "Project" && t.Value == "SourceFlow"); - Assert.Contains(listTagsResponse.Tags, t => t.Key == "ManagedBy" && t.Value == "IntegrationTests"); - } - finally - { - // Cleanup - try - { - await _iamClient.DeleteRoleAsync(new DeleteRoleRequest { RoleName = roleName }); - } - catch - { - // Best effort cleanup - } - } - } -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/Security/IamSecurityPropertyTests.cs b/tests/SourceFlow.Cloud.AWS.Tests/Security/IamSecurityPropertyTests.cs deleted file mode 100644 index 2cfc98fb..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/Security/IamSecurityPropertyTests.cs +++ /dev/null @@ -1,829 +0,0 @@ -using FsCheck; -using FsCheck.Xunit; -using SourceFlow.Cloud.AWS.Tests.TestHelpers; - -namespace SourceFlow.Cloud.AWS.Tests.Security; - -/// -/// Property-based tests for AWS IAM security enforcement -/// **Feature: aws-cloud-integration-testing, Property 13: AWS IAM Security Enforcement** -/// **Validates: Requirements 8.1, 8.2, 8.3** -/// -[Trait("Category", "Integration")] -[Trait("Category", "RequiresAWS")] -public class IamSecurityPropertyTests -{ - /// - /// Property: AWS IAM Security Enforcement - /// **Validates: Requirements 8.1, 8.2, 8.3** - /// - /// For any AWS service operation, proper IAM role authentication should be enforced, - /// permissions should follow least privilege principles, and cross-account access - /// should work correctly with proper permission boundaries. - /// - [Property(MaxTest = 100)] - public Property AwsIamSecurityEnforcement(NonEmptyString roleName, PositiveInt actionCount, - PositiveInt resourceCount, bool useCrossAccount, bool usePermissionBoundary, - NonNegativeInt excessivePermissionCount, PositiveInt requiredPermissionCount, - bool includeWildcardPermissions, NonEmptyString accountId, PositiveInt boundaryActionCount) - { - // Generate IAM configuration from property inputs - var iamConfig = GenerateIamConfiguration( - roleName.Get, - Math.Min(actionCount.Get, 20), // Reasonable action count - Math.Min(resourceCount.Get, 10), // Reasonable resource count - useCrossAccount, - usePermissionBoundary, - Math.Min(excessivePermissionCount.Get, 5), - Math.Min(requiredPermissionCount.Get, 10), - includeWildcardPermissions, - accountId.Get, - Math.Min(boundaryActionCount.Get, 15) - ); - - // Property 1: IAM role authentication should be properly enforced (Requirement 8.1) - var roleAuthenticationValid = ValidateRoleAuthentication(iamConfig); - - // Property 2: Permissions should follow least privilege principles (Requirement 8.2) - var leastPrivilegeEnforced = ValidateLeastPrivilege(iamConfig); - - // Property 3: Cross-account access should work with permission boundaries (Requirement 8.3) - var crossAccountAccessValid = ValidateCrossAccountAccess(iamConfig); - - return (roleAuthenticationValid && leastPrivilegeEnforced && crossAccountAccessValid) - .ToProperty() - .Label($"Role: {iamConfig.RoleName}, Actions: {iamConfig.Actions.Count}, CrossAccount: {iamConfig.UseCrossAccount}"); - } - - /// - /// Property: IAM role credentials should be managed securely - /// Tests that IAM credentials are properly managed and refreshed - /// - [Property(MaxTest = 100)] - public Property IamRoleCredentialsManagement(NonEmptyString roleName, PositiveInt sessionDurationMinutes, - bool autoRefresh, PositiveInt expirationWarningMinutes, NonEmptyString sessionName) - { - // Generate credential configuration with AWS constraints - var actualSessionDuration = Math.Max(15, Math.Min(sessionDurationMinutes.Get, 720)); // 15 min to 12 hours - var actualExpirationWarning = Math.Max(1, Math.Min(expirationWarningMinutes.Get, 60)); - - var credentialConfig = new IamCredentialConfiguration - { - RoleName = SanitizeRoleName(roleName.Get), - SessionDuration = TimeSpan.FromMinutes(actualSessionDuration), - AutoRefresh = autoRefresh, - ExpirationWarning = TimeSpan.FromMinutes(Math.Min(actualExpirationWarning, actualSessionDuration - 1)), - SessionName = SanitizeSessionName(sessionName.Get) - }; - - // Property 1: Session duration should be within AWS limits - var sessionDurationValid = ValidateSessionDuration(credentialConfig); - - // Property 2: Credentials should support auto-refresh when enabled - var autoRefreshValid = ValidateAutoRefresh(credentialConfig); - - // Property 3: Expiration warnings should be configured appropriately - var expirationWarningValid = ValidateExpirationWarning(credentialConfig); - - // Property 4: Session names should be valid - var sessionNameValid = ValidateSessionName(credentialConfig); - - return (sessionDurationValid && autoRefreshValid && expirationWarningValid && sessionNameValid) - .ToProperty() - .Label($"Role: {credentialConfig.RoleName}, Duration: {credentialConfig.SessionDuration.TotalMinutes}m"); - } - - /// - /// Property: IAM policies should enforce least privilege access - /// Tests that IAM policies grant only necessary permissions - /// - [Property(MaxTest = 100)] - public Property IamPoliciesEnforceLeastPrivilege(PositiveInt requiredActionCount, - PositiveInt grantedActionCount, bool includeWildcards, NonEmptyString resourceArn, - PositiveInt resourceWildcardCount) - { - // Generate policy configuration - var actualRequiredActions = Math.Min(requiredActionCount.Get, 15); - var actualGrantedActions = Math.Min(grantedActionCount.Get, 20); - var actualWildcardCount = Math.Min(resourceWildcardCount.Get, 3); - - var policyConfig = GeneratePolicyConfiguration( - actualRequiredActions, - actualGrantedActions, - includeWildcards, - resourceArn.Get, - actualWildcardCount - ); - - // Property 1: Policy should grant all required permissions - var requiredPermissionsGranted = ValidateRequiredPermissions(policyConfig); - - // Property 2: Policy should not grant excessive permissions - var noExcessivePermissions = ValidateNoExcessivePermissions(policyConfig); - - // Property 3: Wildcard permissions should be minimized - var wildcardsMinimized = ValidateWildcardUsage(policyConfig, includeWildcards); - - // Property 4: Resource ARNs should be specific when possible - var resourcesSpecific = ValidateResourceSpecificity(policyConfig); - - // Property 5: Policy should be valid JSON - var policyValid = ValidatePolicyStructure(policyConfig); - - return (requiredPermissionsGranted && noExcessivePermissions && wildcardsMinimized && - resourcesSpecific && policyValid) - .ToProperty() - .Label($"Required: {actualRequiredActions}, Granted: {actualGrantedActions}, Wildcards: {includeWildcards}"); - } - - /// - /// Property: Cross-account IAM access should respect permission boundaries - /// Tests that cross-account access works correctly with boundaries - /// - [Property(MaxTest = 100)] - public Property CrossAccountAccessRespectsPermissionBoundaries(NonEmptyString sourceAccount, - NonEmptyString targetAccount, PositiveInt allowedActionCount, PositiveInt boundaryActionCount, - bool useTrustPolicy, NonEmptyString externalId) - { - // Generate cross-account configuration with different account IDs - var sourceAccountId = SanitizeAccountId(sourceAccount.Get); - var targetAccountId = SanitizeAccountId(targetAccount.Get); - - // Ensure accounts are different for cross-account scenarios - if (sourceAccountId == targetAccountId) - { - targetAccountId = sourceAccountId.Substring(0, 11) + (sourceAccountId[11] == '0' ? '1' : '0'); - } - - // Generate allowed actions first - var allowedActions = GenerateAwsActions(Math.Min(allowedActionCount.Get, 10)); - - // Generate boundary actions that include all allowed actions plus potentially more - // Ensure boundary has at least as many actions as allowed - var totalBoundaryActions = Math.Max(allowedActions.Count, Math.Min(boundaryActionCount.Get, 15)); - var additionalBoundaryActions = totalBoundaryActions - allowedActions.Count; - var boundaryActions = new List(allowedActions); - if (additionalBoundaryActions > 0) - { - boundaryActions.AddRange(GenerateAwsActions(additionalBoundaryActions)); - } - - var crossAccountConfig = new CrossAccountConfiguration - { - SourceAccountId = sourceAccountId, - TargetAccountId = targetAccountId, - AllowedActions = allowedActions, - BoundaryActions = boundaryActions, - UseTrustPolicy = useTrustPolicy, - ExternalId = SanitizeExternalId(externalId.Get) - }; - - // Property 1: Trust policy should be configured for cross-account access - var trustPolicyValid = ValidateTrustPolicy(crossAccountConfig); - - // Property 2: Permission boundary should limit effective permissions - var boundaryEnforced = ValidatePermissionBoundary(crossAccountConfig); - - // Property 3: External ID should be used for security - var externalIdValid = ValidateExternalId(crossAccountConfig); - - // Property 4: Effective permissions should be intersection of policies and boundaries - var effectivePermissionsCorrect = ValidateEffectivePermissions(crossAccountConfig); - - // Property 5: Cross-account access should be auditable - var accessAuditable = ValidateCrossAccountAuditability(crossAccountConfig); - - return (trustPolicyValid && boundaryEnforced && externalIdValid && - effectivePermissionsCorrect && accessAuditable) - .ToProperty() - .Label($"Source: {crossAccountConfig.SourceAccountId}, Target: {crossAccountConfig.TargetAccountId}"); - } - - /// - /// Property: IAM role assumption should validate caller identity - /// Tests that role assumption properly validates the caller - /// - [Property(MaxTest = 100)] - public Property IamRoleAssumptionValidatesCallerIdentity(NonEmptyString principalType, - NonEmptyString principalId, bool requireMfa, bool requireSourceIp, - NonEmptyString ipAddress, PositiveInt maxSessionDuration) - { - // Generate role assumption configuration with AWS constraints - var actualMaxSessionDuration = Math.Max(15, Math.Min(maxSessionDuration.Get, 720)); // 15 min to 12 hours - - var assumptionConfig = new RoleAssumptionConfiguration - { - PrincipalType = SanitizePrincipalType(principalType.Get), - PrincipalId = SanitizePrincipalId(principalId.Get), - RequireMfa = requireMfa, - RequireSourceIp = requireSourceIp, - AllowedIpAddress = SanitizeIpAddress(ipAddress.Get), - MaxSessionDuration = TimeSpan.FromMinutes(actualMaxSessionDuration) - }; - - // Property 1: Principal type should be valid AWS principal - var principalTypeValid = ValidatePrincipalType(assumptionConfig); - - // Property 2: MFA requirement should be enforced when configured - var mfaEnforced = ValidateMfaRequirement(assumptionConfig); - - // Property 3: Source IP restriction should be enforced when configured - var sourceIpEnforced = ValidateSourceIpRestriction(assumptionConfig); - - // Property 4: Session duration should be within AWS limits - var sessionDurationValid = ValidateMaxSessionDuration(assumptionConfig); - - // Property 5: Caller identity should be verifiable - var identityVerifiable = ValidateCallerIdentity(assumptionConfig); - - return (principalTypeValid && mfaEnforced && sourceIpEnforced && - sessionDurationValid && identityVerifiable) - .ToProperty() - .Label($"Principal: {assumptionConfig.PrincipalType}, MFA: {requireMfa}, SourceIP: {requireSourceIp}"); - } - - // Helper Methods - Configuration Generation - - private static IamConfiguration GenerateIamConfiguration(string roleName, int actionCount, - int resourceCount, bool useCrossAccount, bool usePermissionBoundary, - int excessivePermissionCount, int requiredPermissionCount, bool includeWildcardPermissions, - string accountId, int boundaryActionCount) - { - var actions = GenerateAwsActions(actionCount); - - // If permission boundary is used, ensure boundary actions include all regular actions - var boundaryActions = new List(); - if (usePermissionBoundary) - { - boundaryActions.AddRange(actions); - // Ensure boundary has at least as many actions as regular actions - var totalBoundaryActions = Math.Max(actions.Count, boundaryActionCount); - var additionalBoundaryActions = totalBoundaryActions - actions.Count; - if (additionalBoundaryActions > 0) - { - boundaryActions.AddRange(GenerateAwsActions(additionalBoundaryActions)); - } - } - - var config = new IamConfiguration - { - RoleName = SanitizeRoleName(roleName), - Actions = actions, - Resources = GenerateAwsResources(resourceCount), - UseCrossAccount = useCrossAccount, - UsePermissionBoundary = usePermissionBoundary, - ExcessivePermissions = GenerateExcessivePermissions(excessivePermissionCount), - RequiredPermissions = GenerateRequiredPermissions(requiredPermissionCount), - IncludeWildcardPermissions = includeWildcardPermissions, - AccountId = SanitizeAccountId(accountId), - BoundaryActions = boundaryActions - }; - - return config; - } - - private static PolicyConfiguration GeneratePolicyConfiguration(int requiredActionCount, - int grantedActionCount, bool includeWildcards, string resourceArn, int wildcardCount) - { - var requiredActions = GenerateAwsActions(requiredActionCount); - var grantedActions = new List(requiredActions); - - // Add extra granted actions if granted > required - if (grantedActionCount > requiredActionCount) - { - var extraActions = GenerateAwsActions(grantedActionCount - requiredActionCount); - grantedActions.AddRange(extraActions); - } - - return new PolicyConfiguration - { - RequiredActions = requiredActions, - GrantedActions = grantedActions, - IncludeWildcards = includeWildcards, - ResourceArn = SanitizeResourceArn(resourceArn), - WildcardCount = wildcardCount - }; - } - - private static List GenerateAwsActions(int count) - { - var awsServices = new[] { "sqs", "sns", "kms", "s3", "dynamodb", "lambda" }; - var awsOperations = new[] { "SendMessage", "ReceiveMessage", "Publish", "Subscribe", - "Encrypt", "Decrypt", "GetObject", "PutObject", "GetItem", "PutItem", "Invoke" }; - - var actions = new List(); - for (int i = 0; i < count; i++) - { - var service = awsServices[i % awsServices.Length]; - var operation = awsOperations[i % awsOperations.Length]; - actions.Add($"{service}:{operation}"); - } - - return actions.Distinct().ToList(); - } - - private static List GenerateAwsResources(int count) - { - var resources = new List(); - for (int i = 0; i < count; i++) - { - resources.Add($"arn:aws:sqs:us-east-1:123456789012:test-queue-{i}"); - } - return resources; - } - - private static List GenerateExcessivePermissions(int count) - { - var excessive = new[] { "sqs:DeleteQueue", "sqs:*", "sns:DeleteTopic", "kms:DeleteKey", - "s3:DeleteBucket", "dynamodb:DeleteTable" }; - - return excessive.Take(Math.Min(count, excessive.Length)).ToList(); - } - - private static List GenerateRequiredPermissions(int count) - { - var required = new[] { "sqs:SendMessage", "sqs:ReceiveMessage", "sns:Publish", - "kms:Encrypt", "kms:Decrypt", "s3:GetObject", "s3:PutObject" }; - - return required.Take(Math.Min(count, required.Length)).ToList(); - } - - // Helper Methods - Sanitization - - private static string SanitizeRoleName(string input) - { - // IAM role names: alphanumeric, +, =, ,, ., @, -, _ - var sanitized = new string(input.Where(c => char.IsLetterOrDigit(c) || - c == '+' || c == '=' || c == ',' || c == '.' || c == '@' || c == '-' || c == '_').ToArray()); - - // Ensure it starts with alphanumeric - if (string.IsNullOrEmpty(sanitized) || !char.IsLetterOrDigit(sanitized[0])) - sanitized = "TestRole" + sanitized; - - // Limit length to 64 characters (AWS limit) - return sanitized.Length > 64 ? sanitized.Substring(0, 64) : sanitized; - } - - private static string SanitizeAccountId(string input) - { - // AWS account IDs are 12-digit numbers - var digits = new string(input.Where(char.IsDigit).ToArray()); - - if (string.IsNullOrEmpty(digits)) - return "123456789012"; - - // Pad or truncate to 12 digits - if (digits.Length < 12) - digits = digits.PadLeft(12, '0'); - else if (digits.Length > 12) - digits = digits.Substring(0, 12); - - return digits; - } - - private static string SanitizeResourceArn(string input) - { - // Basic ARN format: arn:partition:service:region:account-id:resource - if (string.IsNullOrWhiteSpace(input)) - return "arn:aws:sqs:us-east-1:123456789012:test-queue"; - - // If it looks like an ARN, use it; otherwise create one - if (input.StartsWith("arn:")) - return input; - - var sanitized = new string(input.Where(c => char.IsLetterOrDigit(c) || c == '-' || c == '_').ToArray()); - return $"arn:aws:sqs:us-east-1:123456789012:{sanitized}"; - } - - private static string SanitizeSessionName(string input) - { - // Session names: alphanumeric, =, ,, ., @, - - var sanitized = new string(input.Where(c => char.IsLetterOrDigit(c) || - c == '=' || c == ',' || c == '.' || c == '@' || c == '-').ToArray()); - - if (string.IsNullOrEmpty(sanitized)) - sanitized = "TestSession"; - - // Limit to 64 characters - return sanitized.Length > 64 ? sanitized.Substring(0, 64) : sanitized; - } - - private static string SanitizeExternalId(string input) - { - // External IDs can be any string, but keep it reasonable - if (string.IsNullOrWhiteSpace(input)) - return "external-id-12345"; - - var sanitized = new string(input.Where(c => char.IsLetterOrDigit(c) || c == '-' || c == '_').ToArray()); - if (string.IsNullOrEmpty(sanitized) || sanitized.Length < 2) - return "external-id-12345"; - return sanitized; - } - - private static string SanitizePrincipalType(string input) - { - // Valid principal types: Service, AWS, Federated - var validTypes = new[] { "Service", "AWS", "Federated" }; - - foreach (var type in validTypes) - { - if (input.Contains(type, StringComparison.OrdinalIgnoreCase)) - return type; - } - - return "Service"; // Default - } - - private static string SanitizePrincipalId(string input) - { - var sanitized = new string(input.Where(c => char.IsLetterOrDigit(c) || - c == '.' || c == '-' || c == '_' || c == ':' || c == '/').ToArray()); - - if (string.IsNullOrEmpty(sanitized)) - return "sqs.amazonaws.com"; - - return sanitized; - } - - private static string SanitizeIpAddress(string input) - { - // Simple IP address sanitization - var parts = input.Split('.').Take(4).ToArray(); - var ipParts = new List(); - - foreach (var part in parts) - { - var digits = new string(part.Where(char.IsDigit).ToArray()); - if (!string.IsNullOrEmpty(digits)) - { - var value = int.Parse(digits); - ipParts.Add(Math.Min(value, 255).ToString()); - } - } - - while (ipParts.Count < 4) - ipParts.Add("0"); - - return string.Join(".", ipParts.Take(4)); - } - - // Validation Methods - Role Authentication (Requirement 8.1) - - private static bool ValidateRoleAuthentication(IamConfiguration config) - { - // Role name should be valid - var roleNameValid = !string.IsNullOrWhiteSpace(config.RoleName) && - config.RoleName.Length <= 64 && - config.RoleName.Length >= 1 && - char.IsLetterOrDigit(config.RoleName[0]); - - // Role should have actions defined (at least one) - var hasActions = config.Actions != null && config.Actions.Count > 0; - - // Role should have resources defined (at least one) - var hasResources = config.Resources != null && config.Resources.Count > 0; - - // Account ID should be valid (12 digits) - var accountIdValid = !string.IsNullOrWhiteSpace(config.AccountId) && - config.AccountId.Length == 12 && - config.AccountId.All(char.IsDigit); - - // Role authentication requires all components - return roleNameValid && hasActions && hasResources && accountIdValid; - } - - // Validation Methods - Least Privilege (Requirement 8.2) - - private static bool ValidateLeastPrivilege(IamConfiguration config) - { - // Should not have excessive permissions - var noExcessivePermissions = config.ExcessivePermissions == null || - config.ExcessivePermissions.Count == 0 || - !config.Actions.Any(a => config.ExcessivePermissions.Contains(a)); - - // Should have required permissions (if any are specified) - // Be very lenient: the test generation doesn't guarantee that required permissions - // match the generated actions, so we just check that if there ARE required permissions, - // at least ONE of them is granted (or there are no required permissions specified) - var hasRequiredPermissions = config.RequiredPermissions == null || - config.RequiredPermissions.Count == 0 || - config.Actions.Count == 0 || // No actions means no validation needed - config.RequiredPermissions.Any(rp => config.Actions.Contains(rp)); - - // Wildcard permissions should be minimized when flag is set - // Allow flexibility: wildcards can be 0 if not generated, or up to half of actions - var wildcardCount = config.Actions.Count(a => a.EndsWith(":*") || a == "*"); - var wildcardsMinimized = !config.IncludeWildcardPermissions || - wildcardCount == 0 || - wildcardCount <= Math.Max(2, config.Actions.Count / 2); - - // Actions should be specific to services (contain colon or be wildcard) - var actionsSpecific = config.Actions.All(a => a.Contains(':') || a == "*"); - - return noExcessivePermissions && hasRequiredPermissions && wildcardsMinimized && actionsSpecific; - } - - // Validation Methods - Cross-Account Access (Requirement 8.3) - - private static bool ValidateCrossAccountAccess(IamConfiguration config) - { - if (!config.UseCrossAccount) - return true; // Not testing cross-account, so valid - - // Cross-account requires valid account IDs - var accountIdValid = !string.IsNullOrWhiteSpace(config.AccountId) && - config.AccountId.Length == 12 && - config.AccountId.All(char.IsDigit); - - // Permission boundary should be configured for cross-account when enabled - var boundaryConfigured = !config.UsePermissionBoundary || - (config.BoundaryActions != null && config.BoundaryActions.Count > 0); - - // Boundary actions should limit granted actions when boundary is used - // Be lenient: if boundary is empty or not configured, that's valid - // If boundary is configured, it should include all actions or have wildcards - var boundaryLimitsActions = !config.UsePermissionBoundary || - config.BoundaryActions == null || - config.BoundaryActions.Count == 0 || - config.Actions.Count == 0 || // No actions to validate - config.Actions.All(a => config.BoundaryActions.Contains(a) || - config.BoundaryActions.Any(ba => ba.EndsWith(":*") || ba == "*")); - - // Cross-account access should be auditable (has required identifiers) - var auditable = !string.IsNullOrWhiteSpace(config.RoleName) && - !string.IsNullOrWhiteSpace(config.AccountId); - - return accountIdValid && boundaryConfigured && boundaryLimitsActions && auditable; - } - - // Validation Methods - Credential Management - - private static bool ValidateSessionDuration(IamCredentialConfiguration config) - { - // Session duration should be between 15 minutes and 12 hours - return config.SessionDuration >= TimeSpan.FromMinutes(15) && - config.SessionDuration <= TimeSpan.FromHours(12); - } - - private static bool ValidateAutoRefresh(IamCredentialConfiguration config) - { - // If auto-refresh is enabled, expiration warning should be set - if (config.AutoRefresh) - { - return config.ExpirationWarning > TimeSpan.Zero && - config.ExpirationWarning < config.SessionDuration; - } - - return true; // Auto-refresh not enabled, so valid - } - - private static bool ValidateExpirationWarning(IamCredentialConfiguration config) - { - // Expiration warning should be reasonable (not too short, not longer than session) - return config.ExpirationWarning >= TimeSpan.FromMinutes(1) && - config.ExpirationWarning <= config.SessionDuration; - } - - private static bool ValidateSessionName(IamCredentialConfiguration config) - { - // Session name should be valid and not empty - return !string.IsNullOrWhiteSpace(config.SessionName) && - config.SessionName.Length <= 64; - } - - // Validation Methods - Policy Configuration - - private static bool ValidateRequiredPermissions(PolicyConfiguration config) - { - // All required actions should be in granted actions - return config.RequiredActions.All(ra => config.GrantedActions.Contains(ra)); - } - - private static bool ValidateNoExcessivePermissions(PolicyConfiguration config) - { - // Granted actions should not be significantly more than required - // For property testing, be more lenient: allow up to 5x required or required + 15 - // This accounts for the random nature of property-based test generation - var excessiveThreshold = Math.Max(config.RequiredActions.Count * 5, config.RequiredActions.Count + 15); - return config.GrantedActions.Count <= excessiveThreshold; - } - - private static bool ValidateWildcardUsage(PolicyConfiguration config, bool wildcardsExpected) - { - var wildcardCount = config.GrantedActions.Count(a => a.EndsWith(":*") || a == "*"); - - if (!wildcardsExpected) - { - // Wildcards should be minimal or absent - return wildcardCount <= 1; - } - - // If wildcards are expected, they should be limited (but can be 0 if not generated) - // Allow up to the specified count or a reasonable default - return wildcardCount <= Math.Max(config.WildcardCount, config.GrantedActions.Count / 2); - } - - private static bool ValidateResourceSpecificity(PolicyConfiguration config) - { - // Resource ARN should be specific (not just "*") - if (config.ResourceArn == "*") - return false; - - // Should follow ARN format - return config.ResourceArn.StartsWith("arn:"); - } - - private static bool ValidatePolicyStructure(PolicyConfiguration config) - { - // Policy should have valid structure - var hasActions = config.GrantedActions != null && config.GrantedActions.Count > 0; - var hasResource = !string.IsNullOrWhiteSpace(config.ResourceArn); - var actionsValid = config.GrantedActions.All(a => a.Contains(':') || a == "*"); - - return hasActions && hasResource && actionsValid; - } - - // Validation Methods - Cross-Account Configuration - - private static bool ValidateTrustPolicy(CrossAccountConfiguration config) - { - if (!config.UseTrustPolicy) - return true; // Trust policy not required - - // Trust policy requires valid source and target accounts - // Be lenient: if accounts are the same, that's a test generation issue, not a validation failure - // The important thing is that both accounts are valid 12-digit IDs - var accountsValid = config.SourceAccountId.Length == 12 && - config.TargetAccountId.Length == 12; - - return accountsValid; - } - - private static bool ValidatePermissionBoundary(CrossAccountConfiguration config) - { - // Permission boundary should limit actions - // If no boundary actions, that's valid (no boundary configured) - if (config.BoundaryActions == null || config.BoundaryActions.Count == 0) - return true; // No boundary is valid - - // If no allowed actions, that's valid - if (config.AllowedActions == null || config.AllowedActions.Count == 0) - return true; - - // Boundary should be more restrictive or equal to allowed actions - // Be very lenient: if any allowed action is in the boundary or there's a wildcard, it's valid - var boundaryRestrictive = config.AllowedActions.Count == 0 || - config.AllowedActions.All(aa => - config.BoundaryActions.Contains(aa) || - config.BoundaryActions.Any(ba => ba.EndsWith(":*") || ba == "*")); - - return boundaryRestrictive; - } - - private static bool ValidateExternalId(CrossAccountConfiguration config) - { - // External ID should be present and non-empty for cross-account - return !string.IsNullOrWhiteSpace(config.ExternalId) && - config.ExternalId.Length >= 2; - } - - private static bool ValidateEffectivePermissions(CrossAccountConfiguration config) - { - // Effective permissions are intersection of allowed and boundary - // If no boundary actions are defined, that's valid (no boundary configured) - if (config.BoundaryActions == null || config.BoundaryActions.Count == 0) - return true; - - // If no allowed actions, that's valid - if (config.AllowedActions == null || config.AllowedActions.Count == 0) - return true; - - // All allowed actions should be within boundary - return config.AllowedActions.All(aa => - config.BoundaryActions.Contains(aa) || - config.BoundaryActions.Any(ba => (ba.EndsWith(":*") && aa.StartsWith(ba.Replace(":*", ":"))) || ba == "*")); - } - - private static bool ValidateCrossAccountAuditability(CrossAccountConfiguration config) - { - // Cross-account access should have identifiable components - var hasSourceAccount = !string.IsNullOrWhiteSpace(config.SourceAccountId); - var hasTargetAccount = !string.IsNullOrWhiteSpace(config.TargetAccountId); - var hasExternalId = !string.IsNullOrWhiteSpace(config.ExternalId); - - return hasSourceAccount && hasTargetAccount && hasExternalId; - } - - // Validation Methods - Role Assumption - - private static bool ValidatePrincipalType(RoleAssumptionConfiguration config) - { - // Principal type should be one of the valid AWS types - var validTypes = new[] { "Service", "AWS", "Federated" }; - return validTypes.Contains(config.PrincipalType); - } - - private static bool ValidateMfaRequirement(RoleAssumptionConfiguration config) - { - // If MFA is required, it should be enforceable - // In property testing, we validate the configuration is consistent - return true; // MFA requirement is a boolean flag, always valid - } - - private static bool ValidateSourceIpRestriction(RoleAssumptionConfiguration config) - { - if (!config.RequireSourceIp) - return true; // IP restriction not required - - // IP address should be valid format - var parts = config.AllowedIpAddress.Split('.'); - if (parts.Length != 4) - return false; - - return parts.All(p => int.TryParse(p, out var value) && value >= 0 && value <= 255); - } - - private static bool ValidateMaxSessionDuration(RoleAssumptionConfiguration config) - { - // Session duration should be within AWS limits (15 min to 12 hours) - return config.MaxSessionDuration >= TimeSpan.FromMinutes(15) && - config.MaxSessionDuration <= TimeSpan.FromHours(12); - } - - private static bool ValidateCallerIdentity(RoleAssumptionConfiguration config) - { - // Caller identity should be verifiable through principal - var hasPrincipalType = !string.IsNullOrWhiteSpace(config.PrincipalType); - var hasPrincipalId = !string.IsNullOrWhiteSpace(config.PrincipalId); - - return hasPrincipalType && hasPrincipalId; - } -} - - -/// -/// IAM configuration for property testing -/// -public class IamConfiguration -{ - public string RoleName { get; set; } = ""; - public List Actions { get; set; } = new(); - public List Resources { get; set; } = new(); - public bool UseCrossAccount { get; set; } - public bool UsePermissionBoundary { get; set; } - public List ExcessivePermissions { get; set; } = new(); - public List RequiredPermissions { get; set; } = new(); - public bool IncludeWildcardPermissions { get; set; } - public string AccountId { get; set; } = ""; - public List BoundaryActions { get; set; } = new(); -} - -/// -/// IAM credential configuration for property testing -/// -public class IamCredentialConfiguration -{ - public string RoleName { get; set; } = ""; - public TimeSpan SessionDuration { get; set; } - public bool AutoRefresh { get; set; } - public TimeSpan ExpirationWarning { get; set; } - public string SessionName { get; set; } = ""; -} - -/// -/// IAM policy configuration for property testing -/// -public class PolicyConfiguration -{ - public List RequiredActions { get; set; } = new(); - public List GrantedActions { get; set; } = new(); - public bool IncludeWildcards { get; set; } - public string ResourceArn { get; set; } = ""; - public int WildcardCount { get; set; } -} - -/// -/// Cross-account IAM configuration for property testing -/// -public class CrossAccountConfiguration -{ - public string SourceAccountId { get; set; } = ""; - public string TargetAccountId { get; set; } = ""; - public List AllowedActions { get; set; } = new(); - public List BoundaryActions { get; set; } = new(); - public bool UseTrustPolicy { get; set; } - public string ExternalId { get; set; } = ""; -} - -/// -/// Role assumption configuration for property testing -/// -public class RoleAssumptionConfiguration -{ - public string PrincipalType { get; set; } = ""; - public string PrincipalId { get; set; } = ""; - public bool RequireMfa { get; set; } - public bool RequireSourceIp { get; set; } - public string AllowedIpAddress { get; set; } = ""; - public TimeSpan MaxSessionDuration { get; set; } -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/SourceFlow.Cloud.AWS.Tests.csproj b/tests/SourceFlow.Cloud.AWS.Tests/SourceFlow.Cloud.AWS.Tests.csproj deleted file mode 100644 index c59ac3a1..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/SourceFlow.Cloud.AWS.Tests.csproj +++ /dev/null @@ -1,88 +0,0 @@ - - - - net9.0 - latest - enable - enable - false - true - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/AwsIntegrationTestBase.cs b/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/AwsIntegrationTestBase.cs deleted file mode 100644 index d723283c..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/AwsIntegrationTestBase.cs +++ /dev/null @@ -1,84 +0,0 @@ -using Xunit; -using Xunit.Abstractions; - -namespace SourceFlow.Cloud.AWS.Tests.TestHelpers; - -/// -/// Base class for AWS integration tests that require external services. -/// Validates service availability before running tests and skips gracefully if unavailable. -/// -public abstract class AwsIntegrationTestBase : IAsyncLifetime -{ - protected readonly ITestOutputHelper Output; - protected readonly AwsTestConfiguration Configuration; - - protected AwsIntegrationTestBase(ITestOutputHelper output) - { - Output = output; - Configuration = new AwsTestConfiguration(); - } - - /// - /// Initializes the test by validating service availability. - /// Override this method to add custom initialization logic. - /// - public virtual async Task InitializeAsync() - { - await ValidateServiceAvailabilityAsync(); - } - - /// - /// Cleans up test resources. - /// Override this method to add custom cleanup logic. - /// - public virtual Task DisposeAsync() - { - return Task.CompletedTask; - } - - /// - /// Validates that required AWS services are available. - /// Override this method to customize which services to check. - /// - protected virtual async Task ValidateServiceAvailabilityAsync() - { - // Default implementation - subclasses should override - await Task.CompletedTask; - } - - /// - /// Creates a skip message with actionable guidance for the user. - /// - protected string CreateSkipMessage(string serviceName, bool requiresLocalStack, bool requiresAws) - { - var message = $"{serviceName} is not available.\n\n"; - message += "Options:\n"; - - if (requiresLocalStack) - { - message += "1. Start LocalStack:\n"; - message += " docker run -d -p 4566:4566 localstack/localstack\n"; - message += " OR\n"; - message += " localstack start\n\n"; - } - - if (requiresAws) - { - message += $"2. Configure real AWS {serviceName}:\n"; - - if (serviceName.Contains("SQS") || serviceName.Contains("SNS") || serviceName.Contains("KMS")) - { - message += " set AWS_ACCESS_KEY_ID=your-access-key\n"; - message += " set AWS_SECRET_ACCESS_KEY=your-secret-key\n"; - message += " set AWS_REGION=us-east-1\n\n"; - } - } - - message += "3. Skip integration tests:\n"; - message += " dotnet test --filter \"Category!=Integration\"\n\n"; - - message += "For more information, see: tests/SourceFlow.Cloud.AWS.Tests/README.md"; - - return message; - } -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/AwsIntegrationTestCollection.cs b/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/AwsIntegrationTestCollection.cs deleted file mode 100644 index 5284f865..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/AwsIntegrationTestCollection.cs +++ /dev/null @@ -1,24 +0,0 @@ -namespace SourceFlow.Cloud.AWS.Tests.TestHelpers; - -/// -/// xUnit collection definition for AWS integration tests -/// -/// This collection ensures that all tests marked with [Collection("AWS Integration Tests")] -/// share a single LocalStackTestFixture instance, preventing port conflicts and reducing -/// container startup overhead. -/// -/// Without this collection definition, xUnit would create separate fixture instances per -/// test class, causing multiple LocalStack containers to attempt binding to port 4566 -/// simultaneously, resulting in "port is already allocated" errors. -/// -/// Usage: -/// [Collection("AWS Integration Tests")] -/// public class MyIntegrationTests { ... } -/// -[CollectionDefinition("AWS Integration Tests")] -public class AwsIntegrationTestCollection : ICollectionFixture -{ - // This class has no code, and is never created. Its purpose is simply - // to be the place to apply [CollectionDefinition] and all the - // ICollectionFixture<> interfaces. -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/AwsRequiredTestBase.cs b/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/AwsRequiredTestBase.cs deleted file mode 100644 index 263535a3..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/AwsRequiredTestBase.cs +++ /dev/null @@ -1,77 +0,0 @@ -using Xunit; -using Xunit.Abstractions; - -namespace SourceFlow.Cloud.AWS.Tests.TestHelpers; - -/// -/// Base class for tests that require real AWS services. -/// Validates AWS service availability before running tests. -/// -public abstract class AwsRequiredTestBase : AwsIntegrationTestBase -{ - private readonly bool _requiresSqs; - private readonly bool _requiresSns; - private readonly bool _requiresKms; - - protected AwsRequiredTestBase( - ITestOutputHelper output, - bool requiresSqs = true, - bool requiresSns = false, - bool requiresKms = false) : base(output) - { - _requiresSqs = requiresSqs; - _requiresSns = requiresSns; - _requiresKms = requiresKms; - } - - /// - /// Validates that required AWS services are available. - /// - protected override async Task ValidateServiceAvailabilityAsync() - { - if (_requiresSqs) - { - Output.WriteLine("Checking AWS SQS availability..."); - var isSqsAvailable = await Configuration.IsSqsAvailableAsync(AwsTestDefaults.ConnectionTimeout); - - if (!isSqsAvailable) - { - var skipMessage = CreateSkipMessage("AWS SQS", requiresLocalStack: false, requiresAws: true); - Output.WriteLine($"SKIPPED: {skipMessage}"); - throw new InvalidOperationException($"Test skipped: {skipMessage}"); - } - - Output.WriteLine("AWS SQS is available."); - } - - if (_requiresSns) - { - Output.WriteLine("Checking AWS SNS availability..."); - var isSnsAvailable = await Configuration.IsSnsAvailableAsync(AwsTestDefaults.ConnectionTimeout); - - if (!isSnsAvailable) - { - var skipMessage = CreateSkipMessage("AWS SNS", requiresLocalStack: false, requiresAws: true); - Output.WriteLine($"SKIPPED: {skipMessage}"); - throw new InvalidOperationException($"Test skipped: {skipMessage}"); - } - - Output.WriteLine("AWS SNS is available."); - } - - if (_requiresKms) - { - Output.WriteLine("Checking AWS KMS availability..."); - var isKmsAvailable = await Configuration.IsKmsAvailableAsync(AwsTestDefaults.ConnectionTimeout); - - if (!isKmsAvailable) - { - var skipMessage = CreateSkipMessage("AWS KMS", requiresLocalStack: false, requiresAws: true); - Output.WriteLine($"SKIPPED: {skipMessage}"); - throw new InvalidOperationException($"Test skipped: {skipMessage}"); - } - - Output.WriteLine("AWS KMS is available."); - } - } -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/AwsResourceManager.cs b/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/AwsResourceManager.cs deleted file mode 100644 index dc731ed1..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/AwsResourceManager.cs +++ /dev/null @@ -1,530 +0,0 @@ -using Amazon.CloudFormation; -using Amazon.CloudFormation.Model; -using Microsoft.Extensions.Logging; - -namespace SourceFlow.Cloud.AWS.Tests.TestHelpers; - -/// -/// AWS resource manager implementation -/// Provides automated provisioning, tracking, and cleanup of AWS resources for testing -/// -public class AwsResourceManager : IAwsResourceManager -{ - private readonly IAwsTestEnvironment _testEnvironment; - private readonly ILogger _logger; - private readonly List _trackedResources; - private readonly object _lock = new(); - private bool _disposed; - - public AwsResourceManager(IAwsTestEnvironment testEnvironment, ILogger logger) - { - _testEnvironment = testEnvironment ?? throw new ArgumentNullException(nameof(testEnvironment)); - _logger = logger ?? throw new ArgumentNullException(nameof(logger)); - _trackedResources = new List(); - } - - /// - public async Task CreateTestResourcesAsync(string testPrefix, AwsResourceTypes resourceTypes = AwsResourceTypes.All) - { - if (string.IsNullOrWhiteSpace(testPrefix)) - throw new ArgumentException("Test prefix cannot be null or empty", nameof(testPrefix)); - - _logger.LogInformation("Creating AWS test resources with prefix: {TestPrefix}", testPrefix); - - var resourceSet = new AwsResourceSet - { - TestPrefix = testPrefix, - Tags = new Dictionary - { - ["TestPrefix"] = testPrefix, - ["CreatedBy"] = "SourceFlow.Tests", - ["Environment"] = "Test", - ["CreatedAt"] = DateTime.UtcNow.ToString("yyyy-MM-ddTHH:mm:ssZ") - } - }; - - try - { - // Create SQS queues - if (resourceTypes.HasFlag(AwsResourceTypes.SqsQueues)) - { - await CreateSqsResourcesAsync(resourceSet); - } - - // Create SNS topics - if (resourceTypes.HasFlag(AwsResourceTypes.SnsTopics)) - { - await CreateSnsResourcesAsync(resourceSet); - } - - // Create KMS keys - if (resourceTypes.HasFlag(AwsResourceTypes.KmsKeys)) - { - await CreateKmsResourcesAsync(resourceSet); - } - - // Create IAM roles (if supported) - if (resourceTypes.HasFlag(AwsResourceTypes.IamRoles)) - { - await CreateIamResourcesAsync(resourceSet); - } - - // Track the resource set - lock (_lock) - { - _trackedResources.Add(resourceSet); - } - - _logger.LogInformation("Created AWS test resources: {QueueCount} queues, {TopicCount} topics, {KeyCount} keys, {RoleCount} roles", - resourceSet.QueueUrls.Count, resourceSet.TopicArns.Count, resourceSet.KmsKeyIds.Count, resourceSet.IamRoleArns.Count); - - return resourceSet; - } - catch (Exception ex) - { - _logger.LogError(ex, "Failed to create test resources for prefix: {TestPrefix}", testPrefix); - - // Attempt cleanup of partially created resources - try - { - await CleanupResourcesAsync(resourceSet, force: true); - } - catch (Exception cleanupEx) - { - _logger.LogWarning(cleanupEx, "Failed to cleanup partially created resources"); - } - - throw; - } - } - - /// - public async Task CleanupResourcesAsync(AwsResourceSet resources, bool force = false) - { - if (resources == null || resources.IsEmpty) - return; - - _logger.LogInformation("Cleaning up AWS test resources for prefix: {TestPrefix}", resources.TestPrefix); - - var errors = new List(); - - // Cleanup CloudFormation stacks first (they may contain other resources) - foreach (var stackArn in resources.CloudFormationStacks.ToList()) - { - try - { - await DeleteCloudFormationStackAsync(stackArn); - resources.CloudFormationStacks.Remove(stackArn); - } - catch (Exception ex) - { - errors.Add($"Failed to delete CloudFormation stack {stackArn}: {ex.Message}"); - if (!force) throw; - } - } - - // Cleanup SQS queues - foreach (var queueUrl in resources.QueueUrls.ToList()) - { - try - { - await _testEnvironment.DeleteQueueAsync(queueUrl); - resources.QueueUrls.Remove(queueUrl); - } - catch (Exception ex) - { - errors.Add($"Failed to delete queue {queueUrl}: {ex.Message}"); - if (!force) throw; - } - } - - // Cleanup SNS topics - foreach (var topicArn in resources.TopicArns.ToList()) - { - try - { - await _testEnvironment.DeleteTopicAsync(topicArn); - resources.TopicArns.Remove(topicArn); - } - catch (Exception ex) - { - errors.Add($"Failed to delete topic {topicArn}: {ex.Message}"); - if (!force) throw; - } - } - - // Cleanup KMS keys (schedule for deletion) - foreach (var keyId in resources.KmsKeyIds.ToList()) - { - try - { - await _testEnvironment.DeleteKmsKeyAsync(keyId, pendingWindowInDays: 7); - resources.KmsKeyIds.Remove(keyId); - } - catch (Exception ex) - { - errors.Add($"Failed to delete KMS key {keyId}: {ex.Message}"); - if (!force) throw; - } - } - - // Remove from tracked resources - lock (_lock) - { - _trackedResources.Remove(resources); - } - - if (errors.Any()) - { - _logger.LogWarning("Cleanup completed with errors: {Errors}", string.Join("; ", errors)); - } - else - { - _logger.LogInformation("Successfully cleaned up all resources for prefix: {TestPrefix}", resources.TestPrefix); - } - } - - /// - public async Task ResourceExistsAsync(string resourceArn) - { - if (string.IsNullOrWhiteSpace(resourceArn)) - return false; - - try - { - // Determine resource type from ARN and check existence - if (resourceArn.Contains(":sqs:")) - { - // For SQS, we need to convert ARN to URL or use the URL directly - var queueUrl = resourceArn.StartsWith("https://") ? resourceArn : ConvertSqsArnToUrl(resourceArn); - var response = await _testEnvironment.SqsClient.GetQueueAttributesAsync(new Amazon.SQS.Model.GetQueueAttributesRequest - { - QueueUrl = queueUrl, - AttributeNames = new List { "QueueArn" } - }); - return response != null; - } - else if (resourceArn.Contains(":sns:")) - { - var response = await _testEnvironment.SnsClient.GetTopicAttributesAsync(new Amazon.SimpleNotificationService.Model.GetTopicAttributesRequest - { - TopicArn = resourceArn - }); - return response != null; - } - else if (resourceArn.Contains(":kms:")) - { - var response = await _testEnvironment.KmsClient.DescribeKeyAsync(new Amazon.KeyManagementService.Model.DescribeKeyRequest - { - KeyId = resourceArn - }); - return response?.KeyMetadata != null; - } - - return false; - } - catch - { - return false; - } - } - - /// - public async Task> ListTestResourcesAsync(string testPrefix) - { - var resources = new List(); - - try - { - // List SQS queues - var queueResponse = await _testEnvironment.SqsClient.ListQueuesAsync(new Amazon.SQS.Model.ListQueuesRequest - { - QueueNamePrefix = testPrefix - }); - resources.AddRange(queueResponse.QueueUrls); - - // List SNS topics (no prefix filter available, need to filter manually) - var topicResponse = await _testEnvironment.SnsClient.ListTopicsAsync(new Amazon.SimpleNotificationService.Model.ListTopicsRequest()); - var filteredTopics = topicResponse.Topics - .Where(t => t.TopicArn.Contains(testPrefix)) - .Select(t => t.TopicArn); - resources.AddRange(filteredTopics); - - // List KMS keys (no prefix filter, need to check aliases) - try - { - var keyResponse = await _testEnvironment.KmsClient.ListAliasesAsync(new Amazon.KeyManagementService.Model.ListAliasesRequest()); - var filteredKeys = keyResponse.Aliases - .Where(a => a.AliasName.Contains(testPrefix)) - .Select(a => a.TargetKeyId) - .Where(k => !string.IsNullOrEmpty(k)); - resources.AddRange(filteredKeys!); - } - catch (Exception ex) - { - _logger.LogDebug("Failed to list KMS keys: {Error}", ex.Message); - } - } - catch (Exception ex) - { - _logger.LogWarning(ex, "Failed to list some test resources for prefix: {TestPrefix}", testPrefix); - } - - return resources; - } - - /// - public async Task CleanupOldResourcesAsync(TimeSpan maxAge, string? testPrefix = null) - { - var cutoffTime = DateTime.UtcNow - maxAge; - var cleanedCount = 0; - - List resourcesToCleanup; - lock (_lock) - { - resourcesToCleanup = _trackedResources - .Where(r => r.CreatedAt < cutoffTime) - .Where(r => testPrefix == null || r.TestPrefix.StartsWith(testPrefix)) - .ToList(); - } - - foreach (var resourceSet in resourcesToCleanup) - { - try - { - await CleanupResourcesAsync(resourceSet, force: true); - cleanedCount++; - } - catch (Exception ex) - { - _logger.LogWarning(ex, "Failed to cleanup old resource set: {TestPrefix}", resourceSet.TestPrefix); - } - } - - _logger.LogInformation("Cleaned up {Count} old resource sets older than {MaxAge}", cleanedCount, maxAge); - return cleanedCount; - } - - /// - public async Task EstimateCostAsync(AwsResourceSet resources, TimeSpan duration) - { - // This is a simplified cost estimation - // In a real implementation, you would use AWS Pricing API or Cost Explorer - - decimal estimatedCost = 0; - - // SQS: $0.40 per million requests (very rough estimate) - estimatedCost += resources.QueueUrls.Count * 0.01m; - - // SNS: $0.50 per million requests - estimatedCost += resources.TopicArns.Count * 0.01m; - - // KMS: $1.00 per key per month - var monthlyFraction = (decimal)duration.TotalDays / 30; - estimatedCost += resources.KmsKeyIds.Count * 1.00m * monthlyFraction; - - await Task.CompletedTask; // Placeholder for async pricing API calls - - return estimatedCost; - } - - /// - public async Task TagResourceAsync(string resourceArn, Dictionary tags) - { - // AWS resource tagging is service-specific - // This is a simplified implementation - - try - { - if (resourceArn.Contains(":sqs:")) - { - var queueUrl = resourceArn.StartsWith("https://") ? resourceArn : ConvertSqsArnToUrl(resourceArn); - await _testEnvironment.SqsClient.TagQueueAsync(new Amazon.SQS.Model.TagQueueRequest - { - QueueUrl = queueUrl, - Tags = tags - }); - } - else if (resourceArn.Contains(":sns:")) - { - var tagList = tags.Select(kvp => new Amazon.SimpleNotificationService.Model.Tag - { - Key = kvp.Key, - Value = kvp.Value - }).ToList(); - - await _testEnvironment.SnsClient.TagResourceAsync(new Amazon.SimpleNotificationService.Model.TagResourceRequest - { - ResourceArn = resourceArn, - Tags = tagList - }); - } - // KMS and IAM tagging would be implemented similarly - } - catch (Exception ex) - { - _logger.LogWarning(ex, "Failed to tag resource {ResourceArn}", resourceArn); - } - } - - /// - public async Task CreateCloudFormationStackAsync(string stackName, string templateBody, Dictionary? parameters = null) - { - if (_testEnvironment.IsLocalEmulator) - { - _logger.LogWarning("CloudFormation is not supported in LocalStack free tier"); - throw new NotSupportedException("CloudFormation is not supported in LocalStack free tier"); - } - - var cfClient = new AmazonCloudFormationClient(); - - var request = new CreateStackRequest - { - StackName = stackName, - TemplateBody = templateBody, - Capabilities = new List { "CAPABILITY_IAM" } - }; - - if (parameters != null) - { - request.Parameters = parameters.Select(kvp => new Parameter - { - ParameterKey = kvp.Key, - ParameterValue = kvp.Value - }).ToList(); - } - - var response = await cfClient.CreateStackAsync(request); - return response.StackId; - } - - /// - public async Task DeleteCloudFormationStackAsync(string stackName) - { - if (_testEnvironment.IsLocalEmulator) - { - return; // CloudFormation not supported in LocalStack - } - - var cfClient = new AmazonCloudFormationClient(); - await cfClient.DeleteStackAsync(new DeleteStackRequest - { - StackName = stackName - }); - } - - /// - public async ValueTask DisposeAsync() - { - if (_disposed) return; - - _logger.LogInformation("Disposing AWS resource manager and cleaning up tracked resources"); - - List resourcesToCleanup; - lock (_lock) - { - resourcesToCleanup = _trackedResources.ToList(); - } - - foreach (var resourceSet in resourcesToCleanup) - { - try - { - await CleanupResourcesAsync(resourceSet, force: true); - } - catch (Exception ex) - { - _logger.LogWarning(ex, "Failed to cleanup resource set during disposal: {TestPrefix}", resourceSet.TestPrefix); - } - } - - _disposed = true; - } - - private async Task CreateSqsResourcesAsync(AwsResourceSet resourceSet) - { - var prefix = resourceSet.TestPrefix; - - // Create standard queue - var standardQueueUrl = await _testEnvironment.CreateStandardQueueAsync($"{prefix}-standard-queue"); - resourceSet.QueueUrls.Add(standardQueueUrl); - - // Create FIFO queue - var fifoQueueUrl = await _testEnvironment.CreateFifoQueueAsync($"{prefix}-fifo-queue"); - resourceSet.QueueUrls.Add(fifoQueueUrl); - - // Tag queues - foreach (var queueUrl in new[] { standardQueueUrl, fifoQueueUrl }) - { - await TagResourceAsync(queueUrl, resourceSet.Tags); - } - } - - private async Task CreateSnsResourcesAsync(AwsResourceSet resourceSet) - { - var prefix = resourceSet.TestPrefix; - - // Create topic - var topicArn = await _testEnvironment.CreateTopicAsync($"{prefix}-topic"); - resourceSet.TopicArns.Add(topicArn); - - // Tag topic - await TagResourceAsync(topicArn, resourceSet.Tags); - } - - private async Task CreateKmsResourcesAsync(AwsResourceSet resourceSet) - { - try - { - var prefix = resourceSet.TestPrefix; - - // Create KMS key - var keyId = await _testEnvironment.CreateKmsKeyAsync($"{prefix}-key", $"Test key for {prefix}"); - resourceSet.KmsKeyIds.Add(keyId); - } - catch (Exception ex) - { - _logger.LogWarning("Failed to create KMS resources (might not be supported in LocalStack): {Error}", ex.Message); - } - } - - private async Task CreateIamResourcesAsync(AwsResourceSet resourceSet) - { - try - { - // IAM role creation is complex and might not be needed for basic tests - // This is a placeholder for future implementation - await Task.CompletedTask; - } - catch (Exception ex) - { - _logger.LogWarning("Failed to create IAM resources: {Error}", ex.Message); - } - } - - private string ConvertSqsArnToUrl(string arn) - { - // Convert SQS ARN to URL format - // ARN format: arn:aws:sqs:region:account-id:queue-name - // URL format: https://sqs.region.amazonaws.com/account-id/queue-name - - var parts = arn.Split(':'); - if (parts.Length >= 6) - { - var region = parts[3]; - var accountId = parts[4]; - var queueName = parts[5]; - - if (_testEnvironment.IsLocalEmulator) - { - return $"{_testEnvironment.SqsClient.Config.ServiceURL}/{accountId}/{queueName}"; - } - else - { - return $"https://sqs.{region}.amazonaws.com/{accountId}/{queueName}"; - } - } - - return arn; // Return as-is if parsing fails - } -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/AwsTestConfiguration.cs b/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/AwsTestConfiguration.cs deleted file mode 100644 index 690c8f8f..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/AwsTestConfiguration.cs +++ /dev/null @@ -1,468 +0,0 @@ -using Amazon; -using Amazon.SQS; -using Amazon.SimpleNotificationService; -using Amazon.KeyManagementService; -using Amazon.Runtime; -using System.Net.Sockets; - -namespace SourceFlow.Cloud.AWS.Tests.TestHelpers; - -/// -/// Enhanced configuration for AWS integration tests -/// -public class AwsTestConfiguration -{ - /// - /// AWS region for testing - /// - public RegionEndpoint Region { get; set; } = RegionEndpoint.USEast1; - - /// - /// Whether to use LocalStack emulator - /// - public bool UseLocalStack { get; set; } = true; - - /// - /// LocalStack endpoint URL - /// - public string LocalStackEndpoint { get; set; } = "http://localhost:4566"; - - /// - /// AWS access key for testing (used with LocalStack) - /// LocalStack accepts any credentials when IAM is not enforced, - /// but 'test' is the standard convention - /// - public string AccessKey { get; set; } = Environment.GetEnvironmentVariable("AWS_ACCESS_KEY_ID") ?? "test"; - - /// - /// AWS secret key for testing (used with LocalStack) - /// LocalStack accepts any credentials when IAM is not enforced, - /// but 'test' is the standard convention - /// - public string SecretKey { get; set; } = Environment.GetEnvironmentVariable("AWS_SECRET_ACCESS_KEY") ?? "test"; - - /// - /// Test queue URLs mapped by command type - /// - public Dictionary QueueUrls { get; set; } = new(); - - /// - /// Test topic ARNs mapped by event type - /// - public Dictionary TopicArns { get; set; } = new(); - - /// - /// Whether to run integration tests (requires AWS services or LocalStack) - /// - public bool RunIntegrationTests { get; set; } = true; - - /// - /// Whether to run performance tests - /// - public bool RunPerformanceTests { get; set; } = false; - - /// - /// Whether to run security tests - /// - public bool RunSecurityTests { get; set; } = true; - - /// - /// KMS key ID for encryption tests - /// - public string? KmsKeyId { get; set; } - - /// - /// LocalStack configuration - /// - public LocalStackConfiguration LocalStack { get; set; } = new(); - - /// - /// AWS service configurations - /// - public AwsServiceConfiguration Services { get; set; } = new(); - - /// - /// Performance test configuration - /// - public PerformanceTestConfiguration Performance { get; set; } = new(); - - /// - /// Security test configuration - /// - public SecurityTestConfiguration Security { get; set; } = new(); - - /// - /// Checks if AWS SQS is available with a timeout. - /// - /// Maximum time to wait for connection. - /// True if SQS is available, false otherwise. - public async Task IsSqsAvailableAsync(TimeSpan timeout) - { - try - { - using var cts = new CancellationTokenSource(timeout); - - var config = new AmazonSQSConfig - { - RegionEndpoint = Region - }; - - if (UseLocalStack) - { - config.ServiceURL = LocalStackEndpoint; - config.AuthenticationRegion = Region.SystemName; - } - - // Use AnonymousAWSCredentials for LocalStack to bypass credential validation - AWSCredentials credentials = UseLocalStack - ? (AWSCredentials)new Amazon.Runtime.AnonymousAWSCredentials() - : (AWSCredentials)new BasicAWSCredentials(AccessKey, SecretKey); - using var client = new AmazonSQSClient(credentials, config); - - // Try to list queues to test connectivity - await client.ListQueuesAsync(new Amazon.SQS.Model.ListQueuesRequest(), cts.Token); - - return true; - } - catch (OperationCanceledException) - { - // Timeout occurred - return false; - } - catch (SocketException) - { - // Connection refused - return false; - } - catch (AmazonServiceException) - { - // Service error, but we connected - return true; - } - catch (Exception) - { - // Other connection errors - return false; - } - } - - /// - /// Checks if AWS SNS is available with a timeout. - /// - /// Maximum time to wait for connection. - /// True if SNS is available, false otherwise. - public async Task IsSnsAvailableAsync(TimeSpan timeout) - { - try - { - using var cts = new CancellationTokenSource(timeout); - - var config = new AmazonSimpleNotificationServiceConfig - { - RegionEndpoint = Region - }; - - if (UseLocalStack) - { - config.ServiceURL = LocalStackEndpoint; - config.AuthenticationRegion = Region.SystemName; - } - - // Use AnonymousAWSCredentials for LocalStack to bypass credential validation - AWSCredentials credentials = UseLocalStack - ? (AWSCredentials)new Amazon.Runtime.AnonymousAWSCredentials() - : (AWSCredentials)new BasicAWSCredentials(AccessKey, SecretKey); - using var client = new AmazonSimpleNotificationServiceClient(credentials, config); - - // Try to list topics to test connectivity - await client.ListTopicsAsync(new Amazon.SimpleNotificationService.Model.ListTopicsRequest(), cts.Token); - - return true; - } - catch (OperationCanceledException) - { - // Timeout occurred - return false; - } - catch (SocketException) - { - // Connection refused - return false; - } - catch (AmazonServiceException) - { - // Service error, but we connected - return true; - } - catch (Exception) - { - // Other connection errors - return false; - } - } - - /// - /// Checks if AWS KMS is available with a timeout. - /// - /// Maximum time to wait for connection. - /// True if KMS is available, false otherwise. - public async Task IsKmsAvailableAsync(TimeSpan timeout) - { - try - { - using var cts = new CancellationTokenSource(timeout); - - var config = new AmazonKeyManagementServiceConfig - { - RegionEndpoint = Region - }; - - if (UseLocalStack) - { - config.ServiceURL = LocalStackEndpoint; - config.AuthenticationRegion = Region.SystemName; - } - - // Use AnonymousAWSCredentials for LocalStack to bypass credential validation - AWSCredentials credentials = UseLocalStack - ? (AWSCredentials)new Amazon.Runtime.AnonymousAWSCredentials() - : (AWSCredentials)new BasicAWSCredentials(AccessKey, SecretKey); - using var client = new AmazonKeyManagementServiceClient(credentials, config); - - // Try to list keys to test connectivity - await client.ListKeysAsync(new Amazon.KeyManagementService.Model.ListKeysRequest(), cts.Token); - - return true; - } - catch (OperationCanceledException) - { - // Timeout occurred - return false; - } - catch (SocketException) - { - // Connection refused - return false; - } - catch (AmazonServiceException) - { - // Service error, but we connected - return true; - } - catch (Exception) - { - // Other connection errors - return false; - } - } - - /// - /// Checks if LocalStack is available with a timeout. - /// Uses the health endpoint for faster, more reliable detection. - /// - /// Maximum time to wait for connection. - /// True if LocalStack is available, false otherwise. - public async Task IsLocalStackAvailableAsync(TimeSpan timeout) - { - try - { - using var cts = new CancellationTokenSource(timeout); - using var httpClient = new HttpClient { Timeout = timeout }; - - // Use LocalStack health endpoint for faster detection - // This is more reliable than trying to list queues - var healthUrl = $"{LocalStackEndpoint}/_localstack/health"; - - Console.WriteLine($"Checking LocalStack health endpoint: {healthUrl}"); - var response = await httpClient.GetAsync(healthUrl, cts.Token); - - // Accept any HTTP 200 response - services may still be initializing - // but LocalStack is running and accepting connections - bool isAvailable = response.IsSuccessStatusCode; - - if (isAvailable) - { - var content = await response.Content.ReadAsStringAsync(cts.Token); - Console.WriteLine($"LocalStack health check succeeded. Response: {content}"); - } - else - { - Console.WriteLine($"LocalStack health check failed with status: {response.StatusCode}"); - } - - return isAvailable; - } - catch (OperationCanceledException) - { - Console.WriteLine("LocalStack health check timed out"); - return false; - } - catch (HttpRequestException ex) - { - Console.WriteLine($"LocalStack health check failed: {ex.Message}"); - return false; - } - catch (Exception ex) - { - Console.WriteLine($"LocalStack health check error: {ex.GetType().Name} - {ex.Message}"); - return false; - } - } -} - -/// -/// AWS service-specific configurations -/// -public class AwsServiceConfiguration -{ - /// - /// SQS configuration - /// - public SqsConfiguration Sqs { get; set; } = new(); - - /// - /// SNS configuration - /// - public SnsConfiguration Sns { get; set; } = new(); - - /// - /// KMS configuration - /// - public KmsConfiguration Kms { get; set; } = new(); - - /// - /// IAM configuration - /// - public IamConfiguration Iam { get; set; } = new(); -} - -/// -/// SQS-specific configuration -/// -public class SqsConfiguration -{ - /// - /// Message retention period in seconds (default: 14 days) - /// - public int MessageRetentionPeriod { get; set; } = 1209600; - - /// - /// Visibility timeout in seconds - /// - public int VisibilityTimeout { get; set; } = 30; - - /// - /// Maximum receive count for dead letter queue - /// - public int MaxReceiveCount { get; set; } = 3; - - /// - /// Whether to enable dead letter queue - /// - public bool EnableDeadLetterQueue { get; set; } = true; - - /// - /// Default queue attributes - /// - public Dictionary DefaultAttributes { get; set; } = new(); -} - -/// -/// SNS-specific configuration -/// -public class SnsConfiguration -{ - /// - /// Default topic attributes - /// - public Dictionary DefaultAttributes { get; set; } = new(); - - /// - /// Whether to enable message filtering - /// - public bool EnableMessageFiltering { get; set; } = true; -} - -/// -/// KMS-specific configuration -/// -public class KmsConfiguration -{ - /// - /// Default key alias for testing - /// - public string DefaultKeyAlias { get; set; } = "sourceflow-test"; - - /// - /// Key rotation enabled - /// - public bool EnableKeyRotation { get; set; } = false; - - /// - /// Encryption algorithm to use - /// - public string EncryptionAlgorithm { get; set; } = "SYMMETRIC_DEFAULT"; -} - -/// -/// IAM-specific configuration -/// -public class IamConfiguration -{ - /// - /// Whether to enforce IAM policies in LocalStack - /// - public bool EnforceIamPolicies { get; set; } = false; - - /// - /// Load AWS managed policies in LocalStack - /// - public bool LoadManagedPolicies { get; set; } = false; -} - -/// -/// Performance test configuration -/// -public class PerformanceTestConfiguration -{ - /// - /// Default number of concurrent senders for throughput tests - /// - public int DefaultConcurrentSenders { get; set; } = 10; - - /// - /// Default number of messages per sender - /// - public int DefaultMessagesPerSender { get; set; } = 100; - - /// - /// Default message size in bytes - /// - public int DefaultMessageSize { get; set; } = 1024; - - /// - /// Performance test timeout - /// - public TimeSpan TestTimeout { get; set; } = TimeSpan.FromMinutes(5); -} - -/// -/// Security test configuration -/// -public class SecurityTestConfiguration -{ - /// - /// Whether to test encryption in transit - /// - public bool TestEncryptionInTransit { get; set; } = true; - - /// - /// Whether to test IAM permissions - /// - public bool TestIamPermissions { get; set; } = true; - - /// - /// Whether to test sensitive data masking - /// - public bool TestSensitiveDataMasking { get; set; } = true; -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/AwsTestDefaults.cs b/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/AwsTestDefaults.cs deleted file mode 100644 index ca90feed..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/AwsTestDefaults.cs +++ /dev/null @@ -1,33 +0,0 @@ -namespace SourceFlow.Cloud.AWS.Tests.TestHelpers; - -/// -/// Default configuration values for AWS tests. -/// -public static class AwsTestDefaults -{ - /// - /// Default timeout for initial connection attempts to AWS services. - /// Tests will fail fast if services don't respond within this time. - /// - public static readonly TimeSpan ConnectionTimeout = TimeSpan.FromSeconds(5); - - /// - /// Default timeout for AWS operations during tests. - /// - public static readonly TimeSpan OperationTimeout = TimeSpan.FromSeconds(30); - - /// - /// Default timeout for long-running performance tests. - /// - public static readonly TimeSpan PerformanceTestTimeout = TimeSpan.FromMinutes(5); - - /// - /// Default number of retry attempts for transient failures. - /// - public const int DefaultRetryAttempts = 3; - - /// - /// Default delay between retry attempts. - /// - public static readonly TimeSpan DefaultRetryDelay = TimeSpan.FromSeconds(1); -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/AwsTestEnvironment.cs b/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/AwsTestEnvironment.cs deleted file mode 100644 index a0ce6210..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/AwsTestEnvironment.cs +++ /dev/null @@ -1,538 +0,0 @@ -using Amazon; -using Amazon.Runtime; -using Amazon.IdentityManagement; -using Amazon.IdentityManagement.Model; -using Amazon.KeyManagementService; -using Amazon.KeyManagementService.Model; -using Amazon.SimpleNotificationService; -using Amazon.SimpleNotificationService.Model; -using Amazon.SQS; -using Amazon.SQS.Model; -using Microsoft.Extensions.DependencyInjection; -using Microsoft.Extensions.Logging; - -namespace SourceFlow.Cloud.AWS.Tests.TestHelpers; - -/// -/// Enhanced AWS test environment implementation with full AWS service support -/// Provides comprehensive AWS service clients and resource management capabilities -/// -public class AwsTestEnvironment : IAwsTestEnvironment -{ - private readonly AwsTestConfiguration _configuration; - private readonly ILocalStackManager? _localStackManager; - private IAwsResourceManager? _resourceManager; - private readonly ILogger _logger; - private bool _disposed; - - public AwsTestEnvironment( - AwsTestConfiguration configuration, - ILocalStackManager? localStackManager, - IAwsResourceManager? resourceManager, - ILogger logger) - { - _configuration = configuration ?? throw new ArgumentNullException(nameof(configuration)); - _localStackManager = localStackManager; - _resourceManager = resourceManager; - _logger = logger ?? throw new ArgumentNullException(nameof(logger)); - } - - internal void SetResourceManager(IAwsResourceManager resourceManager) => - _resourceManager = resourceManager ?? throw new ArgumentNullException(nameof(resourceManager)); - - /// - public IAmazonSQS SqsClient { get; private set; } = null!; - - /// - public IAmazonSimpleNotificationService SnsClient { get; private set; } = null!; - - /// - public IAmazonKeyManagementService KmsClient { get; private set; } = null!; - - /// - public IAmazonIdentityManagementService IamClient { get; private set; } = null!; - - /// - public bool IsLocalEmulator => _configuration.UseLocalStack; - - /// - public async Task InitializeAsync() - { - _logger.LogInformation("Initializing AWS test environment (LocalStack: {UseLocalStack})", IsLocalEmulator); - - if (IsLocalEmulator) - { - await InitializeLocalStackEnvironmentAsync(); - } - else - { - await InitializeAwsEnvironmentAsync(); - } - - await ValidateServicesAsync(); - _logger.LogInformation("AWS test environment initialized successfully"); - } - - /// - public async Task IsAvailableAsync() - { - try - { - // Test SQS connectivity - await SqsClient.ListQueuesAsync(new ListQueuesRequest()); - - // Test SNS connectivity - await SnsClient.ListTopicsAsync(new ListTopicsRequest()); - - // Test KMS connectivity (optional, might not be available in LocalStack free tier) - try - { - await KmsClient.ListKeysAsync(new ListKeysRequest()); - } - catch (Exception ex) - { - _logger.LogWarning("KMS service not available: {Error}", ex.Message); - } - - return true; - } - catch (Exception ex) - { - _logger.LogError(ex, "AWS services not available"); - return false; - } - } - - /// - public IServiceCollection CreateTestServices() - { - var services = new ServiceCollection(); - - // Add logging - services.AddLogging(builder => builder.AddConsole().SetMinimumLevel(LogLevel.Debug)); - - // Add AWS clients - services.AddSingleton(SqsClient); - services.AddSingleton(SnsClient); - services.AddSingleton(KmsClient); - services.AddSingleton(IamClient); - - // Add test configuration - services.AddSingleton(_configuration); - - // Add resource manager - if (_resourceManager != null) - services.AddSingleton(_resourceManager); - - return services; - } - - /// - public async Task CleanupAsync() - { - _logger.LogInformation("Cleaning up AWS test environment"); - - // Cleanup will be handled by resource manager - // Individual resources are tracked and cleaned up automatically - - _logger.LogInformation("AWS test environment cleanup completed"); - } - - /// - public async Task CreateFifoQueueAsync(string queueName, Dictionary? attributes = null) - { - var fifoQueueName = queueName.EndsWith(".fifo") ? queueName : $"{queueName}.fifo"; - - var queueAttributes = new Dictionary - { - ["FifoQueue"] = "true", - ["ContentBasedDeduplication"] = "true", - ["MessageRetentionPeriod"] = _configuration.Services.Sqs.MessageRetentionPeriod.ToString(), - ["VisibilityTimeout"] = _configuration.Services.Sqs.VisibilityTimeout.ToString() - }; - - // Add custom attributes - if (attributes != null) - { - foreach (var kvp in attributes) - { - queueAttributes[kvp.Key] = kvp.Value; - } - } - - // Add dead letter queue if enabled - if (_configuration.Services.Sqs.EnableDeadLetterQueue) - { - var baseName = fifoQueueName.EndsWith(".fifo") ? fifoQueueName[..^5] : fifoQueueName; - var dlqName = $"{baseName}-dlq.fifo"; - var dlqResponse = await SqsClient.CreateQueueAsync(new CreateQueueRequest - { - QueueName = dlqName, - Attributes = new Dictionary - { - ["FifoQueue"] = "true" - } - }); - - var dlqArn = await GetQueueArnAsync(dlqResponse.QueueUrl); - queueAttributes["RedrivePolicy"] = $"{{\"deadLetterTargetArn\":\"{dlqArn}\",\"maxReceiveCount\":{_configuration.Services.Sqs.MaxReceiveCount}}}"; - } - - var response = await SqsClient.CreateQueueAsync(new CreateQueueRequest - { - QueueName = fifoQueueName, - Attributes = queueAttributes - }); - - _logger.LogDebug("Created FIFO queue: {QueueName} -> {QueueUrl}", fifoQueueName, response.QueueUrl); - return response.QueueUrl; - } - - /// - public async Task CreateStandardQueueAsync(string queueName, Dictionary? attributes = null) - { - var queueAttributes = new Dictionary - { - ["MessageRetentionPeriod"] = _configuration.Services.Sqs.MessageRetentionPeriod.ToString(), - ["VisibilityTimeout"] = _configuration.Services.Sqs.VisibilityTimeout.ToString() - }; - - // Add custom attributes - if (attributes != null) - { - foreach (var kvp in attributes) - { - queueAttributes[kvp.Key] = kvp.Value; - } - } - - // Add dead letter queue if enabled - if (_configuration.Services.Sqs.EnableDeadLetterQueue) - { - var dlqName = $"{queueName}-dlq"; - var dlqResponse = await SqsClient.CreateQueueAsync(new CreateQueueRequest - { - QueueName = dlqName - }); - - var dlqArn = await GetQueueArnAsync(dlqResponse.QueueUrl); - queueAttributes["RedrivePolicy"] = $"{{\"deadLetterTargetArn\":\"{dlqArn}\",\"maxReceiveCount\":{_configuration.Services.Sqs.MaxReceiveCount}}}"; - } - - var response = await SqsClient.CreateQueueAsync(new CreateQueueRequest - { - QueueName = queueName, - Attributes = queueAttributes - }); - - _logger.LogDebug("Created standard queue: {QueueName} -> {QueueUrl}", queueName, response.QueueUrl); - return response.QueueUrl; - } - - /// - public async Task CreateTopicAsync(string topicName, Dictionary? attributes = null) - { - var topicAttributes = new Dictionary(); - - // Add custom attributes - if (attributes != null) - { - foreach (var kvp in attributes) - { - topicAttributes[kvp.Key] = kvp.Value; - } - } - - var response = await SnsClient.CreateTopicAsync(new CreateTopicRequest - { - Name = topicName, - Attributes = topicAttributes - }); - - _logger.LogDebug("Created SNS topic: {TopicName} -> {TopicArn}", topicName, response.TopicArn); - return response.TopicArn; - } - - /// - public async Task CreateKmsKeyAsync(string keyAlias, string? description = null) - { - try - { - var keyDescription = description ?? $"Test key for SourceFlow integration tests - {keyAlias}"; - - var createKeyResponse = await KmsClient.CreateKeyAsync(new CreateKeyRequest - { - Description = keyDescription, - KeyUsage = KeyUsageType.ENCRYPT_DECRYPT, - Origin = OriginType.AWS_KMS - }); - - var keyId = createKeyResponse.KeyMetadata.KeyId; - - // Create alias for the key - var aliasName = keyAlias.StartsWith("alias/") ? keyAlias : $"alias/{keyAlias}"; - await KmsClient.CreateAliasAsync(new CreateAliasRequest - { - AliasName = aliasName, - TargetKeyId = keyId - }); - - _logger.LogDebug("Created KMS key: {KeyAlias} -> {KeyId}", aliasName, keyId); - return keyId; - } - catch (Exception ex) - { - _logger.LogWarning("Failed to create KMS key (might not be supported in LocalStack free tier): {Error}", ex.Message); - throw; - } - } - - /// - public async Task ValidateIamPermissionsAsync(string action, string resource) - { - try - { - // In LocalStack, IAM simulation might not be fully supported - // For real AWS, we would use IAM policy simulator - if (IsLocalEmulator) - { - // For LocalStack, assume permissions are valid if we can list policies - await IamClient.ListPoliciesAsync(new ListPoliciesRequest { MaxItems = 1 }); - return true; - } - - // For real AWS, implement proper permission validation - // This would typically use IAM policy simulator or STS assume role - return true; - } - catch (Exception ex) - { - _logger.LogWarning("Failed to validate IAM permissions for {Action} on {Resource}: {Error}", action, resource, ex.Message); - return false; - } - } - - /// - public async Task DeleteQueueAsync(string queueUrl) - { - try - { - await SqsClient.DeleteQueueAsync(new DeleteQueueRequest { QueueUrl = queueUrl }); - _logger.LogDebug("Deleted queue: {QueueUrl}", queueUrl); - } - catch (Exception ex) - { - _logger.LogWarning("Failed to delete queue {QueueUrl}: {Error}", queueUrl, ex.Message); - } - } - - /// - public async Task DeleteTopicAsync(string topicArn) - { - try - { - await SnsClient.DeleteTopicAsync(new DeleteTopicRequest { TopicArn = topicArn }); - _logger.LogDebug("Deleted topic: {TopicArn}", topicArn); - } - catch (Exception ex) - { - _logger.LogWarning("Failed to delete topic {TopicArn}: {Error}", topicArn, ex.Message); - } - } - - /// - public async Task DeleteKmsKeyAsync(string keyId, int pendingWindowInDays = 7) - { - try - { - await KmsClient.ScheduleKeyDeletionAsync(new ScheduleKeyDeletionRequest - { - KeyId = keyId, - PendingWindowInDays = pendingWindowInDays - }); - _logger.LogDebug("Scheduled KMS key deletion: {KeyId} (pending window: {Days} days)", keyId, pendingWindowInDays); - } - catch (Exception ex) - { - _logger.LogWarning("Failed to delete KMS key {KeyId}: {Error}", keyId, ex.Message); - } - } - - /// - public async Task> GetHealthStatusAsync() - { - var results = new Dictionary(); - - // Check SQS health - results["sqs"] = await CheckServiceHealthAsync("sqs", async () => - { - var stopwatch = System.Diagnostics.Stopwatch.StartNew(); - await SqsClient.ListQueuesAsync(new ListQueuesRequest()); - stopwatch.Stop(); - return stopwatch.Elapsed; - }); - - // Check SNS health - results["sns"] = await CheckServiceHealthAsync("sns", async () => - { - var stopwatch = System.Diagnostics.Stopwatch.StartNew(); - await SnsClient.ListTopicsAsync(new ListTopicsRequest()); - stopwatch.Stop(); - return stopwatch.Elapsed; - }); - - // Check KMS health - results["kms"] = await CheckServiceHealthAsync("kms", async () => - { - var stopwatch = System.Diagnostics.Stopwatch.StartNew(); - await KmsClient.ListKeysAsync(new ListKeysRequest()); - stopwatch.Stop(); - return stopwatch.Elapsed; - }); - - // Check IAM health - results["iam"] = await CheckServiceHealthAsync("iam", async () => - { - var stopwatch = System.Diagnostics.Stopwatch.StartNew(); - await IamClient.ListPoliciesAsync(new ListPoliciesRequest { MaxItems = 1 }); - stopwatch.Stop(); - return stopwatch.Elapsed; - }); - - return results; - } - - /// - public async ValueTask DisposeAsync() - { - if (_disposed) return; - - await CleanupAsync(); - - SqsClient?.Dispose(); - SnsClient?.Dispose(); - KmsClient?.Dispose(); - IamClient?.Dispose(); - - if (_resourceManager != null) - { - await _resourceManager.DisposeAsync(); - } - - _disposed = true; - } - - private async Task InitializeLocalStackEnvironmentAsync() - { - if (_localStackManager == null) - throw new InvalidOperationException("LocalStack manager is required for LocalStack environment"); - - // LocalStack manager should already be started - if (!_localStackManager.IsRunning) - { - var config = LocalStackConfiguration.CreateDefault(); - await _localStackManager.StartAsync(config); - } - - // Only wait for services that appear in the health endpoint by default. - // IAM is lazily initialized in newer LocalStack versions and won't appear until first use. - await _localStackManager.WaitForServicesAsync(new[] { "sqs", "sns", "kms" }); - - // Configure clients for LocalStack - var endpoint = _localStackManager.Endpoint; - - // Don't set RegionEndpoint when using ServiceURL - it can override the endpoint - var credentials = new Amazon.Runtime.BasicAWSCredentials(_configuration.AccessKey, _configuration.SecretKey); - var regionName = _configuration.Region.SystemName; - - SqsClient = new AmazonSQSClient(credentials, new AmazonSQSConfig - { - ServiceURL = endpoint, - UseHttp = true, - AuthenticationRegion = regionName - }); - - SnsClient = new AmazonSimpleNotificationServiceClient(credentials, new AmazonSimpleNotificationServiceConfig - { - ServiceURL = endpoint, - UseHttp = true, - AuthenticationRegion = regionName - }); - - KmsClient = new AmazonKeyManagementServiceClient(credentials, new AmazonKeyManagementServiceConfig - { - ServiceURL = endpoint, - UseHttp = true, - AuthenticationRegion = regionName - }); - - IamClient = new AmazonIdentityManagementServiceClient(credentials, new AmazonIdentityManagementServiceConfig - { - ServiceURL = endpoint, - UseHttp = true, - AuthenticationRegion = regionName - }); - } - - private async Task InitializeAwsEnvironmentAsync() - { - // Configure clients for real AWS - SqsClient = new AmazonSQSClient(_configuration.Region); - SnsClient = new AmazonSimpleNotificationServiceClient(_configuration.Region); - KmsClient = new AmazonKeyManagementServiceClient(_configuration.Region); - IamClient = new AmazonIdentityManagementServiceClient(_configuration.Region); - - await Task.CompletedTask; - } - - private async Task ValidateServicesAsync() - { - var healthResults = await GetHealthStatusAsync(); - - foreach (var result in healthResults) - { - if (!result.Value.IsAvailable) - { - _logger.LogWarning("AWS service {ServiceName} is not available", result.Key); - } - else - { - _logger.LogDebug("AWS service {ServiceName} is available (response time: {ResponseTime}ms)", - result.Key, result.Value.ResponseTime.TotalMilliseconds); - } - } - } - - private async Task CheckServiceHealthAsync(string serviceName, Func> healthCheck) - { - var result = new AwsHealthCheckResult - { - ServiceName = serviceName, - Endpoint = IsLocalEmulator ? _localStackManager?.Endpoint ?? "" : $"https://{serviceName}.{_configuration.Region.SystemName}.amazonaws.com" - }; - - try - { - result.ResponseTime = await healthCheck(); - result.IsAvailable = true; - } - catch (Exception ex) - { - result.IsAvailable = false; - result.Errors.Add(ex.Message); - } - - return result; - } - - private async Task GetQueueArnAsync(string queueUrl) - { - var response = await SqsClient.GetQueueAttributesAsync(new GetQueueAttributesRequest - { - QueueUrl = queueUrl, - AttributeNames = new List { "QueueArn" } - }); - - return response.Attributes["QueueArn"]; - } -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/AwsTestEnvironmentFactory.cs b/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/AwsTestEnvironmentFactory.cs deleted file mode 100644 index 38c18131..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/AwsTestEnvironmentFactory.cs +++ /dev/null @@ -1,453 +0,0 @@ -using Microsoft.Extensions.DependencyInjection; -using Microsoft.Extensions.Logging; - -namespace SourceFlow.Cloud.AWS.Tests.TestHelpers; - -/// -/// Factory for creating configured AWS test environments -/// Provides convenient methods for setting up test environments with different configurations -/// -public static class AwsTestEnvironmentFactory -{ - /// - /// Create a default AWS test environment using LocalStack - /// - /// Unique prefix for test resources - /// Configured AWS test environment - public static async Task CreateLocalStackEnvironmentAsync(string? testPrefix = null) - { - var configuration = new AwsTestConfiguration - { - UseLocalStack = true, - RunIntegrationTests = true, - RunPerformanceTests = false, - RunSecurityTests = true, - LocalStack = LocalStackConfiguration.CreateDefault() - }; - - return await CreateEnvironmentAsync(configuration, testPrefix); - } - - /// - /// Create an AWS test environment for performance testing - /// - /// Unique prefix for test resources - /// Configured AWS test environment optimized for performance testing - public static async Task CreatePerformanceTestEnvironmentAsync(string? testPrefix = null) - { - var configuration = new AwsTestConfiguration - { - UseLocalStack = true, - RunIntegrationTests = true, - RunPerformanceTests = true, - RunSecurityTests = false, - LocalStack = LocalStackConfiguration.CreateForPerformanceTesting(), - Performance = new PerformanceTestConfiguration - { - DefaultConcurrentSenders = 20, - DefaultMessagesPerSender = 500, - DefaultMessageSize = 2048, - TestTimeout = TimeSpan.FromMinutes(10) - } - }; - - return await CreateEnvironmentAsync(configuration, testPrefix); - } - - /// - /// Create an AWS test environment for security testing - /// - /// Unique prefix for test resources - /// Configured AWS test environment optimized for security testing - public static async Task CreateSecurityTestEnvironmentAsync(string? testPrefix = null) - { - var configuration = new AwsTestConfiguration - { - UseLocalStack = true, - RunIntegrationTests = true, - RunPerformanceTests = false, - RunSecurityTests = true, - LocalStack = LocalStackConfiguration.CreateForSecurityTesting(), - Security = new SecurityTestConfiguration - { - TestEncryptionInTransit = true, - TestIamPermissions = true, - TestSensitiveDataMasking = true - } - }; - - return await CreateEnvironmentAsync(configuration, testPrefix); - } - - /// - /// Create an AWS test environment using real AWS services - /// - /// Unique prefix for test resources - /// Configured AWS test environment using real AWS services - public static async Task CreateRealAwsEnvironmentAsync(string? testPrefix = null) - { - var configuration = new AwsTestConfiguration - { - UseLocalStack = false, - RunIntegrationTests = true, - RunPerformanceTests = true, - RunSecurityTests = true - }; - - return await CreateEnvironmentAsync(configuration, testPrefix); - } - - /// - /// Create an AWS test environment with custom configuration - /// - /// Custom AWS test configuration - /// Unique prefix for test resources - /// Configured AWS test environment - public static async Task CreateEnvironmentAsync(AwsTestConfiguration configuration, string? testPrefix = null) - { - var actualTestPrefix = testPrefix ?? $"test-{Guid.NewGuid():N}"; - - // Create service collection - var services = new ServiceCollection(); - - // Add logging - services.AddLogging(builder => - { - builder.AddConsole(); - builder.SetMinimumLevel(LogLevel.Debug); - }); - - // Add configuration - services.AddSingleton(configuration); - - // Add LocalStack manager if using LocalStack - ILocalStackManager? localStackManager = null; - if (configuration.UseLocalStack) - { - services.AddSingleton(); - var serviceProvider = services.BuildServiceProvider(); - localStackManager = serviceProvider.GetRequiredService(); - - // Start LocalStack - await localStackManager.StartAsync(configuration.LocalStack); - } - - // Build service provider (for logging only - AwsResourceManager is created after AwsTestEnvironment - // to break the circular dependency: AwsTestEnvironment → AwsResourceManager → IAwsTestEnvironment) - var finalServiceProvider = services.BuildServiceProvider(); - - var logger = finalServiceProvider.GetRequiredService>(); - var resourceManagerLogger = finalServiceProvider.GetRequiredService>(); - - // Phase 1: create environment without resource manager, initialize AWS clients - var testEnvironment = new AwsTestEnvironment(configuration, localStackManager, null, logger); - await testEnvironment.InitializeAsync(); - - // Phase 2: create resource manager (environment now has AWS clients), wire back - var resourceManager = new AwsResourceManager(testEnvironment, resourceManagerLogger); - testEnvironment.SetResourceManager(resourceManager); - - return testEnvironment; - } - - /// - /// Create a service collection configured for AWS testing - /// - /// AWS test environment - /// Service collection with AWS test services - public static IServiceCollection CreateTestServiceCollection(IAwsTestEnvironment testEnvironment) - { - var services = testEnvironment.CreateTestServices(); - - // Add the test environment itself - services.AddSingleton(testEnvironment); - - // Add test utilities - services.AddTransient(); - services.AddTransient(); - services.AddTransient(); - - return services; - } - - /// - /// Create a test environment builder for fluent configuration - /// - /// AWS test environment builder - public static AwsTestEnvironmentBuilder CreateBuilder() - { - return new AwsTestEnvironmentBuilder(); - } -} - -/// -/// Builder for creating AWS test environments with fluent configuration -/// -public class AwsTestEnvironmentBuilder -{ - private readonly AwsTestConfiguration _configuration; - private string? _testPrefix; - - public AwsTestEnvironmentBuilder() - { - _configuration = new AwsTestConfiguration(); - } - - /// - /// Use LocalStack for AWS service emulation - /// - public AwsTestEnvironmentBuilder UseLocalStack(bool useLocalStack = true) - { - _configuration.UseLocalStack = useLocalStack; - return this; - } - - /// - /// Configure LocalStack settings - /// - public AwsTestEnvironmentBuilder ConfigureLocalStack(Action configure) - { - configure(_configuration.LocalStack); - return this; - } - - /// - /// Enable integration tests - /// - public AwsTestEnvironmentBuilder EnableIntegrationTests(bool enable = true) - { - _configuration.RunIntegrationTests = enable; - return this; - } - - /// - /// Enable performance tests - /// - public AwsTestEnvironmentBuilder EnablePerformanceTests(bool enable = true) - { - _configuration.RunPerformanceTests = enable; - return this; - } - - /// - /// Enable security tests - /// - public AwsTestEnvironmentBuilder EnableSecurityTests(bool enable = true) - { - _configuration.RunSecurityTests = enable; - return this; - } - - /// - /// Configure AWS services - /// - public AwsTestEnvironmentBuilder ConfigureServices(Action configure) - { - configure(_configuration.Services); - return this; - } - - /// - /// Configure performance testing - /// - public AwsTestEnvironmentBuilder ConfigurePerformance(Action configure) - { - configure(_configuration.Performance); - return this; - } - - /// - /// Configure security testing - /// - public AwsTestEnvironmentBuilder ConfigureSecurity(Action configure) - { - configure(_configuration.Security); - return this; - } - - /// - /// Set test prefix for resource naming - /// - public AwsTestEnvironmentBuilder WithTestPrefix(string testPrefix) - { - _testPrefix = testPrefix; - return this; - } - - /// - /// Build the AWS test environment - /// - public async Task BuildAsync() - { - return await AwsTestEnvironmentFactory.CreateEnvironmentAsync(_configuration, _testPrefix); - } -} - -/// -/// Test scenario runner for AWS integration tests -/// -public class AwsTestScenarioRunner -{ - private readonly IAwsTestEnvironment _testEnvironment; - private readonly ILogger _logger; - - public AwsTestScenarioRunner(IAwsTestEnvironment testEnvironment, ILogger logger) - { - _testEnvironment = testEnvironment ?? throw new ArgumentNullException(nameof(testEnvironment)); - _logger = logger ?? throw new ArgumentNullException(nameof(logger)); - } - - /// - /// Run a basic SQS integration test scenario - /// - public async Task RunSqsBasicScenarioAsync() - { - try - { - _logger.LogInformation("Running basic SQS integration test scenario"); - - // Create test queue - var queueUrl = await _testEnvironment.CreateStandardQueueAsync("basic-test-queue"); - - // Send test message - await _testEnvironment.SqsClient.SendMessageAsync(new Amazon.SQS.Model.SendMessageRequest - { - QueueUrl = queueUrl, - MessageBody = "Test message from SourceFlow AWS integration test" - }); - - // Receive test message - var response = await _testEnvironment.SqsClient.ReceiveMessageAsync(new Amazon.SQS.Model.ReceiveMessageRequest - { - QueueUrl = queueUrl, - MaxNumberOfMessages = 1, - WaitTimeSeconds = 5 - }); - - var success = response.Messages.Count > 0; - - // Cleanup - await _testEnvironment.DeleteQueueAsync(queueUrl); - - _logger.LogInformation("Basic SQS scenario completed: {Success}", success); - return success; - } - catch (Exception ex) - { - _logger.LogError(ex, "Basic SQS scenario failed"); - return false; - } - } - - /// - /// Run a basic SNS integration test scenario - /// - public async Task RunSnsBasicScenarioAsync() - { - try - { - _logger.LogInformation("Running basic SNS integration test scenario"); - - // Create test topic - var topicArn = await _testEnvironment.CreateTopicAsync("basic-test-topic"); - - // Publish test message - await _testEnvironment.SnsClient.PublishAsync(new Amazon.SimpleNotificationService.Model.PublishRequest - { - TopicArn = topicArn, - Message = "Test message from SourceFlow AWS integration test" - }); - - // Cleanup - await _testEnvironment.DeleteTopicAsync(topicArn); - - _logger.LogInformation("Basic SNS scenario completed successfully"); - return true; - } - catch (Exception ex) - { - _logger.LogError(ex, "Basic SNS scenario failed"); - return false; - } - } -} - -/// -/// Performance test runner for AWS services -/// -public class AwsPerformanceTestRunner -{ - private readonly IAwsTestEnvironment _testEnvironment; - private readonly ILogger _logger; - - public AwsPerformanceTestRunner(IAwsTestEnvironment testEnvironment, ILogger logger) - { - _testEnvironment = testEnvironment ?? throw new ArgumentNullException(nameof(testEnvironment)); - _logger = logger ?? throw new ArgumentNullException(nameof(logger)); - } - - /// - /// Run SQS throughput performance test - /// - public async Task RunSqsThroughputTestAsync(int messageCount = 100, int messageSize = 1024) - { - var queueUrl = await _testEnvironment.CreateStandardQueueAsync("perf-test-queue"); - - try - { - var message = new string('x', messageSize); - - var result = await PerformanceTestHelpers.RunPerformanceTestAsync( - "SQS Throughput Test", - async () => - { - await _testEnvironment.SqsClient.SendMessageAsync(new Amazon.SQS.Model.SendMessageRequest - { - QueueUrl = queueUrl, - MessageBody = message - }); - }, - iterations: messageCount, - warmupIterations: 10); - - return result; - } - finally - { - await _testEnvironment.DeleteQueueAsync(queueUrl); - } - } -} - -/// -/// Security test runner for AWS services -/// -public class AwsSecurityTestRunner -{ - private readonly IAwsTestEnvironment _testEnvironment; - private readonly ILogger _logger; - - public AwsSecurityTestRunner(IAwsTestEnvironment testEnvironment, ILogger logger) - { - _testEnvironment = testEnvironment ?? throw new ArgumentNullException(nameof(testEnvironment)); - _logger = logger ?? throw new ArgumentNullException(nameof(logger)); - } - - /// - /// Run basic IAM permission validation test - /// - public async Task RunIamPermissionTestAsync() - { - try - { - // Test basic SQS permissions - var hasPermission = await _testEnvironment.ValidateIamPermissionsAsync("sqs:CreateQueue", "*"); - return hasPermission; - } - catch (Exception ex) - { - _logger.LogError(ex, "IAM permission test failed"); - return false; - } - } -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/AwsTestScenario.cs b/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/AwsTestScenario.cs deleted file mode 100644 index ef446baf..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/AwsTestScenario.cs +++ /dev/null @@ -1,230 +0,0 @@ -namespace SourceFlow.Cloud.AWS.Tests.TestHelpers; - -/// -/// Test scenario for AWS service equivalence testing between LocalStack and real AWS -/// -public class AwsTestScenario -{ - /// - /// Unique prefix for test resources to prevent conflicts - /// - public string TestPrefix { get; set; } = ""; - - /// - /// Unique test identifier for isolation - /// - public string TestId { get; set; } = ""; - - /// - /// Number of messages to send in the test - /// - public int MessageCount { get; set; } = 1; - - /// - /// Size of each message in bytes - /// - public int MessageSize { get; set; } = 256; - - /// - /// Whether to use KMS encryption for messages - /// - public bool UseEncryption { get; set; } = false; - - /// - /// Whether to enable dead letter queue handling - /// - public bool EnableDeadLetterQueue { get; set; } = false; - - /// - /// Test execution timeout in seconds - /// - public int TestTimeoutSeconds { get; set; } = 60; - - /// - /// AWS region for testing - /// - public string Region { get; set; } = "us-east-1"; - - /// - /// Whether to test FIFO queue functionality - /// - public bool UseFifoQueue { get; set; } = false; - - /// - /// Whether to test SNS fan-out messaging - /// - public bool TestFanOutMessaging { get; set; } = false; - - /// - /// Number of SNS subscribers for fan-out testing - /// - public int SubscriberCount { get; set; } = 1; - - /// - /// Whether to test batch operations - /// - public bool TestBatchOperations { get; set; } = false; - - /// - /// Batch size for batch operations (max 10 for SQS) - /// - public int BatchSize { get; set; } = 1; - - /// - /// Additional test metadata - /// - public Dictionary Metadata { get; set; } = new(); - - /// - /// Generate a unique resource name for this test scenario - /// - public string GenerateResourceName(string resourceType) - { - return $"{TestPrefix}-{resourceType}-{TestId}".ToLowerInvariant(); - } - - /// - /// Generate a unique queue name for SQS testing - /// - public string GenerateQueueName(bool isFifo = false) - { - var baseName = GenerateResourceName("queue"); - return (isFifo || UseFifoQueue) ? $"{baseName}.fifo" : baseName; - } - - /// - /// Generate a unique topic name for SNS testing - /// - public string GenerateTopicName() - { - return GenerateResourceName("topic"); - } - - /// - /// Generate a unique KMS key alias - /// - public string GenerateKmsKeyAlias() - { - return $"alias/{GenerateResourceName("key")}"; - } - - /// - /// Generate test message content of specified size - /// - public string GenerateTestMessage(int? customSize = null) - { - var size = customSize ?? MessageSize; - var baseMessage = $"Test message for scenario {TestId}"; - - if (size <= baseMessage.Length) - return baseMessage[..size]; - - var padding = new string('X', size - baseMessage.Length); - return baseMessage + padding; - } - - /// - /// Validate the test scenario configuration - /// - public bool IsValid() - { - return !string.IsNullOrEmpty(TestPrefix) && - !string.IsNullOrEmpty(TestId) && - MessageCount > 0 && - MessageSize >= 100 && // Minimum reasonable message size - MessageSize <= 262144 && // SQS message size limit (256KB) - TestTimeoutSeconds > 0 && - !string.IsNullOrEmpty(Region) && - SubscriberCount > 0 && - BatchSize > 0 && - BatchSize <= 10; // SQS batch limit - } - - /// - /// Get estimated resource count for this scenario - /// - public int GetEstimatedResourceCount() - { - var resourceCount = 1; // Base queue or topic - - if (EnableDeadLetterQueue) - resourceCount++; // DLQ - - if (TestFanOutMessaging) - resourceCount += SubscriberCount; // SNS subscribers - - if (UseEncryption) - resourceCount++; // KMS key - - return resourceCount; - } - - /// - /// Check if scenario requires KMS functionality - /// - public bool RequiresKms() - { - return UseEncryption; - } - - /// - /// Check if scenario requires SNS functionality - /// - public bool RequiresSns() - { - return TestFanOutMessaging; - } - - /// - /// Check if scenario requires SQS functionality - /// - public bool RequiresSqs() - { - return true; // All scenarios use SQS as base - } - - /// - /// Get test tags for resource tagging - /// - public Dictionary GetResourceTags() - { - return new Dictionary - { - ["TestPrefix"] = TestPrefix, - ["TestId"] = TestId, - ["MessageCount"] = MessageCount.ToString(), - ["MessageSize"] = MessageSize.ToString(), - ["UseEncryption"] = UseEncryption.ToString(), - ["UseFifoQueue"] = UseFifoQueue.ToString(), - ["CreatedBy"] = "SourceFlow.Tests", - ["CreatedAt"] = DateTime.UtcNow.ToString("yyyy-MM-ddTHH:mm:ssZ") - }; - } - - /// - /// Create a copy of this scenario with modified parameters - /// - public AwsTestScenario WithModifications(Action modifications) - { - var copy = new AwsTestScenario - { - TestPrefix = TestPrefix, - TestId = TestId, - MessageCount = MessageCount, - MessageSize = MessageSize, - UseEncryption = UseEncryption, - EnableDeadLetterQueue = EnableDeadLetterQueue, - TestTimeoutSeconds = TestTimeoutSeconds, - Region = Region, - UseFifoQueue = UseFifoQueue, - TestFanOutMessaging = TestFanOutMessaging, - SubscriberCount = SubscriberCount, - TestBatchOperations = TestBatchOperations, - BatchSize = BatchSize, - Metadata = new Dictionary(Metadata) - }; - - modifications(copy); - return copy; - } -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/CiCdTestScenario.cs b/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/CiCdTestScenario.cs deleted file mode 100644 index 80dc1480..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/CiCdTestScenario.cs +++ /dev/null @@ -1,134 +0,0 @@ -namespace SourceFlow.Cloud.AWS.Tests.TestHelpers; - -/// -/// Test scenario for CI/CD integration testing -/// -public class CiCdTestScenario -{ - /// - /// Unique prefix for test resources to prevent conflicts - /// - public string TestPrefix { get; set; } = ""; - - /// - /// Unique test identifier for isolation - /// - public string TestId { get; set; } = ""; - - /// - /// Whether to use LocalStack emulator or real AWS services - /// - public bool UseLocalStack { get; set; } = true; - - /// - /// Number of parallel tests to execute - /// - public int ParallelTestCount { get; set; } = 1; - - /// - /// Number of AWS resources to create per test - /// - public int ResourceCount { get; set; } = 1; - - /// - /// Whether automatic resource cleanup is enabled - /// - public bool CleanupEnabled { get; set; } = true; - - /// - /// Test execution timeout in seconds - /// - public int TimeoutSeconds { get; set; } = 300; - - /// - /// Whether to enable comprehensive error reporting - /// - public bool EnableDetailedReporting { get; set; } = true; - - /// - /// AWS region for testing - /// - public string Region { get; set; } = "us-east-1"; - - /// - /// Additional test metadata - /// - public Dictionary Metadata { get; set; } = new(); - - /// - /// Generate a unique resource name for this test scenario - /// - public string GenerateResourceName(string resourceType) - { - return $"{TestPrefix}-{resourceType}-{TestId}".ToLowerInvariant(); - } - - /// - /// Generate a unique queue name for SQS testing - /// - public string GenerateQueueName(bool isFifo = false) - { - var baseName = GenerateResourceName("queue"); - return isFifo ? $"{baseName}.fifo" : baseName; - } - - /// - /// Generate a unique topic name for SNS testing - /// - public string GenerateTopicName() - { - return GenerateResourceName("topic"); - } - - /// - /// Generate a unique KMS key alias - /// - public string GenerateKmsKeyAlias() - { - return $"alias/{GenerateResourceName("key")}"; - } - - /// - /// Validate the test scenario configuration - /// - public bool IsValid() - { - return !string.IsNullOrEmpty(TestPrefix) && - !string.IsNullOrEmpty(TestId) && - ParallelTestCount > 0 && - ResourceCount > 0 && - TimeoutSeconds > 0 && - !string.IsNullOrEmpty(Region); - } - - /// - /// Get estimated resource count for this scenario - /// - public int GetEstimatedResourceCount() - { - return ParallelTestCount * ResourceCount; - } - - /// - /// Check if scenario requires real AWS services - /// - public bool RequiresRealAwsServices() - { - return !UseLocalStack; - } - - /// - /// Get test tags for resource tagging - /// - public Dictionary GetResourceTags() - { - return new Dictionary - { - ["TestPrefix"] = TestPrefix, - ["TestId"] = TestId, - ["Environment"] = UseLocalStack ? "LocalStack" : "AWS", - ["CreatedBy"] = "SourceFlow.Tests", - ["CreatedAt"] = DateTime.UtcNow.ToString("yyyy-MM-ddTHH:mm:ssZ") - }; - } -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/IAwsResourceManager.cs b/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/IAwsResourceManager.cs deleted file mode 100644 index 01ed5e09..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/IAwsResourceManager.cs +++ /dev/null @@ -1,198 +0,0 @@ -namespace SourceFlow.Cloud.AWS.Tests.TestHelpers; - -/// -/// Interface for managing AWS test resources -/// Provides automated provisioning, tracking, and cleanup of AWS resources for testing -/// -public interface IAwsResourceManager : IAsyncDisposable -{ - /// - /// Create a complete set of test resources with unique naming - /// - /// Unique prefix for all resources - /// Types of resources to create - /// Resource set with all created resources - Task CreateTestResourcesAsync(string testPrefix, AwsResourceTypes resourceTypes = AwsResourceTypes.All); - - /// - /// Clean up all resources in the specified resource set - /// - /// Resource set to clean up - /// Force cleanup even if resources are in use - Task CleanupResourcesAsync(AwsResourceSet resources, bool force = false); - - /// - /// Check if a specific AWS resource exists - /// - /// AWS resource ARN or identifier - /// True if resource exists - Task ResourceExistsAsync(string resourceArn); - - /// - /// List all test resources with the specified prefix - /// - /// Test prefix to filter by - /// List of resource identifiers - Task> ListTestResourcesAsync(string testPrefix); - - /// - /// Clean up all test resources older than the specified age - /// - /// Maximum age of resources to keep - /// Optional prefix filter - /// Number of resources cleaned up - Task CleanupOldResourcesAsync(TimeSpan maxAge, string? testPrefix = null); - - /// - /// Get cost estimate for the specified resource set - /// - /// Resource set to estimate - /// Expected usage duration - /// Estimated cost in USD - Task EstimateCostAsync(AwsResourceSet resources, TimeSpan duration); - - /// - /// Tag resources for tracking and cost allocation - /// - /// Resource to tag - /// Tags to apply - Task TagResourceAsync(string resourceArn, Dictionary tags); - - /// - /// Create a CloudFormation stack for complex resource provisioning - /// - /// Name of the CloudFormation stack - /// CloudFormation template - /// Stack parameters - /// Stack ARN - Task CreateCloudFormationStackAsync(string stackName, string templateBody, Dictionary? parameters = null); - - /// - /// Delete a CloudFormation stack and all its resources - /// - /// Name of the stack to delete - Task DeleteCloudFormationStackAsync(string stackName); -} - -/// -/// AWS resource set containing all created test resources -/// -public class AwsResourceSet -{ - /// - /// Unique test prefix for all resources - /// - public string TestPrefix { get; set; } = ""; - - /// - /// SQS queue URLs - /// - public List QueueUrls { get; set; } = new(); - - /// - /// SNS topic ARNs - /// - public List TopicArns { get; set; } = new(); - - /// - /// KMS key IDs - /// - public List KmsKeyIds { get; set; } = new(); - - /// - /// IAM role ARNs - /// - public List IamRoleArns { get; set; } = new(); - - /// - /// CloudFormation stack ARNs - /// - public List CloudFormationStacks { get; set; } = new(); - - /// - /// When the resource set was created - /// - public DateTime CreatedAt { get; set; } = DateTime.UtcNow; - - /// - /// Resource tags for tracking and cost allocation - /// - public Dictionary Tags { get; set; } = new(); - - /// - /// Additional metadata about the resources - /// - public Dictionary Metadata { get; set; } = new(); - - /// - /// Get all resource identifiers in this set - /// - public IEnumerable GetAllResourceIds() - { - return QueueUrls - .Concat(TopicArns) - .Concat(KmsKeyIds) - .Concat(IamRoleArns) - .Concat(CloudFormationStacks); - } - - /// - /// Check if the resource set is empty - /// - public bool IsEmpty => !GetAllResourceIds().Any(); -} - -/// -/// Types of AWS resources to create -/// -[Flags] -public enum AwsResourceTypes -{ - None = 0, - SqsQueues = 1, - SnsTopics = 2, - KmsKeys = 4, - IamRoles = 8, - All = SqsQueues | SnsTopics | KmsKeys | IamRoles -} - -/// -/// AWS health check result for a specific service -/// -public class AwsHealthCheckResult -{ - /// - /// AWS service name - /// - public string ServiceName { get; set; } = ""; - - /// - /// Whether the service is available - /// - public bool IsAvailable { get; set; } - - /// - /// Response time for the health check - /// - public TimeSpan ResponseTime { get; set; } - - /// - /// Service endpoint URL - /// - public string Endpoint { get; set; } = ""; - - /// - /// Additional service metrics - /// - public Dictionary ServiceMetrics { get; set; } = new(); - - /// - /// Any errors encountered during health check - /// - public List Errors { get; set; } = new(); - - /// - /// Timestamp of the health check - /// - public DateTime CheckedAt { get; set; } = DateTime.UtcNow; -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/IAwsTestEnvironment.cs b/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/IAwsTestEnvironment.cs deleted file mode 100644 index a89dc674..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/IAwsTestEnvironment.cs +++ /dev/null @@ -1,98 +0,0 @@ -using Amazon.IdentityManagement; -using Amazon.KeyManagementService; -using Amazon.SimpleNotificationService; -using Amazon.SQS; - -namespace SourceFlow.Cloud.AWS.Tests.TestHelpers; - -/// -/// Enhanced AWS test environment interface with full AWS service support -/// Provides comprehensive AWS service clients and resource management capabilities -/// -public interface IAwsTestEnvironment : ICloudTestEnvironment -{ - /// - /// SQS client for queue operations - /// - IAmazonSQS SqsClient { get; } - - /// - /// SNS client for topic operations - /// - IAmazonSimpleNotificationService SnsClient { get; } - - /// - /// KMS client for encryption operations - /// - IAmazonKeyManagementService KmsClient { get; } - - /// - /// IAM client for identity and access management - /// - IAmazonIdentityManagementService IamClient { get; } - - /// - /// Create a FIFO SQS queue with the specified name - /// - /// Name of the queue (will be suffixed with .fifo if not already) - /// Optional queue attributes - /// Queue URL - Task CreateFifoQueueAsync(string queueName, Dictionary? attributes = null); - - /// - /// Create a standard SQS queue with the specified name - /// - /// Name of the queue - /// Optional queue attributes - /// Queue URL - Task CreateStandardQueueAsync(string queueName, Dictionary? attributes = null); - - /// - /// Create an SNS topic with the specified name - /// - /// Name of the topic - /// Optional topic attributes - /// Topic ARN - Task CreateTopicAsync(string topicName, Dictionary? attributes = null); - - /// - /// Create a KMS key with the specified alias - /// - /// Alias for the key (without 'alias/' prefix) - /// Optional key description - /// Key ID - Task CreateKmsKeyAsync(string keyAlias, string? description = null); - - /// - /// Validate IAM permissions for a specific action and resource - /// - /// AWS action (e.g., "sqs:SendMessage") - /// AWS resource ARN - /// True if permission is granted, false otherwise - Task ValidateIamPermissionsAsync(string action, string resource); - - /// - /// Delete a queue by URL - /// - /// Queue URL to delete - Task DeleteQueueAsync(string queueUrl); - - /// - /// Delete a topic by ARN - /// - /// Topic ARN to delete - Task DeleteTopicAsync(string topicArn); - - /// - /// Delete a KMS key by ID or alias - /// - /// Key ID or alias - /// Pending deletion window (7-30 days) - Task DeleteKmsKeyAsync(string keyId, int pendingWindowInDays = 7); - - /// - /// Get health status for all AWS services - /// - /// Health check results for each service - Task> GetHealthStatusAsync(); -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/ICloudTestEnvironment.cs b/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/ICloudTestEnvironment.cs deleted file mode 100644 index 8024c082..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/ICloudTestEnvironment.cs +++ /dev/null @@ -1,35 +0,0 @@ -using Microsoft.Extensions.DependencyInjection; - -namespace SourceFlow.Cloud.AWS.Tests.TestHelpers; - -/// -/// Base interface for cloud test environments -/// Provides common functionality for managing cloud service test environments -/// -public interface ICloudTestEnvironment : IAsyncDisposable -{ - /// - /// Whether this environment uses local emulators - /// - bool IsLocalEmulator { get; } - - /// - /// Initialize the test environment - /// - Task InitializeAsync(); - - /// - /// Check if the environment is available and ready for testing - /// - Task IsAvailableAsync(); - - /// - /// Create a service collection configured for this test environment - /// - IServiceCollection CreateTestServices(); - - /// - /// Clean up all test resources - /// - Task CleanupAsync(); -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/ILocalStackManager.cs b/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/ILocalStackManager.cs deleted file mode 100644 index b4e545d4..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/ILocalStackManager.cs +++ /dev/null @@ -1,99 +0,0 @@ -namespace SourceFlow.Cloud.AWS.Tests.TestHelpers; - -/// -/// Interface for managing LocalStack container lifecycle -/// Provides comprehensive container management for AWS service emulation -/// -public interface ILocalStackManager : IAsyncDisposable -{ - /// - /// Whether LocalStack container is currently running - /// - bool IsRunning { get; } - - /// - /// LocalStack container endpoint URL - /// - string Endpoint { get; } - - /// - /// Start LocalStack container with the specified configuration - /// - /// LocalStack configuration - Task StartAsync(LocalStackConfiguration config); - - /// - /// Stop LocalStack container and clean up resources - /// - Task StopAsync(); - - /// - /// Check if a specific AWS service is available in LocalStack - /// - /// AWS service name (e.g., "sqs", "sns", "kms") - /// True if service is available and ready - Task IsServiceAvailableAsync(string serviceName); - - /// - /// Wait for multiple AWS services to become available - /// - /// Service names to wait for - /// Maximum time to wait - Task WaitForServicesAsync(string[] services, TimeSpan? timeout = null); - - /// - /// Get the endpoint URL for a specific AWS service - /// - /// AWS service name - /// Service endpoint URL - string GetServiceEndpoint(string serviceName); - - /// - /// Get health status for all enabled services - /// - /// Dictionary of service names and their health status - Task> GetServicesHealthAsync(); - - /// - /// Reset LocalStack data (clear all resources) - /// - Task ResetDataAsync(); - - /// - /// Get LocalStack container logs - /// - /// Number of lines to retrieve from the end - /// Container logs - Task GetLogsAsync(int tail = 100); -} - -/// -/// LocalStack service health information -/// -public class LocalStackServiceHealth -{ - /// - /// Service name - /// - public string ServiceName { get; set; } = ""; - - /// - /// Whether the service is available - /// - public bool IsAvailable { get; set; } - - /// - /// Service status message - /// - public string Status { get; set; } = ""; - - /// - /// Last health check timestamp - /// - public DateTime LastChecked { get; set; } - - /// - /// Response time for health check - /// - public TimeSpan ResponseTime { get; set; } -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/LocalStackConfiguration.cs b/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/LocalStackConfiguration.cs deleted file mode 100644 index a5eb351c..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/LocalStackConfiguration.cs +++ /dev/null @@ -1,263 +0,0 @@ -namespace SourceFlow.Cloud.AWS.Tests.TestHelpers; - -/// -/// Configuration for LocalStack container and AWS service emulation -/// -public class LocalStackConfiguration -{ - /// - /// LocalStack container image to use - /// - public string Image { get; set; } = "localstack/localstack:3"; - - /// - /// LocalStack endpoint URL (typically http://localhost:4566) - /// - public string Endpoint { get; set; } = "http://localhost:4566"; - - /// - /// Port to bind LocalStack to (default 4566) - /// - public int Port { get; set; } = 4566; - - /// - /// AWS services to enable in LocalStack - /// - public List EnabledServices { get; set; } = new() { "sqs", "sns", "kms", "iam" }; - - /// - /// Enable debug logging in LocalStack - /// - public bool Debug { get; set; } = false; - - /// - /// Persist LocalStack data between container restarts - /// - public bool PersistData { get; set; } = false; - - /// - /// Data directory for persistent storage - /// - public string DataDirectory { get; set; } = "/tmp/localstack/data"; - - /// - /// Additional environment variables for LocalStack container - /// - public Dictionary EnvironmentVariables { get; set; } = new(); - - /// - /// Container startup timeout - /// - public TimeSpan StartupTimeout { get; set; } = TimeSpan.FromMinutes(2); - - /// - /// Health check timeout for individual services - /// - public TimeSpan HealthCheckTimeout { get; set; } = TimeSpan.FromSeconds(30); - - /// - /// Maximum number of health check retries - /// - public int MaxHealthCheckRetries { get; set; } = 10; - - /// - /// Delay between health check retries - /// - public TimeSpan HealthCheckRetryDelay { get; set; } = TimeSpan.FromSeconds(2); - - /// - /// Whether to automatically remove the container on disposal - /// - public bool AutoRemove { get; set; } = true; - - /// - /// Container name (auto-generated if not specified) - /// - public string? ContainerName { get; set; } - - /// - /// Network mode for the container - /// - public string NetworkMode { get; set; } = "bridge"; - - /// - /// Additional port bindings for the container - /// - public Dictionary AdditionalPortBindings { get; set; } = new(); - - /// - /// Volume mounts for the container - /// - public Dictionary VolumeMounts { get; set; } = new(); - - /// - /// Get all environment variables including defaults - /// - public Dictionary GetAllEnvironmentVariables() - { - var env = new Dictionary - { - ["SERVICES"] = string.Join(",", EnabledServices), - ["DEBUG"] = Debug ? "1" : "0", - ["DATA_DIR"] = DataDirectory - }; - - if (PersistData) - { - env["PERSISTENCE"] = "1"; - } - - // Add custom environment variables - foreach (var kvp in EnvironmentVariables) - { - env[kvp.Key] = kvp.Value; - } - - return env; - } - - /// - /// Get all port bindings including additional ones - /// - public Dictionary GetAllPortBindings() - { - var ports = new Dictionary { [Port] = Port }; - - foreach (var kvp in AdditionalPortBindings) - { - ports[kvp.Key] = kvp.Value; - } - - return ports; - } - - /// - /// Create a default configuration for testing - /// - public static LocalStackConfiguration CreateDefault() - { - return new LocalStackConfiguration - { - EnabledServices = new List { "sqs", "sns", "kms", "iam" }, - Debug = true, - PersistData = false, - AutoRemove = true - }; - } - - /// - /// Create a configuration for performance testing - /// - public static LocalStackConfiguration CreateForPerformanceTesting() - { - return new LocalStackConfiguration - { - EnabledServices = new List { "sqs", "sns", "kms" }, - Debug = false, - PersistData = false, - AutoRemove = true, - EnvironmentVariables = new Dictionary - { - ["LOCALSTACK_API_KEY"] = "", // Use free tier - ["DISABLE_CORS_CHECKS"] = "1", - ["SKIP_INFRA_DOWNLOADS"] = "1" - } - }; - } - - /// - /// Create a configuration for security testing - /// - public static LocalStackConfiguration CreateForSecurityTesting() - { - return new LocalStackConfiguration - { - EnabledServices = new List { "sqs", "sns", "kms", "iam", "sts" }, - Debug = true, - PersistData = false, - AutoRemove = true, - EnvironmentVariables = new Dictionary - { - ["ENFORCE_IAM"] = "1", - ["IAM_LOAD_MANAGED_POLICIES"] = "1" - } - }; - } - - /// - /// Create a configuration for comprehensive integration testing - /// - public static LocalStackConfiguration CreateForIntegrationTesting() - { - return new LocalStackConfiguration - { - EnabledServices = new List { "sqs", "sns", "kms", "iam", "sts", "cloudformation" }, - Debug = true, - PersistData = false, - AutoRemove = true, - HealthCheckTimeout = TimeSpan.FromSeconds(90), - MaxHealthCheckRetries = 30, - HealthCheckRetryDelay = TimeSpan.FromSeconds(3), - EnvironmentVariables = new Dictionary - { - ["DISABLE_CORS_CHECKS"] = "1", - ["SKIP_INFRA_DOWNLOADS"] = "1", - ["ENFORCE_IAM"] = "0", // Disable for easier testing - ["LOCALSTACK_API_KEY"] = "", // Use free tier - ["PERSISTENCE"] = "0" - } - }; - } - - /// - /// Create a configuration optimized for GitHub Actions CI environment. - /// Uses extended timeouts and enhanced retry logic to accommodate slower - /// container initialization in CI environments. - /// - /// A LocalStackConfiguration with CI-optimized settings - public static LocalStackConfiguration CreateForGitHubActions() - { - return new LocalStackConfiguration - { - EnabledServices = new List { "sqs", "sns", "kms", "iam", "sts", "cloudformation" }, - Debug = true, - PersistData = false, - AutoRemove = true, - StartupTimeout = TimeSpan.FromMinutes(3), - HealthCheckTimeout = TimeSpan.FromSeconds(90), - MaxHealthCheckRetries = 30, - HealthCheckRetryDelay = TimeSpan.FromSeconds(3), - EnvironmentVariables = new Dictionary - { - ["DISABLE_CORS_CHECKS"] = "1", - ["SKIP_INFRA_DOWNLOADS"] = "1", - ["ENFORCE_IAM"] = "0", // Disable for easier testing - ["LOCALSTACK_API_KEY"] = "", // Use free tier - ["PERSISTENCE"] = "0", - ["DEBUG"] = "1", - ["LS_LOG"] = "info" // Enhanced diagnostics for CI troubleshooting - } - }; - } - - /// - /// Create a configuration with enhanced diagnostics - /// - public static LocalStackConfiguration CreateWithDiagnostics() - { - return new LocalStackConfiguration - { - EnabledServices = new List { "sqs", "sns", "kms", "iam" }, - Debug = true, - PersistData = false, - AutoRemove = true, - EnvironmentVariables = new Dictionary - { - ["DEBUG"] = "1", - ["LS_LOG"] = "trace", - ["DISABLE_CORS_CHECKS"] = "1", - ["SKIP_INFRA_DOWNLOADS"] = "1" - } - }; - } -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/LocalStackManager.cs b/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/LocalStackManager.cs deleted file mode 100644 index 0e8c8c69..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/LocalStackManager.cs +++ /dev/null @@ -1,861 +0,0 @@ -using DotNet.Testcontainers.Builders; -using DotNet.Testcontainers.Containers; -using Microsoft.Extensions.Logging; -using System.Text.Json; -using System.Net; -using System.Net.NetworkInformation; -using Amazon.SQS; -using Amazon.SimpleNotificationService; -using Amazon.KeyManagementService; -using Amazon.IdentityManagement; - -namespace SourceFlow.Cloud.AWS.Tests.TestHelpers; - -/// -/// LocalStack container manager implementation -/// Provides comprehensive container lifecycle management for AWS service emulation -/// with enhanced port management, service validation, and diagnostics -/// -public class LocalStackManager : ILocalStackManager -{ - private readonly ILogger _logger; - private IContainer? _container; - private LocalStackConfiguration? _configuration; - private bool _disposed; - private bool _isExternalInstance; - private readonly Dictionary _serviceReadyTimes = new(); - private readonly object _lockObject = new(); - - public LocalStackManager(ILogger logger) - { - _logger = logger ?? throw new ArgumentNullException(nameof(logger)); - } - - /// - public bool IsRunning => _container?.State == TestcontainersStates.Running || _isExternalInstance; - - /// - public string Endpoint => _configuration?.Endpoint ?? "http://localhost:4566"; - - /// - public async Task StartAsync(LocalStackConfiguration config) - { - lock (_lockObject) - { - if (_container != null && IsRunning) - { - _logger.LogInformation("LocalStack container is already running"); - return; - } - } - - _configuration = config ?? throw new ArgumentNullException(nameof(config)); - - // Check if LocalStack is already running externally (e.g., in GitHub Actions) - if (await IsExternalLocalStackAvailableAsync(config.Endpoint)) - { - _logger.LogInformation("Detected existing LocalStack instance at {Endpoint}, using it instead of starting new container", config.Endpoint); - _isExternalInstance = true; - return; - } - - _logger.LogInformation("Starting LocalStack container with services: {Services}", string.Join(", ", config.EnabledServices)); - - // Ensure port is available before starting - var availablePort = await FindAvailablePortAsync(config.Port); - if (availablePort != config.Port) - { - _logger.LogWarning("Port {RequestedPort} is not available, using {AvailablePort} instead", config.Port, availablePort); - config.Port = availablePort; - config.Endpoint = $"http://localhost:{availablePort}"; - } - - var containerBuilder = new ContainerBuilder() - .WithImage(config.Image) - .WithName(config.ContainerName ?? $"localstack-test-{Guid.NewGuid():N}") - .WithAutoRemove(config.AutoRemove) - .WithCleanUp(true); - - // Add port bindings with automatic port management - var portBindings = config.GetAllPortBindings(); - foreach (var portBinding in portBindings) - { - var hostPort = await FindAvailablePortAsync(portBinding.Value); - containerBuilder = containerBuilder.WithPortBinding((ushort)hostPort, (ushort)portBinding.Key); - _logger.LogDebug("Binding container port {ContainerPort} to host port {HostPort}", portBinding.Key, hostPort); - } - - // Add environment variables with enhanced configuration - var environmentVariables = config.GetAllEnvironmentVariables(); - foreach (var env in environmentVariables) - { - containerBuilder = containerBuilder.WithEnvironment(env.Key, env.Value); - } - - // Add volume mounts for data persistence - foreach (var volume in config.VolumeMounts) - { - containerBuilder = containerBuilder.WithBindMount(volume.Key, volume.Value); - } - - // Enhanced wait strategy with multiple health checks - var waitStrategy = Wait.ForUnixContainer() - .UntilHttpRequestIsSucceeded(r => r - .ForPort((ushort)availablePort) - .ForPath("/_localstack/health") - .ForStatusCode(HttpStatusCode.OK)) - .UntilHttpRequestIsSucceeded(r => r - .ForPort((ushort)availablePort) - .ForPath("/_localstack/init") - .ForStatusCode(HttpStatusCode.OK)); // Only check for OK status - - containerBuilder = containerBuilder.WithWaitStrategy(waitStrategy); - - _container = containerBuilder.Build(); - - try - { - _logger.LogInformation("Starting LocalStack container..."); - await _container.StartAsync(); - _logger.LogInformation("LocalStack container started successfully on {Endpoint}", Endpoint); - - // Validate container is actually running - if (!IsRunning) - { - throw new InvalidOperationException("LocalStack container failed to start properly"); - } - - // Add initial delay to allow LocalStack initialization scripts to run - // This is critical in CI environments where service initialization is slower - var isCI = !string.IsNullOrEmpty(Environment.GetEnvironmentVariable("GITHUB_ACTIONS")); - var initialDelay = isCI ? TimeSpan.FromSeconds(5) : TimeSpan.FromSeconds(2); - - _logger.LogInformation("Waiting {DelaySeconds} seconds for LocalStack initialization scripts to complete (CI: {IsCI})", - initialDelay.TotalSeconds, isCI); - await Task.Delay(initialDelay); - - // Wait for services to be ready with enhanced validation - await WaitForServicesAsync(config.EnabledServices.ToArray(), config.HealthCheckTimeout); - - // Perform comprehensive service validation - await ValidateAwsServicesAsync(config.EnabledServices); - - _logger.LogInformation("LocalStack container is fully ready with all services available"); - } - catch (Exception ex) - { - _logger.LogError(ex, "Failed to start LocalStack container"); - await StopAsync(); - throw new InvalidOperationException($"LocalStack container startup failed: {ex.Message}", ex); - } - } - - /// - public async Task StopAsync() - { - if (_isExternalInstance) - { - _logger.LogInformation("Using external LocalStack instance — skipping stop"); - _isExternalInstance = false; - _configuration = null; - return; - } - - if (_container == null) - return; - - _logger.LogInformation("Stopping LocalStack container"); - - try - { - if (_container.State == TestcontainersStates.Running) - { - await _container.StopAsync(); - } - } - catch (Exception ex) - { - _logger.LogWarning(ex, "Error stopping LocalStack container"); - } - finally - { - await _container.DisposeAsync(); - _container = null; - _configuration = null; - } - - _logger.LogInformation("LocalStack container stopped"); - } - - /// - public async Task IsServiceAvailableAsync(string serviceName) - { - if (!IsRunning || _configuration == null) - return false; - - try - { - var healthStatus = await GetServicesHealthAsync(); - return healthStatus.ContainsKey(serviceName) && healthStatus[serviceName].IsAvailable; - } - catch (Exception ex) - { - _logger.LogDebug(ex, "Failed to check service availability for {ServiceName}", serviceName); - return false; - } - } - - /// - public async Task WaitForServicesAsync(string[] services, TimeSpan? timeout = null) - { - if (!IsRunning || _configuration == null) - throw new InvalidOperationException("LocalStack container is not running"); - - var actualTimeout = timeout ?? _configuration.HealthCheckTimeout; - var retryDelay = _configuration.HealthCheckRetryDelay; - var maxRetries = _configuration.MaxHealthCheckRetries; - - // Detect CI environment for enhanced diagnostics - var isCI = !string.IsNullOrEmpty(Environment.GetEnvironmentVariable("GITHUB_ACTIONS")); - - _logger.LogInformation("Waiting for LocalStack services to be ready: {Services} (CI: {IsCI}, Timeout: {Timeout}s, MaxRetries: {MaxRetries})", - string.Join(", ", services), isCI, actualTimeout.TotalSeconds, maxRetries); - - var startTime = DateTime.UtcNow; - var retryCount = 0; - var lastErrors = new List(); - var lastHealthResponse = string.Empty; - - while (DateTime.UtcNow - startTime < actualTimeout && retryCount < maxRetries) - { - try - { - var healthCheckStartTime = DateTime.UtcNow; - var healthStatus = await GetServicesHealthAsync(); - var healthCheckResponseTime = DateTime.UtcNow - healthCheckStartTime; - - var serviceStatuses = new Dictionary(); - - foreach (var service in services) - { - if (healthStatus.ContainsKey(service)) - { - var status = healthStatus[service].Status; - var isReady = healthStatus[service].IsAvailable; - serviceStatuses[service] = status; - - if (isReady && !_serviceReadyTimes.ContainsKey(service)) - { - _serviceReadyTimes[service] = DateTime.UtcNow; - _logger.LogInformation("Service {ServiceName} became ready with status '{Status}' after {ElapsedTime}ms", - service, status, (DateTime.UtcNow - startTime).TotalMilliseconds); - } - } - else - { - serviceStatuses[service] = "not_found"; - } - } - - var allReady = serviceStatuses.All(kvp => - healthStatus.ContainsKey(kvp.Key) && healthStatus[kvp.Key].IsAvailable); - - if (allReady) - { - _logger.LogInformation("All LocalStack services are ready after {ElapsedTime}ms (total attempts: {Attempts})", - (DateTime.UtcNow - startTime).TotalMilliseconds, retryCount + 1); - - // Log individual service ready times for diagnostics - foreach (var service in services) - { - if (_serviceReadyTimes.ContainsKey(service)) - { - var readyTime = (_serviceReadyTimes[service] - startTime).TotalMilliseconds; - _logger.LogDebug("Service {ServiceName} ready time: {ReadyTime}ms", service, readyTime); - } - } - - return; - } - - // Enhanced logging: log individual service status on each retry - var statusDetails = serviceStatuses - .Select(kvp => $"{kvp.Key}:{kvp.Value}") - .ToList(); - - var notReadyServices = serviceStatuses - .Where(kvp => !healthStatus.ContainsKey(kvp.Key) || !healthStatus[kvp.Key].IsAvailable) - .Select(kvp => kvp.Key) - .ToList(); - - _logger.LogInformation("Health check attempt {Attempt}/{MaxAttempts} - Services status: [{StatusDetails}] - Not ready: [{NotReadyServices}] - Response time: {ResponseTime}ms - Elapsed: {ElapsedTime}ms", - retryCount + 1, maxRetries, - string.Join(", ", statusDetails), - string.Join(", ", notReadyServices), - healthCheckResponseTime.TotalMilliseconds, - (DateTime.UtcNow - startTime).TotalMilliseconds); - - lastErrors.Clear(); - } - catch (Exception ex) - { - var errorMessage = $"Health check failed: {ex.Message}"; - lastErrors.Add(errorMessage); - - // Enhanced error logging with response time - var elapsedTime = DateTime.UtcNow - startTime; - _logger.LogWarning(ex, "Health check failed (attempt {Attempt}/{MaxAttempts}, elapsed: {ElapsedTime}ms, CI: {IsCI}): {ErrorMessage}", - retryCount + 1, maxRetries, elapsedTime.TotalMilliseconds, isCI, ex.Message); - - // Try to capture the health endpoint response for diagnostics - try - { - using var httpClient = new HttpClient(); - httpClient.Timeout = TimeSpan.FromSeconds(5); - var healthUrl = $"{_configuration.Endpoint}/_localstack/health"; - var response = await httpClient.GetAsync(healthUrl); - lastHealthResponse = await response.Content.ReadAsStringAsync(); - - if (response.IsSuccessStatusCode) - { - // Parse and log individual service statuses from the JSON response - try - { - var healthData = JsonSerializer.Deserialize(lastHealthResponse); - if (healthData?.Services != null) - { - var serviceDetails = healthData.Services - .Select(s => $"{s.Key}:{s.Value}") - .ToList(); - - _logger.LogInformation("Health endpoint JSON response (attempt {Attempt}/{MaxAttempts}): Services=[{ServiceDetails}], Version={Version}", - retryCount + 1, maxRetries, string.Join(", ", serviceDetails), healthData.Version ?? "unknown"); - } - else - { - _logger.LogWarning("Health endpoint returned empty services list (attempt {Attempt}/{MaxAttempts})", - retryCount + 1, maxRetries); - } - } - catch (JsonException jsonEx) - { - _logger.LogWarning(jsonEx, "Failed to parse health endpoint JSON response (attempt {Attempt}/{MaxAttempts}): {Response}", - retryCount + 1, maxRetries, lastHealthResponse); - } - } - else - { - _logger.LogWarning("Health endpoint returned non-success status {StatusCode} (attempt {Attempt}/{MaxAttempts}): {Response}", - response.StatusCode, retryCount + 1, maxRetries, lastHealthResponse); - } - } - catch (Exception healthEx) - { - _logger.LogDebug(healthEx, "Failed to capture health endpoint response for diagnostics (attempt {Attempt}/{MaxAttempts})", - retryCount + 1, maxRetries); - } - } - - retryCount++; - await Task.Delay(retryDelay); - } - - // Enhanced timeout error message with detailed diagnostics - var errorDetails = lastErrors.Any() ? $" Last errors: {string.Join("; ", lastErrors)}" : ""; - var healthResponseDetails = !string.IsNullOrEmpty(lastHealthResponse) - ? $" Last health response: {lastHealthResponse}" - : ""; - - var serviceReadyTimesDetails = _serviceReadyTimes.Any() - ? $" Services that became ready: {string.Join(", ", _serviceReadyTimes.Select(kvp => $"{kvp.Key}@{(kvp.Value - startTime).TotalMilliseconds}ms"))}" - : " No services became ready"; - - throw new TimeoutException( - $"LocalStack services did not become ready within {actualTimeout} (CI: {isCI}, Attempts: {retryCount}/{maxRetries}): " + - $"{string.Join(", ", services)}.{errorDetails}{healthResponseDetails}{serviceReadyTimesDetails}"); - } - - /// - public string GetServiceEndpoint(string serviceName) - { - if (_configuration == null) - throw new InvalidOperationException("LocalStack is not configured"); - - // LocalStack uses a single endpoint for all services - return _configuration.Endpoint; - } - - /// - public async Task> GetServicesHealthAsync() - { - if (!IsRunning || _configuration == null) - return new Dictionary(); - - try - { - using var httpClient = new HttpClient(); - httpClient.Timeout = TimeSpan.FromSeconds(10); - - var healthUrl = $"{_configuration.Endpoint}/_localstack/health"; - var startTime = DateTime.UtcNow; - - var response = await httpClient.GetAsync(healthUrl); - var responseTime = DateTime.UtcNow - startTime; - - if (!response.IsSuccessStatusCode) - { - _logger.LogWarning("LocalStack health check returned {StatusCode}", response.StatusCode); - return new Dictionary(); - } - - var content = await response.Content.ReadAsStringAsync(); - var healthData = JsonSerializer.Deserialize(content); - - var result = new Dictionary(); - - if (healthData?.Services != null) - { - foreach (var service in healthData.Services) - { - result[service.Key] = new LocalStackServiceHealth - { - ServiceName = service.Key, - IsAvailable = service.Value == "available" || service.Value == "running", - Status = service.Value, - LastChecked = DateTime.UtcNow, - ResponseTime = responseTime - }; - } - } - - return result; - } - catch (Exception ex) - { - _logger.LogWarning(ex, "Failed to get LocalStack services health"); - return new Dictionary(); - } - } - - /// - public async Task ResetDataAsync() - { - if (!IsRunning || _configuration == null) - throw new InvalidOperationException("LocalStack container is not running"); - - try - { - if (_isExternalInstance) - { - // For external instances, use LocalStack's state reset API - _logger.LogInformation("Resetting LocalStack data via HTTP state reset API"); - using var httpClient = new HttpClient { Timeout = TimeSpan.FromSeconds(10) }; - var resetUrl = $"{_configuration.Endpoint}/_localstack/state/reset"; - var response = await httpClient.PostAsync(resetUrl, null); - if (!response.IsSuccessStatusCode) - { - _logger.LogWarning("LocalStack state reset API returned {StatusCode}", response.StatusCode); - } - return; - } - - // For managed containers, restart the container - _logger.LogInformation("Resetting LocalStack data by restarting container"); - var savedConfig = _configuration; - await StopAsync(); - await StartAsync(savedConfig); - } - catch (Exception ex) - { - _logger.LogError(ex, "Failed to reset LocalStack data"); - throw; - } - } - - /// - public async Task GetLogsAsync(int tail = 100) - { - if (_container == null) - return "Container not available"; - - try - { - var (stdout, stderr) = await _container.GetLogsAsync(); - var logs = $"STDOUT:\n{stdout}\n\nSTDERR:\n{stderr}"; - - // Simple tail implementation - var lines = logs.Split('\n'); - if (lines.Length > tail) - { - lines = lines.TakeLast(tail).ToArray(); - } - - return string.Join('\n', lines); - } - catch (Exception ex) - { - _logger.LogWarning(ex, "Failed to get LocalStack container logs"); - return $"Failed to get logs: {ex.Message}"; - } - } - - /// - /// Check if an external LocalStack instance is already available - /// Uses enhanced detection with retry logic and service status validation - /// - /// LocalStack endpoint to check - /// True if external LocalStack is available with services ready - private async Task IsExternalLocalStackAvailableAsync(string endpoint) - { - // Detect CI environment for appropriate timeout configuration - var isCI = !string.IsNullOrEmpty(Environment.GetEnvironmentVariable("GITHUB_ACTIONS")); - var timeout = isCI ? TimeSpan.FromSeconds(10) : TimeSpan.FromSeconds(3); - var maxAttempts = 3; - var retryDelay = TimeSpan.FromSeconds(2); - - _logger.LogDebug("Checking for external LocalStack instance at {Endpoint} (CI: {IsCI}, Timeout: {Timeout}s, Attempts: {MaxAttempts})", - endpoint, isCI, timeout.TotalSeconds, maxAttempts); - - var startTime = DateTime.UtcNow; - - for (int attempt = 1; attempt <= maxAttempts; attempt++) - { - try - { - using var httpClient = new HttpClient(); - httpClient.Timeout = timeout; - - var healthUrl = $"{endpoint}/_localstack/health"; - var attemptStartTime = DateTime.UtcNow; - var response = await httpClient.GetAsync(healthUrl); - var responseTime = DateTime.UtcNow - attemptStartTime; - - if (!response.IsSuccessStatusCode) - { - _logger.LogDebug("External LocalStack health check returned {StatusCode} (attempt {Attempt}/{MaxAttempts}, response time: {ResponseTime}ms)", - response.StatusCode, attempt, maxAttempts, responseTime.TotalMilliseconds); - - if (attempt < maxAttempts) - { - await Task.Delay(retryDelay); - continue; - } - return false; - } - - // If we get HTTP 200, LocalStack is running - accept it even if services aren't fully ready yet - // We'll wait for services to become ready in WaitForServicesAsync - var content = await response.Content.ReadAsStringAsync(); - - try - { - var healthData = JsonSerializer.Deserialize(content); - - if (healthData?.Services != null && healthData.Services.Count > 0) - { - var serviceStatus = healthData.Services - .Select(s => $"{s.Key}:{s.Value}") - .ToList(); - - _logger.LogInformation("Successfully detected external LocalStack instance at {Endpoint} with {ServiceCount} services: {Services} (response time: {ResponseTime}ms)", - endpoint, healthData.Services.Count, string.Join(", ", serviceStatus), responseTime.TotalMilliseconds); - } - else - { - _logger.LogInformation("Successfully detected external LocalStack instance at {Endpoint} (services still initializing, response time: {ResponseTime}ms)", - endpoint, responseTime.TotalMilliseconds); - } - } - catch (JsonException) - { - // JSON parsing failed, but we got HTTP 200, so LocalStack is running - _logger.LogInformation("Successfully detected external LocalStack instance at {Endpoint} (health endpoint responded, response time: {ResponseTime}ms)", - endpoint, responseTime.TotalMilliseconds); - } - - var totalTime = DateTime.UtcNow - startTime; - _logger.LogDebug("External LocalStack detection succeeded after {TotalTime}ms", totalTime.TotalMilliseconds); - - return true; - } - catch (Exception ex) - { - var elapsedTime = DateTime.UtcNow - startTime; - _logger.LogDebug(ex, "External LocalStack detection failed (attempt {Attempt}/{MaxAttempts}, elapsed: {ElapsedTime}ms): {Message}", - attempt, maxAttempts, elapsedTime.TotalMilliseconds, ex.Message); - - if (attempt < maxAttempts) - { - await Task.Delay(retryDelay); - } - } - } - - var totalElapsedTime = DateTime.UtcNow - startTime; - _logger.LogDebug("No external LocalStack instance detected at {Endpoint} after {Attempts} attempts (total time: {TotalTime}ms)", - endpoint, maxAttempts, totalElapsedTime.TotalMilliseconds); - - return false; - } - - /// - /// Find an available port starting from the specified port - /// - /// Starting port to check - /// Available port number - private async Task FindAvailablePortAsync(int startPort) - { - const int maxAttempts = 100; - var currentPort = startPort; - - for (int attempt = 0; attempt < maxAttempts; attempt++) - { - if (await IsPortAvailableAsync(currentPort)) - { - return currentPort; - } - currentPort++; - } - - throw new InvalidOperationException($"Could not find an available port starting from {startPort} after {maxAttempts} attempts"); - } - - /// - /// Check if a specific port is available - /// - /// Port to check - /// True if port is available - private async Task IsPortAvailableAsync(int port) - { - try - { - // Check if port is in use by attempting to bind to it - using var tcpListener = new System.Net.Sockets.TcpListener(IPAddress.Loopback, port); - tcpListener.Start(); - tcpListener.Stop(); - - // Also check using IPGlobalProperties for more thorough validation - var ipGlobalProperties = IPGlobalProperties.GetIPGlobalProperties(); - var tcpConnections = ipGlobalProperties.GetActiveTcpConnections(); - var tcpListeners = ipGlobalProperties.GetActiveTcpListeners(); - - var isInUse = tcpConnections.Any(c => c.LocalEndPoint.Port == port) || - tcpListeners.Any(l => l.Port == port); - - return !isInUse; - } - catch - { - // If we can't bind to the port, it's not available - return false; - } - } - - /// - /// Validate that AWS services are properly emulated and accessible - /// - /// List of services to validate - private async Task ValidateAwsServicesAsync(List enabledServices) - { - _logger.LogInformation("Validating AWS service emulation for: {Services}", string.Join(", ", enabledServices)); - - var validationTasks = new List(); - - if (enabledServices.Contains("sqs")) - { - validationTasks.Add(ValidateSqsServiceAsync()); - } - - if (enabledServices.Contains("sns")) - { - validationTasks.Add(ValidateSnsServiceAsync()); - } - - if (enabledServices.Contains("kms")) - { - validationTasks.Add(ValidateKmsServiceAsync()); - } - - if (enabledServices.Contains("iam")) - { - validationTasks.Add(ValidateIamServiceAsync()); - } - - try - { - await Task.WhenAll(validationTasks); - _logger.LogInformation("All AWS service validations completed successfully"); - } - catch (Exception ex) - { - _logger.LogError(ex, "AWS service validation failed"); - throw new InvalidOperationException($"AWS service validation failed: {ex.Message}", ex); - } - } - - /// - /// Validate SQS service emulation - /// - private async Task ValidateSqsServiceAsync() - { - try - { - var sqsClient = CreateSqsClient(); - var response = await sqsClient.ListQueuesAsync(new Amazon.SQS.Model.ListQueuesRequest()); - _logger.LogDebug("SQS service validation successful - can list queues"); - } - catch (Exception ex) - { - _logger.LogError(ex, "SQS service validation failed"); - throw new InvalidOperationException($"SQS service validation failed: {ex.Message}", ex); - } - } - - /// - /// Validate SNS service emulation - /// - private async Task ValidateSnsServiceAsync() - { - try - { - var snsClient = CreateSnsClient(); - var response = await snsClient.ListTopicsAsync(); - _logger.LogDebug("SNS service validation successful - can list topics"); - } - catch (Exception ex) - { - _logger.LogError(ex, "SNS service validation failed"); - throw new InvalidOperationException($"SNS service validation failed: {ex.Message}", ex); - } - } - - /// - /// Validate KMS service emulation - /// - private async Task ValidateKmsServiceAsync() - { - try - { - var kmsClient = CreateKmsClient(); - var response = await kmsClient.ListKeysAsync(new Amazon.KeyManagementService.Model.ListKeysRequest()); - _logger.LogDebug("KMS service validation successful - can list keys"); - } - catch (Exception ex) - { - _logger.LogError(ex, "KMS service validation failed"); - throw new InvalidOperationException($"KMS service validation failed: {ex.Message}", ex); - } - } - - /// - /// Validate IAM service emulation - /// - private async Task ValidateIamServiceAsync() - { - try - { - var iamClient = CreateIamClient(); - var response = await iamClient.ListRolesAsync(); - _logger.LogDebug("IAM service validation successful - can list roles"); - } - catch (Exception ex) - { - _logger.LogError(ex, "IAM service validation failed"); - throw new InvalidOperationException($"IAM service validation failed: {ex.Message}", ex); - } - } - - /// - /// Create an SQS client configured for LocalStack - /// - private IAmazonSQS CreateSqsClient() - { - if (_configuration == null) - throw new InvalidOperationException("LocalStack is not configured"); - - var config = new AmazonSQSConfig - { - ServiceURL = _configuration.Endpoint, - UseHttp = true, - AuthenticationRegion = "us-east-1" - }; - - return new AmazonSQSClient("test", "test", config); - } - - /// - /// Create an SNS client configured for LocalStack - /// - private IAmazonSimpleNotificationService CreateSnsClient() - { - if (_configuration == null) - throw new InvalidOperationException("LocalStack is not configured"); - - var config = new AmazonSimpleNotificationServiceConfig - { - ServiceURL = _configuration.Endpoint, - UseHttp = true, - AuthenticationRegion = "us-east-1" - }; - - return new AmazonSimpleNotificationServiceClient("test", "test", config); - } - - /// - /// Create a KMS client configured for LocalStack - /// - private IAmazonKeyManagementService CreateKmsClient() - { - if (_configuration == null) - throw new InvalidOperationException("LocalStack is not configured"); - - var config = new AmazonKeyManagementServiceConfig - { - ServiceURL = _configuration.Endpoint, - UseHttp = true, - AuthenticationRegion = "us-east-1" - }; - - return new AmazonKeyManagementServiceClient("test", "test", config); - } - - /// - /// Create an IAM client configured for LocalStack - /// - private IAmazonIdentityManagementService CreateIamClient() - { - if (_configuration == null) - throw new InvalidOperationException("LocalStack is not configured"); - - var config = new AmazonIdentityManagementServiceConfig - { - ServiceURL = _configuration.Endpoint, - UseHttp = true, - AuthenticationRegion = "us-east-1" - }; - - return new AmazonIdentityManagementServiceClient("test", "test", config); - } - - /// - public async ValueTask DisposeAsync() - { - if (_disposed) return; - - await StopAsync(); - _disposed = true; - } - - /// - /// LocalStack health response model - /// - private class LocalStackHealthResponse - { - [System.Text.Json.Serialization.JsonPropertyName("services")] - public Dictionary? Services { get; set; } - [System.Text.Json.Serialization.JsonPropertyName("version")] - public string? Version { get; set; } - [System.Text.Json.Serialization.JsonPropertyName("features")] - public Dictionary? Features { get; set; } - } -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/LocalStackRequiredTestBase.cs b/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/LocalStackRequiredTestBase.cs deleted file mode 100644 index 3c0d46c2..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/LocalStackRequiredTestBase.cs +++ /dev/null @@ -1,34 +0,0 @@ -using Xunit; -using Xunit.Abstractions; - -namespace SourceFlow.Cloud.AWS.Tests.TestHelpers; - -/// -/// Base class for tests that require LocalStack emulator. -/// Validates LocalStack availability before running tests. -/// -public abstract class LocalStackRequiredTestBase : AwsIntegrationTestBase -{ - protected LocalStackRequiredTestBase(ITestOutputHelper output) : base(output) - { - } - - /// - /// Validates that LocalStack emulator is available. - /// - protected override async Task ValidateServiceAvailabilityAsync() - { - Output.WriteLine("Checking LocalStack availability..."); - - var isAvailable = await Configuration.IsLocalStackAvailableAsync(AwsTestDefaults.ConnectionTimeout); - - if (!isAvailable) - { - var skipMessage = CreateSkipMessage("LocalStack emulator", requiresLocalStack: true, requiresAws: false); - Output.WriteLine($"SKIPPED: {skipMessage}"); - throw new InvalidOperationException($"Test skipped: {skipMessage}"); - } - - Output.WriteLine("LocalStack is available."); - } -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/LocalStackTestFixture.cs b/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/LocalStackTestFixture.cs deleted file mode 100644 index 3bffb6d8..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/LocalStackTestFixture.cs +++ /dev/null @@ -1,336 +0,0 @@ -using Amazon; -using Amazon.SQS; -using Amazon.SimpleNotificationService; -using Amazon.KeyManagementService; -using DotNet.Testcontainers.Builders; -using DotNet.Testcontainers.Containers; -using Microsoft.Extensions.DependencyInjection; -using Microsoft.Extensions.Logging; - -namespace SourceFlow.Cloud.AWS.Tests.TestHelpers; - -/// -/// Test fixture for LocalStack integration testing -/// -public class LocalStackTestFixture : IAsyncLifetime -{ - private IContainer? _localStackContainer; - private readonly AwsTestConfiguration _configuration; - - public LocalStackTestFixture() - { - _configuration = new AwsTestConfiguration(); - } - - /// - /// LocalStack endpoint URL - /// - public string LocalStackEndpoint => _configuration.LocalStackEndpoint; - - /// - /// Test configuration - /// - public AwsTestConfiguration Configuration => _configuration; - - /// - /// SQS client configured for LocalStack - /// - public IAmazonSQS? SqsClient { get; private set; } - - /// - /// SNS client configured for LocalStack - /// - public IAmazonSimpleNotificationService? SnsClient { get; private set; } - - /// - /// KMS client configured for LocalStack - /// - public IAmazonKeyManagementService? KmsClient { get; private set; } - - /// - /// Initialize LocalStack container and AWS clients - /// - public async Task InitializeAsync() - { - if (!_configuration.UseLocalStack || !_configuration.RunIntegrationTests) - { - return; - } - - // Detect GitHub Actions CI environment - bool isGitHubActions = !string.IsNullOrEmpty(Environment.GetEnvironmentVariable("GITHUB_ACTIONS")); - - // Use CI-specific configuration in GitHub Actions - LocalStackConfiguration localStackConfig; - if (isGitHubActions) - { - localStackConfig = LocalStackConfiguration.CreateForGitHubActions(); - Console.WriteLine("Using GitHub Actions CI-optimized LocalStack configuration (90s timeout, 30 retries)"); - } - else - { - localStackConfig = LocalStackConfiguration.CreateDefault(); - Console.WriteLine("Using local development LocalStack configuration (30s timeout, 10 retries)"); - } - - // Check if LocalStack is already running (e.g., in GitHub Actions) - // Use longer timeout and retry logic for CI environments - TimeSpan externalCheckTimeout = isGitHubActions ? TimeSpan.FromSeconds(10) : TimeSpan.FromSeconds(3); - int maxRetries = 3; - bool isAlreadyRunning = false; - - for (int attempt = 1; attempt <= maxRetries; attempt++) - { - try - { - Console.WriteLine($"Checking for external LocalStack instance (attempt {attempt}/{maxRetries}, timeout: {externalCheckTimeout.TotalSeconds}s)..."); - isAlreadyRunning = await _configuration.IsLocalStackAvailableAsync(externalCheckTimeout); - - if (isAlreadyRunning) - { - Console.WriteLine("Detected existing LocalStack instance - will reuse it"); - break; - } - else - { - Console.WriteLine($"No external LocalStack instance detected on attempt {attempt}"); - } - } - catch (Exception ex) - { - Console.WriteLine($"External LocalStack check failed on attempt {attempt}: {ex.Message}"); - } - - // Wait before retry (except on last attempt) - if (attempt < maxRetries && !isAlreadyRunning) - { - await Task.Delay(2000); - } - } - - if (!isAlreadyRunning) - { - // In GitHub Actions, we expect LocalStack to be provided as a service container - // If it's not detected, fail fast rather than trying to start a new container - if (isGitHubActions) - { - string errorMessage = "LocalStack service container not detected in GitHub Actions CI. " + - "Ensure the workflow has a 'services.localstack' configuration. " + - "Tests cannot start their own containers in CI due to Docker-in-Docker limitations."; - Console.WriteLine($"ERROR: {errorMessage}"); - throw new InvalidOperationException(errorMessage); - } - - Console.WriteLine("Starting new LocalStack container for local development..."); - - try - { - // Create LocalStack container (local development only) - _localStackContainer = new ContainerBuilder() - .WithImage("localstack/localstack:3") - .WithPortBinding(4566, 4566) - .WithEnvironment("SERVICES", "sqs,sns,kms") - .WithEnvironment("DEBUG", "1") - .WithEnvironment("DATA_DIR", "/tmp/localstack/data") - .WithWaitStrategy(Wait.ForUnixContainer().UntilPortIsAvailable(4566)) - .Build(); - - // Start LocalStack - await _localStackContainer.StartAsync(); - Console.WriteLine("LocalStack container started successfully"); - - // Wait for services to be ready - Console.WriteLine("Waiting 2000ms for LocalStack services to initialize..."); - await Task.Delay(2000); - } - catch (Exception ex) when (ex.ToString().Contains("port", StringComparison.OrdinalIgnoreCase)) - { - // Port conflict means another LocalStack instance is likely running but the health - // check failed under parallel test load. Retry external detection with longer timeout. - Console.WriteLine($"Docker port conflict detected ({ex.Message}). Retrying external LocalStack detection..."); - _localStackContainer = null; - - for (int retry = 1; retry <= 5; retry++) - { - await Task.Delay(1000 * retry); - try - { - isAlreadyRunning = await _configuration.IsLocalStackAvailableAsync(TimeSpan.FromSeconds(10)); - if (isAlreadyRunning) - { - Console.WriteLine($"External LocalStack instance detected on retry {retry}"); - break; - } - } - catch (Exception retryEx) - { - Console.WriteLine($"Retry {retry} failed: {retryEx.Message}"); - } - } - - if (!isAlreadyRunning) - { - throw new InvalidOperationException( - "Port 4566 is in use but LocalStack health endpoint is not responding. " + - "Ensure LocalStack is running correctly or free port 4566.", ex); - } - } - } - - // Create AWS clients configured for LocalStack - // Use BasicAWSCredentials with dummy values for LocalStack - // AnonymousAWSCredentials can cause issues with endpoint resolution - var credentials = new Amazon.Runtime.BasicAWSCredentials("test", "test"); - - var config = new Amazon.SQS.AmazonSQSConfig - { - ServiceURL = LocalStackEndpoint, - UseHttp = true, - // Don't set RegionEndpoint when using ServiceURL - it can override the endpoint - AuthenticationRegion = _configuration.Region.SystemName - }; - - SqsClient = new AmazonSQSClient(credentials, config); - - var snsConfig = new Amazon.SimpleNotificationService.AmazonSimpleNotificationServiceConfig - { - ServiceURL = LocalStackEndpoint, - UseHttp = true, - // Don't set RegionEndpoint when using ServiceURL - AuthenticationRegion = _configuration.Region.SystemName - }; - - SnsClient = new AmazonSimpleNotificationServiceClient(credentials, snsConfig); - - var kmsConfig = new Amazon.KeyManagementService.AmazonKeyManagementServiceConfig - { - ServiceURL = LocalStackEndpoint, - UseHttp = true, - // Don't set RegionEndpoint when using ServiceURL - AuthenticationRegion = _configuration.Region.SystemName - }; - - KmsClient = new AmazonKeyManagementServiceClient(credentials, kmsConfig); - - // Create test resources - await CreateTestResourcesAsync(); - } - - /// - /// Clean up LocalStack container and resources - /// - public async Task DisposeAsync() - { - SqsClient?.Dispose(); - SnsClient?.Dispose(); - KmsClient?.Dispose(); - - // Only stop container if we started it - if (_localStackContainer != null) - { - await _localStackContainer.StopAsync(); - await _localStackContainer.DisposeAsync(); - } - } - - /// - /// Create test queues and topics in LocalStack - /// - private async Task CreateTestResourcesAsync() - { - if (SqsClient == null || SnsClient == null) - return; - - try - { - // Create test queue - var queueName = "test-command-queue.fifo"; - var createQueueResponse = await SqsClient.CreateQueueAsync(new Amazon.SQS.Model.CreateQueueRequest - { - QueueName = queueName, - Attributes = new Dictionary - { - ["FifoQueue"] = "true", - ["ContentBasedDeduplication"] = "true" - } - }); - - _configuration.QueueUrls["TestCommand"] = createQueueResponse.QueueUrl; - - // Create test topic - var topicName = "test-event-topic"; - var createTopicResponse = await SnsClient.CreateTopicAsync(topicName); - _configuration.TopicArns["TestEvent"] = createTopicResponse.TopicArn; - - // Create KMS key for encryption tests - if (KmsClient != null) - { - try - { - var createKeyResponse = await KmsClient.CreateKeyAsync(new Amazon.KeyManagementService.Model.CreateKeyRequest - { - Description = "Test key for SourceFlow integration tests", - KeyUsage = Amazon.KeyManagementService.KeyUsageType.ENCRYPT_DECRYPT - }); - - _configuration.KmsKeyId = createKeyResponse.KeyMetadata.KeyId; - } - catch - { - // KMS might not be fully supported in LocalStack free version - // This is optional for basic integration tests - } - } - } - catch (Exception ex) - { - // Log but don't fail - some tests might still work without all resources - Console.WriteLine($"Warning: Failed to create some test resources: {ex.Message}"); - } - } - - /// - /// Check if LocalStack is available and running - /// - public async Task IsAvailableAsync() - { - if (!_configuration.UseLocalStack || SqsClient == null) - return false; - - try - { - await SqsClient.ListQueuesAsync(new Amazon.SQS.Model.ListQueuesRequest()); - return true; - } - catch - { - return false; - } - } - - /// - /// Create a service collection configured for LocalStack testing - /// - public IServiceCollection CreateTestServices() - { - var services = new ServiceCollection(); - - // Add logging - services.AddLogging(builder => builder.AddConsole().SetMinimumLevel(LogLevel.Debug)); - - // Add AWS clients configured for LocalStack - if (SqsClient != null) - services.AddSingleton(SqsClient); - - if (SnsClient != null) - services.AddSingleton(SnsClient); - - if (KmsClient != null) - services.AddSingleton(KmsClient); - - // Add test configuration - services.AddSingleton(_configuration); - - return services; - } -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/PerformanceTestHelpers.cs b/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/PerformanceTestHelpers.cs deleted file mode 100644 index 3a1b9780..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/PerformanceTestHelpers.cs +++ /dev/null @@ -1,130 +0,0 @@ -using System.Diagnostics; -using BenchmarkDotNet.Attributes; -using BenchmarkDotNet.Running; - -namespace SourceFlow.Cloud.AWS.Tests.TestHelpers; - -/// -/// Helper class for performance testing -/// -public static class PerformanceTestHelpers -{ - /// - /// Measure execution time of an async operation - /// - public static async Task MeasureAsync(Func operation) - { - var stopwatch = Stopwatch.StartNew(); - await operation(); - stopwatch.Stop(); - return stopwatch.Elapsed; - } - - /// - /// Measure execution time of an async operation with result - /// - public static async Task<(T Result, TimeSpan Duration)> MeasureAsync(Func> operation) - { - var stopwatch = Stopwatch.StartNew(); - var result = await operation(); - stopwatch.Stop(); - return (result, stopwatch.Elapsed); - } - - /// - /// Run a performance test with multiple iterations - /// - public static async Task RunPerformanceTestAsync( - string testName, - Func operation, - int iterations = 100, - int warmupIterations = 10) - { - var durations = new List(); - - // Warmup - for (int i = 0; i < warmupIterations; i++) - { - await operation(); - } - - // Actual test - var totalStopwatch = Stopwatch.StartNew(); - - for (int i = 0; i < iterations; i++) - { - var duration = await MeasureAsync(operation); - durations.Add(duration); - } - - totalStopwatch.Stop(); - - return new PerformanceTestResult - { - TestName = testName, - Iterations = iterations, - TotalDuration = totalStopwatch.Elapsed, - AverageDuration = TimeSpan.FromTicks(durations.Sum(d => d.Ticks) / durations.Count), - MinDuration = durations.Min(), - MaxDuration = durations.Max(), - P95Duration = durations.OrderBy(d => d).Skip((int)(durations.Count * 0.95)).First(), - P99Duration = durations.OrderBy(d => d).Skip((int)(durations.Count * 0.99)).First(), - OperationsPerSecond = iterations / totalStopwatch.Elapsed.TotalSeconds - }; - } - - /// - /// Run BenchmarkDotNet performance tests - /// - public static void RunBenchmark() where T : class - { - BenchmarkRunner.Run(); - } -} - -/// -/// Result of a performance test -/// -public class PerformanceTestResult -{ - public string TestName { get; set; } = ""; - public int Iterations { get; set; } - public TimeSpan TotalDuration { get; set; } - public TimeSpan AverageDuration { get; set; } - public TimeSpan MinDuration { get; set; } - public TimeSpan MaxDuration { get; set; } - public TimeSpan P95Duration { get; set; } - public TimeSpan P99Duration { get; set; } - public double OperationsPerSecond { get; set; } - - public override string ToString() - { - return $"{TestName}: {OperationsPerSecond:F2} ops/sec, Avg: {AverageDuration.TotalMilliseconds:F2}ms, P95: {P95Duration.TotalMilliseconds:F2}ms"; - } -} - -/// -/// Base class for BenchmarkDotNet performance tests -/// -[MemoryDiagnoser] -[SimpleJob] -public abstract class PerformanceBenchmarkBase -{ - protected LocalStackTestFixture? LocalStack { get; private set; } - - [GlobalSetup] - public virtual async Task GlobalSetup() - { - LocalStack = new LocalStackTestFixture(); - await LocalStack.InitializeAsync(); - } - - [GlobalCleanup] - public virtual async Task GlobalCleanup() - { - if (LocalStack != null) - { - await LocalStack.DisposeAsync(); - } - } -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/README.md b/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/README.md deleted file mode 100644 index 823422b4..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/README.md +++ /dev/null @@ -1,196 +0,0 @@ -# Enhanced AWS Test Environment Abstractions - -This directory contains the enhanced AWS test environment abstractions that provide comprehensive testing capabilities for SourceFlow's AWS cloud integrations. - -## Core Interfaces - -### ICloudTestEnvironment -Base interface for cloud test environments providing common functionality: -- Environment availability checking -- Service collection creation -- Resource cleanup - -### IAwsTestEnvironment -Enhanced AWS-specific test environment interface extending `ICloudTestEnvironment`: -- Full AWS service client access (SQS, SNS, KMS, IAM) -- FIFO and standard queue creation -- SNS topic management -- KMS key creation and management -- IAM permission validation -- Health status monitoring - -### ILocalStackManager -Container lifecycle management for LocalStack AWS service emulation: -- Container startup and shutdown -- Service availability checking -- Health monitoring -- Data reset capabilities -- Log retrieval - -### IAwsResourceManager -Automated AWS resource provisioning and cleanup: -- Test resource creation with unique naming -- Resource tracking and cleanup -- Cost estimation -- CloudFormation stack management -- Resource tagging - -## Implementations - -### AwsTestEnvironment -Main implementation of `IAwsTestEnvironment` that: -- Supports both LocalStack and real AWS environments -- Provides comprehensive AWS service clients -- Implements resource creation and management -- Includes health checking and validation - -### LocalStackManager -TestContainers-based LocalStack container management: -- Configurable service enablement -- Health checking with retry logic -- Container lifecycle management -- Service endpoint resolution - -### AwsResourceManager -Comprehensive resource management implementation: -- Automatic resource provisioning -- Cleanup with error handling -- Resource existence validation -- Cost estimation capabilities - -## Configuration - -### AwsTestConfiguration -Enhanced configuration supporting: -- LocalStack vs real AWS selection -- Service-specific configurations (SQS, SNS, KMS, IAM) -- Performance test settings -- Security test settings - -### LocalStackConfiguration -Detailed LocalStack container configuration: -- Service selection -- Environment variables -- Port bindings -- Volume mounts -- Health check settings - -## Factory and Builder Pattern - -### AwsTestEnvironmentFactory -Convenient factory methods for creating test environments: -- `CreateLocalStackEnvironmentAsync()` - Default LocalStack setup -- `CreatePerformanceTestEnvironmentAsync()` - Optimized for performance testing -- `CreateSecurityTestEnvironmentAsync()` - Configured for security testing -- `CreateRealAwsEnvironmentAsync()` - Real AWS services - -### AwsTestEnvironmentBuilder -Fluent builder pattern for custom configurations: -```csharp -var environment = await AwsTestEnvironmentFactory.CreateBuilder() - .UseLocalStack(true) - .EnableIntegrationTests(true) - .ConfigureLocalStack(config => config.Debug = true) - .WithTestPrefix("my-test") - .BuildAsync(); -``` - -## Test Runners - -### AwsTestScenarioRunner -Basic integration test scenarios: -- SQS message send/receive validation -- SNS topic publish validation - -### AwsPerformanceTestRunner -Performance testing capabilities: -- SQS throughput measurement -- Latency analysis -- Resource utilization tracking - -### AwsSecurityTestRunner -Security validation: -- IAM permission testing -- Encryption validation -- Access control verification - -## Usage Examples - -### Basic LocalStack Testing -```csharp -var testEnvironment = await AwsTestEnvironmentFactory.CreateLocalStackEnvironmentAsync(); - -// Create resources -var queueUrl = await testEnvironment.CreateFifoQueueAsync("test-queue"); -var topicArn = await testEnvironment.CreateTopicAsync("test-topic"); - -// Use AWS clients -await testEnvironment.SqsClient.SendMessageAsync(new SendMessageRequest -{ - QueueUrl = queueUrl, - MessageBody = "Test message" -}); - -// Cleanup -await testEnvironment.DisposeAsync(); -``` - -### Performance Testing -```csharp -var testEnvironment = await AwsTestEnvironmentFactory.CreatePerformanceTestEnvironmentAsync(); -var services = AwsTestEnvironmentFactory.CreateTestServiceCollection(testEnvironment); -var serviceProvider = services.BuildServiceProvider(); -var performanceRunner = serviceProvider.GetRequiredService(); - -var result = await performanceRunner.RunSqsThroughputTestAsync(messageCount: 1000); -Console.WriteLine($"Throughput: {result.OperationsPerSecond:F2} ops/sec"); -``` - -### Custom Configuration -```csharp -var testEnvironment = await AwsTestEnvironmentFactory.CreateBuilder() - .UseLocalStack(true) - .ConfigureLocalStack(config => - { - config.EnabledServices = new List { "sqs", "sns", "kms" }; - config.Debug = true; - }) - .ConfigureServices(services => - { - services.Sqs.EnableDeadLetterQueue = true; - services.Sqs.MaxReceiveCount = 5; - }) - .EnablePerformanceTests(true) - .WithTestPrefix("custom-test") - .BuildAsync(); -``` - -## Integration with Existing Tests - -The enhanced abstractions are designed to work alongside existing test infrastructure: -- Compatible with existing `LocalStackTestFixture` -- Extends existing `AwsTestConfiguration` -- Uses existing `PerformanceTestResult` model -- Integrates with xUnit test framework - -## Key Features - -1. **Comprehensive AWS Service Support**: Full support for SQS, SNS, KMS, and IAM services -2. **LocalStack Integration**: Seamless LocalStack container management with TestContainers -3. **Resource Management**: Automated provisioning, tracking, and cleanup of test resources -4. **Performance Testing**: Built-in performance measurement and benchmarking capabilities -5. **Security Testing**: IAM permission validation and encryption testing -6. **Flexible Configuration**: Support for both LocalStack and real AWS environments -7. **Factory Pattern**: Convenient creation methods for common test scenarios -8. **Builder Pattern**: Fluent configuration for custom test environments -9. **Health Monitoring**: Comprehensive health checking for all AWS services -10. **Error Handling**: Robust error handling with cleanup guarantees - -## Requirements Satisfied - -This implementation satisfies the following requirements from the AWS Cloud Integration Testing specification: -- **6.1, 6.2, 6.3**: LocalStack integration with full AWS service emulation -- **9.1, 9.2**: CI/CD integration with automated resource provisioning -- **All service requirements**: Comprehensive support for SQS, SNS, KMS, and IAM testing - -The abstractions provide a solid foundation for implementing comprehensive AWS integration tests while maintaining clean separation of concerns and supporting both local development and CI/CD scenarios. \ No newline at end of file diff --git a/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/SnsTestModels.cs b/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/SnsTestModels.cs deleted file mode 100644 index bf91ecbf..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/SnsTestModels.cs +++ /dev/null @@ -1,27 +0,0 @@ -using System.Text.Json.Serialization; - -namespace SourceFlow.Cloud.AWS.Tests.TestHelpers; - -/// -/// Wrapper for SNS messages received via SQS -/// -public class SnsMessageWrapper -{ - [JsonPropertyName("Message")] - public string? Message { get; set; } - - [JsonPropertyName("MessageAttributes")] - public Dictionary? MessageAttributes { get; set; } -} - -/// -/// SNS message attribute structure -/// -public class SnsMessageAttribute -{ - [JsonPropertyName("Type")] - public string? Type { get; set; } - - [JsonPropertyName("Value")] - public string? Value { get; set; } -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/TestCategories.cs b/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/TestCategories.cs deleted file mode 100644 index 4e22a9ad..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/TestCategories.cs +++ /dev/null @@ -1,32 +0,0 @@ -namespace SourceFlow.Cloud.AWS.Tests.TestHelpers; - -/// -/// Constants for test categorization using xUnit traits. -/// Allows filtering tests based on external dependencies. -/// -public static class TestCategories -{ - /// - /// Unit tests with no external dependencies (mocked services). - /// Can run without any AWS infrastructure. - /// - public const string Unit = "Unit"; - - /// - /// Integration tests that require external services (LocalStack or real AWS). - /// Use --filter "Category!=Integration" to skip these tests. - /// - public const string Integration = "Integration"; - - /// - /// Tests that require LocalStack emulator to be running. - /// Use --filter "Category!=RequiresLocalStack" to skip these tests. - /// - public const string RequiresLocalStack = "RequiresLocalStack"; - - /// - /// Tests that require real AWS services (SQS, SNS, KMS, etc.). - /// Use --filter "Category!=RequiresAWS" to skip these tests. - /// - public const string RequiresAWS = "RequiresAWS"; -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/TestCommand.cs b/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/TestCommand.cs deleted file mode 100644 index 00f5e632..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/TestCommand.cs +++ /dev/null @@ -1,14 +0,0 @@ -using SourceFlow.Messaging; -using SourceFlow.Messaging.Commands; - -namespace SourceFlow.Cloud.AWS.Tests.TestHelpers; - -public class TestCommand : Command -{ -} - -public class TestCommandData : IPayload -{ - public string Message { get; set; } = ""; - public int Value { get; set; } -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/TestEvent.cs b/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/TestEvent.cs deleted file mode 100644 index 2f1c51e4..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/TestHelpers/TestEvent.cs +++ /dev/null @@ -1,22 +0,0 @@ -using SourceFlow; -using SourceFlow.Messaging.Events; - -namespace SourceFlow.Cloud.AWS.Tests.TestHelpers; - -public class TestEvent : Event -{ - public TestEvent() : base(new TestEventData { Id = 1 }) - { - } - - public TestEvent(TestEventData data) : base(data) - { - } -} - -public class TestEventData : IEntity -{ - public int Id { get; set; } - public string Message { get; set; } = ""; - public int Value { get; set; } -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/Unit/AwsBusBootstrapperTests.cs b/tests/SourceFlow.Cloud.AWS.Tests/Unit/AwsBusBootstrapperTests.cs deleted file mode 100644 index 99a6cb59..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/Unit/AwsBusBootstrapperTests.cs +++ /dev/null @@ -1,322 +0,0 @@ -using Amazon.SimpleNotificationService; -using Amazon.SimpleNotificationService.Model; -using Amazon.SQS; -using Amazon.SQS.Model; -using Microsoft.Extensions.Logging; -using Moq; -using SourceFlow.Cloud.AWS.Infrastructure; -using SourceFlow.Cloud.AWS.Tests.TestHelpers; -using SourceFlow.Cloud.Configuration; - -namespace SourceFlow.Cloud.AWS.Tests.Unit; - -[Trait("Category", "Unit")] -public class AwsBusBootstrapperTests -{ - private readonly Mock _mockSqsClient; - private readonly Mock _mockSnsClient; - private readonly Mock> _mockLogger; - - public AwsBusBootstrapperTests() - { - _mockSqsClient = new Mock(); - _mockSnsClient = new Mock(); - _mockLogger = new Mock>(); - } - - private BusConfiguration BuildConfig(Action configure) - { - var builder = new BusConfigurationBuilder(); - configure(builder); - return builder.Build(); - } - - private AwsBusBootstrapper CreateBootstrapper(BusConfiguration config) - { - return new AwsBusBootstrapper( - config, - _mockSqsClient.Object, - _mockSnsClient.Object, - _mockLogger.Object); - } - - private void SetupQueueResolution(string queueName, string queueUrl) - { - _mockSqsClient - .Setup(x => x.GetQueueUrlAsync(queueName, It.IsAny())) - .ReturnsAsync(new GetQueueUrlResponse { QueueUrl = queueUrl }); - } - - private void SetupQueueArn(string queueUrl, string queueArn) - { - _mockSqsClient - .Setup(x => x.GetQueueAttributesAsync( - It.Is(r => r.QueueUrl == queueUrl), - It.IsAny())) - .ReturnsAsync(new GetQueueAttributesResponse - { - Attributes = new Dictionary - { - [QueueAttributeName.QueueArn] = queueArn - } - }); - } - - private void SetupTopicResolution(string topicName, string topicArn) - { - _mockSnsClient - .Setup(x => x.CreateTopicAsync(topicName, It.IsAny())) - .ReturnsAsync(new CreateTopicResponse { TopicArn = topicArn }); - } - - // ── Validation Tests ────────────────────────────────────────────────── - - [Fact] - public async Task StartAsync_WithSubscribedTopicsButNoCommandQueues_ThrowsInvalidOperationException() - { - // Arrange - var config = BuildConfig(bus => bus - .Subscribe.To.Topic("order-events")); - - var bootstrapper = CreateBootstrapper(config); - - // Act & Assert - var ex = await Assert.ThrowsAsync( - () => bootstrapper.StartAsync(CancellationToken.None)); - - Assert.Contains("At least one command queue must be configured", ex.Message); - } - - [Fact] - public async Task StartAsync_WithNoSubscribedTopicsAndNoCommandQueues_DoesNotThrow() - { - // Arrange - only outbound event routing, no subscriptions or command queues - var config = BuildConfig(bus => bus - .Raise.Event(t => t.Topic("order-events"))); - - SetupTopicResolution("order-events", "arn:aws:sns:us-east-1:123456:order-events"); - - var bootstrapper = CreateBootstrapper(config); - - // Act & Assert - should not throw - await bootstrapper.StartAsync(CancellationToken.None); - } - - // ── Subscription Tests ──────────────────────────────────────────────── - - [Fact] - public async Task StartAsync_WithSubscribedTopics_SubscribesFirstCommandQueueToEachTopic() - { - // Arrange - var config = BuildConfig(bus => bus - .Listen.To - .CommandQueue("orders.fifo") - .Subscribe.To - .Topic("order-events") - .Topic("payment-events")); - - SetupQueueResolution("orders.fifo", "https://sqs.us-east-1.amazonaws.com/123456/orders.fifo"); - SetupQueueArn("https://sqs.us-east-1.amazonaws.com/123456/orders.fifo", - "arn:aws:sqs:us-east-1:123456:orders.fifo"); - SetupTopicResolution("order-events", "arn:aws:sns:us-east-1:123456:order-events"); - SetupTopicResolution("payment-events", "arn:aws:sns:us-east-1:123456:payment-events"); - - _mockSnsClient - .Setup(x => x.SubscribeAsync(It.IsAny(), It.IsAny())) - .ReturnsAsync(new SubscribeResponse { SubscriptionArn = "arn:aws:sns:us-east-1:123456:sub" }); - - var bootstrapper = CreateBootstrapper(config); - - // Act - await bootstrapper.StartAsync(CancellationToken.None); - - // Assert - subscribed both topics to the queue - _mockSnsClient.Verify(x => x.SubscribeAsync( - It.Is(r => - r.TopicArn == "arn:aws:sns:us-east-1:123456:order-events" && - r.Protocol == "sqs" && - r.Endpoint == "arn:aws:sqs:us-east-1:123456:orders.fifo"), - It.IsAny()), Times.Once); - - _mockSnsClient.Verify(x => x.SubscribeAsync( - It.Is(r => - r.TopicArn == "arn:aws:sns:us-east-1:123456:payment-events" && - r.Protocol == "sqs" && - r.Endpoint == "arn:aws:sqs:us-east-1:123456:orders.fifo"), - It.IsAny()), Times.Once); - } - - [Fact] - public async Task StartAsync_WithMultipleCommandQueues_UsesFirstQueueForSubscriptions() - { - // Arrange - var config = BuildConfig(bus => bus - .Listen.To - .CommandQueue("orders.fifo") - .CommandQueue("inventory.fifo") - .Subscribe.To - .Topic("order-events")); - - SetupQueueResolution("orders.fifo", "https://sqs.us-east-1.amazonaws.com/123456/orders.fifo"); - SetupQueueResolution("inventory.fifo", "https://sqs.us-east-1.amazonaws.com/123456/inventory.fifo"); - SetupQueueArn("https://sqs.us-east-1.amazonaws.com/123456/orders.fifo", - "arn:aws:sqs:us-east-1:123456:orders.fifo"); - SetupTopicResolution("order-events", "arn:aws:sns:us-east-1:123456:order-events"); - - _mockSnsClient - .Setup(x => x.SubscribeAsync(It.IsAny(), It.IsAny())) - .ReturnsAsync(new SubscribeResponse { SubscriptionArn = "arn:aws:sns:us-east-1:123456:sub" }); - - var bootstrapper = CreateBootstrapper(config); - - // Act - await bootstrapper.StartAsync(CancellationToken.None); - - // Assert - subscribed to the first queue (orders.fifo), not inventory.fifo - _mockSnsClient.Verify(x => x.SubscribeAsync( - It.Is(r => - r.Endpoint == "arn:aws:sqs:us-east-1:123456:orders.fifo"), - It.IsAny()), Times.Once); - - // Should never subscribe inventory queue - _mockSnsClient.Verify(x => x.SubscribeAsync( - It.Is(r => - r.Endpoint == "arn:aws:sqs:us-east-1:123456:inventory.fifo"), - It.IsAny()), Times.Never); - } - - [Fact] - public async Task StartAsync_WithNoSubscribedTopics_DoesNotCreateAnySubscriptions() - { - // Arrange - var config = BuildConfig(bus => bus - .Send.Command(q => q.Queue("orders.fifo")) - .Listen.To.CommandQueue("orders.fifo")); - - SetupQueueResolution("orders.fifo", "https://sqs.us-east-1.amazonaws.com/123456/orders.fifo"); - - var bootstrapper = CreateBootstrapper(config); - - // Act - await bootstrapper.StartAsync(CancellationToken.None); - - // Assert - no SNS subscriptions created - _mockSnsClient.Verify(x => x.SubscribeAsync( - It.IsAny(), - It.IsAny()), Times.Never); - } - - // ── Resolve / Event Listening Tests ─────────────────────────────────── - - [Fact] - public async Task StartAsync_WithSubscribedTopics_ResolvesEventListeningUrlToFirstCommandQueue() - { - // Arrange - var config = BuildConfig(bus => bus - .Listen.To - .CommandQueue("orders.fifo") - .Subscribe.To - .Topic("order-events")); - - SetupQueueResolution("orders.fifo", "https://sqs.us-east-1.amazonaws.com/123456/orders.fifo"); - SetupQueueArn("https://sqs.us-east-1.amazonaws.com/123456/orders.fifo", - "arn:aws:sqs:us-east-1:123456:orders.fifo"); - SetupTopicResolution("order-events", "arn:aws:sns:us-east-1:123456:order-events"); - - _mockSnsClient - .Setup(x => x.SubscribeAsync(It.IsAny(), It.IsAny())) - .ReturnsAsync(new SubscribeResponse { SubscriptionArn = "arn:aws:sns:us-east-1:123456:sub" }); - - var bootstrapper = CreateBootstrapper(config); - - // Act - await bootstrapper.StartAsync(CancellationToken.None); - - // Assert - event listening queues should return the first command queue URL - var eventRouting = (IEventRoutingConfiguration)config; - var listeningQueues = eventRouting.GetListeningQueues().ToList(); - Assert.Single(listeningQueues); - Assert.Equal("https://sqs.us-east-1.amazonaws.com/123456/orders.fifo", listeningQueues[0]); - } - - [Fact] - public async Task StartAsync_WithNoSubscribedTopics_ResolvesEmptyEventListeningUrls() - { - // Arrange - var config = BuildConfig(bus => bus - .Send.Command(q => q.Queue("orders.fifo")) - .Listen.To.CommandQueue("orders.fifo")); - - SetupQueueResolution("orders.fifo", "https://sqs.us-east-1.amazonaws.com/123456/orders.fifo"); - - var bootstrapper = CreateBootstrapper(config); - - // Act - await bootstrapper.StartAsync(CancellationToken.None); - - // Assert - no event listening URLs when no topics subscribed - var eventRouting = (IEventRoutingConfiguration)config; - var listeningQueues = eventRouting.GetListeningQueues().ToList(); - Assert.Empty(listeningQueues); - } - - // ── Queue/Topic Resolution Tests ────────────────────────────────────── - - [Fact] - public async Task StartAsync_CreatesQueueWhenNotFound() - { - // Arrange - var config = BuildConfig(bus => bus - .Listen.To.CommandQueue("new-queue.fifo")); - - _mockSqsClient - .Setup(x => x.GetQueueUrlAsync("new-queue.fifo", It.IsAny())) - .ThrowsAsync(new QueueDoesNotExistException("not found")); - - _mockSqsClient - .Setup(x => x.CreateQueueAsync(It.IsAny(), It.IsAny())) - .ReturnsAsync(new CreateQueueResponse - { - QueueUrl = "https://sqs.us-east-1.amazonaws.com/123456/new-queue.fifo" - }); - - var bootstrapper = CreateBootstrapper(config); - - // Act - await bootstrapper.StartAsync(CancellationToken.None); - - // Assert - queue was created with FIFO attributes - _mockSqsClient.Verify(x => x.CreateQueueAsync( - It.Is(r => - r.QueueName == "new-queue.fifo" && - r.Attributes[QueueAttributeName.FifoQueue] == "true" && - r.Attributes[QueueAttributeName.ContentBasedDeduplication] == "true"), - It.IsAny()), Times.Once); - } - - [Fact] - public async Task StartAsync_ResolvesCommandRoutesAndListeningQueues() - { - // Arrange - var config = BuildConfig(bus => bus - .Send.Command(q => q.Queue("orders.fifo")) - .Listen.To.CommandQueue("orders.fifo")); - - SetupQueueResolution("orders.fifo", "https://sqs.us-east-1.amazonaws.com/123456/orders.fifo"); - - var bootstrapper = CreateBootstrapper(config); - - // Act - await bootstrapper.StartAsync(CancellationToken.None); - - // Assert - var commandRouting = (ICommandRoutingConfiguration)config; - Assert.True(commandRouting.ShouldRoute()); - Assert.Equal("https://sqs.us-east-1.amazonaws.com/123456/orders.fifo", - commandRouting.GetQueueName()); - - var listeningQueues = commandRouting.GetListeningQueues().ToList(); - Assert.Single(listeningQueues); - Assert.Equal("https://sqs.us-east-1.amazonaws.com/123456/orders.fifo", listeningQueues[0]); - } -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/Unit/AwsDeadLetterQueuePropertyTests.cs b/tests/SourceFlow.Cloud.AWS.Tests/Unit/AwsDeadLetterQueuePropertyTests.cs deleted file mode 100644 index 6b102a2b..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/Unit/AwsDeadLetterQueuePropertyTests.cs +++ /dev/null @@ -1,480 +0,0 @@ -using Amazon.SQS; -using Amazon.SQS.Model; -using Microsoft.Extensions.Logging.Abstractions; -using Moq; -using SourceFlow.Cloud.AWS.Monitoring; -using SourceFlow.Cloud.DeadLetter; -using SourceFlow.Cloud.Observability; - -namespace SourceFlow.Cloud.AWS.Tests.Unit; - -/// -/// Unit tests for . -/// -[Trait("Category", "Unit")] -public class AwsDeadLetterMonitorTests -{ - private readonly Mock _mockSqsClient; - private readonly Mock _mockDeadLetterStore; - private readonly CloudMetrics _cloudMetrics; - - private const string DlqUrl = "https://sqs.us-east-1.amazonaws.com/123456/test-dlq"; - private const string TargetQueueUrl = "https://sqs.us-east-1.amazonaws.com/123456/test-queue"; - - public AwsDeadLetterMonitorTests() - { - _mockSqsClient = new Mock(); - _mockDeadLetterStore = new Mock(); - _cloudMetrics = new CloudMetrics(NullLogger.Instance); - } - - // ── ReplayMessagesAsync tests (public method, testable directly) ────────── - - [Fact] - public async Task ReplayMessagesAsync_MessagesInDlq_SendsToTargetQueue() - { - // Arrange - var messageId = Guid.NewGuid().ToString(); - var receiptHandle = "receipt-handle-1"; - - _mockSqsClient - .Setup(x => x.ReceiveMessageAsync( - It.Is(r => r.QueueUrl == DlqUrl), - It.IsAny())) - .ReturnsAsync(new ReceiveMessageResponse - { - Messages = new List - { - new Message - { - MessageId = messageId, - Body = "{\"test\":\"value\"}", - ReceiptHandle = receiptHandle, - MessageAttributes = new Dictionary() - } - } - }); - - _mockSqsClient - .Setup(x => x.SendMessageAsync(It.IsAny(), It.IsAny())) - .ReturnsAsync(new SendMessageResponse { MessageId = Guid.NewGuid().ToString() }); - - _mockSqsClient - .Setup(x => x.DeleteMessageAsync(It.IsAny(), It.IsAny())) - .ReturnsAsync(new DeleteMessageResponse()); - - _mockDeadLetterStore - .Setup(x => x.MarkAsReplayedAsync(It.IsAny(), It.IsAny())) - .Returns(Task.CompletedTask); - - var monitor = CreateMonitor(new AwsDeadLetterMonitorOptions - { - Enabled = true, - DeadLetterQueues = new List { DlqUrl } - }); - - // Act - var replayedCount = await monitor.ReplayMessagesAsync(DlqUrl, TargetQueueUrl, maxMessages: 10); - - // Assert - Assert.Equal(1, replayedCount); - _mockSqsClient.Verify( - x => x.SendMessageAsync( - It.Is(r => r.QueueUrl == TargetQueueUrl), - It.IsAny()), - Times.Once); - } - - [Fact] - public async Task ReplayMessagesAsync_MessageSentToTarget_DeletesFromDlq() - { - // Arrange - var receiptHandle = "receipt-handle-delete-test"; - - _mockSqsClient - .Setup(x => x.ReceiveMessageAsync(It.IsAny(), It.IsAny())) - .ReturnsAsync(new ReceiveMessageResponse - { - Messages = new List - { - new Message - { - MessageId = Guid.NewGuid().ToString(), - Body = "body", - ReceiptHandle = receiptHandle, - MessageAttributes = new Dictionary() - } - } - }); - - _mockSqsClient - .Setup(x => x.SendMessageAsync(It.IsAny(), It.IsAny())) - .ReturnsAsync(new SendMessageResponse { MessageId = Guid.NewGuid().ToString() }); - - _mockSqsClient - .Setup(x => x.DeleteMessageAsync(It.IsAny(), It.IsAny())) - .ReturnsAsync(new DeleteMessageResponse()); - - _mockDeadLetterStore - .Setup(x => x.MarkAsReplayedAsync(It.IsAny(), It.IsAny())) - .Returns(Task.CompletedTask); - - var monitor = CreateMonitor(new AwsDeadLetterMonitorOptions - { - Enabled = true, - DeadLetterQueues = new List { DlqUrl } - }); - - // Act - await monitor.ReplayMessagesAsync(DlqUrl, TargetQueueUrl); - - // Assert: delete was called on the DLQ for this receipt handle - _mockSqsClient.Verify( - x => x.DeleteMessageAsync( - It.Is(r => - r.QueueUrl == DlqUrl && - r.ReceiptHandle == receiptHandle), - It.IsAny()), - Times.Once); - } - - [Fact] - public async Task ReplayMessagesAsync_MessageReplayed_MarkAsReplayedCalledOnStore() - { - // Arrange - var messageId = "msg-replay-id"; - - _mockSqsClient - .Setup(x => x.ReceiveMessageAsync(It.IsAny(), It.IsAny())) - .ReturnsAsync(new ReceiveMessageResponse - { - Messages = new List - { - new Message - { - MessageId = messageId, - Body = "body", - ReceiptHandle = "rh", - MessageAttributes = new Dictionary() - } - } - }); - - _mockSqsClient - .Setup(x => x.SendMessageAsync(It.IsAny(), It.IsAny())) - .ReturnsAsync(new SendMessageResponse { MessageId = Guid.NewGuid().ToString() }); - - _mockSqsClient - .Setup(x => x.DeleteMessageAsync(It.IsAny(), It.IsAny())) - .ReturnsAsync(new DeleteMessageResponse()); - - _mockDeadLetterStore - .Setup(x => x.MarkAsReplayedAsync(messageId, It.IsAny())) - .Returns(Task.CompletedTask); - - var monitor = CreateMonitor(new AwsDeadLetterMonitorOptions - { - Enabled = true, - DeadLetterQueues = new List { DlqUrl } - }); - - // Act - await monitor.ReplayMessagesAsync(DlqUrl, TargetQueueUrl); - - // Assert - _mockDeadLetterStore.Verify( - x => x.MarkAsReplayedAsync(messageId, It.IsAny()), - Times.Once); - } - - [Fact] - public async Task ReplayMessagesAsync_EmptyDlq_ReturnsZero() - { - // Arrange - _mockSqsClient - .Setup(x => x.ReceiveMessageAsync(It.IsAny(), It.IsAny())) - .ReturnsAsync(new ReceiveMessageResponse { Messages = new List() }); - - var monitor = CreateMonitor(new AwsDeadLetterMonitorOptions - { - Enabled = true, - DeadLetterQueues = new List { DlqUrl } - }); - - // Act - var replayedCount = await monitor.ReplayMessagesAsync(DlqUrl, TargetQueueUrl); - - // Assert - Assert.Equal(0, replayedCount); - } - - // ── ExecuteAsync path: delete-after-processing tests ───────────────────── - - [Fact] - public async Task ExecuteAsync_DeleteAfterProcessingTrue_DeleteMessageCalledAfterSave() - { - // Arrange - var receiptHandle = "rh-delete-after"; - var messageId = "msg-delete-after"; - - SetupMonitorQueueAttributes(1); - SetupReceiveMessages(new List - { - new Message - { - MessageId = messageId, - Body = "{\"test\":1}", - ReceiptHandle = receiptHandle, - MessageAttributes = new Dictionary(), - Attributes = new Dictionary - { - ["ApproximateReceiveCount"] = "4" - } - } - }); - - _mockSqsClient - .Setup(x => x.DeleteMessageAsync(It.IsAny(), It.IsAny())) - .ReturnsAsync(new DeleteMessageResponse()); - - _mockDeadLetterStore - .Setup(x => x.SaveAsync(It.IsAny(), It.IsAny())) - .Returns(Task.CompletedTask); - - var cts = new CancellationTokenSource(); - - var monitor = CreateMonitor(new AwsDeadLetterMonitorOptions - { - Enabled = true, - DeadLetterQueues = new List { DlqUrl }, - CheckIntervalSeconds = 0, - StoreRecords = true, - DeleteAfterProcessing = true - }); - - // Act: start, allow one iteration, then cancel - var task = monitor.StartAsync(cts.Token); - await Task.Delay(200); - await cts.CancelAsync(); - - try { await task; } catch (OperationCanceledException) { } - - // Assert: both save and delete were called - _mockDeadLetterStore.Verify( - x => x.SaveAsync(It.IsAny(), It.IsAny()), - Times.AtLeastOnce); - - _mockSqsClient.Verify( - x => x.DeleteMessageAsync( - It.Is(r => r.ReceiptHandle == receiptHandle), - It.IsAny()), - Times.AtLeastOnce); - } - - [Fact] - public async Task ExecuteAsync_DeleteAfterProcessingFalse_DeleteMessageNeverCalled() - { - // Arrange - SetupMonitorQueueAttributes(1); - SetupReceiveMessages(new List - { - new Message - { - MessageId = "msg-no-delete", - Body = "{\"test\":1}", - ReceiptHandle = "rh-no-delete", - MessageAttributes = new Dictionary(), - Attributes = new Dictionary - { - ["ApproximateReceiveCount"] = "2" - } - } - }); - - _mockDeadLetterStore - .Setup(x => x.SaveAsync(It.IsAny(), It.IsAny())) - .Returns(Task.CompletedTask); - - var cts = new CancellationTokenSource(); - - var monitor = CreateMonitor(new AwsDeadLetterMonitorOptions - { - Enabled = true, - DeadLetterQueues = new List { DlqUrl }, - CheckIntervalSeconds = 0, - StoreRecords = true, - DeleteAfterProcessing = false - }); - - // Act - var task = monitor.StartAsync(cts.Token); - await Task.Delay(200); - await cts.CancelAsync(); - - try { await task; } catch (OperationCanceledException) { } - - // Assert: delete should NOT have been called - _mockSqsClient.Verify( - x => x.DeleteMessageAsync(It.IsAny(), It.IsAny()), - Times.Never); - } - - [Fact] - public async Task ExecuteAsync_StoreRecordsTrue_SaveAsyncCalled() - { - // Arrange - SetupMonitorQueueAttributes(1); - SetupReceiveMessages(new List - { - new Message - { - MessageId = "msg-store", - Body = "{\"data\":1}", - ReceiptHandle = "rh-store", - MessageAttributes = new Dictionary(), - Attributes = new Dictionary - { - ["ApproximateReceiveCount"] = "3" - } - } - }); - - _mockDeadLetterStore - .Setup(x => x.SaveAsync(It.IsAny(), It.IsAny())) - .Returns(Task.CompletedTask); - - var cts = new CancellationTokenSource(); - - var monitor = CreateMonitor(new AwsDeadLetterMonitorOptions - { - Enabled = true, - DeadLetterQueues = new List { DlqUrl }, - CheckIntervalSeconds = 0, - StoreRecords = true, - DeleteAfterProcessing = false - }); - - // Act - var task = monitor.StartAsync(cts.Token); - await Task.Delay(200); - await cts.CancelAsync(); - - try { await task; } catch (OperationCanceledException) { } - - // Assert - _mockDeadLetterStore.Verify( - x => x.SaveAsync(It.IsAny(), It.IsAny()), - Times.AtLeastOnce); - } - - [Fact] - public async Task ExecuteAsync_StoreRecordsFalse_SaveAsyncNeverCalled() - { - // Arrange - SetupMonitorQueueAttributes(1); - SetupReceiveMessages(new List - { - new Message - { - MessageId = "msg-no-store", - Body = "{}", - ReceiptHandle = "rh-no-store", - MessageAttributes = new Dictionary(), - Attributes = new Dictionary() - } - }); - - var cts = new CancellationTokenSource(); - - var monitor = CreateMonitor(new AwsDeadLetterMonitorOptions - { - Enabled = true, - DeadLetterQueues = new List { DlqUrl }, - CheckIntervalSeconds = 0, - StoreRecords = false, - DeleteAfterProcessing = false - }); - - // Act - var task = monitor.StartAsync(cts.Token); - await Task.Delay(200); - await cts.CancelAsync(); - - try { await task; } catch (OperationCanceledException) { } - - // Assert - _mockDeadLetterStore.Verify( - x => x.SaveAsync(It.IsAny(), It.IsAny()), - Times.Never); - } - - [Fact] - public async Task ExecuteAsync_Disabled_QueuesNotPolled() - { - // Arrange - var cts = new CancellationTokenSource(); - - var monitor = CreateMonitor(new AwsDeadLetterMonitorOptions - { - Enabled = false, - DeadLetterQueues = new List { DlqUrl } - }); - - // Act - await monitor.StartAsync(cts.Token); - await cts.CancelAsync(); - - // Assert: SQS was never called because monitoring is disabled - _mockSqsClient.Verify( - x => x.GetQueueAttributesAsync(It.IsAny(), It.IsAny()), - Times.Never); - } - - // ── Helpers ────────────────────────────────────────────────────────────── - - private void SetupMonitorQueueAttributes(int messageCount) - { - _mockSqsClient - .Setup(x => x.GetQueueAttributesAsync( - It.Is(r => r.QueueUrl == DlqUrl), - It.IsAny())) - .Returns(async (_, ct) => - { - // Task.Yield() forces a yield to the scheduler so the test thread can run, - // preventing the tight loop from blocking StartAsync forever. - await Task.Yield(); - ct.ThrowIfCancellationRequested(); - return new GetQueueAttributesResponse - { - Attributes = new Dictionary - { - ["ApproximateNumberOfMessages"] = messageCount.ToString() - } - }; - }); - } - - private void SetupReceiveMessages(List messages) - { - _mockSqsClient - .Setup(x => x.ReceiveMessageAsync( - It.Is(r => r.QueueUrl == DlqUrl), - It.IsAny())) - .Returns(async (_, ct) => - { - await Task.Yield(); - ct.ThrowIfCancellationRequested(); - return new ReceiveMessageResponse { Messages = messages }; - }); - } - - private AwsDeadLetterMonitor CreateMonitor(AwsDeadLetterMonitorOptions options) - { - return new AwsDeadLetterMonitor( - _mockSqsClient.Object, - _mockDeadLetterStore.Object, - _cloudMetrics, - NullLogger.Instance, - options); - } -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/Unit/AwsHealthCheckTests.cs b/tests/SourceFlow.Cloud.AWS.Tests/Unit/AwsHealthCheckTests.cs deleted file mode 100644 index 650d9d68..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/Unit/AwsHealthCheckTests.cs +++ /dev/null @@ -1,160 +0,0 @@ -using Amazon.SQS; -using Amazon.SQS.Model; -using Amazon.SimpleNotificationService; -using Amazon.SimpleNotificationService.Model; -using Microsoft.Extensions.Diagnostics.HealthChecks; -using Moq; -using SourceFlow.Cloud.AWS.Infrastructure; -using SourceFlow.Cloud.Configuration; -using SourceFlow.Messaging.Commands; -using SourceFlow.Messaging.Events; - -namespace SourceFlow.Cloud.AWS.Tests.Unit; - -[Trait("Category", "Unit")] -public class AwsHealthCheckTests -{ - private readonly Mock _mockSqsClient; - private readonly Mock _mockSnsClient; - private readonly Mock _mockCommandRoutingConfig; - private readonly Mock _mockEventRoutingConfig; - - public AwsHealthCheckTests() - { - _mockSqsClient = new Mock(); - _mockSnsClient = new Mock(); - _mockCommandRoutingConfig = new Mock(); - _mockEventRoutingConfig = new Mock(); - } - - [Fact] - public async Task CheckHealthAsync_SqsAndSnsReachable_ReturnsHealthy() - { - // Arrange - var queueUrl = "https://sqs.us-east-1.amazonaws.com/123456/my-queue"; - - _mockCommandRoutingConfig - .Setup(x => x.GetListeningQueues()) - .Returns(new[] { queueUrl }); - - _mockSqsClient - .Setup(x => x.GetQueueAttributesAsync(queueUrl, It.IsAny>(), It.IsAny())) - .ReturnsAsync(new GetQueueAttributesResponse - { - Attributes = new Dictionary { ["QueueArn"] = "arn:aws:sqs:us-east-1:123456:my-queue" } - }); - - // No listening queues for events → SNS list topics will not be called - _mockEventRoutingConfig - .Setup(x => x.GetListeningQueues()) - .Returns(Enumerable.Empty()); - - var healthCheck = CreateHealthCheck(); - - // Act - var result = await healthCheck.CheckHealthAsync(CreateContext()); - - // Assert - Assert.Equal(HealthStatus.Healthy, result.Status); - } - - [Fact] - public async Task CheckHealthAsync_SqsGetQueueAttributesThrows_ReturnsUnhealthy() - { - // Arrange - var queueUrl = "https://sqs.us-east-1.amazonaws.com/123456/missing-queue"; - - _mockCommandRoutingConfig - .Setup(x => x.GetListeningQueues()) - .Returns(new[] { queueUrl }); - - _mockSqsClient - .Setup(x => x.GetQueueAttributesAsync(queueUrl, It.IsAny>(), It.IsAny())) - .ThrowsAsync(new QueueDoesNotExistException("Queue does not exist")); - - _mockEventRoutingConfig - .Setup(x => x.GetListeningQueues()) - .Returns(Enumerable.Empty()); - - var healthCheck = CreateHealthCheck(); - - // Act - var result = await healthCheck.CheckHealthAsync(CreateContext()); - - // Assert - Assert.Equal(HealthStatus.Unhealthy, result.Status); - } - - [Fact] - public async Task CheckHealthAsync_NoQueuesConfigured_ReturnsHealthy() - { - // Arrange: nothing configured — nothing to check - _mockCommandRoutingConfig - .Setup(x => x.GetListeningQueues()) - .Returns(Enumerable.Empty()); - - _mockEventRoutingConfig - .Setup(x => x.GetListeningQueues()) - .Returns(Enumerable.Empty()); - - var healthCheck = CreateHealthCheck(); - - // Act - var result = await healthCheck.CheckHealthAsync(CreateContext()); - - // Assert - Assert.Equal(HealthStatus.Healthy, result.Status); - - // Neither SQS nor SNS clients were called - _mockSqsClient.Verify( - x => x.GetQueueAttributesAsync(It.IsAny(), It.IsAny>(), It.IsAny()), - Times.Never); - _mockSnsClient.Verify( - x => x.ListTopicsAsync(It.IsAny()), - Times.Never); - } - - [Fact] - public async Task CheckHealthAsync_SnsListTopicsThrows_ReturnsUnhealthy() - { - // Arrange: no command queues, but event listening queues are configured - _mockCommandRoutingConfig - .Setup(x => x.GetListeningQueues()) - .Returns(Enumerable.Empty()); - - _mockEventRoutingConfig - .Setup(x => x.GetListeningQueues()) - .Returns(new[] { "https://sqs.us-east-1.amazonaws.com/123456/events-queue" }); - - _mockSnsClient - .Setup(x => x.ListTopicsAsync(It.IsAny())) - .ThrowsAsync(new Exception("SNS not reachable")); - - var healthCheck = CreateHealthCheck(); - - // Act - var result = await healthCheck.CheckHealthAsync(CreateContext()); - - // Assert - Assert.Equal(HealthStatus.Unhealthy, result.Status); - } - - // ── Helpers ────────────────────────────────────────────────────────────── - - private AwsHealthCheck CreateHealthCheck() => - new AwsHealthCheck( - _mockSqsClient.Object, - _mockSnsClient.Object, - _mockCommandRoutingConfig.Object, - _mockEventRoutingConfig.Object); - - private static HealthCheckContext CreateContext() => - new HealthCheckContext - { - Registration = new HealthCheckRegistration( - "aws", - Mock.Of(), - HealthStatus.Unhealthy, - null) - }; -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/Unit/AwsJsonConverterTests.cs b/tests/SourceFlow.Cloud.AWS.Tests/Unit/AwsJsonConverterTests.cs deleted file mode 100644 index 262186f7..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/Unit/AwsJsonConverterTests.cs +++ /dev/null @@ -1,171 +0,0 @@ -using System.Text.Json; -using SourceFlow.Cloud.AWS.Messaging.Serialization; -using SourceFlow.Cloud.AWS.Tests.TestHelpers; -using SourceFlow.Messaging; - -namespace SourceFlow.Cloud.AWS.Tests.Unit; - -[Trait("Category", "Unit")] -public class AwsJsonConverterTests -{ - // ── CommandPayloadConverter ─────────────────────────────────────────────── - - [Fact] - public void CommandPayloadConverter_RoundTrip_PreservesConcreteType() - { - // Arrange - var options = new JsonSerializerOptions(); - options.Converters.Add(new CommandPayloadConverter()); - - var payload = new TestCommandData { Message = "hello", Value = 42 }; - - // Act - var json = JsonSerializer.Serialize(payload, options); - var result = JsonSerializer.Deserialize(json, options); - - // Assert - Assert.NotNull(result); - Assert.IsType(result); - var deserialized = (TestCommandData)result; - Assert.Equal("hello", deserialized.Message); - Assert.Equal(42, deserialized.Value); - } - - [Fact] - public void CommandPayloadConverter_Write_IncludesTypePropAndValueProp() - { - // Arrange - var options = new JsonSerializerOptions(); - options.Converters.Add(new CommandPayloadConverter()); - var payload = new TestCommandData { Message = "test", Value = 1 }; - - // Act - var json = JsonSerializer.Serialize(payload, options); - using var doc = JsonDocument.Parse(json); - - // Assert: envelope contains $type and $value - Assert.True(doc.RootElement.TryGetProperty("$type", out _), - "Serialized payload should contain $type"); - Assert.True(doc.RootElement.TryGetProperty("$value", out _), - "Serialized payload should contain $value"); - } - - [Fact] - public void CommandPayloadConverter_Read_MissingTypeProperty_ThrowsJsonException() - { - // Arrange - var options = new JsonSerializerOptions(); - options.Converters.Add(new CommandPayloadConverter()); - - const string json = "{\"$value\":{\"message\":\"x\",\"value\":0}}"; - - // Act & Assert - Assert.Throws(() => - JsonSerializer.Deserialize(json, options)); - } - - [Fact] - public void CommandPayloadConverter_Read_UnknownTypeName_ThrowsJsonException() - { - // Arrange - var options = new JsonSerializerOptions(); - options.Converters.Add(new CommandPayloadConverter()); - - const string json = "{\"$type\":\"NonExistent.Type, FakeAssembly\",\"$value\":{}}"; - - // Act & Assert - var ex = Assert.Throws(() => - JsonSerializer.Deserialize(json, options)); - Assert.Contains("NonExistent.Type", ex.Message); - } - - // ── MetadataConverter ───────────────────────────────────────────────────── - - [Fact] - public void MetadataConverter_RoundTrip_PreservesAllFields() - { - // Arrange - var options = new JsonSerializerOptions(); - options.Converters.Add(new MetadataConverter()); - - var eventId = Guid.NewGuid(); - var occurredOn = new DateTime(2025, 6, 15, 12, 0, 0, DateTimeKind.Utc); - - var metadata = new Metadata - { - EventId = eventId, - IsReplay = false, - OccurredOn = occurredOn, - SequenceNo = 42, - Properties = new Dictionary { ["key"] = "value" } - }; - - // Act - var json = JsonSerializer.Serialize(metadata, options); - var result = JsonSerializer.Deserialize(json, options); - - // Assert - Assert.NotNull(result); - Assert.Equal(eventId, result!.EventId); - Assert.Equal(42, result.SequenceNo); - Assert.False(result.IsReplay); - } - - [Fact] - public void MetadataConverter_RoundTrip_PreservesPropertiesDictionary() - { - // Arrange - var options = new JsonSerializerOptions(); - options.Converters.Add(new MetadataConverter()); - - var metadata = new Metadata - { - EventId = Guid.NewGuid(), - IsReplay = true, - OccurredOn = DateTime.UtcNow, - SequenceNo = 7, - Properties = new Dictionary - { - ["correlationId"] = "abc-123", - ["source"] = "test" - } - }; - - // Act - var json = JsonSerializer.Serialize(metadata, options); - var result = JsonSerializer.Deserialize(json, options); - - // Assert - Assert.NotNull(result); - Assert.NotNull(result!.Properties); - Assert.True(result.Properties.ContainsKey("correlationId"), "Properties should contain 'correlationId'"); - } - - [Fact] - public void MetadataConverter_Write_NullValue_ProducesNullToken() - { - // Arrange - var options = new JsonSerializerOptions(); - options.Converters.Add(new MetadataConverter()); - - // Act – serialise a null Metadata - var json = JsonSerializer.Serialize(null!, options); - - // Assert - Assert.Equal("null", json); - } - - [Fact] - public void MetadataConverter_Read_NullToken_ReturnsNull() - { - // Arrange - var options = new JsonSerializerOptions(); - options.Converters.Add(new MetadataConverter()); - - // Act - var result = JsonSerializer.Deserialize("null", options); - - // Assert - Assert.Null(result); - } -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/Unit/AwsKmsMessageEncryptionTests.cs b/tests/SourceFlow.Cloud.AWS.Tests/Unit/AwsKmsMessageEncryptionTests.cs deleted file mode 100644 index 344d3cf1..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/Unit/AwsKmsMessageEncryptionTests.cs +++ /dev/null @@ -1,180 +0,0 @@ -using Amazon.KeyManagementService; -using Amazon.KeyManagementService.Model; -using Microsoft.Extensions.Caching.Memory; -using Microsoft.Extensions.Logging.Abstractions; -using Moq; -using SourceFlow.Cloud.AWS.Security; - -namespace SourceFlow.Cloud.AWS.Tests.Unit; - -[Trait("Category", "Unit")] -public class AwsKmsMessageEncryptionTests -{ - private readonly Mock _mockKmsClient; - private readonly byte[] _plaintextKey; - private readonly byte[] _encryptedKey; - - private const string TestKeyId = "arn:aws:kms:us-east-1:123456:key/test-key-id"; - - public AwsKmsMessageEncryptionTests() - { - _mockKmsClient = new Mock(); - - // AES-256 requires 32 bytes - _plaintextKey = new byte[32]; - _encryptedKey = new byte[64]; - System.Random.Shared.NextBytes(_plaintextKey); - System.Random.Shared.NextBytes(_encryptedKey); - - SetupDefaultKmsMocks(); - } - - [Fact] - public async Task EncryptAsync_CallsGenerateDataKeyAsync() - { - // Arrange - var encryption = CreateEncryption(cacheSeconds: 0); - - // Act - await encryption.EncryptAsync("hello world"); - - // Assert - _mockKmsClient.Verify( - x => x.GenerateDataKeyAsync( - It.Is(r => r.KeyId == TestKeyId), - It.IsAny()), - Times.Once); - } - - [Fact] - public async Task EncryptAsync_ProducesBase64Output() - { - // Arrange - var encryption = CreateEncryption(cacheSeconds: 0); - - // Act - var result = await encryption.EncryptAsync("hello world"); - - // Assert: result should be valid base64 - var exception = Record.Exception(() => Convert.FromBase64String(result)); - Assert.Null(exception); - Assert.False(string.IsNullOrEmpty(result)); - } - - [Fact] - public async Task DecryptAsync_CallsKmsDecryptAsync() - { - // Arrange - var encryption = CreateEncryption(cacheSeconds: 0); - var encrypted = await encryption.EncryptAsync("test message"); - - // Reset invocation tracking so we only see calls from DecryptAsync - _mockKmsClient.Invocations.Clear(); - SetupDefaultKmsMocks(); // re-register - - // Act - await encryption.DecryptAsync(encrypted); - - // Assert - _mockKmsClient.Verify( - x => x.DecryptAsync(It.IsAny(), It.IsAny()), - Times.Once); - } - - [Fact] - public async Task EncryptThenDecrypt_RoundTrip_ReturnsOriginalPlaintext() - { - // Arrange – no caching so each call hits KMS - var encryption = CreateEncryption(cacheSeconds: 0); - const string original = "hello world"; - - // Act - var encrypted = await encryption.EncryptAsync(original); - var decrypted = await encryption.DecryptAsync(encrypted); - - // Assert - Assert.Equal(original, decrypted); - } - - [Fact] - public async Task EncryptAsync_CachingEnabled_GenerateDataKeyCalledOnceForMultipleCalls() - { - // Arrange – use real MemoryCache with a long TTL - var cache = new MemoryCache(new MemoryCacheOptions()); - var encryption = CreateEncryption(cacheSeconds: 300, cache: cache); - - // Act - await encryption.EncryptAsync("message 1"); - await encryption.EncryptAsync("message 2"); - await encryption.EncryptAsync("message 3"); - - // Assert: GenerateDataKey should be called exactly once (key cached after first call) - _mockKmsClient.Verify( - x => x.GenerateDataKeyAsync(It.IsAny(), It.IsAny()), - Times.Once); - } - - [Fact] - public async Task EncryptAsync_CachingDisabled_GenerateDataKeyCalledForEachCall() - { - // Arrange – caching disabled (0 seconds) - var encryption = CreateEncryption(cacheSeconds: 0); - - // Act - await encryption.EncryptAsync("message 1"); - await encryption.EncryptAsync("message 2"); - - // Assert: GenerateDataKey should be called for every encrypt operation - _mockKmsClient.Verify( - x => x.GenerateDataKeyAsync(It.IsAny(), It.IsAny()), - Times.Exactly(2)); - } - - [Fact] - public void AlgorithmName_ReturnsExpectedValue() - { - var encryption = CreateEncryption(cacheSeconds: 0); - Assert.Equal("AWS-KMS-AES256", encryption.AlgorithmName); - } - - [Fact] - public void KeyIdentifier_ReturnsMasterKeyId() - { - var encryption = CreateEncryption(cacheSeconds: 0); - Assert.Equal(TestKeyId, encryption.KeyIdentifier); - } - - // ── Helpers ────────────────────────────────────────────────────────────── - - private void SetupDefaultKmsMocks() - { - // Each call to GenerateDataKey returns the same key bytes for predictable round-trips - _mockKmsClient - .Setup(x => x.GenerateDataKeyAsync(It.IsAny(), It.IsAny())) - .ReturnsAsync(new GenerateDataKeyResponse - { - Plaintext = new MemoryStream(_plaintextKey.ToArray()), - CiphertextBlob = new MemoryStream(_encryptedKey.ToArray()) - }); - - _mockKmsClient - .Setup(x => x.DecryptAsync(It.IsAny(), It.IsAny())) - .ReturnsAsync(new DecryptResponse - { - Plaintext = new MemoryStream(_plaintextKey.ToArray()) - }); - } - - private AwsKmsMessageEncryption CreateEncryption(int cacheSeconds, IMemoryCache? cache = null) - { - return new AwsKmsMessageEncryption( - _mockKmsClient.Object, - NullLogger.Instance, - cache ?? new MemoryCache(new MemoryCacheOptions()), - new AwsKmsOptions - { - MasterKeyId = TestKeyId, - CacheDataKeySeconds = cacheSeconds - }); - } -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/Unit/AwsPerformanceMeasurementPropertyTests.cs b/tests/SourceFlow.Cloud.AWS.Tests/Unit/AwsPerformanceMeasurementPropertyTests.cs deleted file mode 100644 index c38470e3..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/Unit/AwsPerformanceMeasurementPropertyTests.cs +++ /dev/null @@ -1,809 +0,0 @@ -using Amazon.SQS.Model; -using Amazon.SimpleNotificationService.Model; -using FsCheck; -using FsCheck.Xunit; -using SourceFlow.Cloud.AWS.Tests.TestHelpers; -using System.Diagnostics; -using System.Text; - -namespace SourceFlow.Cloud.AWS.Tests.Unit; - -/// -/// Property-based tests for AWS performance measurement consistency -/// Validates that performance measurements are consistent and reliable across test runs -/// **Feature: aws-cloud-integration-testing, Property 9: AWS Performance Measurement Consistency** -/// -[Collection("AWS Integration Tests")] -[Trait("Category", "Unit")] -public class AwsPerformanceMeasurementPropertyTests : IClassFixture, IAsyncDisposable -{ - private readonly LocalStackTestFixture _localStack; - private readonly List _createdQueues = new(); - private readonly List _createdTopics = new(); - - public AwsPerformanceMeasurementPropertyTests(LocalStackTestFixture localStack) - { - _localStack = localStack; - } - - /// - /// Property 9: AWS Performance Measurement Consistency - /// For any AWS performance test scenario, when executed multiple times under similar conditions, - /// the performance measurements (SQS/SNS throughput, end-to-end latency, resource utilization) - /// should be consistent within acceptable variance ranges and scale appropriately with load. - /// **Validates: Requirements 5.1, 5.2, 5.3, 5.4, 5.5** - /// - [Fact] - public async Task Property_AwsPerformanceMeasurementConsistency() - { - // Skip if not configured for performance tests - if (!_localStack.Configuration.RunPerformanceTests || _localStack.SqsClient == null) - { - return; - } - - // Generate a few test scenarios to validate - var scenarios = new[] - { - new AwsPerformanceScenario - { - TestSqsThroughput = true, - TestSnsThroughput = false, - TestEndToEndLatency = false, - MessageCount = 10, - MessageSizeBytes = 256, - ConcurrentOperations = 2, - UseFifoQueue = false, - NumberOfRuns = 3, - TestScalability = false - }, - new AwsPerformanceScenario - { - TestSqsThroughput = false, - TestSnsThroughput = true, - TestEndToEndLatency = false, - MessageCount = 10, - MessageSizeBytes = 512, - ConcurrentOperations = 2, - UseFifoQueue = false, - NumberOfRuns = 3, - TestScalability = false - }, - new AwsPerformanceScenario - { - TestSqsThroughput = false, - TestSnsThroughput = false, - TestEndToEndLatency = true, - MessageCount = 5, - MessageSizeBytes = 256, - ConcurrentOperations = 1, - UseFifoQueue = false, - NumberOfRuns = 3, - TestScalability = false - } - }; - - foreach (var scenario in scenarios) - { - await ValidatePerformanceScenario(scenario); - } - } - - private async Task ValidatePerformanceScenario(AwsPerformanceScenario scenario) - { - // Arrange - Create test resources - var resources = await CreatePerformanceTestResourcesAsync(scenario); - - try - { - // Act - Run performance test multiple times - var measurements = new List(); - - for (int run = 0; run < scenario.NumberOfRuns; run++) - { - var measurement = await ExecutePerformanceTestAsync(resources, scenario); - measurements.Add(measurement); - - // Small delay between runs to avoid interference - if (run < scenario.NumberOfRuns - 1) - { - await Task.Delay(100); - } - } - - // Assert - Performance measurements are consistent - AssertPerformanceConsistency(measurements, scenario); - - // Assert - Throughput measurements are within acceptable variance - AssertThroughputConsistency(measurements, scenario); - - // Assert - Latency measurements are within acceptable variance - AssertLatencyConsistency(measurements, scenario); - - // Assert - Resource utilization is reasonable - AssertResourceUtilization(measurements, scenario); - - // Assert - Performance scales appropriately with load - if (scenario.TestScalability) - { - await AssertPerformanceScalability(resources, scenario); - } - } - finally - { - // Clean up resources - await CleanupPerformanceResourcesAsync(resources); - } - } - - /// - /// Create performance test resources based on scenario - /// - private async Task CreatePerformanceTestResourcesAsync(AwsPerformanceScenario scenario) - { - var resources = new PerformanceTestResources(); - - if (scenario.TestSqsThroughput || scenario.TestEndToEndLatency) - { - var queueName = scenario.UseFifoQueue - ? $"perf-test-{Guid.NewGuid():N}.fifo" - : $"perf-test-{Guid.NewGuid():N}"; - - var createRequest = new CreateQueueRequest - { - QueueName = queueName, - Attributes = new Dictionary - { - ["MessageRetentionPeriod"] = "3600", - ["VisibilityTimeout"] = "30" - } - }; - - if (scenario.UseFifoQueue) - { - createRequest.Attributes["FifoQueue"] = "true"; - createRequest.Attributes["ContentBasedDeduplication"] = "true"; - } - - var response = await _localStack.SqsClient!.CreateQueueAsync(createRequest); - resources.QueueUrl = response.QueueUrl; - _createdQueues.Add(response.QueueUrl); - } - - if (scenario.TestSnsThroughput) - { - var topicName = $"perf-test-{Guid.NewGuid():N}"; - var response = await _localStack.SnsClient!.CreateTopicAsync(new CreateTopicRequest - { - Name = topicName - }); - resources.TopicArn = response.TopicArn; - _createdTopics.Add(response.TopicArn); - - // Create SQS queue for SNS subscription - var queueName = $"perf-test-sns-sub-{Guid.NewGuid():N}"; - var queueResponse = await _localStack.SqsClient!.CreateQueueAsync(new CreateQueueRequest - { - QueueName = queueName - }); - resources.SubscriptionQueueUrl = queueResponse.QueueUrl; - _createdQueues.Add(queueResponse.QueueUrl); - - // Subscribe queue to topic - await _localStack.SnsClient.SubscribeAsync(new SubscribeRequest - { - TopicArn = resources.TopicArn, - Protocol = "sqs", - Endpoint = $"arn:aws:sqs:us-east-1:000000000000:{queueName}" - }); - } - - return resources; - } - - /// - /// Execute a single performance test run - /// - private async Task ExecutePerformanceTestAsync( - PerformanceTestResources resources, - AwsPerformanceScenario scenario) - { - var measurement = new PerformanceMeasurement - { - TestType = scenario.TestSqsThroughput ? "SQS Throughput" : - scenario.TestSnsThroughput ? "SNS Throughput" : "End-to-End Latency", - MessageCount = scenario.MessageCount, - MessageSizeBytes = scenario.MessageSizeBytes, - ConcurrentOperations = scenario.ConcurrentOperations - }; - - var stopwatch = Stopwatch.StartNew(); - var startMemory = GC.GetTotalMemory(false); - - try - { - if (scenario.TestSqsThroughput) - { - await MeasureSqsThroughputAsync(resources, scenario, measurement); - } - else if (scenario.TestSnsThroughput) - { - await MeasureSnsThroughputAsync(resources, scenario, measurement); - } - else if (scenario.TestEndToEndLatency) - { - await MeasureEndToEndLatencyAsync(resources, scenario, measurement); - } - - stopwatch.Stop(); - var endMemory = GC.GetTotalMemory(false); - - measurement.TotalDuration = stopwatch.Elapsed; - measurement.MemoryUsedBytes = endMemory - startMemory; - measurement.Success = true; - - // Calculate throughput - if (measurement.TotalDuration.TotalSeconds > 0) - { - measurement.MessagesPerSecond = measurement.MessageCount / measurement.TotalDuration.TotalSeconds; - } - } - catch (Exception ex) - { - measurement.Success = false; - measurement.ErrorMessage = ex.Message; - } - - return measurement; - } - - /// - /// Measure SQS throughput performance - /// - private async Task MeasureSqsThroughputAsync( - PerformanceTestResources resources, - AwsPerformanceScenario scenario, - PerformanceMeasurement measurement) - { - var messageBody = GenerateMessageBody(scenario.MessageSizeBytes); - var messagesPerOperation = scenario.MessageCount / scenario.ConcurrentOperations; - var operationLatencies = new List(); - - var tasks = Enumerable.Range(0, scenario.ConcurrentOperations) - .Select(async operationId => - { - var operationStopwatch = Stopwatch.StartNew(); - - for (int i = 0; i < messagesPerOperation; i++) - { - var request = new SendMessageRequest - { - QueueUrl = resources.QueueUrl, - MessageBody = messageBody, - MessageAttributes = new Dictionary - { - ["OperationId"] = new Amazon.SQS.Model.MessageAttributeValue - { - DataType = "Number", - StringValue = operationId.ToString() - }, - ["MessageIndex"] = new Amazon.SQS.Model.MessageAttributeValue - { - DataType = "Number", - StringValue = i.ToString() - } - } - }; - - if (scenario.UseFifoQueue) - { - request.MessageGroupId = $"group-{operationId}"; - request.MessageDeduplicationId = $"op-{operationId}-msg-{i}-{Guid.NewGuid():N}"; - } - - await _localStack.SqsClient!.SendMessageAsync(request); - } - - operationStopwatch.Stop(); - lock (operationLatencies) - { - operationLatencies.Add(operationStopwatch.Elapsed); - } - }); - - await Task.WhenAll(tasks); - - measurement.AverageLatency = TimeSpan.FromMilliseconds(operationLatencies.Average(l => l.TotalMilliseconds)); - measurement.MinLatency = operationLatencies.Min(); - measurement.MaxLatency = operationLatencies.Max(); - } - - /// - /// Measure SNS throughput performance - /// - private async Task MeasureSnsThroughputAsync( - PerformanceTestResources resources, - AwsPerformanceScenario scenario, - PerformanceMeasurement measurement) - { - var messageBody = GenerateMessageBody(scenario.MessageSizeBytes); - var messagesPerOperation = scenario.MessageCount / scenario.ConcurrentOperations; - var operationLatencies = new List(); - - var tasks = Enumerable.Range(0, scenario.ConcurrentOperations) - .Select(async operationId => - { - var operationStopwatch = Stopwatch.StartNew(); - - for (int i = 0; i < messagesPerOperation; i++) - { - await _localStack.SnsClient!.PublishAsync(new PublishRequest - { - TopicArn = resources.TopicArn, - Message = messageBody, - MessageAttributes = new Dictionary - { - ["OperationId"] = new Amazon.SimpleNotificationService.Model.MessageAttributeValue - { - DataType = "Number", - StringValue = operationId.ToString() - }, - ["MessageIndex"] = new Amazon.SimpleNotificationService.Model.MessageAttributeValue - { - DataType = "Number", - StringValue = i.ToString() - } - } - }); - } - - operationStopwatch.Stop(); - lock (operationLatencies) - { - operationLatencies.Add(operationStopwatch.Elapsed); - } - }); - - await Task.WhenAll(tasks); - - measurement.AverageLatency = TimeSpan.FromMilliseconds(operationLatencies.Average(l => l.TotalMilliseconds)); - measurement.MinLatency = operationLatencies.Min(); - measurement.MaxLatency = operationLatencies.Max(); - } - - /// - /// Measure end-to-end latency (send + receive + delete) - /// - private async Task MeasureEndToEndLatencyAsync( - PerformanceTestResources resources, - AwsPerformanceScenario scenario, - PerformanceMeasurement measurement) - { - var messageBody = GenerateMessageBody(scenario.MessageSizeBytes); - var latencies = new List(); - - for (int i = 0; i < scenario.MessageCount; i++) - { - var e2eStopwatch = Stopwatch.StartNew(); - - // Send message - var sendRequest = new SendMessageRequest - { - QueueUrl = resources.QueueUrl, - MessageBody = messageBody, - MessageAttributes = new Dictionary - { - ["Timestamp"] = new Amazon.SQS.Model.MessageAttributeValue - { - DataType = "Number", - StringValue = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds().ToString() - } - } - }; - - if (scenario.UseFifoQueue) - { - sendRequest.MessageGroupId = $"e2e-group-{i}"; - sendRequest.MessageDeduplicationId = $"e2e-{i}-{Guid.NewGuid():N}"; - } - - await _localStack.SqsClient!.SendMessageAsync(sendRequest); - - // Receive message - var receiveResponse = await _localStack.SqsClient.ReceiveMessageAsync(new ReceiveMessageRequest - { - QueueUrl = resources.QueueUrl, - MaxNumberOfMessages = 1, - WaitTimeSeconds = 2, - MessageAttributeNames = new List { "All" } - }); - - // Delete message - if (receiveResponse.Messages.Count > 0) - { - await _localStack.SqsClient.DeleteMessageAsync(new DeleteMessageRequest - { - QueueUrl = resources.QueueUrl, - ReceiptHandle = receiveResponse.Messages[0].ReceiptHandle - }); - } - - e2eStopwatch.Stop(); - latencies.Add(e2eStopwatch.Elapsed); - } - - measurement.AverageLatency = TimeSpan.FromMilliseconds(latencies.Average(l => l.TotalMilliseconds)); - measurement.MinLatency = latencies.Min(); - measurement.MaxLatency = latencies.Max(); - } - - /// - /// Assert that performance measurements are consistent across runs - /// - private void AssertPerformanceConsistency(List measurements, AwsPerformanceScenario scenario) - { - // All measurements should be successful - var successfulMeasurements = measurements.Where(m => m.Success).ToList(); - Assert.True(successfulMeasurements.Count >= measurements.Count * 0.9, - $"At least 90% of performance measurements should succeed, got {successfulMeasurements.Count}/{measurements.Count}"); - - if (successfulMeasurements.Count < 2) - { - return; // Need at least 2 measurements for consistency check - } - - // Calculate coefficient of variation (CV) for total duration - var durations = successfulMeasurements.Select(m => m.TotalDuration.TotalMilliseconds).ToList(); - var avgDuration = durations.Average(); - var stdDevDuration = Math.Sqrt(durations.Average(d => Math.Pow(d - avgDuration, 2))); - var cvDuration = stdDevDuration / avgDuration; - - // CV should be less than 0.5 (50%) for reasonable consistency - Assert.True(cvDuration < 0.5, - $"Performance duration should be consistent (CV < 0.5), got CV = {cvDuration:F3}"); - } - - /// - /// Assert that throughput measurements are within acceptable variance - /// - private void AssertThroughputConsistency(List measurements, AwsPerformanceScenario scenario) - { - var successfulMeasurements = measurements.Where(m => m.Success && m.MessagesPerSecond > 0).ToList(); - - if (successfulMeasurements.Count < 2) - { - return; // Need at least 2 measurements - } - - var throughputs = successfulMeasurements.Select(m => m.MessagesPerSecond).ToList(); - var avgThroughput = throughputs.Average(); - var minThroughput = throughputs.Min(); - var maxThroughput = throughputs.Max(); - - // Throughput should be positive - Assert.True(avgThroughput > 0, "Average throughput should be positive"); - - // Variance should be within acceptable range (within 2x of average) - var varianceRatio = maxThroughput / minThroughput; - Assert.True(varianceRatio < 3.0, - $"Throughput variance should be reasonable (max/min < 3.0), got {varianceRatio:F2}"); - - // For LocalStack, throughput should be at least 1 msg/sec - Assert.True(avgThroughput >= 1.0, - $"Average throughput should be at least 1 msg/sec, got {avgThroughput:F2}"); - } - - /// - /// Assert that latency measurements are within acceptable variance - /// - private void AssertLatencyConsistency(List measurements, AwsPerformanceScenario scenario) - { - var successfulMeasurements = measurements.Where(m => m.Success && m.AverageLatency > TimeSpan.Zero).ToList(); - - if (successfulMeasurements.Count < 2) - { - return; // Need at least 2 measurements - } - - var avgLatencies = successfulMeasurements.Select(m => m.AverageLatency.TotalMilliseconds).ToList(); - var overallAvgLatency = avgLatencies.Average(); - var stdDevLatency = Math.Sqrt(avgLatencies.Average(l => Math.Pow(l - overallAvgLatency, 2))); - var cvLatency = stdDevLatency / overallAvgLatency; - - // Latency CV should be less than 0.6 (60%) for reasonable consistency - Assert.True(cvLatency < 0.6, - $"Latency should be consistent (CV < 0.6), got CV = {cvLatency:F3}"); - - // Average latency should be reasonable (less than 10 seconds for LocalStack) - Assert.True(overallAvgLatency < 10000, - $"Average latency should be less than 10 seconds, got {overallAvgLatency:F2}ms"); - - // Min latency should be less than max latency - foreach (var measurement in successfulMeasurements) - { - Assert.True(measurement.MinLatency <= measurement.MaxLatency, - "Min latency should be less than or equal to max latency"); - Assert.True(measurement.MinLatency <= measurement.AverageLatency, - "Min latency should be less than or equal to average latency"); - Assert.True(measurement.AverageLatency <= measurement.MaxLatency, - "Average latency should be less than or equal to max latency"); - } - } - - /// - /// Assert that resource utilization is reasonable - /// - private void AssertResourceUtilization(List measurements, AwsPerformanceScenario scenario) - { - var successfulMeasurements = measurements.Where(m => m.Success).ToList(); - - if (successfulMeasurements.Count == 0) - { - return; - } - - // Memory usage should be reasonable (less than 100MB per test run) - var maxMemoryUsage = successfulMeasurements.Max(m => m.MemoryUsedBytes); - Assert.True(maxMemoryUsage < 100 * 1024 * 1024, - $"Memory usage should be less than 100MB, got {maxMemoryUsage / (1024.0 * 1024.0):F2}MB"); - - // Memory usage should scale reasonably with message count and size - var avgMemoryPerMessage = successfulMeasurements.Average(m => - m.MessageCount > 0 ? (double)m.MemoryUsedBytes / m.MessageCount : 0); - - // Should use less than 10KB per message on average (accounting for overhead) - Assert.True(avgMemoryPerMessage < 10 * 1024, - $"Average memory per message should be less than 10KB, got {avgMemoryPerMessage / 1024.0:F2}KB"); - } - - /// - /// Assert that performance scales appropriately with load - /// - private async Task AssertPerformanceScalability(PerformanceTestResources resources, AwsPerformanceScenario scenario) - { - // Test with different load levels - var loadLevels = new[] { scenario.MessageCount / 2, scenario.MessageCount, scenario.MessageCount * 2 }; - var scalabilityMeasurements = new List<(int Load, double Throughput)>(); - - foreach (var load in loadLevels) - { - var scalabilityScenario = new AwsPerformanceScenario - { - TestSqsThroughput = scenario.TestSqsThroughput, - TestSnsThroughput = scenario.TestSnsThroughput, - TestEndToEndLatency = scenario.TestEndToEndLatency, - MessageCount = load, - MessageSizeBytes = scenario.MessageSizeBytes, - ConcurrentOperations = scenario.ConcurrentOperations, - UseFifoQueue = scenario.UseFifoQueue, - NumberOfRuns = 1, - TestScalability = false - }; - - var measurement = await ExecutePerformanceTestAsync(resources, scalabilityScenario); - - if (measurement.Success && measurement.MessagesPerSecond > 0) - { - scalabilityMeasurements.Add((load, measurement.MessagesPerSecond)); - } - - // Small delay between scalability tests - await Task.Delay(200); - } - - if (scalabilityMeasurements.Count >= 2) - { - // Throughput should generally increase or remain stable with load - // (or at least not decrease dramatically) - var firstThroughput = scalabilityMeasurements[0].Throughput; - var lastThroughput = scalabilityMeasurements[^1].Throughput; - - // Allow throughput to decrease by at most 50% as load increases - // (LocalStack may have different characteristics than real AWS) - Assert.True(lastThroughput > firstThroughput * 0.5, - $"Throughput should not decrease dramatically with load. " + - $"First: {firstThroughput:F2} msg/s, Last: {lastThroughput:F2} msg/s"); - } - } - - /// - /// Clean up performance test resources - /// - private async Task CleanupPerformanceResourcesAsync(PerformanceTestResources resources) - { - if (!string.IsNullOrEmpty(resources.QueueUrl)) - { - try - { - // Purge queue first to speed up deletion - await _localStack.SqsClient!.PurgeQueueAsync(new PurgeQueueRequest - { - QueueUrl = resources.QueueUrl - }); - - await Task.Delay(100); // Small delay after purge - - await _localStack.SqsClient.DeleteQueueAsync(new DeleteQueueRequest - { - QueueUrl = resources.QueueUrl - }); - } - catch - { - // Ignore cleanup errors - } - } - - if (!string.IsNullOrEmpty(resources.SubscriptionQueueUrl)) - { - try - { - await _localStack.SqsClient!.DeleteQueueAsync(new DeleteQueueRequest - { - QueueUrl = resources.SubscriptionQueueUrl - }); - } - catch - { - // Ignore cleanup errors - } - } - - if (!string.IsNullOrEmpty(resources.TopicArn)) - { - try - { - await _localStack.SnsClient!.DeleteTopicAsync(new DeleteTopicRequest - { - TopicArn = resources.TopicArn - }); - } - catch - { - // Ignore cleanup errors - } - } - } - - /// - /// Generate message body of specified size - /// - private string GenerateMessageBody(int sizeBytes) - { - var sb = new StringBuilder(sizeBytes); - var random = new System.Random(); - - while (sb.Length < sizeBytes) - { - sb.Append((char)('A' + random.Next(26))); - } - - return sb.ToString(0, sizeBytes); - } - - /// - /// Clean up created resources - /// - public async ValueTask DisposeAsync() - { - if (_localStack.SqsClient != null) - { - foreach (var queueUrl in _createdQueues) - { - try - { - await _localStack.SqsClient.DeleteQueueAsync(new DeleteQueueRequest { QueueUrl = queueUrl }); - } - catch - { - // Ignore cleanup errors - } - } - } - - if (_localStack.SnsClient != null) - { - foreach (var topicArn in _createdTopics) - { - try - { - await _localStack.SnsClient.DeleteTopicAsync(new DeleteTopicRequest { TopicArn = topicArn }); - } - catch - { - // Ignore cleanup errors - } - } - } - - _createdQueues.Clear(); - _createdTopics.Clear(); - } -} - - -#region Test Models and Generators - -/// -/// Scenario for AWS performance testing -/// -public class AwsPerformanceScenario -{ - public bool TestSqsThroughput { get; set; } - public bool TestSnsThroughput { get; set; } - public bool TestEndToEndLatency { get; set; } - public int MessageCount { get; set; } - public int MessageSizeBytes { get; set; } - public int ConcurrentOperations { get; set; } - public bool UseFifoQueue { get; set; } - public int NumberOfRuns { get; set; } - public bool TestScalability { get; set; } -} - -/// -/// Resources created for performance testing -/// -public class PerformanceTestResources -{ - public string? QueueUrl { get; set; } - public string? TopicArn { get; set; } - public string? SubscriptionQueueUrl { get; set; } -} - -/// -/// Performance measurement result -/// -public class PerformanceMeasurement -{ - public string TestType { get; set; } = ""; - public int MessageCount { get; set; } - public int MessageSizeBytes { get; set; } - public int ConcurrentOperations { get; set; } - public TimeSpan TotalDuration { get; set; } - public TimeSpan AverageLatency { get; set; } - public TimeSpan MinLatency { get; set; } - public TimeSpan MaxLatency { get; set; } - public double MessagesPerSecond { get; set; } - public long MemoryUsedBytes { get; set; } - public bool Success { get; set; } - public string? ErrorMessage { get; set; } -} - - -/// -/// FsCheck generators for AWS performance scenarios -/// -public static class AwsPerformanceGenerators -{ - /// - /// Generate valid AWS performance test scenarios - /// - public static Arbitrary AwsPerformanceScenario() - { - var generator = from testType in Gen.Choose(0, 2) - from messageCount in Gen.Choose(5, 50) // Keep small for property tests - from messageSizeBytes in Gen.Elements(128, 256, 512, 1024) - from concurrentOps in Gen.Choose(1, 5) - from useFifo in Arb.Generate() - from numberOfRuns in Gen.Choose(2, 5) // Multiple runs for consistency check - from testScalability in Gen.Frequency( - Tuple.Create(8, Gen.Constant(false)), // 80% no scalability test - Tuple.Create(2, Gen.Constant(true))) // 20% with scalability test - select new AwsPerformanceScenario - { - TestSqsThroughput = testType == 0, - TestSnsThroughput = testType == 1, - TestEndToEndLatency = testType == 2, - MessageCount = messageCount, - MessageSizeBytes = messageSizeBytes, - ConcurrentOperations = concurrentOps, - UseFifoQueue = useFifo && testType != 1, // SNS doesn't use FIFO - NumberOfRuns = numberOfRuns, - TestScalability = testScalability && messageCount >= 10 // Only test scalability with sufficient messages - }; - - return Arb.From(generator); - } -} - -#endregion diff --git a/tests/SourceFlow.Cloud.AWS.Tests/Unit/AwsResiliencePatternPropertyTests.cs b/tests/SourceFlow.Cloud.AWS.Tests/Unit/AwsResiliencePatternPropertyTests.cs deleted file mode 100644 index cb88bacf..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/Unit/AwsResiliencePatternPropertyTests.cs +++ /dev/null @@ -1,491 +0,0 @@ -using FsCheck; -using FsCheck.Xunit; -using SourceFlow.Cloud.Resilience; -using SourceFlow.Cloud.AWS.Tests.TestHelpers; -using Microsoft.Extensions.Logging; -using Microsoft.Extensions.Options; - -namespace SourceFlow.Cloud.AWS.Tests.Unit; - -/// -/// Property-based tests for AWS resilience pattern compliance -/// **Feature: aws-cloud-integration-testing, Property 11: AWS Resilience Pattern Compliance** -/// **Validates: Requirements 7.1, 7.2, 7.4, 7.5** -/// -[Trait("Category", "Unit")] -public class AwsResiliencePatternPropertyTests -{ - /// - /// Property: AWS Resilience Pattern Compliance - /// **Validates: Requirements 7.1, 7.2, 7.4, 7.5** - /// - /// For any AWS service operation, when failures occur, the system should implement proper circuit breaker patterns, - /// exponential backoff retry policies with jitter, graceful handling of service throttling, and automatic recovery - /// when services become available. - /// - [Property(MaxTest = 100)] - public Property AwsResiliencePatternCompliance(PositiveInt failureThreshold, PositiveInt openDurationSeconds, - PositiveInt successThreshold, PositiveInt operationTimeoutSeconds, bool enableFallback, - NonNegativeInt maxRetries, PositiveInt baseDelayMs, PositiveInt maxDelayMs, bool useJitter, - PositiveInt failureCount, PositiveInt recoveryAfterFailures, bool isTransient, PositiveInt throttleDelayMs) - { - // Create circuit breaker options from generated values - var cbOptions = new CircuitBreakerOptions - { - FailureThreshold = Math.Min(failureThreshold.Get, 10), - OpenDuration = TimeSpan.FromSeconds(Math.Min(openDurationSeconds.Get, 300)), - SuccessThreshold = Math.Min(successThreshold.Get, 5), - OperationTimeout = TimeSpan.FromSeconds(Math.Min(operationTimeoutSeconds.Get, 60)), - EnableFallback = enableFallback - }; - - // Create retry configuration from generated values - var retryConfig = new AwsRetryConfiguration - { - MaxRetries = Math.Min(maxRetries.Get, 10), - BaseDelayMs = Math.Max(50, Math.Min(baseDelayMs.Get, 5000)), - MaxDelayMs = Math.Max(1000, Math.Min(maxDelayMs.Get, 30000)), - UseJitter = useJitter, - BackoffMultiplier = 2.0 // Fixed reasonable value - }; - - // Ensure max delay >= base delay - retryConfig.MaxDelayMs = Math.Max(retryConfig.MaxDelayMs, retryConfig.BaseDelayMs); - - // Create failure scenario from generated values - var failureScenario = new AwsServiceFailureScenario - { - FailureType = AwsFailureType.ServiceUnavailable, // Use a fixed type for simplicity - FailureCount = Math.Min(failureCount.Get, 20), - RecoveryAfterFailures = Math.Min(recoveryAfterFailures.Get, 10), - IsTransient = isTransient, - ThrottleDelayMs = Math.Max(100, Math.Min(throttleDelayMs.Get, 5000)) - }; - - // Ensure recovery doesn't exceed failures - failureScenario.RecoveryAfterFailures = Math.Min(failureScenario.RecoveryAfterFailures, failureScenario.FailureCount); - - // Property 1: Circuit breaker should open after consecutive failures (Requirement 7.1) - var circuitBreakerValid = ValidateCircuitBreakerPattern(cbOptions, failureScenario); - - // Property 2: Retry policy should implement exponential backoff with jitter (Requirement 7.2) - var retryPolicyValid = ValidateExponentialBackoffWithJitter(retryConfig); - - // Property 3: System should handle service throttling gracefully (Requirement 7.4) - var throttlingHandlingValid = ValidateThrottlingHandling(retryConfig, failureScenario); - - // Property 4: System should recover automatically when services become available (Requirement 7.5) - var automaticRecoveryValid = ValidateAutomaticRecovery(cbOptions, failureScenario); - - return (circuitBreakerValid && retryPolicyValid && throttlingHandlingValid && automaticRecoveryValid).ToProperty(); - } - - /// - /// Validates circuit breaker pattern implementation - /// Requirement 7.1: Automatic circuit opening on SQS/SNS failures and recovery scenarios - /// - private static bool ValidateCircuitBreakerPattern(CircuitBreakerOptions options, - AwsServiceFailureScenario scenario) - { - // Circuit breaker configuration should be valid - var configurationValid = ValidateCircuitBreakerConfiguration(options); - - // Circuit should open after failure threshold is reached - var openingBehaviorValid = ValidateCircuitOpeningBehavior(options, scenario); - - // Circuit should transition to half-open after timeout - var halfOpenTransitionValid = ValidateHalfOpenTransition(options); - - // Circuit should close after successful operations in half-open state - var closingBehaviorValid = ValidateCircuitClosingBehavior(options); - - // Circuit should reopen immediately on failure in half-open state - var halfOpenFailureValid = ValidateHalfOpenFailureHandling(options); - - return configurationValid && openingBehaviorValid && halfOpenTransitionValid && - closingBehaviorValid && halfOpenFailureValid; - } - - /// - /// Validates exponential backoff with jitter implementation - /// Requirement 7.2: Exponential backoff retry policies with jitter - /// - private static bool ValidateExponentialBackoffWithJitter(AwsRetryConfiguration config) - { - // Retry configuration should be valid - var configurationValid = ValidateRetryConfiguration(config); - - // Backoff delays should increase exponentially - var exponentialGrowthValid = ValidateExponentialGrowth(config); - - // Jitter should be applied to prevent thundering herd - var jitterValid = ValidateJitterApplication(config); - - // Maximum retry limit should be enforced - var maxRetryValid = ValidateMaxRetryEnforcement(config); - - // Delays should not exceed maximum configured delay - var maxDelayValid = ValidateMaxDelayEnforcement(config); - - return configurationValid && exponentialGrowthValid && jitterValid && - maxRetryValid && maxDelayValid; - } - - /// - /// Validates graceful handling of service throttling - /// Requirement 7.4: Graceful handling of service throttling - /// - private static bool ValidateThrottlingHandling(AwsRetryConfiguration config, - AwsServiceFailureScenario scenario) - { - // Throttling errors should trigger backoff - var throttlingBackoffValid = ValidateThrottlingBackoff(config, scenario); - - // Backoff should be longer for throttling than other errors - var throttlingDelayValid = ValidateThrottlingDelay(config, scenario); - - // System should not overwhelm service during throttling - var rateControlValid = ValidateRateControl(config, scenario); - - // Throttling should not immediately open circuit breaker - var throttlingCircuitValid = ValidateThrottlingCircuitBehavior(scenario); - - return throttlingBackoffValid && throttlingDelayValid && rateControlValid && throttlingCircuitValid; - } - - /// - /// Validates automatic recovery when services become available - /// Requirement 7.5: Automatic recovery when services become available - /// - private static bool ValidateAutomaticRecovery(CircuitBreakerOptions options, - AwsServiceFailureScenario scenario) - { - // System should detect service recovery - var recoveryDetectionValid = ValidateRecoveryDetection(scenario); - - // Circuit breaker should transition to half-open for testing - var halfOpenTestingValid = ValidateHalfOpenTesting(options); - - // Successful operations should close the circuit - var circuitClosingValid = ValidateCircuitClosingOnRecovery(options, scenario); - - // Recovery should be gradual and controlled - var gradualRecoveryValid = ValidateGradualRecovery(options, scenario); - - // System should resume normal operation after recovery - var normalOperationValid = ValidateNormalOperationResumption(scenario); - - return recoveryDetectionValid && halfOpenTestingValid && circuitClosingValid && - gradualRecoveryValid && normalOperationValid; - } - - // Circuit Breaker Validation Methods - - private static bool ValidateCircuitBreakerConfiguration(CircuitBreakerOptions options) - { - // Failure threshold should be positive and reasonable - var failureThresholdValid = options.FailureThreshold >= 1 && options.FailureThreshold <= 100; - - // Open duration should be positive and reasonable - var openDurationValid = options.OpenDuration > TimeSpan.Zero && - options.OpenDuration <= TimeSpan.FromHours(1); - - // Success threshold should be positive and reasonable - var successThresholdValid = options.SuccessThreshold >= 1 && options.SuccessThreshold <= 10; - - // Operation timeout should be positive and reasonable - var operationTimeoutValid = options.OperationTimeout > TimeSpan.Zero && - options.OperationTimeout <= TimeSpan.FromMinutes(5); - - // All thresholds should be reasonable (removed overly strict constraint) - var thresholdsReasonable = options.SuccessThreshold <= 100 && options.FailureThreshold <= 100; - - return failureThresholdValid && openDurationValid && successThresholdValid && - operationTimeoutValid && thresholdsReasonable; - } - - private static bool ValidateCircuitOpeningBehavior(CircuitBreakerOptions options, - AwsServiceFailureScenario scenario) - { - // Circuit should open when consecutive failures reach threshold - var shouldOpen = scenario.FailureCount >= options.FailureThreshold; - - // Circuit should remain closed if failures are below threshold - var shouldStayClosed = scenario.FailureCount < options.FailureThreshold; - - // Behavior should be deterministic based on failure count - var behaviorDeterministic = shouldOpen || shouldStayClosed; - - return behaviorDeterministic; - } - - private static bool ValidateHalfOpenTransition(CircuitBreakerOptions options) - { - // Half-open transition should occur after open duration - var transitionTimingValid = options.OpenDuration > TimeSpan.Zero; - - // Half-open state should allow test operations - var testOperationsAllowed = true; // Circuit breaker allows operations in half-open - - return transitionTimingValid && testOperationsAllowed; - } - - private static bool ValidateCircuitClosingBehavior(CircuitBreakerOptions options) - { - // Circuit should close after success threshold is met in half-open state - var closingThresholdValid = options.SuccessThreshold >= 1; - - // Closing should reset failure counters - var resetBehaviorValid = true; // Circuit breaker resets on close - - return closingThresholdValid && resetBehaviorValid; - } - - private static bool ValidateHalfOpenFailureHandling(CircuitBreakerOptions options) - { - // Any failure in half-open should immediately reopen circuit - var immediateReopenValid = true; // Circuit breaker reopens on half-open failure - - // Reopen should reset the open duration timer - var timerResetValid = options.OpenDuration > TimeSpan.Zero; - - return immediateReopenValid && timerResetValid; - } - - // Retry Policy Validation Methods - - private static bool ValidateRetryConfiguration(AwsRetryConfiguration config) - { - // Max retries should be non-negative and reasonable - var maxRetriesValid = config.MaxRetries >= 0 && config.MaxRetries <= 20; - - // Base delay should be positive and reasonable - var baseDelayValid = config.BaseDelayMs > 0 && config.BaseDelayMs <= 10000; - - // Max delay should be greater than or equal to base delay - var maxDelayValid = config.MaxDelayMs >= config.BaseDelayMs; - - // Backoff multiplier should be >= 1.0 for exponential growth - var multiplierValid = config.BackoffMultiplier >= 1.0 && config.BackoffMultiplier <= 10.0; - - return maxRetriesValid && baseDelayValid && maxDelayValid && multiplierValid; - } - - private static bool ValidateExponentialGrowth(AwsRetryConfiguration config) - { - if (config.MaxRetries == 0) - return true; // No retries, no growth needed - - // Calculate expected delays for exponential backoff - var delays = new List(); - var currentDelay = config.BaseDelayMs; - - for (int i = 0; i < Math.Min(config.MaxRetries, 5); i++) - { - delays.Add(Math.Min(currentDelay, config.MaxDelayMs)); - currentDelay = (int)(currentDelay * config.BackoffMultiplier); - } - - // Verify delays increase (or stay at max) - for (int i = 1; i < delays.Count; i++) - { - if (delays[i] < delays[i - 1] && delays[i - 1] < config.MaxDelayMs) - return false; // Delays should not decrease unless at max - } - - return true; - } - - private static bool ValidateJitterApplication(AwsRetryConfiguration config) - { - if (!config.UseJitter) - return true; // Jitter not required - - // Jitter should add randomness to prevent thundering herd - // In practice, jitter means delays will vary slightly between retries - // For property testing, we validate that jitter is configurable - var jitterConfigurable = true; - - // Jitter should not make delays negative - var jitterBoundsValid = config.BaseDelayMs > 0; - - return jitterConfigurable && jitterBoundsValid; - } - - private static bool ValidateMaxRetryEnforcement(AwsRetryConfiguration config) - { - // System should stop retrying after max retries - var maxRetryEnforced = config.MaxRetries >= 0; - - // Zero retries should mean no retries - var zeroRetriesValid = config.MaxRetries >= 0; - - return maxRetryEnforced && zeroRetriesValid; - } - - private static bool ValidateMaxDelayEnforcement(AwsRetryConfiguration config) - { - // Delays should never exceed max delay - var maxDelayRespected = config.MaxDelayMs >= config.BaseDelayMs; - - // Max delay should be reasonable - var maxDelayReasonable = config.MaxDelayMs <= 300000; // 5 minutes max - - return maxDelayRespected && maxDelayReasonable; - } - - // Throttling Validation Methods - - private static bool ValidateThrottlingBackoff(AwsRetryConfiguration config, - AwsServiceFailureScenario scenario) - { - if (scenario.FailureType != AwsFailureType.Throttling) - return true; // Not a throttling scenario - - // Throttling should trigger retry with backoff - var backoffTriggered = config.MaxRetries > 0; - - // Backoff delay should be configured - var delayConfigured = config.BaseDelayMs > 0; - - return backoffTriggered && delayConfigured; - } - - private static bool ValidateThrottlingDelay(AwsRetryConfiguration config, - AwsServiceFailureScenario scenario) - { - if (scenario.FailureType != AwsFailureType.Throttling) - return true; // Not a throttling scenario - - // Throttling delay should be reasonable - var delayReasonable = scenario.ThrottleDelayMs >= 100 && scenario.ThrottleDelayMs <= 60000; - - // Retry delay should accommodate throttling - var retryDelayAdequate = config.BaseDelayMs >= 50; // Minimum reasonable delay - - return delayReasonable && retryDelayAdequate; - } - - private static bool ValidateRateControl(AwsRetryConfiguration config, - AwsServiceFailureScenario scenario) - { - if (scenario.FailureType != AwsFailureType.Throttling) - return true; // Not a throttling scenario - - // Exponential backoff provides rate control - var rateControlEnabled = config.BackoffMultiplier > 1.0; - - // Max delay prevents indefinite waiting - var maxDelaySet = config.MaxDelayMs > config.BaseDelayMs; - - return rateControlEnabled && maxDelaySet; - } - - private static bool ValidateThrottlingCircuitBehavior(AwsServiceFailureScenario scenario) - { - if (scenario.FailureType != AwsFailureType.Throttling) - return true; // Not a throttling scenario - - // Throttling should be treated as transient - // Circuit breaker should be more lenient with throttling - var throttlingTransient = scenario.IsTransient || scenario.FailureType == AwsFailureType.Throttling; - - return throttlingTransient; - } - - // Recovery Validation Methods - - private static bool ValidateRecoveryDetection(AwsServiceFailureScenario scenario) - { - // System should detect when service recovers - var recoveryDetectable = scenario.RecoveryAfterFailures > 0; - - // Recovery should be testable - var recoveryTestable = scenario.RecoveryAfterFailures <= scenario.FailureCount; - - return recoveryDetectable && recoveryTestable; - } - - private static bool ValidateHalfOpenTesting(CircuitBreakerOptions options) - { - // Half-open state should allow test operations - var testingAllowed = options.SuccessThreshold >= 1; - - // Testing should be controlled (limited operations) - var testingControlled = options.SuccessThreshold <= 10; - - return testingAllowed && testingControlled; - } - - private static bool ValidateCircuitClosingOnRecovery(CircuitBreakerOptions options, - AwsServiceFailureScenario scenario) - { - // Circuit should close after successful operations - var closingEnabled = options.SuccessThreshold >= 1; - - // Recovery should be achievable - var recoveryAchievable = scenario.RecoveryAfterFailures > 0; - - return closingEnabled && recoveryAchievable; - } - - private static bool ValidateGradualRecovery(CircuitBreakerOptions options, - AwsServiceFailureScenario scenario) - { - // Recovery should require multiple successful operations - var gradualRecoveryEnabled = options.SuccessThreshold >= 1; - - // Recovery should not be instantaneous (requires success threshold) - var notInstantaneous = options.SuccessThreshold > 0; - - return gradualRecoveryEnabled && notInstantaneous; - } - - private static bool ValidateNormalOperationResumption(AwsServiceFailureScenario scenario) - { - // After recovery, system should resume normal operation - var normalOperationPossible = scenario.RecoveryAfterFailures > 0; - - // Recovery should be complete (not partial) - var recoveryComplete = scenario.RecoveryAfterFailures <= scenario.FailureCount; - - return normalOperationPossible && recoveryComplete; - } -} - -/// -/// AWS retry policy configuration for property testing -/// -public class AwsRetryConfiguration -{ - public int MaxRetries { get; set; } - public int BaseDelayMs { get; set; } - public int MaxDelayMs { get; set; } - public bool UseJitter { get; set; } - public double BackoffMultiplier { get; set; } -} - -/// -/// AWS service failure scenario for property testing -/// -public class AwsServiceFailureScenario -{ - public AwsFailureType FailureType { get; set; } - public int FailureCount { get; set; } - public int RecoveryAfterFailures { get; set; } - public bool IsTransient { get; set; } - public int ThrottleDelayMs { get; set; } -} - -/// -/// Types of AWS service failures -/// -public enum AwsFailureType -{ - NetworkTimeout, - ServiceUnavailable, - Throttling, - PermissionDenied, - ResourceNotFound, - InternalError -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/Unit/AwsSnsEventDispatcherEnhancedTests.cs b/tests/SourceFlow.Cloud.AWS.Tests/Unit/AwsSnsEventDispatcherEnhancedTests.cs deleted file mode 100644 index f4f8d8e9..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/Unit/AwsSnsEventDispatcherEnhancedTests.cs +++ /dev/null @@ -1,199 +0,0 @@ -using Amazon.SimpleNotificationService; -using Amazon.SimpleNotificationService.Model; -using Microsoft.Extensions.Logging.Abstractions; -using Moq; -using SourceFlow.Cloud.AWS.Messaging.Events; -using SourceFlow.Cloud.AWS.Tests.TestHelpers; -using SourceFlow.Cloud.Configuration; -using SourceFlow.Cloud.Observability; -using SourceFlow.Cloud.Resilience; -using SourceFlow.Cloud.Security; -using SourceFlow.Observability; - -namespace SourceFlow.Cloud.AWS.Tests.Unit; - -[Trait("Category", "Unit")] -public class AwsSnsEventDispatcherEnhancedTests -{ - private readonly Mock _mockSnsClient; - private readonly Mock _mockRoutingConfig; - private readonly Mock _mockDomainTelemetry; - private readonly Mock _mockCircuitBreaker; - private readonly CloudTelemetry _cloudTelemetry; - private readonly CloudMetrics _cloudMetrics; - private readonly SensitiveDataMasker _dataMasker; - - private const string TestTopicArn = "arn:aws:sns:us-east-1:123456:test-topic"; - - public AwsSnsEventDispatcherEnhancedTests() - { - _mockSnsClient = new Mock(); - _mockRoutingConfig = new Mock(); - _mockDomainTelemetry = new Mock(); - _mockCircuitBreaker = new Mock(); - _cloudTelemetry = new CloudTelemetry(NullLogger.Instance); - _cloudMetrics = new CloudMetrics(NullLogger.Instance); - _dataMasker = new SensitiveDataMasker(); - - // Default routing setup - _mockRoutingConfig.Setup(x => x.ShouldRoute()).Returns(true); - _mockRoutingConfig.Setup(x => x.GetTopicName()).Returns(TestTopicArn); - - // Default SNS response - _mockSnsClient - .Setup(x => x.PublishAsync(It.IsAny(), It.IsAny())) - .ReturnsAsync(new PublishResponse { MessageId = Guid.NewGuid().ToString() }); - } - - [Fact] - public async Task Dispatch_CircuitBreakerOpen_ThrowsCircuitBreakerOpenException() - { - // Arrange - _mockCircuitBreaker - .Setup(x => x.ExecuteAsync(It.IsAny>>(), It.IsAny())) - .ThrowsAsync(new CircuitBreakerOpenException(CircuitState.Open, TimeSpan.FromSeconds(30))); - - var dispatcher = CreateDispatcher(); - var @event = new TestEvent(); - - // Act & Assert - await Assert.ThrowsAsync( - () => dispatcher.Dispatch(@event)); - } - - [Fact] - public async Task Dispatch_CircuitBreakerOpen_SnsClientNotCalled() - { - // Arrange - _mockCircuitBreaker - .Setup(x => x.ExecuteAsync(It.IsAny>>(), It.IsAny())) - .ThrowsAsync(new CircuitBreakerOpenException(CircuitState.Open, TimeSpan.FromSeconds(30))); - - var dispatcher = CreateDispatcher(); - var @event = new TestEvent(); - - // Act - try { await dispatcher.Dispatch(@event); } catch (CircuitBreakerOpenException) { } - - // Assert - _mockSnsClient.Verify( - x => x.PublishAsync(It.IsAny(), It.IsAny()), - Times.Never); - } - - [Fact] - public async Task Dispatch_CircuitBreakerClosed_EventPublishedToSns() - { - // Arrange - SetupCircuitBreakerClosed(); - - var dispatcher = CreateDispatcher(); - var @event = new TestEvent(); - - // Act - await dispatcher.Dispatch(@event); - - // Assert - _mockSnsClient.Verify( - x => x.PublishAsync( - It.Is(r => r.TopicArn == TestTopicArn), - It.IsAny()), - Times.Once); - } - - [Fact] - public async Task Dispatch_EncryptionEnabled_EncryptAsyncCalledBeforePublish() - { - // Arrange - SetupCircuitBreakerClosed(); - - var mockEncryption = new Mock(); - mockEncryption.Setup(x => x.AlgorithmName).Returns("TEST-AES"); - mockEncryption - .Setup(x => x.EncryptAsync(It.IsAny(), It.IsAny())) - .ReturnsAsync("ENCRYPTED_PAYLOAD"); - - var dispatcher = CreateDispatcher(encryption: mockEncryption.Object); - var @event = new TestEvent(); - - // Act - await dispatcher.Dispatch(@event); - - // Assert: EncryptAsync was called - mockEncryption.Verify( - x => x.EncryptAsync(It.IsAny(), It.IsAny()), - Times.Once); - - // Assert: SNS was called with the encrypted message body - _mockSnsClient.Verify( - x => x.PublishAsync( - It.Is(r => r.Message == "ENCRYPTED_PAYLOAD"), - It.IsAny()), - Times.Once); - } - - [Fact] - public async Task Dispatch_EncryptionDisabled_PublishCalledWithPlaintextBody() - { - // Arrange - SetupCircuitBreakerClosed(); - - var dispatcher = CreateDispatcher(encryption: null); - var @event = new TestEvent(); - - // Act - await dispatcher.Dispatch(@event); - - // Assert: SNS was called with a non-empty, non-encrypted message body - _mockSnsClient.Verify( - x => x.PublishAsync( - It.Is(r => - r.TopicArn == TestTopicArn && - !string.IsNullOrEmpty(r.Message) && - r.Message != "ENCRYPTED_PAYLOAD"), - It.IsAny()), - Times.Once); - } - - [Fact] - public async Task Dispatch_ShouldRoute_ReturnsFalse_SnsClientNotCalled() - { - // Arrange - _mockRoutingConfig.Setup(x => x.ShouldRoute()).Returns(false); - SetupCircuitBreakerClosed(); - - var dispatcher = CreateDispatcher(); - var @event = new TestEvent(); - - // Act - await dispatcher.Dispatch(@event); - - // Assert - _mockSnsClient.Verify( - x => x.PublishAsync(It.IsAny(), It.IsAny()), - Times.Never); - } - - // ── Helpers ────────────────────────────────────────────────────────────── - - private void SetupCircuitBreakerClosed() - { - _mockCircuitBreaker - .Setup(x => x.ExecuteAsync(It.IsAny>>(), It.IsAny())) - .Returns>, CancellationToken>(async (op, ct) => { await op(); return true; }); - } - - private AwsSnsEventDispatcherEnhanced CreateDispatcher(IMessageEncryption? encryption = null) - { - return new AwsSnsEventDispatcherEnhanced( - _mockSnsClient.Object, - _mockRoutingConfig.Object, - NullLogger.Instance, - _mockDomainTelemetry.Object, - _cloudTelemetry, - _cloudMetrics, - _mockCircuitBreaker.Object, - _dataMasker, - encryption); - } -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/Unit/AwsSnsEventDispatcherTests.cs b/tests/SourceFlow.Cloud.AWS.Tests/Unit/AwsSnsEventDispatcherTests.cs deleted file mode 100644 index 0be84c06..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/Unit/AwsSnsEventDispatcherTests.cs +++ /dev/null @@ -1,114 +0,0 @@ -using Amazon.SimpleNotificationService; -using Amazon.SimpleNotificationService.Model; -using Microsoft.Extensions.Logging; -using Moq; -using SourceFlow.Cloud.AWS.Messaging.Events; -using SourceFlow.Cloud.AWS.Observability; -using SourceFlow.Cloud.AWS.Tests.TestHelpers; -using SourceFlow.Cloud.Configuration; -using SourceFlow.Observability; - -namespace SourceFlow.Cloud.AWS.Tests.Unit; - -[Trait("Category", "Unit")] -public class AwsSnsEventDispatcherTests -{ - private readonly Mock _mockSnsClient; - private readonly Mock _mockRoutingConfig; - private readonly Mock> _mockLogger; - private readonly Mock _mockTelemetry; - private readonly AwsSnsEventDispatcher _dispatcher; - - public AwsSnsEventDispatcherTests() - { - _mockSnsClient = new Mock(); - _mockRoutingConfig = new Mock(); - _mockLogger = new Mock>(); - _mockTelemetry = new Mock(); - - _dispatcher = new AwsSnsEventDispatcher( - _mockSnsClient.Object, - _mockRoutingConfig.Object, - _mockLogger.Object, - _mockTelemetry.Object); - } - - [Fact] - public async Task Dispatch_WhenRouteToAwsIsFalse_ShouldNotPublishMessage() - { - // Arrange - var @event = new TestEvent(); - _mockRoutingConfig.Setup(x => x.ShouldRoute()).Returns(false); - - // Act - await _dispatcher.Dispatch(@event); - - // Assert - _mockSnsClient.Verify(x => x.PublishAsync(It.IsAny(), default), Times.Never); - } - - [Fact] - public async Task Dispatch_WhenRouteToAwsIsTrue_ShouldPublishMessageWithCorrectAttributes() - { - // Arrange - var @event = new TestEvent(); - var topicArn = "arn:aws:sns:us-east-1:123456:test-topic"; - - _mockRoutingConfig.Setup(x => x.ShouldRoute()).Returns(true); - _mockRoutingConfig.Setup(x => x.GetTopicName()).Returns(topicArn); - - _mockSnsClient.Setup(x => x.PublishAsync(It.IsAny(), default)) - .ReturnsAsync(new PublishResponse { MessageId = "msg-123" }); - - // Act - await _dispatcher.Dispatch(@event); - - // Assert - _mockSnsClient.Verify(x => x.PublishAsync( - It.Is(r => - r.TopicArn == topicArn && - r.MessageAttributes.ContainsKey("EventType") && - r.MessageAttributes.ContainsKey("EventName") && - r.Subject == @event.Name), - default), Times.Once); - } - - [Fact] - public async Task Dispatch_WhenSuccessful_ShouldCallSnsClient() - { - // Arrange - var @event = new TestEvent(); - var topicArn = "arn:aws:sns:us-east-1:123456:test-topic"; - - _mockRoutingConfig.Setup(x => x.ShouldRoute()).Returns(true); - _mockRoutingConfig.Setup(x => x.GetTopicName()).Returns(topicArn); - - _mockSnsClient.Setup(x => x.PublishAsync(It.IsAny(), default)) - .ReturnsAsync(new PublishResponse { MessageId = "msg-123" }); - - // Act - await _dispatcher.Dispatch(@event); - - // Assert - verify message was published - _mockSnsClient.Verify(x => x.PublishAsync( - It.Is(r => r.TopicArn == topicArn), - default), Times.Once); - } - - [Fact] - public async Task Dispatch_WhenSnsClientThrowsException_ShouldPropagate() - { - // Arrange - var @event = new TestEvent(); - var topicArn = "arn:aws:sns:us-east-1:123456:test-topic"; - - _mockRoutingConfig.Setup(x => x.ShouldRoute()).Returns(true); - _mockRoutingConfig.Setup(x => x.GetTopicName()).Returns(topicArn); - - _mockSnsClient.Setup(x => x.PublishAsync(It.IsAny(), default)) - .ThrowsAsync(new Exception("SNS error")); - - // Act & Assert - await Assert.ThrowsAsync(async () => await _dispatcher.Dispatch(@event)); - } -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/Unit/AwsSnsEventListenerEnhancedTests.cs b/tests/SourceFlow.Cloud.AWS.Tests/Unit/AwsSnsEventListenerEnhancedTests.cs deleted file mode 100644 index cd430f00..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/Unit/AwsSnsEventListenerEnhancedTests.cs +++ /dev/null @@ -1,252 +0,0 @@ -using Amazon.SQS; -using Amazon.SQS.Model; -using Microsoft.Extensions.DependencyInjection; -using Microsoft.Extensions.Logging.Abstractions; -using Moq; -using SourceFlow.Cloud.AWS.Configuration; -using SourceFlow.Cloud.AWS.Messaging.Events; -using SourceFlow.Cloud.AWS.Tests.TestHelpers; -using SourceFlow.Cloud.Configuration; -using SourceFlow.Cloud.DeadLetter; -using SourceFlow.Cloud.Observability; -using SourceFlow.Cloud.Security; -using SourceFlow.Messaging.Events; -using SourceFlow.Observability; -using System.Text.Json; - -namespace SourceFlow.Cloud.AWS.Tests.Unit; - -[Trait("Category", "Unit")] -public class AwsSnsEventListenerEnhancedTests -{ - private static readonly string TestQueueUrl = "https://sqs.us-east-1.amazonaws.com/123456/events-queue"; - - private readonly Mock _mockSqs; - private readonly Mock _mockRouting; - private readonly Mock _mockServiceProvider; - private readonly Mock _mockScopeFactory; - private readonly Mock _mockScope; - private readonly Mock _mockScopedProvider; - private readonly Mock _mockSubscriber; - private readonly Mock _mockDomainTelemetry; - private readonly Mock _mockIdempotency; - private readonly Mock _mockDeadLetterStore; - private readonly CloudTelemetry _cloudTelemetry; - private readonly CloudMetrics _cloudMetrics; - private readonly SensitiveDataMasker _dataMasker; - private readonly AwsOptions _options; - - public AwsSnsEventListenerEnhancedTests() - { - _mockSqs = new Mock(); - _mockRouting = new Mock(); - _mockServiceProvider = new Mock(); - _mockScopeFactory = new Mock(); - _mockScope = new Mock(); - _mockScopedProvider = new Mock(); - _mockSubscriber = new Mock(); - _mockDomainTelemetry = new Mock(); - _mockIdempotency = new Mock(); - _mockDeadLetterStore = new Mock(); - _cloudTelemetry = new CloudTelemetry(NullLogger.Instance); - _cloudMetrics = new CloudMetrics(NullLogger.Instance); - _dataMasker = new SensitiveDataMasker(); - _options = new AwsOptions { SqsMaxNumberOfMessages = 10, SqsReceiveWaitTimeSeconds = 0, SqsVisibilityTimeoutSeconds = 30 }; - - _mockServiceProvider - .Setup(x => x.GetService(typeof(IServiceScopeFactory))) - .Returns(_mockScopeFactory.Object); - _mockScopeFactory.Setup(x => x.CreateScope()).Returns(_mockScope.Object); - _mockScope.Setup(x => x.ServiceProvider).Returns(_mockScopedProvider.Object); - _mockScopedProvider - .Setup(x => x.GetService(typeof(IEnumerable))) - .Returns(new[] { _mockSubscriber.Object }); - - _mockSubscriber - .Setup(x => x.Subscribe(It.IsAny())) - .Returns(Task.CompletedTask); - - _mockDeadLetterStore - .Setup(x => x.SaveAsync(It.IsAny())) - .Returns(Task.CompletedTask); - } - - [Fact] - public async Task ExecuteAsync_NoQueuesConfigured_ReceiveMessageNeverCalled() - { - _mockRouting.Setup(x => x.GetListeningQueues()).Returns(Enumerable.Empty()); - - var listener = CreateListener(); - await listener.StartAsync(CancellationToken.None); - await listener.StopAsync(CancellationToken.None); - - _mockSqs.Verify( - x => x.ReceiveMessageAsync(It.IsAny(), It.IsAny()), - Times.Never); - } - - [Fact] - public async Task ProcessMessage_DuplicateEvent_SubscriberNotCalledMessageDeleted() - { - // Arrange — idempotency: already processed - _mockRouting.Setup(x => x.GetListeningQueues()).Returns(new[] { TestQueueUrl }); - _mockIdempotency - .Setup(x => x.HasProcessedAsync(It.IsAny(), It.IsAny())) - .ReturnsAsync(true); - - var message = BuildValidSnsMessage("msg-dup"); - var deleted = new SemaphoreSlim(0, 1); - - SetupReceiveOnceAndBlock(message); - _mockSqs - .Setup(x => x.DeleteMessageAsync(It.IsAny(), It.IsAny())) - .Callback(() => deleted.Release()) - .ReturnsAsync(new DeleteMessageResponse()); - - var listener = CreateListener(); - await listener.StartAsync(CancellationToken.None); - var messageDeleted = await deleted.WaitAsync(TimeSpan.FromSeconds(5)); - await listener.StopAsync(CancellationToken.None); - - Assert.True(messageDeleted, "Duplicate event message should be deleted"); - _mockSubscriber.Verify(x => x.Subscribe(It.IsAny()), Times.Never); - _mockIdempotency.Verify( - x => x.MarkAsProcessedAsync(It.IsAny(), It.IsAny(), It.IsAny()), - Times.Never); - } - - [Fact] - public async Task ProcessMessage_ValidEvent_SubscriberCalledAndMarkedProcessed() - { - // Arrange - _mockRouting.Setup(x => x.GetListeningQueues()).Returns(new[] { TestQueueUrl }); - _mockIdempotency - .Setup(x => x.HasProcessedAsync(It.IsAny(), It.IsAny())) - .ReturnsAsync(false); - _mockIdempotency - .Setup(x => x.MarkAsProcessedAsync(It.IsAny(), It.IsAny(), It.IsAny())) - .Returns(Task.CompletedTask); - - var message = BuildValidSnsMessage("msg-valid"); - var deleted = new SemaphoreSlim(0, 1); - - SetupReceiveOnceAndBlock(message); - _mockSqs - .Setup(x => x.DeleteMessageAsync(It.IsAny(), It.IsAny())) - .Callback(() => deleted.Release()) - .ReturnsAsync(new DeleteMessageResponse()); - - var listener = CreateListener(); - await listener.StartAsync(CancellationToken.None); - var processed = await deleted.WaitAsync(TimeSpan.FromSeconds(5)); - await listener.StopAsync(CancellationToken.None); - - Assert.True(processed, "Message should be deleted after successful event processing"); - _mockSubscriber.Verify(x => x.Subscribe(It.IsAny()), Times.Once); - _mockIdempotency.Verify( - x => x.MarkAsProcessedAsync( - It.Is(k => k.Contains(typeof(TestEvent).FullName!)), - TimeSpan.FromHours(24), - It.IsAny()), - Times.Once); - } - - [Fact] - public async Task ProcessMessage_EncryptionEnabled_DecryptCalledBeforeDeserialization() - { - // Arrange - _mockRouting.Setup(x => x.GetListeningQueues()).Returns(new[] { TestQueueUrl }); - _mockIdempotency - .Setup(x => x.HasProcessedAsync(It.IsAny(), It.IsAny())) - .ReturnsAsync(false); - _mockIdempotency - .Setup(x => x.MarkAsProcessedAsync(It.IsAny(), It.IsAny(), It.IsAny())) - .Returns(Task.CompletedTask); - - var mockEncryption = new Mock(); - mockEncryption.Setup(x => x.AlgorithmName).Returns("TEST"); - mockEncryption - .Setup(x => x.DecryptAsync(It.IsAny(), It.IsAny())) - .Returns((s, _) => Task.FromResult(s)); // identity decryption - - var message = BuildValidSnsMessage("msg-enc"); - var deleted = new SemaphoreSlim(0, 1); - - SetupReceiveOnceAndBlock(message); - _mockSqs - .Setup(x => x.DeleteMessageAsync(It.IsAny(), It.IsAny())) - .Callback(() => deleted.Release()) - .ReturnsAsync(new DeleteMessageResponse()); - - var listener = CreateListener(encryption: mockEncryption.Object); - await listener.StartAsync(CancellationToken.None); - await deleted.WaitAsync(TimeSpan.FromSeconds(5)); - await listener.StopAsync(CancellationToken.None); - - mockEncryption.Verify(x => x.DecryptAsync(It.IsAny()), Times.Once); - } - - // ── Helpers ────────────────────────────────────────────────────────────── - - private static Message BuildValidSnsMessage(string messageId) - { - var @event = new TestEvent(); - var eventJson = JsonSerializer.Serialize(@event, new JsonSerializerOptions - { - PropertyNamingPolicy = JsonNamingPolicy.CamelCase - }); - - var snsBody = JsonSerializer.Serialize(new - { - type = "Notification", - messageId = "sns-" + messageId, - topicArn = "arn:aws:sns:us-east-1:123456:test-topic", - subject = "", - message = eventJson, - messageAttributes = new Dictionary - { - ["EventType"] = new { type = "String", value = typeof(TestEvent).AssemblyQualifiedName } - } - }); - - return new Message - { - MessageId = messageId, - ReceiptHandle = "rh-" + messageId, - Body = snsBody, - MessageAttributes = new Dictionary(), - Attributes = new Dictionary - { - ["ApproximateReceiveCount"] = "1" - } - }; - } - - private void SetupReceiveOnceAndBlock(Message message) - { - int callCount = 0; - _mockSqs - .Setup(x => x.ReceiveMessageAsync(It.IsAny(), It.IsAny())) - .Returns((_, ct) => - ++callCount == 1 - ? Task.FromResult(new ReceiveMessageResponse { Messages = new List { message } }) - : Task.Delay(Timeout.Infinite, ct).ContinueWith( - _ => new ReceiveMessageResponse(), - TaskContinuationOptions.OnlyOnCanceled)); - } - - private AwsSnsEventListenerEnhanced CreateListener(IMessageEncryption? encryption = null) => - new AwsSnsEventListenerEnhanced( - _mockSqs.Object, - _mockServiceProvider.Object, - _mockRouting.Object, - NullLogger.Instance, - _mockDomainTelemetry.Object, - _cloudTelemetry, - _cloudMetrics, - _mockIdempotency.Object, - _mockDeadLetterStore.Object, - _dataMasker, - _options, - encryption); -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/Unit/AwsSnsEventListenerTests.cs b/tests/SourceFlow.Cloud.AWS.Tests/Unit/AwsSnsEventListenerTests.cs deleted file mode 100644 index 8abc8bf7..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/Unit/AwsSnsEventListenerTests.cs +++ /dev/null @@ -1,211 +0,0 @@ -using Amazon.SQS; -using Amazon.SQS.Model; -using Microsoft.Extensions.DependencyInjection; -using Microsoft.Extensions.Logging.Abstractions; -using Moq; -using SourceFlow.Cloud.AWS.Configuration; -using SourceFlow.Cloud.AWS.Messaging.Events; -using SourceFlow.Cloud.AWS.Tests.TestHelpers; -using SourceFlow.Cloud.Configuration; -using SourceFlow.Messaging.Events; -using System.Text.Json; - -namespace SourceFlow.Cloud.AWS.Tests.Unit; - -[Trait("Category", "Unit")] -public class AwsSnsEventListenerTests -{ - private static readonly string TestQueueUrl = "https://sqs.us-east-1.amazonaws.com/123456/events-queue"; - - private readonly Mock _mockSqs; - private readonly Mock _mockRouting; - private readonly Mock _mockServiceProvider; - private readonly Mock _mockScopeFactory; - private readonly Mock _mockScope; - private readonly Mock _mockScopedProvider; - private readonly Mock _mockSubscriber; - private readonly AwsOptions _options; - - public AwsSnsEventListenerTests() - { - _mockSqs = new Mock(); - _mockRouting = new Mock(); - _mockServiceProvider = new Mock(); - _mockScopeFactory = new Mock(); - _mockScope = new Mock(); - _mockScopedProvider = new Mock(); - _mockSubscriber = new Mock(); - _options = new AwsOptions { SqsMaxNumberOfMessages = 10, SqsReceiveWaitTimeSeconds = 0, SqsVisibilityTimeoutSeconds = 30 }; - - _mockServiceProvider - .Setup(x => x.GetService(typeof(IServiceScopeFactory))) - .Returns(_mockScopeFactory.Object); - _mockScopeFactory.Setup(x => x.CreateScope()).Returns(_mockScope.Object); - _mockScope.Setup(x => x.ServiceProvider).Returns(_mockScopedProvider.Object); - - // GetServices() resolves IEnumerable - _mockScopedProvider - .Setup(x => x.GetService(typeof(IEnumerable))) - .Returns(new[] { _mockSubscriber.Object }); - - _mockSubscriber - .Setup(x => x.Subscribe(It.IsAny())) - .Returns(Task.CompletedTask); - } - - [Fact] - public async Task ExecuteAsync_NoQueuesConfigured_ReceiveMessageNeverCalled() - { - _mockRouting.Setup(x => x.GetListeningQueues()).Returns(Enumerable.Empty()); - - var listener = CreateListener(); - await listener.StartAsync(CancellationToken.None); - await listener.StopAsync(CancellationToken.None); - - _mockSqs.Verify( - x => x.ReceiveMessageAsync(It.IsAny(), It.IsAny()), - Times.Never); - } - - [Fact] - public async Task ProcessMessage_ValidSnsNotification_CallsSubscriberAndDeletesMessage() - { - // Arrange - _mockRouting.Setup(x => x.GetListeningQueues()).Returns(new[] { TestQueueUrl }); - - var message = BuildValidSnsMessage("msg-valid"); - var deleted = new SemaphoreSlim(0, 1); - - SetupReceiveOnceAndBlock(message); - _mockSqs - .Setup(x => x.DeleteMessageAsync(It.IsAny(), It.IsAny())) - .Callback(() => deleted.Release()) - .ReturnsAsync(new DeleteMessageResponse()); - - var listener = CreateListener(); - await listener.StartAsync(CancellationToken.None); - var processed = await deleted.WaitAsync(TimeSpan.FromSeconds(5)); - await listener.StopAsync(CancellationToken.None); - - Assert.True(processed, "Message should be deleted after successful event processing"); - _mockSubscriber.Verify(x => x.Subscribe(It.IsAny()), Times.Once); - } - - [Fact] - public async Task ProcessMessage_MalformedJson_DeletesMalformedMessageToPreventRetries() - { - // Arrange - _mockRouting.Setup(x => x.GetListeningQueues()).Returns(new[] { TestQueueUrl }); - - var message = new Message - { - MessageId = "msg-bad-json", - ReceiptHandle = "rh-bad-json", - Body = "not-json{{{", - MessageAttributes = new Dictionary() - }; - - var deleted = new SemaphoreSlim(0, 1); - SetupReceiveOnceAndBlock(message); - _mockSqs - .Setup(x => x.DeleteMessageAsync(It.IsAny(), It.IsAny())) - .Callback(() => deleted.Release()) - .ReturnsAsync(new DeleteMessageResponse()); - - var listener = CreateListener(); - await listener.StartAsync(CancellationToken.None); - var cleaned = await deleted.WaitAsync(TimeSpan.FromSeconds(5)); - await listener.StopAsync(CancellationToken.None); - - Assert.True(cleaned, "Malformed SNS notification should be deleted to prevent infinite retries"); - _mockSubscriber.Verify(x => x.Subscribe(It.IsAny()), Times.Never); - } - - [Fact] - public async Task ProcessMessage_MissingEventTypeAttribute_SubscriberNotCalled() - { - // Arrange - _mockRouting.Setup(x => x.GetListeningQueues()).Returns(new[] { TestQueueUrl }); - - // SNS notification with no EventType attribute - var snsBody = JsonSerializer.Serialize(new - { - Type = "Notification", - MessageId = "sns-msg-id", - TopicArn = "arn:aws:sns:us-east-1:123456:test-topic", - Message = "{}", - MessageAttributes = new Dictionary() // empty — no EventType - }, new JsonSerializerOptions { PropertyNamingPolicy = JsonNamingPolicy.CamelCase }); - - var message = new Message - { - MessageId = "msg-no-event-type", - ReceiptHandle = "rh-no-event-type", - Body = snsBody, - MessageAttributes = new Dictionary() - }; - - SetupReceiveOnceAndBlock(message); - - var listener = CreateListener(); - await listener.StartAsync(CancellationToken.None); - await Task.Delay(500); // give time to process - await listener.StopAsync(CancellationToken.None); - - _mockSubscriber.Verify(x => x.Subscribe(It.IsAny()), Times.Never); - } - - // ── Helpers ────────────────────────────────────────────────────────────── - - private static Message BuildValidSnsMessage(string messageId) - { - var @event = new TestEvent(); - var eventJson = JsonSerializer.Serialize(@event, new JsonSerializerOptions - { - PropertyNamingPolicy = JsonNamingPolicy.CamelCase - }); - - // SNS notification envelope (camelCase matches JsonNamingPolicy.CamelCase in listener) - var snsBody = JsonSerializer.Serialize(new - { - type = "Notification", - messageId = "sns-" + messageId, - topicArn = "arn:aws:sns:us-east-1:123456:test-topic", - subject = "", - message = eventJson, - messageAttributes = new Dictionary - { - ["EventType"] = new { type = "String", value = typeof(TestEvent).AssemblyQualifiedName } - } - }); - - return new Message - { - MessageId = messageId, - ReceiptHandle = "rh-" + messageId, - Body = snsBody, - MessageAttributes = new Dictionary() - }; - } - - private void SetupReceiveOnceAndBlock(Message message) - { - int callCount = 0; - _mockSqs - .Setup(x => x.ReceiveMessageAsync(It.IsAny(), It.IsAny())) - .Returns((_, ct) => - ++callCount == 1 - ? Task.FromResult(new ReceiveMessageResponse { Messages = new List { message } }) - : Task.Delay(Timeout.Infinite, ct).ContinueWith( - _ => new ReceiveMessageResponse(), - TaskContinuationOptions.OnlyOnCanceled)); - } - - private AwsSnsEventListener CreateListener() => - new AwsSnsEventListener( - _mockSqs.Object, - _mockServiceProvider.Object, - _mockRouting.Object, - NullLogger.Instance, - _options); -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/Unit/AwsSqsCommandDispatcherEnhancedTests.cs b/tests/SourceFlow.Cloud.AWS.Tests/Unit/AwsSqsCommandDispatcherEnhancedTests.cs deleted file mode 100644 index 82a11c99..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/Unit/AwsSqsCommandDispatcherEnhancedTests.cs +++ /dev/null @@ -1,251 +0,0 @@ -using Amazon.SQS; -using Amazon.SQS.Model; -using Microsoft.Extensions.Logging.Abstractions; -using Moq; -using SourceFlow.Cloud.AWS.Messaging.Commands; -using SourceFlow.Cloud.AWS.Observability; -using SourceFlow.Cloud.AWS.Tests.TestHelpers; -using SourceFlow.Cloud.Configuration; -using SourceFlow.Cloud.Observability; -using SourceFlow.Cloud.Resilience; -using SourceFlow.Cloud.Security; -using SourceFlow.Observability; - -namespace SourceFlow.Cloud.AWS.Tests.Unit; - -[Trait("Category", "Unit")] -public class AwsSqsCommandDispatcherEnhancedTests -{ - private readonly Mock _mockSqsClient; - private readonly Mock _mockRoutingConfig; - private readonly Mock _mockDomainTelemetry; - private readonly Mock _mockCircuitBreaker; - private readonly CloudTelemetry _cloudTelemetry; - private readonly CloudMetrics _cloudMetrics; - private readonly SensitiveDataMasker _dataMasker; - - private const string TestQueueUrl = "https://sqs.us-east-1.amazonaws.com/123456/test-queue"; - - public AwsSqsCommandDispatcherEnhancedTests() - { - _mockSqsClient = new Mock(); - _mockRoutingConfig = new Mock(); - _mockDomainTelemetry = new Mock(); - _mockCircuitBreaker = new Mock(); - _cloudTelemetry = new CloudTelemetry(NullLogger.Instance); - _cloudMetrics = new CloudMetrics(NullLogger.Instance); - _dataMasker = new SensitiveDataMasker(); - - // Default routing setup - _mockRoutingConfig.Setup(x => x.ShouldRoute()).Returns(true); - _mockRoutingConfig.Setup(x => x.GetQueueName()).Returns(TestQueueUrl); - - // Default SQS response - _mockSqsClient - .Setup(x => x.SendMessageAsync(It.IsAny(), It.IsAny())) - .ReturnsAsync(new SendMessageResponse { MessageId = Guid.NewGuid().ToString() }); - } - - [Fact] - public async Task Dispatch_CircuitBreakerOpen_ThrowsCircuitBreakerOpenException() - { - // Arrange - _mockCircuitBreaker - .Setup(x => x.ExecuteAsync(It.IsAny>>(), It.IsAny())) - .ThrowsAsync(new CircuitBreakerOpenException(CircuitState.Open, TimeSpan.FromSeconds(30))); - - var dispatcher = CreateDispatcher(); - var command = new TestCommand(); - - // Act & Assert - await Assert.ThrowsAsync( - () => dispatcher.Dispatch(command)); - } - - [Fact] - public async Task Dispatch_CircuitBreakerOpen_SqsClientNotCalled() - { - // Arrange - _mockCircuitBreaker - .Setup(x => x.ExecuteAsync(It.IsAny>>(), It.IsAny())) - .ThrowsAsync(new CircuitBreakerOpenException(CircuitState.Open, TimeSpan.FromSeconds(30))); - - var dispatcher = CreateDispatcher(); - var command = new TestCommand(); - - // Act - try { await dispatcher.Dispatch(command); } catch (CircuitBreakerOpenException) { } - - // Assert - _mockSqsClient.Verify( - x => x.SendMessageAsync(It.IsAny(), It.IsAny()), - Times.Never); - } - - [Fact] - public async Task Dispatch_CircuitBreakerClosed_MessageDispatchedToSqs() - { - // Arrange - SetupCircuitBreakerClosed(); - - var dispatcher = CreateDispatcher(); - var command = new TestCommand(); - - // Act - await dispatcher.Dispatch(command); - - // Assert - _mockSqsClient.Verify( - x => x.SendMessageAsync( - It.Is(r => r.QueueUrl == TestQueueUrl), - It.IsAny()), - Times.Once); - } - - [Fact] - public async Task Dispatch_EncryptionEnabled_EncryptAsyncCalledBeforeSend() - { - // Arrange - SetupCircuitBreakerClosed(); - - var mockEncryption = new Mock(); - mockEncryption.Setup(x => x.AlgorithmName).Returns("TEST-AES"); - mockEncryption - .Setup(x => x.EncryptAsync(It.IsAny(), It.IsAny())) - .ReturnsAsync("ENCRYPTED_PAYLOAD"); - - var dispatcher = CreateDispatcher(encryption: mockEncryption.Object); - var command = new TestCommand(); - - // Act - await dispatcher.Dispatch(command); - - // Assert: EncryptAsync was called - mockEncryption.Verify( - x => x.EncryptAsync(It.IsAny(), It.IsAny()), - Times.Once); - - // Assert: SQS was called with the encrypted body - _mockSqsClient.Verify( - x => x.SendMessageAsync( - It.Is(r => r.MessageBody == "ENCRYPTED_PAYLOAD"), - It.IsAny()), - Times.Once); - } - - [Fact] - public async Task Dispatch_EncryptionDisabled_SendCalledWithPlaintextBody() - { - // Arrange - SetupCircuitBreakerClosed(); - - var dispatcher = CreateDispatcher(encryption: null); - var command = new TestCommand(); - - // Act - await dispatcher.Dispatch(command); - - // Assert: SQS was called (no encryption, body is plain JSON) - _mockSqsClient.Verify( - x => x.SendMessageAsync( - It.Is(r => - r.QueueUrl == TestQueueUrl && - !string.IsNullOrEmpty(r.MessageBody) && - r.MessageBody != "ENCRYPTED_PAYLOAD"), - It.IsAny()), - Times.Once); - } - - [Fact] - public async Task Dispatch_EncryptionDisabled_EncryptAsyncNeverCalled() - { - // Arrange - SetupCircuitBreakerClosed(); - - var mockEncryption = new Mock(); - - // Create dispatcher without encryption (null) - var dispatcher = CreateDispatcher(encryption: null); - var command = new TestCommand(); - - // Act - await dispatcher.Dispatch(command); - - // Assert: EncryptAsync was never called since encryption is disabled - mockEncryption.Verify( - x => x.EncryptAsync(It.IsAny(), It.IsAny()), - Times.Never); - } - - [Fact] - public async Task Dispatch_ShouldRoute_ReturnsFalse_SqsClientNotCalled() - { - // Arrange - _mockRoutingConfig.Setup(x => x.ShouldRoute()).Returns(false); - SetupCircuitBreakerClosed(); - - var dispatcher = CreateDispatcher(); - var command = new TestCommand(); - - // Act - await dispatcher.Dispatch(command); - - // Assert - _mockSqsClient.Verify( - x => x.SendMessageAsync(It.IsAny(), It.IsAny()), - Times.Never); - } - - [Fact] - public async Task Dispatch_SensitiveDataMasker_UsedForLoggingNotForMessageBody() - { - // Arrange - SetupCircuitBreakerClosed(); - - var mockEncryption = new Mock(); - mockEncryption.Setup(x => x.AlgorithmName).Returns("TEST-AES"); - mockEncryption - .Setup(x => x.EncryptAsync(It.IsAny(), It.IsAny())) - .ReturnsAsync((string input, CancellationToken _) => input); // pass-through - - var dispatcher = CreateDispatcher(encryption: mockEncryption.Object); - var command = new TestCommand(); - - // Act - await dispatcher.Dispatch(command); - - // Assert: The message body sent to SQS should be the serialized JSON (potentially encrypted), - // not the output of SensitiveDataMasker (which truncates/hides data). - // We verify the sent body contains recognisable JSON structure rather than masked text. - _mockSqsClient.Verify( - x => x.SendMessageAsync( - It.Is(r => - r.MessageBody != null && - !r.MessageBody.Contains("***")), // masker output would contain asterisks - It.IsAny()), - Times.Once); - } - - // ── Helpers ────────────────────────────────────────────────────────────── - - private void SetupCircuitBreakerClosed() - { - _mockCircuitBreaker - .Setup(x => x.ExecuteAsync(It.IsAny>>(), It.IsAny())) - .Returns>, CancellationToken>(async (op, ct) => { await op(); return true; }); - } - - private AwsSqsCommandDispatcherEnhanced CreateDispatcher(IMessageEncryption? encryption = null) - { - return new AwsSqsCommandDispatcherEnhanced( - _mockSqsClient.Object, - _mockRoutingConfig.Object, - NullLogger.Instance, - _mockDomainTelemetry.Object, - _cloudTelemetry, - _cloudMetrics, - _mockCircuitBreaker.Object, - _dataMasker, - encryption); - } -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/Unit/AwsSqsCommandDispatcherTests.cs b/tests/SourceFlow.Cloud.AWS.Tests/Unit/AwsSqsCommandDispatcherTests.cs deleted file mode 100644 index 0c5556fa..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/Unit/AwsSqsCommandDispatcherTests.cs +++ /dev/null @@ -1,115 +0,0 @@ -using Amazon.SQS; -using Amazon.SQS.Model; -using Microsoft.Extensions.Logging; -using Moq; -using SourceFlow.Cloud.AWS.Messaging.Commands; -using SourceFlow.Cloud.AWS.Observability; -using SourceFlow.Cloud.AWS.Tests.TestHelpers; -using SourceFlow.Cloud.Configuration; -using SourceFlow.Observability; - -namespace SourceFlow.Cloud.AWS.Tests.Unit; - -[Trait("Category", "Unit")] -public class AwsSqsCommandDispatcherTests -{ - private readonly Mock _mockSqsClient; - private readonly Mock _mockRoutingConfig; - private readonly Mock> _mockLogger; - private readonly Mock _mockTelemetry; - private readonly AwsSqsCommandDispatcher _dispatcher; - - public AwsSqsCommandDispatcherTests() - { - _mockSqsClient = new Mock(); - _mockRoutingConfig = new Mock(); - _mockLogger = new Mock>(); - _mockTelemetry = new Mock(); - - _dispatcher = new AwsSqsCommandDispatcher( - _mockSqsClient.Object, - _mockRoutingConfig.Object, - _mockLogger.Object, - _mockTelemetry.Object); - } - - [Fact] - public async Task Dispatch_WhenRouteToAwsIsFalse_ShouldNotSendMessage() - { - // Arrange - var command = new TestCommand(); - _mockRoutingConfig.Setup(x => x.ShouldRoute()).Returns(false); - - // Act - await _dispatcher.Dispatch(command); - - // Assert - _mockSqsClient.Verify(x => x.SendMessageAsync(It.IsAny(), default), Times.Never); - } - - [Fact] - public async Task Dispatch_WhenRouteToAwsIsTrue_ShouldSendMessageWithCorrectAttributes() - { - // Arrange - var command = new TestCommand(); - var queueUrl = "https://sqs.us-east-1.amazonaws.com/123456/test-queue"; - - _mockRoutingConfig.Setup(x => x.ShouldRoute()).Returns(true); - _mockRoutingConfig.Setup(x => x.GetQueueName()).Returns(queueUrl); - - _mockSqsClient.Setup(x => x.SendMessageAsync(It.IsAny(), default)) - .ReturnsAsync(new SendMessageResponse()); - - // Act - await _dispatcher.Dispatch(command); - - // Assert - _mockSqsClient.Verify(x => x.SendMessageAsync( - It.Is(r => - r.QueueUrl == queueUrl && - r.MessageAttributes.ContainsKey("CommandType") && - r.MessageAttributes.ContainsKey("EntityId") && - r.MessageAttributes.ContainsKey("SequenceNo") && - r.MessageGroupId != null), - default), Times.Once); - } - - [Fact] - public async Task Dispatch_WhenSuccessful_ShouldCallSqsClient() - { - // Arrange - var command = new TestCommand(); - var queueUrl = "https://sqs.us-east-1.amazonaws.com/123456/test-queue"; - - _mockRoutingConfig.Setup(x => x.ShouldRoute()).Returns(true); - _mockRoutingConfig.Setup(x => x.GetQueueName()).Returns(queueUrl); - - _mockSqsClient.Setup(x => x.SendMessageAsync(It.IsAny(), default)) - .ReturnsAsync(new SendMessageResponse()); - - // Act - await _dispatcher.Dispatch(command); - - // Assert - verify message was sent - _mockSqsClient.Verify(x => x.SendMessageAsync( - It.Is(r => r.QueueUrl == queueUrl), - default), Times.Once); - } - - [Fact] - public async Task Dispatch_WhenSqsClientThrowsException_ShouldPropagate() - { - // Arrange - var command = new TestCommand(); - var queueUrl = "https://sqs.us-east-1.amazonaws.com/123456/test-queue"; - - _mockRoutingConfig.Setup(x => x.ShouldRoute()).Returns(true); - _mockRoutingConfig.Setup(x => x.GetQueueName()).Returns(queueUrl); - - _mockSqsClient.Setup(x => x.SendMessageAsync(It.IsAny(), default)) - .ThrowsAsync(new Exception("SQS error")); - - // Act & Assert - await Assert.ThrowsAsync(async () => await _dispatcher.Dispatch(command)); - } -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/Unit/AwsSqsCommandListenerEnhancedTests.cs b/tests/SourceFlow.Cloud.AWS.Tests/Unit/AwsSqsCommandListenerEnhancedTests.cs deleted file mode 100644 index 2bd42d72..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/Unit/AwsSqsCommandListenerEnhancedTests.cs +++ /dev/null @@ -1,285 +0,0 @@ -using Amazon.SQS; -using Amazon.SQS.Model; -using Microsoft.Extensions.DependencyInjection; -using Microsoft.Extensions.Logging.Abstractions; -using Moq; -using SourceFlow.Cloud.AWS.Configuration; -using SourceFlow.Cloud.AWS.Messaging.Commands; -using SourceFlow.Cloud.AWS.Tests.TestHelpers; -using SourceFlow.Cloud.Configuration; -using SourceFlow.Cloud.DeadLetter; -using SourceFlow.Cloud.Observability; -using SourceFlow.Cloud.Security; -using SourceFlow.Messaging.Commands; -using SourceFlow.Observability; -using System.Text.Json; - -namespace SourceFlow.Cloud.AWS.Tests.Unit; - -[Trait("Category", "Unit")] -public class AwsSqsCommandListenerEnhancedTests -{ - private static readonly string TestQueueUrl = "https://sqs.us-east-1.amazonaws.com/123456/test-queue.fifo"; - - private readonly Mock _mockSqs; - private readonly Mock _mockRouting; - private readonly Mock _mockServiceProvider; - private readonly Mock _mockScopeFactory; - private readonly Mock _mockScope; - private readonly Mock _mockScopedProvider; - private readonly Mock _mockSubscriber; - private readonly Mock _mockDomainTelemetry; - private readonly Mock _mockIdempotency; - private readonly Mock _mockDeadLetterStore; - private readonly CloudTelemetry _cloudTelemetry; - private readonly CloudMetrics _cloudMetrics; - private readonly SensitiveDataMasker _dataMasker; - private readonly AwsOptions _options; - - public AwsSqsCommandListenerEnhancedTests() - { - _mockSqs = new Mock(); - _mockRouting = new Mock(); - _mockServiceProvider = new Mock(); - _mockScopeFactory = new Mock(); - _mockScope = new Mock(); - _mockScopedProvider = new Mock(); - _mockSubscriber = new Mock(); - _mockDomainTelemetry = new Mock(); - _mockIdempotency = new Mock(); - _mockDeadLetterStore = new Mock(); - _cloudTelemetry = new CloudTelemetry(NullLogger.Instance); - _cloudMetrics = new CloudMetrics(NullLogger.Instance); - _dataMasker = new SensitiveDataMasker(); - _options = new AwsOptions { SqsMaxNumberOfMessages = 10, SqsReceiveWaitTimeSeconds = 0, SqsVisibilityTimeoutSeconds = 30 }; - - // Wire up scoped service provider - _mockServiceProvider - .Setup(x => x.GetService(typeof(IServiceScopeFactory))) - .Returns(_mockScopeFactory.Object); - _mockScopeFactory.Setup(x => x.CreateScope()).Returns(_mockScope.Object); - _mockScope.Setup(x => x.ServiceProvider).Returns(_mockScopedProvider.Object); - _mockScopedProvider - .Setup(x => x.GetService(typeof(ICommandSubscriber))) - .Returns(_mockSubscriber.Object); - - _mockSubscriber - .Setup(x => x.Subscribe(It.IsAny())) - .Returns(Task.CompletedTask); - - _mockDeadLetterStore - .Setup(x => x.SaveAsync(It.IsAny())) - .Returns(Task.CompletedTask); - } - - [Fact] - public async Task ExecuteAsync_NoQueuesConfigured_ReceiveMessageNeverCalled() - { - _mockRouting.Setup(x => x.GetListeningQueues()).Returns(Enumerable.Empty()); - - var listener = CreateListener(); - await listener.StartAsync(CancellationToken.None); - await listener.StopAsync(CancellationToken.None); - - _mockSqs.Verify( - x => x.ReceiveMessageAsync(It.IsAny(), It.IsAny()), - Times.Never); - } - - [Fact] - public async Task ProcessMessage_DuplicateMessage_SubscriberNotCalledMessageDeleted() - { - // Arrange — idempotency says already processed - _mockRouting.Setup(x => x.GetListeningQueues()).Returns(new[] { TestQueueUrl }); - _mockIdempotency - .Setup(x => x.HasProcessedAsync(It.IsAny(), It.IsAny())) - .ReturnsAsync(true); - - var message = BuildValidCommandMessage("msg-dup"); - var deleted = new SemaphoreSlim(0, 1); - - SetupReceiveOnceAndBlock(message); - _mockSqs - .Setup(x => x.DeleteMessageAsync(It.IsAny(), It.IsAny())) - .Callback(() => deleted.Release()) - .ReturnsAsync(new DeleteMessageResponse()); - - var listener = CreateListener(); - await listener.StartAsync(CancellationToken.None); - var messageDeleted = await deleted.WaitAsync(TimeSpan.FromSeconds(5)); - await listener.StopAsync(CancellationToken.None); - - // Subscriber must NOT be invoked for duplicates - Assert.True(messageDeleted, "Duplicate message should be deleted to prevent re-delivery"); - _mockSubscriber.Verify(x => x.Subscribe(It.IsAny()), Times.Never); - _mockIdempotency.Verify( - x => x.MarkAsProcessedAsync(It.IsAny(), It.IsAny(), It.IsAny()), - Times.Never); - } - - [Fact] - public async Task ProcessMessage_ValidCommand_SubscriberCalledThenMarkedProcessedThenDeleted() - { - // Arrange - _mockRouting.Setup(x => x.GetListeningQueues()).Returns(new[] { TestQueueUrl }); - _mockIdempotency - .Setup(x => x.HasProcessedAsync(It.IsAny(), It.IsAny())) - .ReturnsAsync(false); - _mockIdempotency - .Setup(x => x.MarkAsProcessedAsync(It.IsAny(), It.IsAny(), It.IsAny())) - .Returns(Task.CompletedTask); - - var message = BuildValidCommandMessage("msg-valid"); - var deleted = new SemaphoreSlim(0, 1); - - SetupReceiveOnceAndBlock(message); - _mockSqs - .Setup(x => x.DeleteMessageAsync(It.IsAny(), It.IsAny())) - .Callback(() => deleted.Release()) - .ReturnsAsync(new DeleteMessageResponse()); - - var listener = CreateListener(); - await listener.StartAsync(CancellationToken.None); - var processed = await deleted.WaitAsync(TimeSpan.FromSeconds(5)); - await listener.StopAsync(CancellationToken.None); - - Assert.True(processed, "Message should be deleted after successful processing"); - _mockSubscriber.Verify(x => x.Subscribe(It.IsAny()), Times.Once); - _mockIdempotency.Verify( - x => x.MarkAsProcessedAsync( - It.Is(k => k.Contains(typeof(TestCommand).FullName!)), - TimeSpan.FromHours(24), - It.IsAny()), - Times.Once); - } - - [Fact] - public async Task ProcessMessage_EncryptionEnabled_DecryptCalledBeforeDeserialization() - { - // Arrange - _mockRouting.Setup(x => x.GetListeningQueues()).Returns(new[] { TestQueueUrl }); - _mockIdempotency - .Setup(x => x.HasProcessedAsync(It.IsAny(), It.IsAny())) - .ReturnsAsync(false); - _mockIdempotency - .Setup(x => x.MarkAsProcessedAsync(It.IsAny(), It.IsAny(), It.IsAny())) - .Returns(Task.CompletedTask); - - // Encryption that pass-throughs (returns same content after "decryption") - var mockEncryption = new Mock(); - mockEncryption.Setup(x => x.AlgorithmName).Returns("TEST"); - mockEncryption - .Setup(x => x.DecryptAsync(It.IsAny(), It.IsAny())) - .Returns((s, _) => Task.FromResult(s)); // identity decryption - - var message = BuildValidCommandMessage("msg-enc"); - var deleted = new SemaphoreSlim(0, 1); - - SetupReceiveOnceAndBlock(message); - _mockSqs - .Setup(x => x.DeleteMessageAsync(It.IsAny(), It.IsAny())) - .Callback(() => deleted.Release()) - .ReturnsAsync(new DeleteMessageResponse()); - - var listener = CreateListener(encryption: mockEncryption.Object); - await listener.StartAsync(CancellationToken.None); - await deleted.WaitAsync(TimeSpan.FromSeconds(5)); - await listener.StopAsync(CancellationToken.None); - - mockEncryption.Verify(x => x.DecryptAsync(It.IsAny()), Times.Once); - } - - [Fact] - public async Task ProcessMessage_HighReceiveCount_CreatesDeadLetterRecordOnFailure() - { - // Arrange — subscriber throws, receive count > 3 - _mockRouting.Setup(x => x.GetListeningQueues()).Returns(new[] { TestQueueUrl }); - _mockIdempotency - .Setup(x => x.HasProcessedAsync(It.IsAny(), It.IsAny())) - .ReturnsAsync(false); - _mockSubscriber - .Setup(x => x.Subscribe(It.IsAny())) - .ThrowsAsync(new InvalidOperationException("handler failed")); - - var message = BuildValidCommandMessage("msg-dlq"); - message.Attributes["ApproximateReceiveCount"] = "5"; // above threshold of 3 - - var dlqSaved = new SemaphoreSlim(0, 1); - _mockDeadLetterStore - .Setup(x => x.SaveAsync(It.IsAny())) - .Callback(() => dlqSaved.Release()) - .Returns(Task.CompletedTask); - - SetupReceiveOnceAndBlock(message); - - var listener = CreateListener(); - await listener.StartAsync(CancellationToken.None); - var saved = await dlqSaved.WaitAsync(TimeSpan.FromSeconds(5)); - await listener.StopAsync(CancellationToken.None); - - Assert.True(saved, "DeadLetterRecord should be created for messages that fail with high receive count"); - _mockDeadLetterStore.Verify( - x => x.SaveAsync(It.Is(r => - r.Reason == "ProcessingFailure" && - r.CloudProvider == "aws")), - Times.Once); - } - - // ── Helpers ────────────────────────────────────────────────────────────── - - private static Message BuildValidCommandMessage(string messageId = "msg-1") - { - var command = new TestCommand(); - var json = JsonSerializer.Serialize(command, new JsonSerializerOptions - { - PropertyNamingPolicy = JsonNamingPolicy.CamelCase - }); - - return new Message - { - MessageId = messageId, - ReceiptHandle = $"rh-{messageId}", - Body = json, - MessageAttributes = new Dictionary - { - ["CommandType"] = new MessageAttributeValue - { - DataType = "String", - StringValue = typeof(TestCommand).AssemblyQualifiedName - } - }, - Attributes = new Dictionary - { - ["ApproximateReceiveCount"] = "1" - } - }; - } - - private void SetupReceiveOnceAndBlock(Message message) - { - int callCount = 0; - _mockSqs - .Setup(x => x.ReceiveMessageAsync(It.IsAny(), It.IsAny())) - .Returns((_, ct) => - ++callCount == 1 - ? Task.FromResult(new ReceiveMessageResponse { Messages = new List { message } }) - : Task.Delay(Timeout.Infinite, ct).ContinueWith( - _ => new ReceiveMessageResponse(), - TaskContinuationOptions.OnlyOnCanceled)); - } - - private AwsSqsCommandListenerEnhanced CreateListener(IMessageEncryption? encryption = null) => - new AwsSqsCommandListenerEnhanced( - _mockSqs.Object, - _mockServiceProvider.Object, - _mockRouting.Object, - NullLogger.Instance, - _mockDomainTelemetry.Object, - _cloudTelemetry, - _cloudMetrics, - _mockIdempotency.Object, - _mockDeadLetterStore.Object, - _dataMasker, - _options, - encryption); -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/Unit/AwsSqsCommandListenerTests.cs b/tests/SourceFlow.Cloud.AWS.Tests/Unit/AwsSqsCommandListenerTests.cs deleted file mode 100644 index 8d435e1c..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/Unit/AwsSqsCommandListenerTests.cs +++ /dev/null @@ -1,248 +0,0 @@ -using Amazon.SQS; -using Amazon.SQS.Model; -using Microsoft.Extensions.DependencyInjection; -using Microsoft.Extensions.Logging.Abstractions; -using Moq; -using SourceFlow.Cloud.AWS.Configuration; -using SourceFlow.Cloud.AWS.Messaging.Commands; -using SourceFlow.Cloud.AWS.Tests.TestHelpers; -using SourceFlow.Cloud.Configuration; -using SourceFlow.Messaging.Commands; -using System.Text.Json; - -namespace SourceFlow.Cloud.AWS.Tests.Unit; - -[Trait("Category", "Unit")] -public class AwsSqsCommandListenerTests -{ - private static readonly string TestQueueUrl = "https://sqs.us-east-1.amazonaws.com/123456/test-queue.fifo"; - - private readonly Mock _mockSqs; - private readonly Mock _mockRouting; - private readonly Mock _mockServiceProvider; - private readonly Mock _mockScopeFactory; - private readonly Mock _mockScope; - private readonly Mock _mockScopedProvider; - private readonly Mock _mockSubscriber; - private readonly AwsOptions _options; - - public AwsSqsCommandListenerTests() - { - _mockSqs = new Mock(); - _mockRouting = new Mock(); - _mockServiceProvider = new Mock(); - _mockScopeFactory = new Mock(); - _mockScope = new Mock(); - _mockScopedProvider = new Mock(); - _mockSubscriber = new Mock(); - _options = new AwsOptions { SqsMaxNumberOfMessages = 10, SqsReceiveWaitTimeSeconds = 0, SqsVisibilityTimeoutSeconds = 30 }; - - // Wire up scoped service provider - _mockServiceProvider - .Setup(x => x.GetService(typeof(IServiceScopeFactory))) - .Returns(_mockScopeFactory.Object); - _mockScopeFactory.Setup(x => x.CreateScope()).Returns(_mockScope.Object); - _mockScope.Setup(x => x.ServiceProvider).Returns(_mockScopedProvider.Object); - _mockScopedProvider - .Setup(x => x.GetService(typeof(ICommandSubscriber))) - .Returns(_mockSubscriber.Object); - - _mockSubscriber - .Setup(x => x.Subscribe(It.IsAny())) - .Returns(Task.CompletedTask); - } - - [Fact] - public async Task ExecuteAsync_NoQueuesConfigured_ReceiveMessageNeverCalled() - { - _mockRouting.Setup(x => x.GetListeningQueues()).Returns(Enumerable.Empty()); - - var listener = CreateListener(); - using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(2)); - - await listener.StartAsync(cts.Token); - await listener.StopAsync(CancellationToken.None); - - _mockSqs.Verify( - x => x.ReceiveMessageAsync(It.IsAny(), It.IsAny()), - Times.Never); - } - - [Fact] - public async Task ProcessMessage_ValidCommand_CallsSubscriberAndDeletesMessage() - { - // Arrange - _mockRouting.Setup(x => x.GetListeningQueues()).Returns(new[] { TestQueueUrl }); - - var message = BuildValidCommandMessage(); - var deleted = new SemaphoreSlim(0, 1); - - SetupReceiveOnceAndBlock(message); - _mockSqs - .Setup(x => x.DeleteMessageAsync(It.IsAny(), It.IsAny())) - .Callback(() => deleted.Release()) - .ReturnsAsync(new DeleteMessageResponse()); - - var listener = CreateListener(); - await listener.StartAsync(CancellationToken.None); - var processed = await deleted.WaitAsync(TimeSpan.FromSeconds(5)); - await listener.StopAsync(CancellationToken.None); - - // Assert - Assert.True(processed, "DeleteMessageAsync should have been called within 5 seconds"); - _mockSubscriber.Verify(x => x.Subscribe(It.IsAny()), Times.Once); - _mockSqs.Verify( - x => x.DeleteMessageAsync( - It.Is(r => r.ReceiptHandle == message.ReceiptHandle), - It.IsAny()), - Times.Once); - } - - [Fact] - public async Task ProcessMessage_MissingCommandTypeAttribute_DeletesMessageForCleanup() - { - // Arrange - _mockRouting.Setup(x => x.GetListeningQueues()).Returns(new[] { TestQueueUrl }); - - var message = new Message - { - MessageId = "msg-no-attr", - ReceiptHandle = "rh-no-attr", - Body = "{}", - MessageAttributes = new Dictionary() // missing CommandType - }; - - var deleted = new SemaphoreSlim(0, 1); - SetupReceiveOnceAndBlock(message); - _mockSqs - .Setup(x => x.DeleteMessageAsync(It.IsAny(), It.IsAny(), It.IsAny())) - .Callback(() => deleted.Release()) - .ReturnsAsync(new DeleteMessageResponse()); - - var listener = CreateListener(); - await listener.StartAsync(CancellationToken.None); - await Task.Delay(500); // give listener time to attempt processing - await listener.StopAsync(CancellationToken.None); - - // Subscriber must NOT have been invoked - _mockSubscriber.Verify(x => x.Subscribe(It.IsAny()), Times.Never); - } - - [Fact] - public async Task ProcessMessage_UnresolvableCommandType_DoesNotCallSubscriber() - { - // Arrange - _mockRouting.Setup(x => x.GetListeningQueues()).Returns(new[] { TestQueueUrl }); - - var message = new Message - { - MessageId = "msg-bad-type", - ReceiptHandle = "rh-bad-type", - Body = "{}", - MessageAttributes = new Dictionary - { - ["CommandType"] = new MessageAttributeValue - { - DataType = "String", - StringValue = "NonExistent.Type.That.DoesNotExist, NoSuchAssembly" - } - } - }; - - SetupReceiveOnceAndBlock(message); - _mockSqs - .Setup(x => x.DeleteMessageAsync(It.IsAny(), It.IsAny(), It.IsAny())) - .ReturnsAsync(new DeleteMessageResponse()); - - var listener = CreateListener(); - await listener.StartAsync(CancellationToken.None); - await Task.Delay(500); - await listener.StopAsync(CancellationToken.None); - - _mockSubscriber.Verify(x => x.Subscribe(It.IsAny()), Times.Never); - } - - [Fact] - public async Task ProcessMessage_InvalidJson_DeletesMessageAndDoesNotCallSubscriber() - { - // Arrange - _mockRouting.Setup(x => x.GetListeningQueues()).Returns(new[] { TestQueueUrl }); - - var message = new Message - { - MessageId = "msg-bad-json", - ReceiptHandle = "rh-bad-json", - Body = "not-valid-json{{{", - MessageAttributes = new Dictionary - { - ["CommandType"] = new MessageAttributeValue - { - DataType = "String", - StringValue = typeof(TestCommand).AssemblyQualifiedName - } - } - }; - - var deleted = new SemaphoreSlim(0, 1); - SetupReceiveOnceAndBlock(message); - _mockSqs - .Setup(x => x.DeleteMessageAsync(It.IsAny(), It.IsAny(), It.IsAny())) - .Callback(() => deleted.Release()) - .ReturnsAsync(new DeleteMessageResponse()); - - var listener = CreateListener(); - await listener.StartAsync(CancellationToken.None); - var cleaned = await deleted.WaitAsync(TimeSpan.FromSeconds(5)); - await listener.StopAsync(CancellationToken.None); - - Assert.True(cleaned, "Malformed message should be deleted to prevent infinite retries"); - _mockSubscriber.Verify(x => x.Subscribe(It.IsAny()), Times.Never); - } - - // ── Helpers ────────────────────────────────────────────────────────────── - - private static Message BuildValidCommandMessage() - { - var command = new TestCommand(); - var json = JsonSerializer.Serialize(command, new JsonSerializerOptions - { - PropertyNamingPolicy = JsonNamingPolicy.CamelCase - }); - - return new Message - { - MessageId = "msg-valid", - ReceiptHandle = "rh-valid", - Body = json, - MessageAttributes = new Dictionary - { - ["CommandType"] = new MessageAttributeValue - { - DataType = "String", - StringValue = typeof(TestCommand).AssemblyQualifiedName - } - } - }; - } - - private void SetupReceiveOnceAndBlock(Message message) - { - int callCount = 0; - _mockSqs - .Setup(x => x.ReceiveMessageAsync(It.IsAny(), It.IsAny())) - .Returns((_, ct) => - ++callCount == 1 - ? Task.FromResult(new ReceiveMessageResponse { Messages = new List { message } }) - : Task.Delay(Timeout.Infinite, ct).ContinueWith( - _ => new ReceiveMessageResponse(), - TaskContinuationOptions.OnlyOnCanceled)); - } - - private AwsSqsCommandListener CreateListener() => - new AwsSqsCommandListener( - _mockSqs.Object, - _mockServiceProvider.Object, - _mockRouting.Object, - NullLogger.Instance, - _options); -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/Unit/BusConfigurationTests.cs b/tests/SourceFlow.Cloud.AWS.Tests/Unit/BusConfigurationTests.cs deleted file mode 100644 index 9deb07be..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/Unit/BusConfigurationTests.cs +++ /dev/null @@ -1,234 +0,0 @@ -using SourceFlow.Cloud.AWS.Tests.TestHelpers; -using SourceFlow.Cloud.Configuration; - -namespace SourceFlow.Cloud.AWS.Tests.Unit; - -[Trait("Category", "Unit")] -public class BusConfigurationTests -{ - private BusConfiguration BuildConfig(Action configure) - { - var builder = new BusConfigurationBuilder(); - configure(builder); - return builder.Build(); - } - - // ── Builder Tests ───────────────────────────────────────────────────── - - [Fact] - public void Builder_RegistersCommandRoutes() - { - // Act - var config = BuildConfig(bus => bus - .Send.Command(q => q.Queue("orders.fifo"))); - - // Assert - var bootstrap = (IBusBootstrapConfiguration)config; - Assert.Single(bootstrap.CommandTypeToQueueName); - Assert.Equal("orders.fifo", bootstrap.CommandTypeToQueueName[typeof(TestCommand)]); - } - - [Fact] - public void Builder_RegistersEventRoutes() - { - // Act - var config = BuildConfig(bus => bus - .Raise.Event(t => t.Topic("order-events"))); - - // Assert - var bootstrap = (IBusBootstrapConfiguration)config; - Assert.Single(bootstrap.EventTypeToTopicName); - Assert.Equal("order-events", bootstrap.EventTypeToTopicName[typeof(TestEvent)]); - } - - [Fact] - public void Builder_RegistersCommandListeningQueues() - { - // Act - var config = BuildConfig(bus => bus - .Listen.To - .CommandQueue("orders.fifo") - .CommandQueue("inventory.fifo")); - - // Assert - var bootstrap = (IBusBootstrapConfiguration)config; - Assert.Equal(2, bootstrap.CommandListeningQueueNames.Count); - Assert.Equal("orders.fifo", bootstrap.CommandListeningQueueNames[0]); - Assert.Equal("inventory.fifo", bootstrap.CommandListeningQueueNames[1]); - } - - [Fact] - public void Builder_RegistersSubscribedTopics() - { - // Act - var config = BuildConfig(bus => bus - .Subscribe.To - .Topic("order-events") - .Topic("payment-events")); - - // Assert - var bootstrap = (IBusBootstrapConfiguration)config; - Assert.Equal(2, bootstrap.SubscribedTopicNames.Count); - Assert.Equal("order-events", bootstrap.SubscribedTopicNames[0]); - Assert.Equal("payment-events", bootstrap.SubscribedTopicNames[1]); - } - - [Fact] - public void Builder_RejectsFullUrlAsQueueName() - { - Assert.Throws(() => BuildConfig(bus => bus - .Send.Command(q => q.Queue("https://sqs.us-east-1.amazonaws.com/123456/orders")))); - } - - [Fact] - public void Builder_RejectsFullArnAsTopicName() - { - Assert.Throws(() => BuildConfig(bus => bus - .Raise.Event(t => t.Topic("arn:aws:sns:us-east-1:123456:order-events")))); - } - - // ── Pre-Bootstrap Guard Tests ───────────────────────────────────────── - - [Fact] - public void GetQueueName_BeforeResolve_ThrowsInvalidOperationException() - { - var config = BuildConfig(bus => bus - .Send.Command(q => q.Queue("orders.fifo"))); - - var commandRouting = (ICommandRoutingConfiguration)config; - - var ex = Assert.Throws(() => - commandRouting.GetQueueName()); - - Assert.Contains("has not been bootstrapped yet", ex.Message); - } - - [Fact] - public void GetTopicName_BeforeResolve_ThrowsInvalidOperationException() - { - var config = BuildConfig(bus => bus - .Raise.Event(t => t.Topic("order-events"))); - - var eventRouting = (IEventRoutingConfiguration)config; - - var ex = Assert.Throws(() => - eventRouting.GetTopicName()); - - Assert.Contains("has not been bootstrapped yet", ex.Message); - } - - [Fact] - public void EventRouting_GetListeningQueues_BeforeResolve_ThrowsInvalidOperationException() - { - var config = BuildConfig(bus => bus - .Subscribe.To.Topic("order-events")); - - var eventRouting = (IEventRoutingConfiguration)config; - - Assert.Throws(() => - eventRouting.GetListeningQueues()); - } - - // ── Post-Bootstrap Tests ────────────────────────────────────────────── - - [Fact] - public void EventRouting_GetListeningQueues_AfterResolve_ReturnsEventListeningUrls() - { - // Arrange - var config = BuildConfig(bus => bus - .Listen.To.CommandQueue("orders.fifo") - .Subscribe.To.Topic("order-events")); - - var bootstrap = (IBusBootstrapConfiguration)config; - bootstrap.Resolve( - commandRoutes: new Dictionary(), - eventRoutes: new Dictionary(), - commandListeningUrls: new List { "https://sqs.us-east-1.amazonaws.com/123456/orders.fifo" }, - subscribedTopicArns: new List { "arn:aws:sns:us-east-1:123456:order-events" }, - eventListeningUrls: new List { "https://sqs.us-east-1.amazonaws.com/123456/orders.fifo" }); - - // Act - var eventRouting = (IEventRoutingConfiguration)config; - var listeningQueues = eventRouting.GetListeningQueues().ToList(); - - // Assert - Assert.Single(listeningQueues); - Assert.Equal("https://sqs.us-east-1.amazonaws.com/123456/orders.fifo", listeningQueues[0]); - } - - [Fact] - public void EventRouting_GetListeningQueues_AfterResolveWithNoTopics_ReturnsEmpty() - { - // Arrange - var config = BuildConfig(bus => bus - .Listen.To.CommandQueue("orders.fifo")); - - var bootstrap = (IBusBootstrapConfiguration)config; - bootstrap.Resolve( - commandRoutes: new Dictionary(), - eventRoutes: new Dictionary(), - commandListeningUrls: new List { "https://sqs.us-east-1.amazonaws.com/123456/orders.fifo" }, - subscribedTopicArns: new List(), - eventListeningUrls: new List()); - - // Act - var eventRouting = (IEventRoutingConfiguration)config; - var listeningQueues = eventRouting.GetListeningQueues().ToList(); - - // Assert - Assert.Empty(listeningQueues); - } - - [Fact] - public void CommandRouting_AfterResolve_ReturnsCorrectQueueUrl() - { - // Arrange - var config = BuildConfig(bus => bus - .Send.Command(q => q.Queue("orders.fifo")) - .Listen.To.CommandQueue("orders.fifo")); - - var bootstrap = (IBusBootstrapConfiguration)config; - bootstrap.Resolve( - commandRoutes: new Dictionary - { - [typeof(TestCommand)] = "https://sqs.us-east-1.amazonaws.com/123456/orders.fifo" - }, - eventRoutes: new Dictionary(), - commandListeningUrls: new List { "https://sqs.us-east-1.amazonaws.com/123456/orders.fifo" }, - subscribedTopicArns: new List(), - eventListeningUrls: new List()); - - // Act - var commandRouting = (ICommandRoutingConfiguration)config; - - // Assert - Assert.True(commandRouting.ShouldRoute()); - Assert.Equal("https://sqs.us-east-1.amazonaws.com/123456/orders.fifo", - commandRouting.GetQueueName()); - } - - [Fact] - public void EventRouting_GetSubscribedTopics_AfterResolve_ReturnsResolvedArns() - { - // Arrange - var config = BuildConfig(bus => bus - .Listen.To.CommandQueue("orders.fifo") - .Subscribe.To.Topic("order-events")); - - var bootstrap = (IBusBootstrapConfiguration)config; - bootstrap.Resolve( - commandRoutes: new Dictionary(), - eventRoutes: new Dictionary(), - commandListeningUrls: new List { "https://sqs.us-east-1.amazonaws.com/123456/orders.fifo" }, - subscribedTopicArns: new List { "arn:aws:sns:us-east-1:123456:order-events" }, - eventListeningUrls: new List { "https://sqs.us-east-1.amazonaws.com/123456/orders.fifo" }); - - // Act - var eventRouting = (IEventRoutingConfiguration)config; - var subscribedTopics = eventRouting.GetSubscribedTopics().ToList(); - - // Assert - Assert.Single(subscribedTopics); - Assert.Equal("arn:aws:sns:us-east-1:123456:order-events", subscribedTopics[0]); - } -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/Unit/IocExtensionsTests.cs b/tests/SourceFlow.Cloud.AWS.Tests/Unit/IocExtensionsTests.cs deleted file mode 100644 index a8d00b7d..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/Unit/IocExtensionsTests.cs +++ /dev/null @@ -1,63 +0,0 @@ -using Microsoft.Extensions.DependencyInjection; -using SourceFlow.Cloud.AWS.Configuration; -using SourceFlow.Cloud.AWS.Tests.TestHelpers; -using SourceFlow.Cloud.Configuration; - -namespace SourceFlow.Cloud.AWS.Tests.Unit; - -[Trait("Category", "Unit")] -public class IocExtensionsTests -{ - [Fact] - public void UseSourceFlowAws_RegistersAllRequiredServices() - { - // Arrange - var services = new ServiceCollection(); - - // Act - services.UseSourceFlowAws( - options => { options.Region = Amazon.RegionEndpoint.USEast1; }, - bus => bus - .Send.Command(q => q.Queue("test-queue.fifo")) - .Listen.To.CommandQueue("test-queue.fifo")); - - var provider = services.BuildServiceProvider(); - - // Assert - var awsOptions = provider.GetRequiredService(); - var commandRouting = provider.GetRequiredService(); - var eventRouting = provider.GetRequiredService(); - var bootstrapConfig = provider.GetRequiredService(); - - Assert.NotNull(awsOptions); - Assert.NotNull(commandRouting); - Assert.NotNull(eventRouting); - Assert.NotNull(bootstrapConfig); - } - - [Fact] - public void UseSourceFlowAws_RegistersBusConfigurationAsSingletonAcrossInterfaces() - { - // Arrange - var services = new ServiceCollection(); - - // Act - services.UseSourceFlowAws( - options => { options.Region = Amazon.RegionEndpoint.USEast1; }, - bus => bus - .Send.Command(q => q.Queue("test-queue.fifo")) - .Listen.To.CommandQueue("test-queue.fifo")); - - var provider = services.BuildServiceProvider(); - - // Assert - all routing interfaces resolve to the same BusConfiguration instance - var busConfig = provider.GetRequiredService(); - var commandRouting = provider.GetRequiredService(); - var eventRouting = provider.GetRequiredService(); - var bootstrapConfig = provider.GetRequiredService(); - - Assert.Same(busConfig, commandRouting); - Assert.Same(busConfig, eventRouting); - Assert.Same(busConfig, bootstrapConfig); - } -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/Unit/LocalStackEquivalencePropertyTest.cs b/tests/SourceFlow.Cloud.AWS.Tests/Unit/LocalStackEquivalencePropertyTest.cs deleted file mode 100644 index 919100e0..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/Unit/LocalStackEquivalencePropertyTest.cs +++ /dev/null @@ -1,102 +0,0 @@ -using FsCheck; -using FsCheck.Xunit; -using SourceFlow.Cloud.AWS.Tests.TestHelpers; - -namespace SourceFlow.Cloud.AWS.Tests.Unit; - -/// -/// Dedicated property test for LocalStack AWS service equivalence. -/// -/// NOTE: Real LocalStack equivalence testing (verifying that LocalStack SQS, SNS, and KMS behave -/// identically to real AWS services under various scenarios) must be done in integration tests -/// that actually spin up a LocalStack container and execute API calls. Property tests that do not -/// exercise real infrastructure cannot validate functional equivalence. -/// -/// This class validates only the structural invariants of itself, -/// ensuring that generated test scenarios satisfy their own documented constraints. -/// -[Trait("Category", "Unit")] -public class LocalStackEquivalencePropertyTest -{ - /// - /// Generator for AWS test scenarios that can run on both LocalStack and real AWS - /// - public static Arbitrary AwsTestScenarioGenerator() - { - return Arb.From( - from testPrefix in Arb.Generate() - .Select(x => new string(x.Get.Where(c => char.IsLetterOrDigit(c) || c == '-').ToArray())) - .Where(x => !string.IsNullOrEmpty(x) && x.Length >= 3 && x.Length <= 20) - from messageCount in Arb.Generate().Where(x => x >= 1 && x <= 10) - from messageSize in Arb.Generate().Where(x => x >= 100 && x <= 1024) - from useEncryption in Arb.Generate() - from enableDlq in Arb.Generate() - from testTimeout in Arb.Generate().Where(x => x >= 30 && x <= 300) - select new AwsTestScenario - { - TestPrefix = testPrefix, - MessageCount = messageCount, - MessageSize = messageSize, - UseEncryption = useEncryption, - EnableDeadLetterQueue = enableDlq, - TestTimeoutSeconds = testTimeout, - TestId = Guid.NewGuid().ToString("N")[..8] - }); - } - - /// - /// Property: AwsTestScenario invariants are satisfied by the generator. - /// - /// This validates that generated objects satisfy their own - /// documented constraints (e.g., MessageCount > 0, MessageSize within SQS limits, - /// BatchSize <= 10, etc.) as expressed by . - /// - /// Real LocalStack/AWS equivalence testing belongs in integration tests that make actual - /// network calls to LocalStack or AWS endpoints. - /// - [Property(Arbitrary = new[] { typeof(LocalStackEquivalencePropertyTest) })] - public Property GeneratedScenarioSatisfiesItsOwnInvariants(AwsTestScenario scenario) - { - // The scenario must not be null - var notNull = scenario != null; - - if (!notNull) - return false.ToProperty(); - - // MessageCount must be positive (required by SQS: at least 1 message) - var messageCountPositive = scenario!.MessageCount > 0; - - // MessageSize must be within SQS limits (100 bytes minimum, 256 KB maximum) - var messageSizeValid = scenario.MessageSize >= 100 && scenario.MessageSize <= 262144; - - // BatchSize must respect the AWS SQS batch limit of 10 - var batchSizeValid = scenario.BatchSize > 0 && scenario.BatchSize <= 10; - - // TestTimeoutSeconds must be positive - var timeoutPositive = scenario.TestTimeoutSeconds > 0; - - // TestPrefix and TestId must be non-empty (needed to generate unique resource names) - var namesPresent = !string.IsNullOrEmpty(scenario.TestPrefix) && - !string.IsNullOrEmpty(scenario.TestId); - - // Region must be specified - var regionPresent = !string.IsNullOrEmpty(scenario.Region); - - // SubscriberCount must be at least 1 - var subscriberCountValid = scenario.SubscriberCount >= 1; - - // IsValid() should agree with all the above - var isValidConsistent = scenario.IsValid() == - (messageCountPositive && messageSizeValid && batchSizeValid && - timeoutPositive && namesPresent && regionPresent && subscriberCountValid); - - return (messageCountPositive && - messageSizeValid && - batchSizeValid && - timeoutPositive && - namesPresent && - regionPresent && - subscriberCountValid && - isValidConsistent).ToProperty(); - } -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/Unit/PropertyBasedTests.cs b/tests/SourceFlow.Cloud.AWS.Tests/Unit/PropertyBasedTests.cs deleted file mode 100644 index ef3a0aa0..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/Unit/PropertyBasedTests.cs +++ /dev/null @@ -1,329 +0,0 @@ -using FsCheck; -using FsCheck.Xunit; -using SourceFlow.Cloud.AWS.Tests.TestHelpers; -using SourceFlow.Messaging.Commands; - -namespace SourceFlow.Cloud.AWS.Tests.Unit; - -[Trait("Category", "Unit")] -public class PropertyBasedTests -{ - /// - /// Generator for test commands - /// - public static Arbitrary TestCommandGenerator() - { - return Arb.From( - from entityId in Arb.Generate().Where(x => x > 0) - from message in Arb.Generate().Where(x => !string.IsNullOrEmpty(x)) - from value in Arb.Generate() - select new TestCommand - { - Entity = new EntityRef { Id = entityId }, - Payload = new TestCommandData { Message = message, Value = value } - }); - } - - /// - /// Generator for test events - /// - public static Arbitrary TestEventGenerator() - { - return Arb.From( - from id in Arb.Generate().Where(x => x > 0) - from message in Arb.Generate().Where(x => !string.IsNullOrEmpty(x)) - from value in Arb.Generate() - select new TestEvent(new TestEventData { Id = id, Message = message, Value = value })); - } - - /// - /// Property: Command serialization should be round-trip safe - /// **Feature: cloud-integration-testing, Property 1: Command serialization round-trip consistency** - /// **Validates: Requirements 1.1** - /// - [Property(Arbitrary = new[] { typeof(PropertyBasedTests) })] - public Property CommandSerializationRoundTrip(TestCommand command) - { - return (command != null).ToProperty().And(() => - { - // This would test actual serialization logic when implemented - // For now, just verify the command structure is valid - var isValid = command.Entity != null && - command.Entity.Id > 0 && - command.Payload != null && - !string.IsNullOrEmpty(command.Payload.Message); - - return isValid; - }); - } - - /// - /// Property: Event serialization should be round-trip safe - /// **Feature: cloud-integration-testing, Property 2: Event serialization round-trip consistency** - /// **Validates: Requirements 1.2** - /// - [Property(Arbitrary = new[] { typeof(PropertyBasedTests) })] - public Property EventSerializationRoundTrip(TestEvent @event) - { - return (@event != null).ToProperty().And(() => - { - // This would test actual serialization logic when implemented - // For now, just verify the event structure is valid - var isValid = !string.IsNullOrEmpty(@event.Name) && - @event.Payload != null && - @event.Payload.Id > 0; - - return isValid; - }); - } - - /// - /// Property: Queue URLs should be valid AWS SQS URLs - /// **Feature: cloud-integration-testing, Property 3: Queue URL validation** - /// **Validates: Requirements 1.1** - /// - [Property] - public Property QueueUrlValidation(NonEmptyString accountId, NonEmptyString region, NonEmptyString queueName) - { - // Filter out control characters and invalid URL characters - var cleanAccountId = new string(accountId.Get.Where(c => char.IsLetterOrDigit(c)).ToArray()); - var cleanRegion = new string(region.Get.Where(c => char.IsLetterOrDigit(c) || c == '-').ToArray()); - var cleanQueueName = new string(queueName.Get.Where(c => char.IsLetterOrDigit(c) || c == '-' || c == '_').ToArray()); - - // Skip if any cleaned string is empty - if (string.IsNullOrEmpty(cleanAccountId) || string.IsNullOrEmpty(cleanRegion) || string.IsNullOrEmpty(cleanQueueName)) - return true.ToProperty(); // Trivially true for invalid inputs - - var queueUrl = $"https://sqs.{cleanRegion}.amazonaws.com/{cleanAccountId}/{cleanQueueName}"; - - return (Uri.TryCreate(queueUrl, UriKind.Absolute, out var uri) && - uri.Host.Contains("sqs") && - uri.Host.Contains("amazonaws.com")).ToProperty(); - } - - /// - /// Property: Topic ARNs should be valid AWS SNS ARNs - /// **Feature: cloud-integration-testing, Property 4: Topic ARN validation** - /// **Validates: Requirements 1.2** - /// - [Property] - public Property TopicArnValidation(NonEmptyString accountId, NonEmptyString region, NonEmptyString topicName) - { - var topicArn = $"arn:aws:sns:{region.Get}:{accountId.Get}:{topicName.Get}"; - - return (topicArn.StartsWith("arn:aws:sns:") && - topicArn.Contains(accountId.Get) && - topicArn.Contains(region.Get) && - topicArn.EndsWith(topicName.Get)).ToProperty(); - } - - /// - /// Property: Message attributes should preserve type information - /// **Feature: cloud-integration-testing, Property 5: Message attribute preservation** - /// **Validates: Requirements 1.1, 1.2** - /// - [Property] - public Property MessageAttributePreservation(NonEmptyString attributeName, NonEmptyString attributeValue) - { - var attributes = new Dictionary - { - [attributeName.Get] = attributeValue.Get - }; - - // Verify attributes are preserved (this would test actual message attribute handling) - return (attributes.ContainsKey(attributeName.Get) && - attributes[attributeName.Get] == attributeValue.Get).ToProperty(); - } - - /// - /// Generator for CI/CD test scenarios - /// - public static Arbitrary CiCdTestScenarioGenerator() - { - return Arb.From( - from testPrefix in Arb.Generate() - .Select(x => new string(x.Get.Where(c => char.IsLetterOrDigit(c) || c == '-').ToArray())) - .Where(x => !string.IsNullOrEmpty(x) && x.Length >= 3 && x.Length <= 20) - from useLocalStack in Arb.Generate() - from parallelTests in Arb.Generate().Where(x => x >= 1 && x <= 10) - from resourceCount in Arb.Generate().Where(x => x >= 1 && x <= 5) - from cleanupEnabled in Arb.Generate() - select new CiCdTestScenario - { - TestPrefix = testPrefix, - UseLocalStack = useLocalStack, - ParallelTestCount = parallelTests, - ResourceCount = resourceCount, - CleanupEnabled = cleanupEnabled, - TestId = Guid.NewGuid().ToString("N")[..8] // Short unique ID - }); - } - - /// - /// Property: AWS CI/CD Integration Reliability - /// **Validates: Requirements 9.1, 9.2, 9.3, 9.4, 9.5** - /// - /// For any CI/CD test execution, tests should run successfully against both LocalStack and real AWS services, - /// automatically provision and clean up resources, provide comprehensive reporting with actionable error messages, - /// and maintain proper test isolation. - /// - [Property] - public Property AwsCiCdIntegrationReliability(NonEmptyString testPrefix, bool useLocalStack, - PositiveInt parallelTests, PositiveInt resourceCount, bool cleanupEnabled) - { - // Create a valid test scenario from the generated inputs - var cleanedPrefix = new string(testPrefix.Get.Where(c => char.IsLetterOrDigit(c) || c == '-').ToArray()); - - // Ensure prefix starts with alphanumeric character (AWS requirement) - if (!string.IsNullOrEmpty(cleanedPrefix) && cleanedPrefix.StartsWith('-')) - { - cleanedPrefix = "test" + cleanedPrefix; - } - - // Ensure prefix ends with alphanumeric character (AWS requirement) - if (!string.IsNullOrEmpty(cleanedPrefix) && cleanedPrefix.EndsWith('-')) - { - cleanedPrefix = cleanedPrefix.TrimEnd('-') + "test"; - } - - var scenario = new CiCdTestScenario - { - TestPrefix = cleanedPrefix, - UseLocalStack = useLocalStack, - ParallelTestCount = Math.Min(parallelTests.Get, 10), // Limit to reasonable range - ResourceCount = Math.Min(resourceCount.Get, 5), // Limit to reasonable range - CleanupEnabled = cleanupEnabled, - TestId = Guid.NewGuid().ToString("N")[..8] - }; - - // Skip invalid scenarios - if (string.IsNullOrEmpty(scenario.TestPrefix) || scenario.TestPrefix.Length < 3) - return true.ToProperty(); // Trivially true for invalid inputs - - return (scenario != null && !string.IsNullOrEmpty(scenario.TestPrefix)).ToProperty().And(() => - { - // Property 1: Test environment configuration should be valid - var environmentValid = ValidateTestEnvironment(scenario); - - // Property 2: Resource naming should prevent conflicts - var resourceNamingValid = ValidateResourceNaming(scenario); - - // Property 3: Parallel execution should be properly configured - var parallelExecutionValid = ValidateParallelExecution(scenario); - - // Property 4: Resource cleanup should be properly configured - var cleanupValid = ValidateResourceCleanup(scenario); - - // Property 5: Test isolation should be maintained - var isolationValid = ValidateTestIsolation(scenario); - - return environmentValid && resourceNamingValid && parallelExecutionValid && - cleanupValid && isolationValid; - }); - } - - /// - /// Validates test environment configuration for CI/CD scenarios - /// - private static bool ValidateTestEnvironment(CiCdTestScenario scenario) - { - // Requirement 9.1: Tests should run against both LocalStack and real AWS services - var environmentConfigured = scenario.UseLocalStack || HasAwsCredentials(); - - // Environment should have proper configuration - var configurationValid = !string.IsNullOrEmpty(scenario.TestPrefix) && - scenario.TestPrefix.Length <= 50 && // AWS resource name limits - scenario.TestPrefix.All(c => char.IsLetterOrDigit(c) || c == '-'); - - return environmentConfigured && configurationValid; - } - - /// - /// Validates resource naming for conflict prevention - /// - private static bool ValidateResourceNaming(CiCdTestScenario scenario) - { - // Requirement 9.5: Unique resource naming prevents test interference - var hasUniquePrefix = !string.IsNullOrEmpty(scenario.TestPrefix) && - !string.IsNullOrEmpty(scenario.TestId); - - // Resource names should follow AWS naming conventions - var validNaming = scenario.TestPrefix.Length >= 3 && // Minimum length - scenario.TestPrefix.Length <= 20 && // Reasonable max for prefix - !scenario.TestPrefix.StartsWith('-') && - !scenario.TestPrefix.EndsWith('-') && - scenario.TestPrefix.All(c => char.IsLetterOrDigit(c) || c == '-'); // Only alphanumeric and hyphens - - // Test ID should be unique and valid - var validTestId = scenario.TestId.Length >= 8 && - scenario.TestId.All(c => char.IsLetterOrDigit(c)); - - return hasUniquePrefix && validNaming && validTestId; - } - - /// - /// Validates parallel execution configuration - /// - private static bool ValidateParallelExecution(CiCdTestScenario scenario) - { - // Requirement 9.3: Test environment isolation and parallel execution - var parallelCountValid = scenario.ParallelTestCount >= 1 && - scenario.ParallelTestCount <= 10; // Reasonable limit - - // Each parallel test should have unique resource identifiers - var resourceCountValid = scenario.ResourceCount >= 1 && - scenario.ResourceCount <= 5; // Reasonable limit per test - - // Total resources should not exceed reasonable limits - var totalResourcesValid = (scenario.ParallelTestCount * scenario.ResourceCount) <= 50; - - return parallelCountValid && resourceCountValid && totalResourcesValid; - } - - /// - /// Validates resource cleanup configuration - /// - private static bool ValidateResourceCleanup(CiCdTestScenario scenario) - { - // Requirement 9.2: Automatic AWS resource provisioning and cleanup - // Cleanup should be configurable - it's recommended but not always required - // (e.g., for debugging failed tests, cleanup might be disabled) - - // Resource count should be manageable regardless of cleanup setting - var manageableResourceCount = scenario.ResourceCount <= 10; - - // If cleanup is disabled, resource count should be more conservative to prevent resource leaks - var reasonableForNoCleanup = scenario.CleanupEnabled || scenario.ResourceCount <= 5; - - return manageableResourceCount && reasonableForNoCleanup; - } - - /// - /// Validates test isolation mechanisms - /// - private static bool ValidateTestIsolation(CiCdTestScenario scenario) - { - // Requirement 9.5: Proper test isolation prevents interference - var hasIsolationMechanism = !string.IsNullOrEmpty(scenario.TestPrefix) && - !string.IsNullOrEmpty(scenario.TestId); - - // Isolation should work for parallel execution - var isolationScales = scenario.ParallelTestCount <= 10; // Reasonable concurrency limit - - // Resource naming should support isolation - var namingSupportsIsolation = scenario.TestPrefix.Length >= 3 && // Meaningful prefix - scenario.TestId.Length >= 8; // Sufficient uniqueness - - return hasIsolationMechanism && isolationScales && namingSupportsIsolation; - } - - /// - /// Checks if AWS credentials are available (simulated for property testing) - /// - private static bool HasAwsCredentials() - { - // In a real implementation, this would check for AWS credentials - // For property testing, we simulate this check - return true; // Assume credentials are available for testing - } -} diff --git a/tests/SourceFlow.Cloud.AWS.Tests/run-integration-tests.ps1 b/tests/SourceFlow.Cloud.AWS.Tests/run-integration-tests.ps1 deleted file mode 100644 index ef2cb789..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/run-integration-tests.ps1 +++ /dev/null @@ -1,226 +0,0 @@ -#!/usr/bin/env pwsh -<# -.SYNOPSIS - Launches LocalStack via Docker and runs AWS integration tests locally. - -.DESCRIPTION - This script: - 1. Checks Docker is running - 2. Starts a LocalStack container (or reuses an existing one) - 3. Waits for services (SQS, SNS, KMS) to be healthy - 4. Sets required environment variables - 5. Runs the integration tests - 6. Tears down the container (unless -KeepRunning is specified) - -.PARAMETER KeepRunning - Keep LocalStack container running after tests complete. - -.PARAMETER Filter - Optional test filter expression (passed to dotnet test --filter). - -.PARAMETER Configuration - Build configuration (default: Debug). - -.EXAMPLE - ./run-integration-tests.ps1 - ./run-integration-tests.ps1 -KeepRunning - ./run-integration-tests.ps1 -Filter "FullyQualifiedName~SqsStandard" -#> -param( - [switch]$KeepRunning, - [string]$Filter = "", - [string]$Configuration = "Debug" -) - -$ErrorActionPreference = "Stop" -$ContainerName = "sourceflow-localstack" -$LocalStackPort = 4566 -$LocalStackEndpoint = "http://localhost:$LocalStackPort" -$HealthUrl = "$LocalStackEndpoint/_localstack/health" -$ScriptDir = $PSScriptRoot -$ProjectDir = $ScriptDir - -# --- Helper functions --- - -function Write-Step($message) { - Write-Host "`n>> $message" -ForegroundColor Cyan -} - -function Test-DockerRunning { - try { - docker info 2>&1 | Out-Null - return $LASTEXITCODE -eq 0 - } catch { - return $false - } -} - -function Test-LocalStackHealthy { - try { - $response = Invoke-RestMethod -Uri $HealthUrl -TimeoutSec 5 -ErrorAction Stop - return $true - } catch { - return $false - } -} - -function Wait-ForLocalStack { - param([int]$MaxAttempts = 30, [int]$DelaySeconds = 3) - - Write-Host "Waiting for LocalStack to become healthy..." - for ($i = 1; $i -le $MaxAttempts; $i++) { - if (Test-LocalStackHealthy) { - Write-Host "LocalStack is healthy!" -ForegroundColor Green - $health = Invoke-RestMethod -Uri $HealthUrl -TimeoutSec 5 - Write-Host "Services: $($health.services | ConvertTo-Json -Compress)" - return $true - } - Write-Host " Attempt $i/$MaxAttempts - not ready yet..." - Start-Sleep -Seconds $DelaySeconds - } - Write-Host "LocalStack did not become healthy in time." -ForegroundColor Red - return $false -} - -function Wait-ForServices { - param([string[]]$Services = @("sqs", "sns", "kms"), [int]$MaxAttempts = 20, [int]$DelaySeconds = 3) - - Write-Host "Waiting for services: $($Services -join ', ')..." - for ($i = 1; $i -le $MaxAttempts; $i++) { - try { - $health = Invoke-RestMethod -Uri $HealthUrl -TimeoutSec 5 - $allReady = $true - foreach ($svc in $Services) { - $status = $health.services.$svc - if ($status -ne "available" -and $status -ne "running") { - $allReady = $false - break - } - } - if ($allReady) { - Write-Host "All services ready!" -ForegroundColor Green - return $true - } - } catch { } - Write-Host " Attempt $i/$MaxAttempts - services not all ready..." - Start-Sleep -Seconds $DelaySeconds - } - Write-Host "Services did not become ready in time." -ForegroundColor Red - return $false -} - -# --- Main --- - -Write-Step "Checking Docker" -if (-not (Test-DockerRunning)) { - Write-Host "Docker is not running. Please start Docker Desktop and try again." -ForegroundColor Red - exit 1 -} -Write-Host "Docker is running." -ForegroundColor Green - -# Check if LocalStack is already running -$existingContainer = docker ps --filter "name=$ContainerName" --format "{{.Names}}" 2>$null -$alreadyRunning = $false - -if ($existingContainer -eq $ContainerName) { - Write-Step "Found existing LocalStack container '$ContainerName'" - if (Test-LocalStackHealthy) { - Write-Host "Container is healthy - reusing it." -ForegroundColor Green - $alreadyRunning = $true - } else { - Write-Host "Container exists but not healthy. Removing and recreating..." - docker rm -f $ContainerName 2>$null | Out-Null - } -} else { - # Also check if any container is using port 4566 - $portInUse = docker ps --format "{{.Ports}}" 2>$null | Select-String ":$LocalStackPort->" - if ($portInUse) { - Write-Host "Port $LocalStackPort is already in use by another container." -ForegroundColor Yellow - if (Test-LocalStackHealthy) { - Write-Host "LocalStack is responding on port $LocalStackPort - reusing it." -ForegroundColor Green - $alreadyRunning = $true - } else { - Write-Host "Port $LocalStackPort is in use but not responding as LocalStack." -ForegroundColor Red - Write-Host "Please free port $LocalStackPort and try again." - exit 1 - } - } -} - -if (-not $alreadyRunning) { - Write-Step "Starting LocalStack container" - docker run -d ` - --name $ContainerName ` - -p "${LocalStackPort}:${LocalStackPort}" ` - -e "SERVICES=sqs,sns,kms" ` - -e "DEBUG=1" ` - -e "EAGER_SERVICE_LOADING=1" ` - -e "SKIP_SSL_CERT_DOWNLOAD=1" ` - localstack/localstack:3 - - if ($LASTEXITCODE -ne 0) { - Write-Host "Failed to start LocalStack container." -ForegroundColor Red - exit 1 - } - Write-Host "Container started." -ForegroundColor Green -} - -Write-Step "Waiting for LocalStack health" -if (-not (Wait-ForLocalStack)) { - Write-Host "Dumping container logs for diagnostics:" -ForegroundColor Yellow - docker logs $ContainerName 2>&1 | Select-Object -Last 30 - exit 1 -} - -Write-Step "Waiting for AWS services" -if (-not (Wait-ForServices -Services @("sqs", "sns", "kms"))) { - Write-Host "Dumping container logs for diagnostics:" -ForegroundColor Yellow - docker logs $ContainerName 2>&1 | Select-Object -Last 30 - exit 1 -} - -Write-Step "Setting environment variables" -$env:AWS_ACCESS_KEY_ID = "test" -$env:AWS_SECRET_ACCESS_KEY = "test" -$env:AWS_DEFAULT_REGION = "us-east-1" -$env:AWS_ENDPOINT_URL = $LocalStackEndpoint - -Write-Host " AWS_ACCESS_KEY_ID = $env:AWS_ACCESS_KEY_ID" -Write-Host " AWS_SECRET_ACCESS_KEY = $env:AWS_SECRET_ACCESS_KEY" -Write-Host " AWS_DEFAULT_REGION = $env:AWS_DEFAULT_REGION" -Write-Host " AWS_ENDPOINT_URL = $env:AWS_ENDPOINT_URL" - -Write-Step "Running integration tests" -$testArgs = @( - "test" - $ProjectDir - "--configuration", $Configuration - "--logger", "console;verbosity=normal" - "--", "RunConfiguration.TestSessionTimeout=600000" -) - -if ($Filter) { - $testArgs += "--filter" - $testArgs += $Filter -} - -& dotnet @testArgs -$testExitCode = $LASTEXITCODE - -if (-not $KeepRunning -and -not $alreadyRunning) { - Write-Step "Stopping LocalStack container" - docker rm -f $ContainerName 2>$null | Out-Null - Write-Host "Container removed." -ForegroundColor Green -} else { - Write-Host "`nLocalStack container '$ContainerName' is still running." -ForegroundColor Yellow - Write-Host " Stop it with: docker rm -f $ContainerName" -} - -Write-Host "" -if ($testExitCode -eq 0) { - Write-Host "All tests passed!" -ForegroundColor Green -} else { - Write-Host "Some tests failed (exit code: $testExitCode)." -ForegroundColor Red -} - -exit $testExitCode diff --git a/tests/SourceFlow.Cloud.AWS.Tests/run-integration-tests.sh b/tests/SourceFlow.Cloud.AWS.Tests/run-integration-tests.sh deleted file mode 100644 index 908ac657..00000000 --- a/tests/SourceFlow.Cloud.AWS.Tests/run-integration-tests.sh +++ /dev/null @@ -1,205 +0,0 @@ -#!/usr/bin/env bash -# -# Launches LocalStack via Docker and runs AWS integration tests locally. -# -# Usage: -# ./run-integration-tests.sh # run all tests, stop container after -# ./run-integration-tests.sh --keep # keep container running after tests -# ./run-integration-tests.sh --filter "Name~SqsStandard" # run subset of tests -# ./run-integration-tests.sh --configuration Release # use Release build -# -set -euo pipefail - -CONTAINER_NAME="sourceflow-localstack" -LOCALSTACK_PORT=4566 -LOCALSTACK_ENDPOINT="http://localhost:${LOCALSTACK_PORT}" -HEALTH_URL="${LOCALSTACK_ENDPOINT}/_localstack/health" -SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -PROJECT_DIR="$SCRIPT_DIR" - -KEEP_RUNNING=false -FILTER="" -CONFIGURATION="Debug" - -# --- Parse arguments --- -while [[ $# -gt 0 ]]; do - case "$1" in - --keep) KEEP_RUNNING=true; shift ;; - --filter) FILTER="$2"; shift 2 ;; - --configuration) CONFIGURATION="$2"; shift 2 ;; - *) echo "Unknown argument: $1"; exit 1 ;; - esac -done - -# --- Helper functions --- - -step() { printf "\n\033[36m>> %s\033[0m\n" "$1"; } -ok() { printf "\033[32m%s\033[0m\n" "$1"; } -warn() { printf "\033[33m%s\033[0m\n" "$1"; } -err() { printf "\033[31m%s\033[0m\n" "$1"; } - -check_docker() { - if ! docker info >/dev/null 2>&1; then - err "Docker is not running. Please start Docker and try again." - exit 1 - fi -} - -check_localstack_healthy() { - curl -sf "$HEALTH_URL" >/dev/null 2>&1 -} - -wait_for_localstack() { - local max_attempts=${1:-30} - local delay=${2:-3} - echo "Waiting for LocalStack to become healthy..." - for ((i=1; i<=max_attempts; i++)); do - if check_localstack_healthy; then - ok "LocalStack is healthy!" - curl -s "$HEALTH_URL" | python3 -m json.tool 2>/dev/null || curl -s "$HEALTH_URL" - return 0 - fi - echo " Attempt $i/$max_attempts - not ready yet..." - sleep "$delay" - done - err "LocalStack did not become healthy in time." - return 1 -} - -wait_for_services() { - local services=("sqs" "sns" "kms") - local max_attempts=20 - local delay=3 - echo "Waiting for services: ${services[*]}..." - for ((i=1; i<=max_attempts; i++)); do - local all_ready=true - local health - health=$(curl -sf "$HEALTH_URL" 2>/dev/null) || { all_ready=false; } - if $all_ready; then - for svc in "${services[@]}"; do - local status - status=$(echo "$health" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('services',{}).get('$svc',''))" 2>/dev/null || echo "") - if [[ "$status" != "available" && "$status" != "running" ]]; then - all_ready=false - break - fi - done - fi - if $all_ready; then - ok "All services ready!" - return 0 - fi - echo " Attempt $i/$max_attempts - services not all ready..." - sleep "$delay" - done - err "Services did not become ready in time." - return 1 -} - -# --- Main --- - -step "Checking Docker" -check_docker -ok "Docker is running." - -ALREADY_RUNNING=false - -# Check for existing container -existing=$(docker ps --filter "name=$CONTAINER_NAME" --format "{{.Names}}" 2>/dev/null || true) -if [[ "$existing" == "$CONTAINER_NAME" ]]; then - step "Found existing LocalStack container '$CONTAINER_NAME'" - if check_localstack_healthy; then - ok "Container is healthy - reusing it." - ALREADY_RUNNING=true - else - warn "Container exists but not healthy. Removing and recreating..." - docker rm -f "$CONTAINER_NAME" >/dev/null 2>&1 || true - fi -else - # Check if port is in use by another container - if docker ps --format "{{.Ports}}" 2>/dev/null | grep -q ":${LOCALSTACK_PORT}->"; then - if check_localstack_healthy; then - ok "LocalStack is responding on port $LOCALSTACK_PORT - reusing it." - ALREADY_RUNNING=true - else - err "Port $LOCALSTACK_PORT is in use but not responding as LocalStack." - echo "Please free port $LOCALSTACK_PORT and try again." - exit 1 - fi - fi -fi - -if ! $ALREADY_RUNNING; then - step "Starting LocalStack container" - docker run -d \ - --name "$CONTAINER_NAME" \ - -p "${LOCALSTACK_PORT}:${LOCALSTACK_PORT}" \ - -e "SERVICES=sqs,sns,kms" \ - -e "DEBUG=1" \ - -e "EAGER_SERVICE_LOADING=1" \ - -e "SKIP_SSL_CERT_DOWNLOAD=1" \ - localstack/localstack:3 - - ok "Container started." -fi - -step "Waiting for LocalStack health" -if ! wait_for_localstack; then - warn "Dumping container logs for diagnostics:" - docker logs "$CONTAINER_NAME" 2>&1 | tail -30 - exit 1 -fi - -step "Waiting for AWS services" -if ! wait_for_services; then - warn "Dumping container logs for diagnostics:" - docker logs "$CONTAINER_NAME" 2>&1 | tail -30 - exit 1 -fi - -step "Setting environment variables" -export AWS_ACCESS_KEY_ID="test" -export AWS_SECRET_ACCESS_KEY="test" -export AWS_DEFAULT_REGION="us-east-1" -export AWS_ENDPOINT_URL="$LOCALSTACK_ENDPOINT" - -echo " AWS_ACCESS_KEY_ID = $AWS_ACCESS_KEY_ID" -echo " AWS_SECRET_ACCESS_KEY = $AWS_SECRET_ACCESS_KEY" -echo " AWS_DEFAULT_REGION = $AWS_DEFAULT_REGION" -echo " AWS_ENDPOINT_URL = $AWS_ENDPOINT_URL" - -step "Running integration tests" -test_args=( - test "$PROJECT_DIR" - --configuration "$CONFIGURATION" - --logger "console;verbosity=normal" - -- "RunConfiguration.TestSessionTimeout=600000" -) - -if [[ -n "$FILTER" ]]; then - test_args+=(--filter "$FILTER") -fi - -set +e -dotnet "${test_args[@]}" -TEST_EXIT=$? -set -e - -if ! $KEEP_RUNNING && ! $ALREADY_RUNNING; then - step "Stopping LocalStack container" - docker rm -f "$CONTAINER_NAME" >/dev/null 2>&1 || true - ok "Container removed." -else - echo "" - warn "LocalStack container '$CONTAINER_NAME' is still running." - echo " Stop it with: docker rm -f $CONTAINER_NAME" -fi - -echo "" -if [[ $TEST_EXIT -eq 0 ]]; then - ok "All tests passed!" -else - err "Some tests failed (exit code: $TEST_EXIT)." -fi - -exit $TEST_EXIT diff --git a/tests/SourceFlow.Cloud.GCP.Tests/Integration/PubSubEmulatorFixture.cs b/tests/SourceFlow.Cloud.GCP.Tests/Integration/PubSubEmulatorFixture.cs deleted file mode 100644 index 31508b00..00000000 --- a/tests/SourceFlow.Cloud.GCP.Tests/Integration/PubSubEmulatorFixture.cs +++ /dev/null @@ -1,53 +0,0 @@ -using Google.Cloud.PubSub.V1; -using SourceFlow.Cloud.GCP.Infrastructure; - -namespace SourceFlow.Cloud.GCP.Tests.Integration; - -/// -/// Shared fixture for Pub/Sub integration tests. Connects to the Pub/Sub emulator when -/// PUBSUB_EMULATOR_HOST is set; otherwise tests using it are skipped. -/// -public sealed class PubSubEmulatorFixture -{ - public bool EmulatorAvailable { get; } - public string ProjectId { get; } - public PublisherServiceApiClient? Publisher { get; } - public SubscriberServiceApiClient? Subscriber { get; } - - public PubSubEmulatorFixture() - { - EmulatorAvailable = !string.IsNullOrEmpty(Environment.GetEnvironmentVariable("PUBSUB_EMULATOR_HOST")); - ProjectId = "sourceflow-it-" + Guid.NewGuid().ToString("N").Substring(0, 8); - - if (EmulatorAvailable) - { - Publisher = PubSubClientFactory.CreatePublisher(); - Subscriber = PubSubClientFactory.CreateSubscriber(); - } - } - - /// Pulls from a subscription, retrying briefly to absorb publish/pull propagation lag. - public async Task> PullWithRetryAsync(SubscriptionName subscription, int expected, int attempts = 10) - { - var collected = new List(); - for (var i = 0; i < attempts && collected.Count < expected; i++) - { - var response = await Subscriber!.PullAsync(new PullRequest - { - SubscriptionAsSubscriptionName = subscription, - MaxMessages = expected - }); - - if (response.ReceivedMessages.Count > 0) - { - collected.AddRange(response.ReceivedMessages); - await Subscriber.AcknowledgeAsync(subscription, response.ReceivedMessages.Select(m => m.AckId)); - } - else - { - await Task.Delay(250); - } - } - return collected; - } -} diff --git a/tests/SourceFlow.Cloud.GCP.Tests/Integration/PubSubRoundTripTests.cs b/tests/SourceFlow.Cloud.GCP.Tests/Integration/PubSubRoundTripTests.cs deleted file mode 100644 index 9dd5c90f..00000000 --- a/tests/SourceFlow.Cloud.GCP.Tests/Integration/PubSubRoundTripTests.cs +++ /dev/null @@ -1,137 +0,0 @@ -using Google.Cloud.PubSub.V1; -using Microsoft.Extensions.Logging.Abstractions; -using Moq; -using SourceFlow.Cloud.Configuration; -using SourceFlow.Cloud.GCP.Configuration; -using SourceFlow.Cloud.GCP.Infrastructure; -using SourceFlow.Cloud.GCP.Messaging.Commands; -using SourceFlow.Cloud.GCP.Messaging.Events; -using SourceFlow.Cloud.GCP.Tests.TestHelpers; -using SourceFlow.Messaging.Commands; -using SourceFlow.Observability; - -namespace SourceFlow.Cloud.GCP.Tests.Integration; - -/// -/// End-to-end tests against the Pub/Sub emulator: bootstrap provisioning, command publish→pull, -/// and event publish→pull. Skipped unless PUBSUB_EMULATOR_HOST is set. -/// -[Trait("Category", TestCategories.Integration)] -public class PubSubRoundTripTests : IClassFixture -{ - private readonly PubSubEmulatorFixture _fixture; - - public PubSubRoundTripTests(PubSubEmulatorFixture fixture) => _fixture = fixture; - - private GcpOptions Options() => new() { ProjectId = _fixture.ProjectId }; - - private async Task BootstrapAsync(string commandQueue, string eventTopic) - { - var builder = new BusConfigurationBuilder(); - builder - .Send.Command(q => q.Queue(commandQueue)) - .Raise.Event(t => t.Topic(eventTopic)) - .Listen.To.CommandQueue(commandQueue) - .Subscribe.To.Topic(eventTopic); - var busConfig = builder.Build(); - - var bootstrapper = new GcpBusBootstrapper( - busConfig, _fixture.Publisher!, _fixture.Subscriber!, Options(), - NullLogger.Instance); - - await bootstrapper.StartAsync(default); - return busConfig; - } - - [SkippableFact] - public async Task Bootstrapper_Provisions_Topics_And_Subscriptions() - { - Skip.IfNot(_fixture.EmulatorAvailable, "PUBSUB_EMULATOR_HOST is not set."); - - var suffix = Guid.NewGuid().ToString("N").Substring(0, 6); - var commandQueue = $"it-commands-{suffix}"; - var eventTopic = $"it-events-{suffix}"; - - await BootstrapAsync(commandQueue, eventTopic); - - // Topics exist - await _fixture.Publisher!.GetTopicAsync(TopicName.FromProjectTopic(_fixture.ProjectId, commandQueue)); - await _fixture.Publisher.GetTopicAsync(TopicName.FromProjectTopic(_fixture.ProjectId, eventTopic)); - - // Subscriptions exist - await _fixture.Subscriber!.GetSubscriptionAsync(SubscriptionName.FromProjectSubscription(_fixture.ProjectId, $"{commandQueue}-sub")); - await _fixture.Subscriber.GetSubscriptionAsync(SubscriptionName.FromProjectSubscription(_fixture.ProjectId, $"{eventTopic}-sub")); - } - - [SkippableFact] - public async Task CommandDispatch_Publishes_Message_Pullable_From_Subscription() - { - Skip.IfNot(_fixture.EmulatorAvailable, "PUBSUB_EMULATOR_HOST is not set."); - - var suffix = Guid.NewGuid().ToString("N").Substring(0, 6); - var commandQueue = $"it-commands-{suffix}"; - var busConfig = await BootstrapAsync(commandQueue, $"it-events-{suffix}"); - - var dispatcher = new PubSubCommandDispatcher( - _fixture.Publisher!, busConfig, NullLogger.Instance, Mock.Of()); - - var command = new TestCommand - { - Name = "CreateOrder", - Entity = new EntityRef { Id = 99 }, - Payload = new TestPayload { Data = "round-trip", Value = 5 } - }; - command.Metadata.SequenceNo = 3; - - await dispatcher.Dispatch(command); - - var subscription = SubscriptionName.FromProjectSubscription(_fixture.ProjectId, $"{commandQueue}-sub"); - var messages = await _fixture.PullWithRetryAsync(subscription, expected: 1); - - var received = Assert.Single(messages); - Assert.Equal(typeof(TestCommand).AssemblyQualifiedName, received.Message.Attributes["CommandType"]); - Assert.Equal("99", received.Message.Attributes["EntityId"]); - Assert.Equal("3", received.Message.Attributes["SequenceNo"]); - // The command Name round-trips in the JSON body (the IPayload-typed Payload is - // serialized by its declared interface type, matching the AWS base dispatcher). - Assert.Contains("CreateOrder", received.Message.Data.ToStringUtf8()); - } - - [SkippableFact] - public async Task EventDispatch_Publishes_Message_Pullable_From_Subscription() - { - Skip.IfNot(_fixture.EmulatorAvailable, "PUBSUB_EMULATOR_HOST is not set."); - - var suffix = Guid.NewGuid().ToString("N").Substring(0, 6); - var eventTopic = $"it-events-{suffix}"; - var busConfig = await BootstrapAsync($"it-commands-{suffix}", eventTopic); - - var dispatcher = new PubSubEventDispatcher( - _fixture.Publisher!, busConfig, NullLogger.Instance, Mock.Of()); - - await dispatcher.Dispatch(new TestEvent { Name = "OrderCreated", Payload = new TestEntity { Id = 7 } }); - - var subscription = SubscriptionName.FromProjectSubscription(_fixture.ProjectId, $"{eventTopic}-sub"); - var messages = await _fixture.PullWithRetryAsync(subscription, expected: 1); - - var received = Assert.Single(messages); - Assert.Equal(typeof(TestEvent).AssemblyQualifiedName, received.Message.Attributes["EventType"]); - Assert.Equal("OrderCreated", received.Message.Attributes["EventName"]); - } - - [SkippableFact] - public async Task Bootstrap_Is_Idempotent_On_Repeated_Runs() - { - Skip.IfNot(_fixture.EmulatorAvailable, "PUBSUB_EMULATOR_HOST is not set."); - - var suffix = Guid.NewGuid().ToString("N").Substring(0, 6); - var commandQueue = $"it-commands-{suffix}"; - var eventTopic = $"it-events-{suffix}"; - - await BootstrapAsync(commandQueue, eventTopic); - - // Running again must not throw (AlreadyExists tolerated). - var ex = await Record.ExceptionAsync(() => BootstrapAsync(commandQueue, eventTopic)); - Assert.Null(ex); - } -} diff --git a/tests/SourceFlow.Cloud.GCP.Tests/SourceFlow.Cloud.GCP.Tests.csproj b/tests/SourceFlow.Cloud.GCP.Tests/SourceFlow.Cloud.GCP.Tests.csproj deleted file mode 100644 index c55e8c2e..00000000 --- a/tests/SourceFlow.Cloud.GCP.Tests/SourceFlow.Cloud.GCP.Tests.csproj +++ /dev/null @@ -1,35 +0,0 @@ - - - - net9.0 - latest - enable - enable - false - true - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/tests/SourceFlow.Cloud.GCP.Tests/TestHelpers/TestMessages.cs b/tests/SourceFlow.Cloud.GCP.Tests/TestHelpers/TestMessages.cs deleted file mode 100644 index f185e6ba..00000000 --- a/tests/SourceFlow.Cloud.GCP.Tests/TestHelpers/TestMessages.cs +++ /dev/null @@ -1,39 +0,0 @@ -using SourceFlow; -using SourceFlow.Messaging; -using SourceFlow.Messaging.Commands; -using SourceFlow.Messaging.Events; - -namespace SourceFlow.Cloud.GCP.Tests.TestHelpers; - -/// Test categories used as xUnit traits for filtering. -public static class TestCategories -{ - public const string Unit = "Unit"; - public const string Integration = "Integration"; -} - -public class TestPayload : IPayload -{ - public string Data { get; set; } = string.Empty; - public int Value { get; set; } -} - -public class TestEntity : IEntity -{ - public int Id { get; set; } -} - -public class TestCommand : ICommand -{ - public string Name { get; set; } = "TestCommand"; - public IPayload Payload { get; set; } = new TestPayload(); - public EntityRef Entity { get; set; } = new EntityRef { Id = 1 }; - public Metadata Metadata { get; set; } = new Metadata(); -} - -public class TestEvent : IEvent -{ - public string Name { get; set; } = "TestEvent"; - public IEntity Payload { get; set; } = new TestEntity { Id = 1 }; - public Metadata Metadata { get; set; } = new Metadata(); -} diff --git a/tests/SourceFlow.Cloud.GCP.Tests/Unit/GcpIocExtensionsTests.cs b/tests/SourceFlow.Cloud.GCP.Tests/Unit/GcpIocExtensionsTests.cs deleted file mode 100644 index f12e3b74..00000000 --- a/tests/SourceFlow.Cloud.GCP.Tests/Unit/GcpIocExtensionsTests.cs +++ /dev/null @@ -1,91 +0,0 @@ -using Microsoft.Extensions.DependencyInjection; -using Microsoft.Extensions.Diagnostics.HealthChecks; -using Microsoft.Extensions.Hosting; -using SourceFlow.Cloud.Configuration; -using SourceFlow.Cloud.GCP; -using SourceFlow.Cloud.GCP.Configuration; -using SourceFlow.Cloud.GCP.Tests.TestHelpers; -using SourceFlow.Messaging.Commands; -using SourceFlow.Messaging.Events; - -namespace SourceFlow.Cloud.GCP.Tests.Unit; - -[Trait("Category", TestCategories.Unit)] -public class GcpIocExtensionsTests -{ - private static IServiceCollection Configure() - { - var services = new ServiceCollection(); - services.AddLogging(); - services.UseSourceFlowGcp( - options => { options.ProjectId = "test-project"; }, - bus => bus - .Send.Command(q => q.Queue("orders")) - .Raise.Event(t => t.Topic("order-events")) - .Listen.To.CommandQueue("orders") - .Subscribe.To.Topic("order-events")); - return services; - } - - [Fact] - public void Registers_Dispatchers_And_RoutingConfiguration() - { - var services = Configure(); - - Assert.Contains(services, d => d.ServiceType == typeof(ICommandDispatcher)); - Assert.Contains(services, d => d.ServiceType == typeof(IEventDispatcher)); - Assert.Contains(services, d => d.ServiceType == typeof(ICommandRoutingConfiguration)); - Assert.Contains(services, d => d.ServiceType == typeof(IEventRoutingConfiguration)); - Assert.Contains(services, d => d.ServiceType == typeof(IBusBootstrapConfiguration)); - Assert.Contains(services, d => d.ServiceType == typeof(GcpOptions)); - } - - [Fact] - public void Registers_InMemory_Idempotency_AsSingleton() - { - var services = Configure(); - - var descriptor = Assert.Single(services, d => d.ServiceType == typeof(IIdempotencyService)); - Assert.Equal(ServiceLifetime.Singleton, descriptor.Lifetime); - } - - [Fact] - public void Registers_Bootstrapper_And_Listeners_As_HostedServices() - { - var services = Configure(); - - var hosted = services - .Where(d => d.ServiceType == typeof(IHostedService)) - .Select(d => d.ImplementationType) - .ToList(); - - Assert.Contains(typeof(SourceFlow.Cloud.GCP.Infrastructure.GcpBusBootstrapper), hosted); - Assert.Contains(typeof(SourceFlow.Cloud.GCP.Messaging.Commands.PubSubCommandListener), hosted); - Assert.Contains(typeof(SourceFlow.Cloud.GCP.Messaging.Events.PubSubEventListener), hosted); - } - - [Fact] - public void Registers_HealthCheck() - { - var services = Configure(); - Assert.Contains(services, d => d.ServiceType == typeof(IHealthCheck)); - } - - [Fact] - public void Listeners_NotRegistered_When_Disabled() - { - var services = new ServiceCollection(); - services.AddLogging(); - services.UseSourceFlowGcp( - options => { options.ProjectId = "test-project"; options.EnableCommandListener = false; options.EnableEventListener = false; }, - bus => bus.Send.Command(q => q.Queue("orders"))); - - var hosted = services - .Where(d => d.ServiceType == typeof(IHostedService)) - .Select(d => d.ImplementationType) - .ToList(); - - Assert.DoesNotContain(typeof(SourceFlow.Cloud.GCP.Messaging.Commands.PubSubCommandListener), hosted); - Assert.DoesNotContain(typeof(SourceFlow.Cloud.GCP.Messaging.Events.PubSubEventListener), hosted); - } -} diff --git a/tests/SourceFlow.Cloud.GCP.Tests/Unit/GcpOptionsTests.cs b/tests/SourceFlow.Cloud.GCP.Tests/Unit/GcpOptionsTests.cs deleted file mode 100644 index f4bc5405..00000000 --- a/tests/SourceFlow.Cloud.GCP.Tests/Unit/GcpOptionsTests.cs +++ /dev/null @@ -1,23 +0,0 @@ -using SourceFlow.Cloud.GCP.Configuration; -using SourceFlow.Cloud.GCP.Tests.TestHelpers; - -namespace SourceFlow.Cloud.GCP.Tests.Unit; - -[Trait("Category", TestCategories.Unit)] -public class GcpOptionsTests -{ - [Fact] - public void Defaults_AreSensible() - { - var options = new GcpOptions(); - - Assert.Equal(string.Empty, options.ProjectId); - Assert.True(options.EnableCommandRouting); - Assert.True(options.EnableEventRouting); - Assert.True(options.EnableCommandListener); - Assert.True(options.EnableEventListener); - Assert.Equal(10, options.MaxMessagesPerPull); - Assert.Equal(60, options.AckDeadlineSeconds); - Assert.Equal("-sub", options.SubscriptionSuffix); - } -} diff --git a/tests/SourceFlow.Cloud.GCP.Tests/Unit/PubSubCommandDispatcherTests.cs b/tests/SourceFlow.Cloud.GCP.Tests/Unit/PubSubCommandDispatcherTests.cs deleted file mode 100644 index 44719132..00000000 --- a/tests/SourceFlow.Cloud.GCP.Tests/Unit/PubSubCommandDispatcherTests.cs +++ /dev/null @@ -1,71 +0,0 @@ -using Google.Api.Gax.Grpc; -using Google.Cloud.PubSub.V1; -using Microsoft.Extensions.Logging.Abstractions; -using Moq; -using SourceFlow.Cloud.Configuration; -using SourceFlow.Cloud.GCP.Messaging.Commands; -using SourceFlow.Cloud.GCP.Tests.TestHelpers; -using SourceFlow.Observability; - -namespace SourceFlow.Cloud.GCP.Tests.Unit; - -[Trait("Category", TestCategories.Unit)] -public class PubSubCommandDispatcherTests -{ - private static PubSubCommandDispatcher CreateDispatcher( - Mock publisher, - Mock routing) - => new( - publisher.Object, - routing.Object, - NullLogger.Instance, - Mock.Of()); - - [Fact] - public async Task Dispatch_SkipsPublish_When_ShouldRoute_IsFalse() - { - var publisher = new Mock(); - var routing = new Mock(); - routing.Setup(r => r.ShouldRoute()).Returns(false); - - await CreateDispatcher(publisher, routing).Dispatch(new TestCommand()); - - publisher.Verify(p => p.PublishAsync( - It.IsAny(), It.IsAny>(), It.IsAny()), - Times.Never); - routing.Verify(r => r.GetQueueName(), Times.Never); - } - - [Fact] - public async Task Dispatch_Publishes_To_ResolvedTopic_With_Attributes() - { - var publisher = new Mock(); - PubsubMessage? captured = null; - TopicName? capturedTopic = null; - publisher - .Setup(p => p.PublishAsync(It.IsAny(), It.IsAny>(), It.IsAny())) - .Callback, CallSettings>((t, msgs, _) => - { - capturedTopic = t; - captured = msgs.Single(); - }) - .ReturnsAsync(new PublishResponse()); - - var routing = new Mock(); - routing.Setup(r => r.ShouldRoute()).Returns(true); - routing.Setup(r => r.GetQueueName()) - .Returns(TopicName.FromProjectTopic("test-project", "orders").ToString()); - - var command = new TestCommand { Entity = new SourceFlow.Messaging.Commands.EntityRef { Id = 42 } }; - command.Metadata.SequenceNo = 7; - - await CreateDispatcher(publisher, routing).Dispatch(command); - - Assert.NotNull(captured); - Assert.Equal("orders", capturedTopic!.TopicId); - Assert.Equal(typeof(TestCommand).AssemblyQualifiedName, captured!.Attributes["CommandType"]); - Assert.Equal("42", captured.Attributes["EntityId"]); - Assert.Equal("7", captured.Attributes["SequenceNo"]); - Assert.Contains("TestCommand", captured.Data.ToStringUtf8()); - } -} diff --git a/tests/SourceFlow.Cloud.GCP.Tests/Unit/PubSubEventDispatcherTests.cs b/tests/SourceFlow.Cloud.GCP.Tests/Unit/PubSubEventDispatcherTests.cs deleted file mode 100644 index 2009c9cc..00000000 --- a/tests/SourceFlow.Cloud.GCP.Tests/Unit/PubSubEventDispatcherTests.cs +++ /dev/null @@ -1,59 +0,0 @@ -using Google.Api.Gax.Grpc; -using Google.Cloud.PubSub.V1; -using Microsoft.Extensions.Logging.Abstractions; -using Moq; -using SourceFlow.Cloud.Configuration; -using SourceFlow.Cloud.GCP.Messaging.Events; -using SourceFlow.Cloud.GCP.Tests.TestHelpers; -using SourceFlow.Observability; - -namespace SourceFlow.Cloud.GCP.Tests.Unit; - -[Trait("Category", TestCategories.Unit)] -public class PubSubEventDispatcherTests -{ - private static PubSubEventDispatcher CreateDispatcher( - Mock publisher, - Mock routing) - => new( - publisher.Object, - routing.Object, - NullLogger.Instance, - Mock.Of()); - - [Fact] - public async Task Dispatch_SkipsPublish_When_ShouldRoute_IsFalse() - { - var publisher = new Mock(); - var routing = new Mock(); - routing.Setup(r => r.ShouldRoute()).Returns(false); - - await CreateDispatcher(publisher, routing).Dispatch(new TestEvent()); - - publisher.Verify(p => p.PublishAsync( - It.IsAny(), It.IsAny>(), It.IsAny()), - Times.Never); - } - - [Fact] - public async Task Dispatch_Publishes_To_ResolvedTopic_With_EventAttributes() - { - var publisher = new Mock(); - PubsubMessage? captured = null; - publisher - .Setup(p => p.PublishAsync(It.IsAny(), It.IsAny>(), It.IsAny())) - .Callback, CallSettings>((_, msgs, _) => captured = msgs.Single()) - .ReturnsAsync(new PublishResponse()); - - var routing = new Mock(); - routing.Setup(r => r.ShouldRoute()).Returns(true); - routing.Setup(r => r.GetTopicName()) - .Returns(TopicName.FromProjectTopic("test-project", "order-events").ToString()); - - await CreateDispatcher(publisher, routing).Dispatch(new TestEvent { Name = "OrderCreated" }); - - Assert.NotNull(captured); - Assert.Equal(typeof(TestEvent).AssemblyQualifiedName, captured!.Attributes["EventType"]); - Assert.Equal("OrderCreated", captured.Attributes["EventName"]); - } -} diff --git a/tests/SourceFlow.Core.Tests/Aggregates/AggregateTests.cs b/tests/SourceFlow.Core.Tests/Aggregates/AggregateTests.cs deleted file mode 100644 index 612df362..00000000 --- a/tests/SourceFlow.Core.Tests/Aggregates/AggregateTests.cs +++ /dev/null @@ -1,110 +0,0 @@ -using Microsoft.Extensions.Logging; -using Moq; -using SourceFlow.Aggregate; -using SourceFlow.Core.Tests.Impl; -using SourceFlow.Messaging.Commands; - -namespace SourceFlow.Core.Tests.Aggregates -{ - [TestFixture] - [Category("Unit")] - public class AggregateTests - { - private Mock commandPublisherMock; - private Mock> loggerMock; - private Lazy lazyCommandPublisher; - private TestAggregate aggregate; - - [SetUp] - public void Setup() - { - commandPublisherMock = new Mock(); - loggerMock = new Mock>(); - lazyCommandPublisher = new Lazy(() => commandPublisherMock.Object); - aggregate = new TestAggregate(lazyCommandPublisher, loggerMock.Object); - } - - [Test] - public void Constructor_SetsCommandPublisher() - { - // Assert - Assert.That(aggregate.GetCommandPublisher().Value, Is.EqualTo(commandPublisherMock.Object)); - } - - [Test] - public void Constructor_SetsLogger() - { - // Assert - Assert.That(aggregate.GetLogger(), Is.EqualTo(loggerMock.Object)); - } - - [Test] - public async Task ReplayCommands_DelegatesToCommandPublisher() - { - // Arrange - var entityId = 42; - - // Act - await aggregate.ReplayCommands(entityId); - - // Assert - commandPublisherMock.Verify(cp => cp.ReplayCommands(entityId), Times.Once); - } - - [Test] - public async Task Send_ValidCommand_DelegatesToCommandPublisher() - { - // Arrange - var command = new DummyCommand(); - - // Act - await aggregate.SendCommand(command); - - // Assert - commandPublisherMock.Verify(cp => cp.Publish(It.IsAny()), Times.Once); - } - - [Test] - public async Task Send_NullCommand_ThrowsArgumentNullException() - { - // Assert - Assert.ThrowsAsync(async () => - await aggregate.SendCommand(null!)); - } - - [Test] - public async Task Send_NullPayload_PublishesCommand() - { - // Arrange - var command = new DummyCommand { Payload = null! }; - - // This should delegate to publisher (no validation in Send method) - await aggregate.SendCommand(command); - - // Assert - commandPublisherMock.Verify(cp => cp.Publish(It.IsAny()), Times.Once); - } - - // Test aggregate concrete implementation - private class TestAggregate : Aggregate - { - public TestAggregate(Lazy commandPublisher, ILogger logger) - : base(commandPublisher, logger) - { - } - - // Expose protected members for testing - public Lazy GetCommandPublisher() => commandPublisher; - - public ILogger GetLogger() => logger; - - // Expose Send method for testing - public Task SendCommand(ICommand command) => Send(command); - } - - private class TestEntity : IEntity - { - public int Id { get; set; } = 1; - } - } -} diff --git a/tests/SourceFlow.Core.Tests/Aggregates/EventSubscriberTests.cs b/tests/SourceFlow.Core.Tests/Aggregates/EventSubscriberTests.cs deleted file mode 100644 index 236e4c20..00000000 --- a/tests/SourceFlow.Core.Tests/Aggregates/EventSubscriberTests.cs +++ /dev/null @@ -1,255 +0,0 @@ -using Microsoft.Extensions.Logging; -using Moq; -using SourceFlow.Aggregate; -using SourceFlow.Messaging.Events; - -namespace SourceFlow.Core.Tests.Aggregates -{ - public class DummyAggregateEntity : IEntity - { - public int Id { get; set; } - } - - public class DummyAggregateEvent : Event - { - public DummyAggregateEvent(DummyAggregateEntity payload) : base(payload) - { - } - } - - public class TestAggregate : IAggregate, ISubscribes - { - public bool Handled { get; private set; } = false; - - public Task On(DummyAggregateEvent @event) - { - Handled = true; - return Task.CompletedTask; - } - } - - public class NonMatchingAggregate : IAggregate - { - // This aggregate does not implement ISubscribes so won't handle DummyAggregateEvent - } - - [TestFixture] - [Category("Unit")] - public class AggregateEventSubscriberTests - { - private Mock> _mockLogger; - private DummyAggregateEvent _testEvent; - - [SetUp] - public void SetUp() - { - _mockLogger = new Mock>(); - _testEvent = new DummyAggregateEvent(new DummyAggregateEntity { Id = 1 }); - } - - [Test] - public void Constructor_WithNullAggregates_ThrowsArgumentNullException() - { - // Arrange - IEnumerable nullAggregates = null!; - - // Act & Assert - Assert.Throws(() => - new EventSubscriber(nullAggregates, _mockLogger.Object, Enumerable.Empty())); - } - - [Test] - public void Constructor_WithNullLogger_ThrowsArgumentNullException() - { - // Arrange - var aggregates = new List { new TestAggregate() }; - - // Act & Assert - Assert.Throws(() => - new EventSubscriber(aggregates, null, Enumerable.Empty())); - } - - [Test] - public void Constructor_NullMiddleware_ThrowsArgumentNullException() - { - // Arrange - var aggregates = new List { new TestAggregate() }; - - // Act & Assert - Assert.Throws(() => - new EventSubscriber(aggregates, _mockLogger.Object, null)); - } - - [Test] - public void Constructor_WithValidParameters_Succeeds() - { - // Arrange - var aggregates = new List { new TestAggregate() }; - - // Act - var subscriber = new EventSubscriber(aggregates, _mockLogger.Object, Enumerable.Empty()); - - // Assert - Assert.IsNotNull(subscriber); - } - - [Test] - public async Task Subscribe_WithMatchingAggregate_HandlesEvent() - { - // Arrange - var testAggregate = new TestAggregate(); - var aggregates = new List { testAggregate }; - var subscriber = new EventSubscriber(aggregates, _mockLogger.Object, Enumerable.Empty()); - - // Act - await subscriber.Subscribe(_testEvent); - - // Assert - Assert.IsTrue(testAggregate.Handled); - } - - [Test] - public async Task Subscribe_WithNonMatchingAggregate_DoesNotHandleEvent() - { - // Arrange - var nonMatchingAggregate = new NonMatchingAggregate(); - var aggregates = new List { nonMatchingAggregate }; - var subscriber = new EventSubscriber(aggregates, _mockLogger.Object, Enumerable.Empty()); - - // Act - await subscriber.Subscribe(_testEvent); - - // This test is more about ensuring no exception is thrown and that non-matching aggregates - // are simply skipped, which is the expected behavior - } - - [Test] - public async Task Subscribe_WithMultipleAggregates_HandlesEventInMatchingAggregatesOnly() - { - // Arrange - var matchingAggregate1 = new TestAggregate(); - var matchingAggregate2 = new TestAggregate(); - var nonMatchingAggregate = new NonMatchingAggregate(); - var aggregates = new List { matchingAggregate1, nonMatchingAggregate, matchingAggregate2 }; - var subscriber = new EventSubscriber(aggregates, _mockLogger.Object, Enumerable.Empty()); - - // Act - await subscriber.Subscribe(_testEvent); - - // Assert - Assert.IsTrue(matchingAggregate1.Handled); - Assert.IsTrue(matchingAggregate2.Handled); - } - - [Test] - public async Task Subscribe_WithNoMatchingAggregates_DoesNotThrow() - { - // Arrange - var nonMatchingAggregate = new NonMatchingAggregate(); - var aggregates = new List { nonMatchingAggregate }; - var subscriber = new EventSubscriber(aggregates, _mockLogger.Object, Enumerable.Empty()); - - // Act & Assert - Assert.DoesNotThrowAsync(async () => await subscriber.Subscribe(_testEvent)); - } - - [Test] - public async Task Subscribe_WithEmptyAggregatesCollection_DoesNotThrow() - { - // Arrange - var aggregates = new List(); - var subscriber = new EventSubscriber(aggregates, _mockLogger.Object, Enumerable.Empty()); - - // Act & Assert - Assert.DoesNotThrowAsync(async () => await subscriber.Subscribe(_testEvent)); - } - - [Test] - public async Task Subscribe_WithMiddleware_ExecutesMiddlewareAroundCoreLogic() - { - // Arrange - var callOrder = new List(); - var testAggregate = new TestAggregate(); - var aggregates = new List { testAggregate }; - - var middlewareMock = new Mock(); - middlewareMock - .Setup(m => m.InvokeAsync(It.IsAny(), It.IsAny>())) - .Returns>(async (evt, next) => - { - callOrder.Add("middleware-before"); - await next(evt); - callOrder.Add("middleware-after"); - }); - - var subscriber = new EventSubscriber(aggregates, _mockLogger.Object, new[] { middlewareMock.Object }); - - // Act - await subscriber.Subscribe(_testEvent); - - // Assert - Assert.That(callOrder[0], Is.EqualTo("middleware-before")); - Assert.That(callOrder[1], Is.EqualTo("middleware-after")); - Assert.IsTrue(testAggregate.Handled); - } - - [Test] - public async Task Subscribe_WithMultipleMiddleware_ExecutesInRegistrationOrder() - { - // Arrange - var callOrder = new List(); - var testAggregate = new TestAggregate(); - var aggregates = new List { testAggregate }; - - var middleware1 = new Mock(); - middleware1 - .Setup(m => m.InvokeAsync(It.IsAny(), It.IsAny>())) - .Returns>(async (evt, next) => - { - callOrder.Add("m1-before"); - await next(evt); - callOrder.Add("m1-after"); - }); - - var middleware2 = new Mock(); - middleware2 - .Setup(m => m.InvokeAsync(It.IsAny(), It.IsAny>())) - .Returns>(async (evt, next) => - { - callOrder.Add("m2-before"); - await next(evt); - callOrder.Add("m2-after"); - }); - - var subscriber = new EventSubscriber(aggregates, _mockLogger.Object, - new IEventSubscribeMiddleware[] { middleware1.Object, middleware2.Object }); - - // Act - await subscriber.Subscribe(_testEvent); - - // Assert - Assert.That(callOrder, Is.EqualTo(new[] { "m1-before", "m2-before", "m2-after", "m1-after" })); - } - - [Test] - public async Task Subscribe_MiddlewareShortCircuits_DoesNotCallCoreLogic() - { - // Arrange - var testAggregate = new TestAggregate(); - var aggregates = new List { testAggregate }; - - var middlewareMock = new Mock(); - middlewareMock - .Setup(m => m.InvokeAsync(It.IsAny(), It.IsAny>())) - .Returns(Task.CompletedTask); // Does NOT call next - - var subscriber = new EventSubscriber(aggregates, _mockLogger.Object, new[] { middlewareMock.Object }); - - // Act - await subscriber.Subscribe(_testEvent); - - // Assert - aggregate was never reached - Assert.IsFalse(testAggregate.Handled); - } - } -} diff --git a/tests/SourceFlow.Core.Tests/Cloud/CircuitBreakerTests.cs b/tests/SourceFlow.Core.Tests/Cloud/CircuitBreakerTests.cs deleted file mode 100644 index d95dd6fb..00000000 --- a/tests/SourceFlow.Core.Tests/Cloud/CircuitBreakerTests.cs +++ /dev/null @@ -1,388 +0,0 @@ -using System; -using System.Collections.Generic; -using System.Threading; -using System.Threading.Tasks; -using Microsoft.Extensions.Logging.Abstractions; -using Microsoft.Extensions.Options; -using SourceFlow.Cloud.Resilience; - -namespace SourceFlow.Core.Tests.Cloud -{ - [TestFixture] - [Category("Unit")] - public class CircuitBreakerTests - { - private CircuitBreaker CreateBreaker(Action? configure = null) - { - var opts = new CircuitBreakerOptions - { - FailureThreshold = 3, - OpenDuration = TimeSpan.FromMinutes(1), - SuccessThreshold = 2, - OperationTimeout = TimeSpan.FromSeconds(30) - }; - configure?.Invoke(opts); - return new CircuitBreaker(Options.Create(opts), NullLogger.Instance); - } - - // ─── Initial state ──────────────────────────────────────────────────────── - - [Test] - public void InitialState_IsClosed() - { - var cb = CreateBreaker(); - Assert.That(cb.State, Is.EqualTo(CircuitState.Closed)); - } - - // ─── Closed → Open after FailureThreshold consecutive failures ─────────── - - [Test] - public async Task ClosedToOpen_AfterExactlyFailureThresholdConsecutiveFailures() - { - var cb = CreateBreaker(o => o.FailureThreshold = 3); - - for (var i = 0; i < 2; i++) - { - try { await cb.ExecuteAsync(() => throw new InvalidOperationException("fail")); } - catch (InvalidOperationException) { } - } - - Assert.That(cb.State, Is.EqualTo(CircuitState.Closed), - "Should still be Closed after FailureThreshold-1 failures"); - - try { await cb.ExecuteAsync(() => throw new InvalidOperationException("fail")); } - catch (InvalidOperationException) { } - - Assert.That(cb.State, Is.EqualTo(CircuitState.Open), - "Should be Open after reaching FailureThreshold failures"); - } - - // ─── Open → throws CircuitBreakerOpenException without calling operation ── - - [Test] - public async Task WhenOpen_ExecuteAsync_ThrowsCircuitBreakerOpenExceptionWithoutCallingOperation() - { - var cb = CreateBreaker(o => o.FailureThreshold = 1); - - try { await cb.ExecuteAsync(() => throw new InvalidOperationException()); } - catch (InvalidOperationException) { } - - Assert.That(cb.State, Is.EqualTo(CircuitState.Open)); - - var operationCalled = false; - Assert.ThrowsAsync(async () => - await cb.ExecuteAsync(() => - { - operationCalled = true; - return Task.FromResult(42); - })); - - Assert.That(operationCalled, Is.False, "Operation lambda must not be called when circuit is Open"); - } - - // ─── Open → HalfOpen after OpenDuration elapses ─────────────────────────── - - [Test] - public async Task OpenToHalfOpen_AfterOpenDurationElapses() - { - var cb = CreateBreaker(o => - { - o.FailureThreshold = 1; - o.OpenDuration = TimeSpan.FromMilliseconds(50); - }); - - try { await cb.ExecuteAsync(() => throw new InvalidOperationException()); } - catch (InvalidOperationException) { } - - Assert.That(cb.State, Is.EqualTo(CircuitState.Open)); - - await Task.Delay(100); - - // Trigger state re-evaluation by calling ExecuteAsync (will succeed, transitioning to HalfOpen first) - var result = await cb.ExecuteAsync(() => Task.FromResult(1)); - Assert.That(cb.State, Is.EqualTo(CircuitState.Closed).Or.EqualTo(CircuitState.HalfOpen), - "After OpenDuration elapses, circuit should transition out of Open"); - } - - // ─── HalfOpen → Closed after SuccessThreshold successes ────────────────── - - [Test] - public async Task HalfOpenToClosed_AfterSuccessThresholdSuccesses() - { - var cb = CreateBreaker(o => - { - o.FailureThreshold = 1; - o.OpenDuration = TimeSpan.FromMilliseconds(50); - o.SuccessThreshold = 2; - }); - - // Trip the breaker - try { await cb.ExecuteAsync(() => throw new InvalidOperationException()); } - catch (InvalidOperationException) { } - - // Wait for Open → HalfOpen - await Task.Delay(100); - - // SuccessThreshold successes - await cb.ExecuteAsync(() => Task.FromResult(1)); - await cb.ExecuteAsync(() => Task.FromResult(1)); - - Assert.That(cb.State, Is.EqualTo(CircuitState.Closed), - "Should be Closed after SuccessThreshold successes in HalfOpen"); - } - - // ─── HalfOpen → Open on first failure ───────────────────────────────────── - - [Test] - public async Task HalfOpenToOpen_OnFirstFailure() - { - var cb = CreateBreaker(o => - { - o.FailureThreshold = 1; - o.OpenDuration = TimeSpan.FromMilliseconds(50); - o.SuccessThreshold = 3; - }); - - try { await cb.ExecuteAsync(() => throw new InvalidOperationException()); } - catch (InvalidOperationException) { } - - await Task.Delay(100); - - // One success to confirm we've entered HalfOpen, then fail - await cb.ExecuteAsync(() => Task.FromResult(1)); - - // Only if SuccessThreshold > 1 we are still in HalfOpen; we need to verify - // that a failure now opens the circuit - Assert.That(cb.State, Is.EqualTo(CircuitState.HalfOpen), - "Should be in HalfOpen after one success when SuccessThreshold is 3"); - - try { await cb.ExecuteAsync(() => throw new InvalidOperationException()); } - catch (InvalidOperationException) { } - - Assert.That(cb.State, Is.EqualTo(CircuitState.Open), - "Should transition back to Open on failure in HalfOpen"); - } - - // ─── HandledExceptions only trip the breaker ───────────────────────────── - - [Test] - public async Task HandledExceptions_OnlyListedTypeTripsBreaker() - { - var cb = CreateBreaker(o => - { - o.FailureThreshold = 1; - o.HandledExceptions = new[] { typeof(InvalidOperationException) }; - }); - - // ArgumentException is NOT in HandledExceptions: should propagate but not trip - try { await cb.ExecuteAsync(() => throw new ArgumentException("not handled")); } - catch (ArgumentException) { } - - Assert.That(cb.State, Is.EqualTo(CircuitState.Closed), - "Unlisted exception type should NOT trip the breaker"); - - // InvalidOperationException IS in HandledExceptions: should trip - try { await cb.ExecuteAsync(() => throw new InvalidOperationException("handled")); } - catch (InvalidOperationException) { } - - Assert.That(cb.State, Is.EqualTo(CircuitState.Open), - "Listed exception type should trip the breaker"); - } - - // ─── IgnoredExceptions do not record a failure ──────────────────────────── - - [Test] - public async Task IgnoredExceptions_DoNotRecordFailure() - { - var cb = CreateBreaker(o => - { - o.FailureThreshold = 1; - o.IgnoredExceptions = new[] { typeof(ArgumentException) }; - }); - - // Throw the ignored exception multiple times — circuit must stay Closed - for (var i = 0; i < 5; i++) - { - try { await cb.ExecuteAsync(() => throw new ArgumentException("ignored")); } - catch (ArgumentException) { } - } - - Assert.That(cb.State, Is.EqualTo(CircuitState.Closed), - "Ignored exceptions must not trip the breaker"); - - var stats = cb.GetStatistics(); - Assert.That(stats.FailedCalls, Is.EqualTo(0), - "FailedCalls should not increment for ignored exceptions"); - } - - // ─── Reset() forces Closed ──────────────────────────────────────────────── - - [Test] - public async Task Reset_ForcesClosed_RegardlessOfCurrentState() - { - var cb = CreateBreaker(o => o.FailureThreshold = 1); - - try { await cb.ExecuteAsync(() => throw new InvalidOperationException()); } - catch (InvalidOperationException) { } - - Assert.That(cb.State, Is.EqualTo(CircuitState.Open)); - - cb.Reset(); - - Assert.That(cb.State, Is.EqualTo(CircuitState.Closed)); - } - - // ─── Trip() forces Open from Closed ─────────────────────────────────────── - - [Test] - public void Trip_ForcesOpen_FromClosed() - { - var cb = CreateBreaker(); - Assert.That(cb.State, Is.EqualTo(CircuitState.Closed)); - - cb.Trip(); - - Assert.That(cb.State, Is.EqualTo(CircuitState.Open)); - } - - // ─── GetStatistics() returns correct counts ─────────────────────────────── - - [Test] - public async Task GetStatistics_ReturnsCorrectCountsAfterSequenceOfOperations() - { - var cb = CreateBreaker(o => o.FailureThreshold = 5); - - // 2 successes - await cb.ExecuteAsync(() => Task.FromResult(1)); - await cb.ExecuteAsync(() => Task.FromResult(1)); - - // 2 failures (threshold is 5 so still closed) - try { await cb.ExecuteAsync(() => throw new InvalidOperationException()); } - catch (InvalidOperationException) { } - try { await cb.ExecuteAsync(() => throw new InvalidOperationException()); } - catch (InvalidOperationException) { } - - var stats = cb.GetStatistics(); - - Assert.That(stats.TotalCalls, Is.EqualTo(4)); - Assert.That(stats.SuccessfulCalls, Is.EqualTo(2)); - Assert.That(stats.FailedCalls, Is.EqualTo(2)); - Assert.That(stats.RejectedCalls, Is.EqualTo(0)); - } - - [Test] - public async Task GetStatistics_RejectedCalls_IncrementWhenCircuitOpen() - { - var cb = CreateBreaker(o => o.FailureThreshold = 1); - - try { await cb.ExecuteAsync(() => throw new InvalidOperationException()); } - catch (InvalidOperationException) { } - - // Two rejected calls - try { await cb.ExecuteAsync(() => Task.FromResult(1)); } - catch (CircuitBreakerOpenException) { } - try { await cb.ExecuteAsync(() => Task.FromResult(1)); } - catch (CircuitBreakerOpenException) { } - - var stats = cb.GetStatistics(); - Assert.That(stats.RejectedCalls, Is.EqualTo(2)); - Assert.That(stats.TotalCalls, Is.EqualTo(3)); // 1 failure + 2 rejected - } - - // ─── StateChanged event raised on every state transition ───────────────── - - [Test] - public async Task StateChanged_RaisedOnEveryTransitionWithCorrectFromAndToState() - { - var cb = CreateBreaker(o => - { - o.FailureThreshold = 1; - o.OpenDuration = TimeSpan.FromMilliseconds(50); - o.SuccessThreshold = 1; - }); - - var events = new List<(CircuitState From, CircuitState To)>(); - cb.StateChanged += (_, args) => events.Add((args.PreviousState, args.NewState)); - - // Closed → Open - try { await cb.ExecuteAsync(() => throw new InvalidOperationException()); } - catch (InvalidOperationException) { } - - // Wait for Open → HalfOpen transition - await Task.Delay(100); - - // HalfOpen → Closed - await cb.ExecuteAsync(() => Task.FromResult(1)); - - Assert.That(events.Count, Is.GreaterThanOrEqualTo(2), - "At least two state change events should have been raised"); - - Assert.That(events[0], Is.EqualTo((CircuitState.Closed, CircuitState.Open)), - "First transition should be Closed → Open"); - - // Find the HalfOpen → Closed transition - Assert.That(events, Has.Some.EqualTo((CircuitState.HalfOpen, CircuitState.Closed)), - "Should have a HalfOpen → Closed transition"); - } - - // ─── Thread safety ──────────────────────────────────────────────────────── - - [Test] - public async Task ThreadSafety_ConcurrentCallsProduceConsistentStatistics() - { - const int total = 50; - var cb = CreateBreaker(o => - { - o.FailureThreshold = 100; // keep it open long enough - o.OperationTimeout = TimeSpan.FromSeconds(5); - }); - - var tasks = new Task[total]; - for (var i = 0; i < total; i++) - { - tasks[i] = Task.Run(async () => - { - try - { - await cb.ExecuteAsync(() => Task.FromResult(1)); - } - catch (CircuitBreakerOpenException) { } - }); - } - - await Task.WhenAll(tasks); - - var stats = cb.GetStatistics(); - Assert.That(stats.TotalCalls + stats.RejectedCalls, Is.GreaterThanOrEqualTo(total), - "TotalCalls + RejectedCalls must account for all attempted calls (no corrupt state)"); - Assert.That(stats.SuccessfulCalls + stats.FailedCalls, Is.LessThanOrEqualTo(stats.TotalCalls)); - } - - // ─── OperationTimeout records a failure ─────────────────────────────────── - - [Test] - public async Task OperationTimeout_RecordsFailure_WhenOperationExceedsTimeout() - { - var cb = CreateBreaker(o => - { - o.FailureThreshold = 10; - o.OperationTimeout = TimeSpan.FromMilliseconds(50); - }); - - // Operation that takes longer than the timeout - try - { - await cb.ExecuteAsync(async () => - { - await Task.Delay(500); - return 1; - }); - } - catch (OperationCanceledException) { } - - var stats = cb.GetStatistics(); - Assert.That(stats.FailedCalls, Is.GreaterThan(0), - "A timed-out operation should record a failure"); - } - } -} diff --git a/tests/SourceFlow.Core.Tests/Cloud/CloudTelemetryTests.cs b/tests/SourceFlow.Core.Tests/Cloud/CloudTelemetryTests.cs deleted file mode 100644 index 6b0315b2..00000000 --- a/tests/SourceFlow.Core.Tests/Cloud/CloudTelemetryTests.cs +++ /dev/null @@ -1,162 +0,0 @@ -using System; -using System.Collections.Generic; -using System.Diagnostics; -using Microsoft.Extensions.Logging.Abstractions; -using SourceFlow.Cloud.Observability; - -namespace SourceFlow.Core.Tests.Cloud -{ - [TestFixture] - [Category("Unit")] - public class CloudTelemetryTests - { - private CloudTelemetry _telemetry = null!; - private ActivityListener _listener = null!; - - [SetUp] - public void SetUp() - { - _telemetry = new CloudTelemetry(NullLogger.Instance); - - // Register an activity listener so that activities are actually started - _listener = new ActivityListener - { - ShouldListenTo = _ => true, - Sample = (ref ActivityCreationOptions _) => - ActivitySamplingResult.AllDataAndRecorded - }; - ActivitySource.AddActivityListener(_listener); - } - - [TearDown] - public void TearDown() - { - _listener.Dispose(); - } - - // ── StartCommandDispatch ────────────────────────────────────────────────── - - [Test] - public void StartCommandDispatch_WithListener_ReturnsNonNullActivity() - { - using var activity = _telemetry.StartCommandDispatch( - commandType: "CreateOrder", - destination: "https://sqs.us-east-1.amazonaws.com/123/orders", - cloudProvider: "aws"); - - Assert.That(activity, Is.Not.Null); - } - - [Test] - public void StartCommandDispatch_ActivityHasCorrectOperationName() - { - using var activity = _telemetry.StartCommandDispatch( - commandType: "CreateOrder", - destination: "queue-url", - cloudProvider: "aws"); - - Assert.That(activity, Is.Not.Null); - Assert.That(activity!.OperationName, Does.Contain("CreateOrder")); - } - - // ── InjectTraceContext ──────────────────────────────────────────────────── - - [Test] - public void InjectTraceContext_WritesTraceparentToAttributes() - { - using var activity = _telemetry.StartCommandDispatch( - commandType: "TestCommand", - destination: "queue", - cloudProvider: "aws"); - - var attributes = new Dictionary(); - _telemetry.InjectTraceContext(activity, attributes); - - Assert.That(attributes.ContainsKey("traceparent"), Is.True, - "InjectTraceContext should write 'traceparent' to the attributes dictionary"); - Assert.That(attributes["traceparent"], Is.Not.Null.And.Not.Empty); - } - - [Test] - public void InjectTraceContext_NullActivity_DoesNotThrow() - { - var attributes = new Dictionary(); - - Assert.DoesNotThrow(() => _telemetry.InjectTraceContext(null, attributes)); - Assert.That(attributes, Is.Empty); - } - - // ── ExtractTraceParent ──────────────────────────────────────────────────── - - [Test] - public void ExtractTraceParent_AttributeAbsent_ReturnsNull() - { - var attributes = new Dictionary { ["other"] = "value" }; - - var result = _telemetry.ExtractTraceParent(attributes); - - Assert.That(result, Is.Null); - } - - [Test] - public void ExtractTraceParent_AttributePresent_ReturnsValue() - { - const string traceId = "00-abc123-def456-01"; - var attributes = new Dictionary { ["traceparent"] = traceId }; - - var result = _telemetry.ExtractTraceParent(attributes); - - Assert.That(result, Is.EqualTo(traceId)); - } - - [Test] - public void ExtractTraceParent_NullDictionary_ReturnsNull() - { - var result = _telemetry.ExtractTraceParent(null); - - Assert.That(result, Is.Null); - } - - // ── RecordError ─────────────────────────────────────────────────────────── - - [Test] - public void RecordError_SetsActivityStatusCodeToError() - { - using var activity = _telemetry.StartCommandDispatch( - commandType: "FailingCommand", - destination: "queue", - cloudProvider: "aws"); - - Assert.That(activity, Is.Not.Null); - - var exception = new InvalidOperationException("something went wrong"); - _telemetry.RecordError(activity, exception); - - Assert.That(activity!.Status, Is.EqualTo(ActivityStatusCode.Error)); - } - - [Test] - public void RecordError_NullActivity_DoesNotThrow() - { - var ex = new Exception("boom"); - Assert.DoesNotThrow(() => _telemetry.RecordError(null, ex)); - } - - // ── RecordSuccess ───────────────────────────────────────────────────────── - - [Test] - public void RecordSuccess_SetsActivityStatusCodeToOk() - { - using var activity = _telemetry.StartCommandDispatch( - commandType: "SuccessCommand", - destination: "queue", - cloudProvider: "aws"); - - Assert.That(activity, Is.Not.Null); - - _telemetry.RecordSuccess(activity); - - Assert.That(activity!.Status, Is.EqualTo(ActivityStatusCode.Ok)); - } - } -} diff --git a/tests/SourceFlow.Core.Tests/Cloud/InMemoryDeadLetterStoreTests.cs b/tests/SourceFlow.Core.Tests/Cloud/InMemoryDeadLetterStoreTests.cs deleted file mode 100644 index 7da694bf..00000000 --- a/tests/SourceFlow.Core.Tests/Cloud/InMemoryDeadLetterStoreTests.cs +++ /dev/null @@ -1,224 +0,0 @@ -using System; -using System.Collections.Generic; -using System.Linq; -using System.Threading.Tasks; -using Microsoft.Extensions.Logging.Abstractions; -using SourceFlow.Cloud.DeadLetter; - -namespace SourceFlow.Core.Tests.Cloud -{ - [TestFixture] - [Category("Unit")] - public class InMemoryDeadLetterStoreTests - { - private InMemoryDeadLetterStore _store = null!; - - [SetUp] - public void SetUp() - { - _store = new InMemoryDeadLetterStore(NullLogger.Instance); - } - - // ── SaveAsync / GetAsync ────────────────────────────────────────────────── - - [Test] - public async Task SaveAsync_PersistsRecord_GetAsyncReturnsIt() - { - var record = MakeRecord(); - await _store.SaveAsync(record); - - var result = await _store.GetAsync(record.Id); - - Assert.That(result, Is.Not.Null); - Assert.That(result!.Id, Is.EqualTo(record.Id)); - Assert.That(result.MessageType, Is.EqualTo(record.MessageType)); - } - - [Test] - public async Task GetAsync_UnknownId_ReturnsNull() - { - var result = await _store.GetAsync("does-not-exist"); - - Assert.That(result, Is.Null); - } - - // ── QueryAsync filters ──────────────────────────────────────────────────── - - [Test] - public async Task QueryAsync_FilterByMessageType_ReturnsOnlyMatchingRecords() - { - await _store.SaveAsync(MakeRecord(messageType: "OrderPlaced")); - await _store.SaveAsync(MakeRecord(messageType: "OrderPlaced")); - await _store.SaveAsync(MakeRecord(messageType: "PaymentProcessed")); - - var results = (await _store.QueryAsync(new DeadLetterQuery { MessageType = "OrderPlaced" })).ToList(); - - Assert.That(results.Count, Is.EqualTo(2)); - Assert.That(results.All(r => r.MessageType == "OrderPlaced"), Is.True); - } - - [Test] - public async Task QueryAsync_FilterByReason_ReturnsOnlyMatchingRecords() - { - await _store.SaveAsync(MakeRecord(reason: "ProcessingError")); - await _store.SaveAsync(MakeRecord(reason: "DeadLetterQueueThresholdExceeded")); - - var results = (await _store.QueryAsync(new DeadLetterQuery { Reason = "ProcessingError" })).ToList(); - - Assert.That(results.Count, Is.EqualTo(1)); - Assert.That(results[0].Reason, Is.EqualTo("ProcessingError")); - } - - [Test] - public async Task QueryAsync_FilterByCloudProvider_ReturnsOnlyMatchingRecords() - { - await _store.SaveAsync(MakeRecord(cloudProvider: "aws")); - await _store.SaveAsync(MakeRecord(cloudProvider: "azure")); - - var results = (await _store.QueryAsync(new DeadLetterQuery { CloudProvider = "azure" })).ToList(); - - Assert.That(results.Count, Is.EqualTo(1)); - Assert.That(results[0].CloudProvider, Is.EqualTo("azure")); - } - - [Test] - public async Task QueryAsync_FilterByDateRange_ReturnsOnlyRecordsInRange() - { - var past = DateTime.UtcNow.AddHours(-2); - var recent = DateTime.UtcNow; - var future = DateTime.UtcNow.AddHours(2); - - await _store.SaveAsync(MakeRecord(deadLetteredAt: past)); - await _store.SaveAsync(MakeRecord(deadLetteredAt: recent)); - - var results = (await _store.QueryAsync(new DeadLetterQuery - { - FromDate = DateTime.UtcNow.AddHours(-1), - ToDate = DateTime.UtcNow.AddHours(1) - })).ToList(); - - Assert.That(results.Count, Is.EqualTo(1)); - } - - [Test] - public async Task QueryAsync_FilterByReplayedFlag_ReturnsOnlyMatchingRecords() - { - var notReplayed = MakeRecord(); - var replayed = MakeRecord(); - replayed.Replayed = true; - - await _store.SaveAsync(notReplayed); - await _store.SaveAsync(replayed); - - var notReplayedResults = (await _store.QueryAsync(new DeadLetterQuery { Replayed = false })).ToList(); - var replayedResults = (await _store.QueryAsync(new DeadLetterQuery { Replayed = true })).ToList(); - - Assert.That(notReplayedResults.All(r => !r.Replayed), Is.True); - Assert.That(replayedResults.All(r => r.Replayed), Is.True); - } - - [Test] - public async Task QueryAsync_Pagination_SkipAndTakeRespected() - { - for (int i = 0; i < 5; i++) - await _store.SaveAsync(MakeRecord(messageType: "PaginationTest")); - - var page1 = (await _store.QueryAsync(new DeadLetterQuery - { - MessageType = "PaginationTest", - Skip = 0, - Take = 2 - })).ToList(); - - var page2 = (await _store.QueryAsync(new DeadLetterQuery - { - MessageType = "PaginationTest", - Skip = 2, - Take = 2 - })).ToList(); - - Assert.That(page1.Count, Is.EqualTo(2)); - Assert.That(page2.Count, Is.EqualTo(2)); - - // Pages should not overlap - var page1Ids = page1.Select(r => r.Id).ToHashSet(); - var page2Ids = page2.Select(r => r.Id).ToHashSet(); - Assert.That(page1Ids.Intersect(page2Ids), Is.Empty); - } - - // ── GetCountAsync ───────────────────────────────────────────────────────── - - [Test] - public async Task GetCountAsync_ReturnsCorrectCountForFilter() - { - await _store.SaveAsync(MakeRecord(messageType: "CountTest")); - await _store.SaveAsync(MakeRecord(messageType: "CountTest")); - await _store.SaveAsync(MakeRecord(messageType: "OtherType")); - - var count = await _store.GetCountAsync(new DeadLetterQuery { MessageType = "CountTest" }); - - Assert.That(count, Is.EqualTo(2)); - } - - // ── MarkAsReplayedAsync ─────────────────────────────────────────────────── - - [Test] - public async Task MarkAsReplayedAsync_SetsReplayedToTrue() - { - var record = MakeRecord(); - await _store.SaveAsync(record); - - await _store.MarkAsReplayedAsync(record.Id); - - var updated = await _store.GetAsync(record.Id); - Assert.That(updated, Is.Not.Null); - Assert.That(updated!.Replayed, Is.True); - Assert.That(updated.ReplayedAt, Is.Not.Null); - } - - // ── DeleteOlderThanAsync ────────────────────────────────────────────────── - - [Test] - public async Task DeleteOlderThanAsync_RemovesOnlyRecordsBeforeCutoff() - { - var old = MakeRecord(deadLetteredAt: DateTime.UtcNow.AddDays(-10)); - var recent = MakeRecord(deadLetteredAt: DateTime.UtcNow); - - await _store.SaveAsync(old); - await _store.SaveAsync(recent); - - var cutoff = DateTime.UtcNow.AddDays(-1); - await _store.DeleteOlderThanAsync(cutoff); - - var oldResult = await _store.GetAsync(old.Id); - var recentResult = await _store.GetAsync(recent.Id); - - Assert.That(oldResult, Is.Null, "Old record should have been deleted"); - Assert.That(recentResult, Is.Not.Null, "Recent record should remain"); - } - - // ── Helpers ─────────────────────────────────────────────────────────────── - - private static DeadLetterRecord MakeRecord( - string? messageType = null, - string? reason = null, - string? cloudProvider = null, - DateTime? deadLetteredAt = null) - { - return new DeadLetterRecord - { - Id = Guid.NewGuid().ToString(), - MessageId = Guid.NewGuid().ToString(), - Body = "{}", - MessageType = messageType ?? "TestMessage", - Reason = reason ?? "TestReason", - CloudProvider = cloudProvider ?? "aws", - OriginalSource = "test-queue", - DeadLetterSource = "test-dlq", - DeadLetteredAt = deadLetteredAt ?? DateTime.UtcNow, - DeliveryCount = 3, - Replayed = false - }; - } - } -} diff --git a/tests/SourceFlow.Core.Tests/Cloud/InMemoryIdempotencyServiceTests.cs b/tests/SourceFlow.Core.Tests/Cloud/InMemoryIdempotencyServiceTests.cs deleted file mode 100644 index deded686..00000000 --- a/tests/SourceFlow.Core.Tests/Cloud/InMemoryIdempotencyServiceTests.cs +++ /dev/null @@ -1,138 +0,0 @@ -using System; -using System.Threading.Tasks; -using Microsoft.Extensions.Logging.Abstractions; -using SourceFlow.Cloud.Configuration; - -namespace SourceFlow.Core.Tests.Cloud -{ - [TestFixture] - [Category("Unit")] - public class InMemoryIdempotencyServiceTests - { - private InMemoryIdempotencyService _service = null!; - - [SetUp] - public void SetUp() - { - _service = new InMemoryIdempotencyService(NullLogger.Instance); - } - - // ── HasProcessedAsync ───────────────────────────────────────────────────── - - [Test] - public async Task HasProcessedAsync_UnknownKey_ReturnsFalse() - { - var result = await _service.HasProcessedAsync("unknown-key"); - - Assert.That(result, Is.False); - } - - [Test] - public async Task HasProcessedAsync_KnownKeyWithinTtl_ReturnsTrue() - { - const string key = "processed-key"; - await _service.MarkAsProcessedAsync(key, TimeSpan.FromMinutes(5)); - - var result = await _service.HasProcessedAsync(key); - - Assert.That(result, Is.True); - } - - [Test] - public async Task HasProcessedAsync_ExpiredKey_ReturnsFalse() - { - const string key = "expired-key"; - // Mark as processed with a TTL that has already elapsed - await _service.MarkAsProcessedAsync(key, TimeSpan.FromMilliseconds(-1)); - - var result = await _service.HasProcessedAsync(key); - - Assert.That(result, Is.False); - } - - // ── MarkAsProcessedAsync ────────────────────────────────────────────────── - - [Test] - public async Task MarkAsProcessedAsync_StoresKeyWithCorrectTtl() - { - const string key = "ttl-key"; - var ttl = TimeSpan.FromMinutes(10); - - await _service.MarkAsProcessedAsync(key, ttl); - - // Immediately after marking, the key should be found - var result = await _service.HasProcessedAsync(key); - Assert.That(result, Is.True); - } - - [Test] - public async Task MarkAsProcessedAsync_OverwritesExistingRecord() - { - const string key = "overwrite-key"; - - // Mark as processed then mark again with longer TTL - await _service.MarkAsProcessedAsync(key, TimeSpan.FromMilliseconds(-100)); // effectively expired - await _service.MarkAsProcessedAsync(key, TimeSpan.FromMinutes(5)); // fresh - - var result = await _service.HasProcessedAsync(key); - Assert.That(result, Is.True); - } - - // ── GetStatisticsAsync ──────────────────────────────────────────────────── - - [Test] - public async Task GetStatisticsAsync_IncrementsTotalChecks() - { - await _service.HasProcessedAsync("key-1"); - await _service.HasProcessedAsync("key-2"); - - var stats = await _service.GetStatisticsAsync(); - - Assert.That(stats.TotalChecks, Is.EqualTo(2)); - } - - [Test] - public async Task GetStatisticsAsync_IncrementsDuplicatesDetected_WhenKeyAlreadyProcessed() - { - const string key = "dup-key"; - await _service.MarkAsProcessedAsync(key, TimeSpan.FromMinutes(5)); - - // First check: key was not present before mark, so not a duplicate - // The duplicate is detected when the key IS found - await _service.HasProcessedAsync(key); // duplicate detected - await _service.HasProcessedAsync(key); // duplicate detected again - - var stats = await _service.GetStatisticsAsync(); - - Assert.That(stats.DuplicatesDetected, Is.EqualTo(2)); - } - - [Test] - public async Task GetStatisticsAsync_UniqueMessages_EqualsChecksMinusDuplicates() - { - const string key = "stats-key"; - await _service.MarkAsProcessedAsync(key, TimeSpan.FromMinutes(5)); - - await _service.HasProcessedAsync("fresh-key"); // not a duplicate - await _service.HasProcessedAsync(key); // duplicate - - var stats = await _service.GetStatisticsAsync(); - - Assert.That(stats.UniqueMessages, Is.EqualTo(stats.TotalChecks - stats.DuplicatesDetected)); - } - - // ── RemoveAsync ─────────────────────────────────────────────────────────── - - [Test] - public async Task RemoveAsync_RemovesKey_SubsequentCheckReturnsFalse() - { - const string key = "remove-key"; - await _service.MarkAsProcessedAsync(key, TimeSpan.FromMinutes(5)); - - await _service.RemoveAsync(key); - - var result = await _service.HasProcessedAsync(key); - Assert.That(result, Is.False); - } - } -} diff --git a/tests/SourceFlow.Core.Tests/Cloud/PolymorphicJsonConverterTests.cs b/tests/SourceFlow.Core.Tests/Cloud/PolymorphicJsonConverterTests.cs deleted file mode 100644 index 906b800c..00000000 --- a/tests/SourceFlow.Core.Tests/Cloud/PolymorphicJsonConverterTests.cs +++ /dev/null @@ -1,130 +0,0 @@ -using System; -using System.Text.Json; -using SourceFlow.Cloud.Serialization; - -namespace SourceFlow.Core.Tests.Cloud -{ - // ── Test types ──────────────────────────────────────────────────────────────── - - internal abstract class TestBase - { - public string Common { get; set; } = ""; - } - - internal class TestConcrete : TestBase - { - public string Specific { get; set; } = ""; - } - - // Concrete converter for TestBase - internal class TestConverter : PolymorphicJsonConverter { } - - [TestFixture] - [Category("Unit")] - public class PolymorphicJsonConverterTests - { - private JsonSerializerOptions _options = null!; - - [SetUp] - public void SetUp() - { - _options = new JsonSerializerOptions(); - _options.Converters.Add(new TestConverter()); - } - - // ── Round-trip ──────────────────────────────────────────────────────────── - - [Test] - public void RoundTrip_ConcreteThroughWriteRead_PreservesConcreteType() - { - var original = new TestConcrete { Common = "shared", Specific = "detail" }; - - var json = JsonSerializer.Serialize(original, _options); - var result = JsonSerializer.Deserialize(json, _options); - - Assert.That(result, Is.Not.Null); - Assert.That(result, Is.InstanceOf()); - var concrete = (TestConcrete)result!; - Assert.That(concrete.Common, Is.EqualTo("shared")); - Assert.That(concrete.Specific, Is.EqualTo("detail")); - } - - [Test] - public void Write_IncludesTypeDiscriminator() - { - var original = new TestConcrete { Common = "c" }; - - var json = JsonSerializer.Serialize(original, _options); - using var doc = JsonDocument.Parse(json); - - Assert.That(doc.RootElement.TryGetProperty("$type", out _), Is.True, - "Serialized JSON should contain $type discriminator"); - } - - // ── Missing discriminator ───────────────────────────────────────────────── - - [Test] - public void Read_MissingTypeDiscriminator_ThrowsJsonException() - { - const string json = "{\"common\":\"x\",\"specific\":\"y\"}"; - - var ex = Assert.Throws(() => - JsonSerializer.Deserialize(json, _options)); - - Assert.That(ex!.Message, Does.Contain("$type").Or.Contain("discriminator").IgnoreCase); - } - - // ── Unknown type name ───────────────────────────────────────────────────── - - [Test] - public void Read_UnknownTypeName_ThrowsJsonExceptionContainingTypeName() - { - const string unknownType = "UnknownNamespace.UnknownType, UnknownAssembly"; - var json = $"{{\"$type\":\"{unknownType}\",\"common\":\"x\"}}"; - - var ex = Assert.Throws(() => - JsonSerializer.Deserialize(json, _options)); - - Assert.That(ex!.Message, Does.Contain("UnknownNamespace.UnknownType")); - } - - // ── Null value ──────────────────────────────────────────────────────────── - - [Test] - public void Write_NullValue_ProducesNullJson() - { - var json = JsonSerializer.Serialize(null!, _options); - - Assert.That(json, Is.EqualTo("null")); - } - - [Test] - public void Read_NullToken_ReturnsNullWithoutCallingConverter() - { - // JsonSerializer handles null tokens before delegating to converters, - // so a null JSON token for a nullable reference type should return null. - TestBase? result = null; - Exception? thrownException = null; - - try - { - result = JsonSerializer.Deserialize("null", _options); - } - catch (JsonException ex) - { - thrownException = ex; - } - - // Either returns null or throws JsonException — both acceptable outcomes - // for a class-typed (non-nullable-annotated) converter - if (thrownException == null) - { - Assert.That(result, Is.Null); - } - else - { - Assert.That(thrownException, Is.InstanceOf()); - } - } - } -} diff --git a/tests/SourceFlow.Core.Tests/Cloud/SensitiveDataMaskerTests.cs b/tests/SourceFlow.Core.Tests/Cloud/SensitiveDataMaskerTests.cs deleted file mode 100644 index fccbf473..00000000 --- a/tests/SourceFlow.Core.Tests/Cloud/SensitiveDataMaskerTests.cs +++ /dev/null @@ -1,203 +0,0 @@ -using System; -using System.Text.Json; -using SourceFlow.Cloud.Security; - -namespace SourceFlow.Core.Tests.Cloud -{ - [TestFixture] - [Category("Unit")] - public class SensitiveDataMaskerTests - { - private SensitiveDataMasker _masker = null!; - - // ── Test helper types ───────────────────────────────────────────────────── - - private class PaymentInfo - { - [SensitiveData(SensitiveDataType.CreditCard)] - public string CardNumber { get; set; } = ""; - - [SensitiveData(SensitiveDataType.Email)] - public string Email { get; set; } = ""; - } - - private class PersonInfo - { - [SensitiveData(SensitiveDataType.PhoneNumber)] - public string Phone { get; set; } = ""; - - [SensitiveData(SensitiveDataType.SSN)] - public string Ssn { get; set; } = ""; - - [SensitiveData(SensitiveDataType.PersonalName)] - public string FullName { get; set; } = ""; - - [SensitiveData(SensitiveDataType.IPAddress)] - public string IpAddress { get; set; } = ""; - - [SensitiveData(SensitiveDataType.Password)] - public string Password { get; set; } = ""; - - [SensitiveData(SensitiveDataType.ApiKey)] - public string ApiKey { get; set; } = ""; - } - - private class PlainObject - { - public string Name { get; set; } = ""; - public int Value { get; set; } - } - - [SetUp] - public void SetUp() - { - _masker = new SensitiveDataMasker(); - } - - // ── CreditCard ──────────────────────────────────────────────────────────── - - [Test] - public void Mask_CreditCard_ShowsLastFourDigits() - { - var obj = new PaymentInfo { CardNumber = "4111111111111234", Email = "x@example.com" }; - - var result = _masker.Mask(obj); - - Assert.That(result, Does.Contain("1234")); - // First digits should be masked - Assert.That(result, Does.Contain("*")); - } - - // ── Email ───────────────────────────────────────────────────────────────── - - [Test] - public void Mask_Email_ShowsDomainOnlyWithTripleStarPrefix() - { - var obj = new PaymentInfo { CardNumber = "1234", Email = "user@example.com" }; - - var result = _masker.Mask(obj); - - Assert.That(result, Does.Contain("***@example.com")); - Assert.That(result, Does.Not.Contain("user@")); - } - - // ── PhoneNumber ─────────────────────────────────────────────────────────── - - [Test] - public void Mask_PhoneNumber_ShowsLastFourDigits() - { - var obj = new PersonInfo { Phone = "5551234567" }; - - var result = _masker.Mask(obj); - - Assert.That(result, Does.Contain("4567")); - Assert.That(result, Does.Contain("***-***-")); - } - - // ── SSN ─────────────────────────────────────────────────────────────────── - - [Test] - public void Mask_Ssn_ShowsLastFourDigits() - { - var obj = new PersonInfo { Ssn = "123-45-6789" }; - - var result = _masker.Mask(obj); - - Assert.That(result, Does.Contain("6789")); - Assert.That(result, Does.Contain("***-**-")); - } - - // ── PersonalName ────────────────────────────────────────────────────────── - - [Test] - public void Mask_PersonalName_ShowsFirstLetterOfEachWord() - { - var obj = new PersonInfo { FullName = "John Doe" }; - - var result = _masker.Mask(obj); - - // First letter of each word should be visible - Assert.That(result, Does.Contain("J")); - Assert.That(result, Does.Contain("D")); - // Rest should be masked - Assert.That(result, Does.Contain("*")); - } - - // ── IPAddress ───────────────────────────────────────────────────────────── - - [Test] - public void Mask_IpAddress_ShowsFirstOctetOnly() - { - var obj = new PersonInfo { IpAddress = "192.168.1.100" }; - - var result = _masker.Mask(obj); - - Assert.That(result, Does.Contain("192.*.*.*")); - } - - // ── Password ────────────────────────────────────────────────────────────── - - [Test] - public void Mask_Password_FullyRedacted() - { - var obj = new PersonInfo { Password = "supersecretpassword" }; - - var result = _masker.Mask(obj); - - Assert.That(result, Does.Contain("********")); - Assert.That(result, Does.Not.Contain("supersecret")); - } - - // ── ApiKey ──────────────────────────────────────────────────────────────── - - [Test] - public void Mask_ApiKey_ShowsFirstAndLastFourChars() - { - var obj = new PersonInfo { ApiKey = "abcd1234efgh5678" }; - - var result = _masker.Mask(obj); - - // First 4 and last 4 should be visible with "..." in between - Assert.That(result, Does.Contain("abcd")); - Assert.That(result, Does.Contain("5678")); - Assert.That(result, Does.Contain("...")); - } - - // ── Null input ──────────────────────────────────────────────────────────── - - [Test] - public void Mask_NullInput_ReturnsNullStringWithoutThrowing() - { - var result = _masker.Mask(null); - - Assert.That(result, Is.EqualTo("null")); - } - - // ── Object with no sensitive attributes ─────────────────────────────────── - - [Test] - public void Mask_ObjectWithNoSensitiveAttributes_ReturnedUnchanged() - { - var obj = new PlainObject { Name = "Alice", Value = 42 }; - - var result = _masker.Mask(obj); - - // Should contain the original values since nothing is marked sensitive - Assert.That(result, Does.Contain("Alice")); - Assert.That(result, Does.Contain("42")); - } - - // ── MaskLazy ───────────────────────────────────────────────────────────── - - [Test] - public void MaskLazy_ToStringDelegatestoMask() - { - var obj = new PaymentInfo { CardNumber = "4111111111111234", Email = "user@example.com" }; - - var lazy = _masker.MaskLazy(obj); - - var result = lazy.ToString(); - Assert.That(result, Does.Contain("***@example.com")); - } - } -} diff --git a/tests/SourceFlow.Core.Tests/E2E/Aggregates/AccountAggregate.cs b/tests/SourceFlow.Core.Tests/E2E/Aggregates/AccountAggregate.cs deleted file mode 100644 index 546dce0d..00000000 --- a/tests/SourceFlow.Core.Tests/E2E/Aggregates/AccountAggregate.cs +++ /dev/null @@ -1,68 +0,0 @@ -using Microsoft.Extensions.Logging; -using SourceFlow.Aggregate; -using SourceFlow.Core.Tests.E2E.Commands; -using SourceFlow.Core.Tests.E2E.Events; -using SourceFlow.Messaging.Commands; - -namespace SourceFlow.Core.Tests.E2E.Aggregates -{ - public class AccountAggregate : Aggregate, - ISubscribes, IAccountAggregate - { - public AccountAggregate(Lazy commandPublisher, ILogger logger) : - base(commandPublisher, logger) - { - } - - public Task CreateAccount(int accountId, string holder, decimal amount) - { - var command = new CreateAccount(new Payload - { - AccountName = holder, - InitialAmount = amount - }); - - command.Entity.Id = accountId; - - return Send(command); - } - - public Task Deposit(int accountId, decimal amount) - { - return Send(new DepositMoney(accountId, new TransactPayload - { - Amount = amount, - Type = TransactionType.Deposit - })); - } - - public Task Withdraw(int accountId, decimal amount) - { - return Send(new WithdrawMoney(accountId, new TransactPayload - { - Amount = amount, - Type = TransactionType.Withdrawal - })); - } - - public Task CloseAccount(int accountId, string reason) - { - return Send(new CloseAccount(accountId, new ClosurePayload - { - ClosureReason = reason - })); - } - - public Task On(AccountCreated @event) - { - logger.LogInformation("Action=Aggregate_Subscribes, Aggregate={Aggregate}, Event={Event}, ", this.GetType().Name, @event.GetType().Name); - - return Task.CompletedTask; - } - - public Task RepayHistory(int accountId) - { - return ReplayCommands(accountId); - } - } -} diff --git a/tests/SourceFlow.Core.Tests/E2E/Aggregates/BankAccount.cs b/tests/SourceFlow.Core.Tests/E2E/Aggregates/BankAccount.cs deleted file mode 100644 index 27349860..00000000 --- a/tests/SourceFlow.Core.Tests/E2E/Aggregates/BankAccount.cs +++ /dev/null @@ -1,13 +0,0 @@ -namespace SourceFlow.Core.Tests.E2E.Aggregates -{ - public class BankAccount : IEntity - { - public int Id { get; set; } - public DateTime CreatedOn { get; set; } = DateTime.UtcNow; - public string AccountName { get; set; } = string.Empty; - public decimal Balance { get; set; } - public bool IsClosed { get; set; } - public string ClosureReason { get; internal set; } = string.Empty; - public DateTime ActiveOn { get; internal set; } - } -} diff --git a/tests/SourceFlow.Core.Tests/E2E/Aggregates/IAccountAggregate.cs b/tests/SourceFlow.Core.Tests/E2E/Aggregates/IAccountAggregate.cs deleted file mode 100644 index ff83071d..00000000 --- a/tests/SourceFlow.Core.Tests/E2E/Aggregates/IAccountAggregate.cs +++ /dev/null @@ -1,19 +0,0 @@ -using SourceFlow.Core.Tests.E2E.Events; - -namespace SourceFlow.Core.Tests.E2E.Aggregates -{ - public interface IAccountAggregate - { - Task CloseAccount(int accountId, string reason); - - Task CreateAccount(int accountId, string holder, decimal amount); - - Task Deposit(int accountId, decimal amount); - - Task On(AccountCreated @event); - - Task Withdraw(int accountId, decimal amount); - - Task RepayHistory(int accountId); - } -} diff --git a/tests/SourceFlow.Core.Tests/E2E/Aggregates/TransactionType.cs b/tests/SourceFlow.Core.Tests/E2E/Aggregates/TransactionType.cs deleted file mode 100644 index 002df2b6..00000000 --- a/tests/SourceFlow.Core.Tests/E2E/Aggregates/TransactionType.cs +++ /dev/null @@ -1,8 +0,0 @@ -namespace SourceFlow.Core.Tests.E2E.Aggregates -{ - public enum TransactionType - { - Deposit, - Withdrawal - } -} diff --git a/tests/SourceFlow.Core.Tests/E2E/Commands/ActivateAccount.cs b/tests/SourceFlow.Core.Tests/E2E/Commands/ActivateAccount.cs deleted file mode 100644 index f6117d32..00000000 --- a/tests/SourceFlow.Core.Tests/E2E/Commands/ActivateAccount.cs +++ /dev/null @@ -1,11 +0,0 @@ -using SourceFlow.Messaging.Commands; - -namespace SourceFlow.Core.Tests.E2E.Commands -{ - public class ActivateAccount : Command - { - public ActivateAccount(int entityId, ActivationPayload payload) : base(entityId, payload) - { - } - } -} diff --git a/tests/SourceFlow.Core.Tests/E2E/Commands/CloseAccount.cs b/tests/SourceFlow.Core.Tests/E2E/Commands/CloseAccount.cs deleted file mode 100644 index 0e21f4d7..00000000 --- a/tests/SourceFlow.Core.Tests/E2E/Commands/CloseAccount.cs +++ /dev/null @@ -1,11 +0,0 @@ -using SourceFlow.Messaging.Commands; - -namespace SourceFlow.Core.Tests.E2E.Commands -{ - public class CloseAccount : Command - { - public CloseAccount(int entityId, ClosurePayload payload) : base(entityId, payload) - { - } - } -} diff --git a/tests/SourceFlow.Core.Tests/E2E/Commands/CreateAccount.cs b/tests/SourceFlow.Core.Tests/E2E/Commands/CreateAccount.cs deleted file mode 100644 index cbae1cba..00000000 --- a/tests/SourceFlow.Core.Tests/E2E/Commands/CreateAccount.cs +++ /dev/null @@ -1,11 +0,0 @@ -using SourceFlow.Messaging.Commands; - -namespace SourceFlow.Core.Tests.E2E.Commands -{ - public class CreateAccount : Command - { - public CreateAccount(Payload payload) : base(true, payload) - { - } - } -} diff --git a/tests/SourceFlow.Core.Tests/E2E/Commands/DepositMoney.cs b/tests/SourceFlow.Core.Tests/E2E/Commands/DepositMoney.cs deleted file mode 100644 index 68f15e66..00000000 --- a/tests/SourceFlow.Core.Tests/E2E/Commands/DepositMoney.cs +++ /dev/null @@ -1,11 +0,0 @@ -using SourceFlow.Messaging.Commands; - -namespace SourceFlow.Core.Tests.E2E.Commands -{ - public class DepositMoney : Command - { - public DepositMoney(int entityId, TransactPayload payload) : base(entityId, payload) - { - } - } -} diff --git a/tests/SourceFlow.Core.Tests/E2E/Commands/Payload.cs b/tests/SourceFlow.Core.Tests/E2E/Commands/Payload.cs deleted file mode 100644 index 15182ca8..00000000 --- a/tests/SourceFlow.Core.Tests/E2E/Commands/Payload.cs +++ /dev/null @@ -1,33 +0,0 @@ -using SourceFlow.Core.Tests.E2E.Aggregates; -using SourceFlow.Messaging; - -namespace SourceFlow.Core.Tests.E2E.Commands -{ - public class ActivationPayload : IPayload - { - public int Id { get; set; } - public DateTime ActiveOn { get; set; } - } - - public class Payload : IPayload - { - public int Id { get; set; } - public decimal InitialAmount { get; set; } - public string AccountName { get; set; } = string.Empty; - } - - public class TransactPayload : IPayload - { - public int Id { get; set; } - public TransactionType Type { get; set; } - public decimal Amount { get; set; } - public decimal CurrentBalance { get; set; } - } - - public class ClosurePayload : IPayload - { - public int Id { get; set; } - public bool IsClosed { get; set; } - public string ClosureReason { get; set; } = string.Empty; - } -} diff --git a/tests/SourceFlow.Core.Tests/E2E/Commands/WithdrawMoney.cs b/tests/SourceFlow.Core.Tests/E2E/Commands/WithdrawMoney.cs deleted file mode 100644 index cd7e2b3e..00000000 --- a/tests/SourceFlow.Core.Tests/E2E/Commands/WithdrawMoney.cs +++ /dev/null @@ -1,11 +0,0 @@ -using SourceFlow.Messaging.Commands; - -namespace SourceFlow.Core.Tests.E2E.Commands -{ - public class WithdrawMoney : Command - { - public WithdrawMoney(int entityId, TransactPayload payload) : base(entityId, payload) - { - } - } -} diff --git a/tests/SourceFlow.Core.Tests/E2E/E2E.Tests.cs b/tests/SourceFlow.Core.Tests/E2E/E2E.Tests.cs deleted file mode 100644 index 39fba4e7..00000000 --- a/tests/SourceFlow.Core.Tests/E2E/E2E.Tests.cs +++ /dev/null @@ -1,100 +0,0 @@ -using System.Reflection; -using Microsoft.Extensions.DependencyInjection; -using Microsoft.Extensions.Logging; -using SourceFlow.Core.Tests.E2E.Aggregates; -using SourceFlow.Core.Tests.E2E.Projections; -using SourceFlow.Saga; - -namespace SourceFlow.Core.Tests.E2E -{ - [TestFixture] - [Category("Integration")] - public class ProgramIntegrationTests - { - private ServiceProvider _serviceProvider; - private IAccountAggregate _accountAggregate; - private ISaga _saga; - private ILogger _logger; - private IViewModelStoreAdapter _viewRepository; - private int _accountId = 999; - - [SetUp] - public void SetUp() - { - var services = new ServiceCollection(); - - // Register logging with console provider - services.AddLogging(builder => - { - builder.AddConsole(); - builder.SetMinimumLevel(LogLevel.Information); - }); - - // Register SourceFlow and all required services - // Pass the test assembly so it can discover E2E aggregates, sagas, and projections - services.UseSourceFlow(Assembly.GetExecutingAssembly()); - - _serviceProvider = services.BuildServiceProvider(); - - _saga = _serviceProvider.GetRequiredService(); - _accountAggregate = _serviceProvider.GetRequiredService(); - - _logger = _serviceProvider.GetRequiredService>(); - _viewRepository = _serviceProvider.GetRequiredService(); - } - - [TearDown] - public void TearDown() - { - if (_serviceProvider is not null) - _serviceProvider.Dispose(); - } - - [Test] - public async Task EndToEnd_AccountLifecycle_WorksAsExpected() - { - // Create account - await _accountAggregate.CreateAccount(_accountId, "John Doe", 1000m); - _logger.LogInformation("Action=Test_Create_Account, Account: {accountId}", _accountId); - - // Perform deposit - var amount = 500m; - _logger.LogInformation("Action=Test_Deposit, Amount={Amount}", amount); - await _accountAggregate.Deposit(_accountId, amount); - - // Perform withdraw - amount = 200m; - _logger.LogInformation("Action=Test_Withdraw, Amount={Amount}", amount); - await _accountAggregate.Withdraw(_accountId, amount); - - // Perform another deposit - amount = 100m; - _logger.LogInformation("Action=Test_Deposit, Amount={Amount}", amount); - await _accountAggregate.Deposit(_accountId, amount); - - // Get current state and assertions - var account = await _viewRepository.Find(_accountId); - Assert.That(account, Is.Not.Null); - Assert.That(_accountId, Is.EqualTo(account.Id)); - Assert.That(account.AccountName, Is.EqualTo("John Doe")); - Assert.That(account.CurrentBalance, Is.EqualTo(1000m + 500m - 200m + 100m)); - Assert.That(account.TransactionCount, Is.GreaterThanOrEqualTo(3)); - Assert.That(account.IsClosed, Is.False); - - // Replay account history (should not throw) - Assert.DoesNotThrowAsync(async () => await _accountAggregate.RepayHistory(_accountId)); - - // Fetch state again, should be the same - var replayedAccount = await _viewRepository.Find(_accountId); - Assert.That(account.CurrentBalance, Is.EqualTo(replayedAccount.CurrentBalance)); - Assert.That(account.TransactionCount, Is.EqualTo(replayedAccount.TransactionCount)); - - // CloseAccount account - Assert.DoesNotThrowAsync(async () => await _accountAggregate.CloseAccount(_accountId, "Customer account close request")); - - // Final state - var closedAccount = await _viewRepository.Find(_accountId); - Assert.That(closedAccount.IsClosed, Is.True); - } - } -} diff --git a/tests/SourceFlow.Core.Tests/E2E/Events/AccountCreated.cs b/tests/SourceFlow.Core.Tests/E2E/Events/AccountCreated.cs deleted file mode 100644 index b1ae37fd..00000000 --- a/tests/SourceFlow.Core.Tests/E2E/Events/AccountCreated.cs +++ /dev/null @@ -1,12 +0,0 @@ -using SourceFlow.Core.Tests.E2E.Aggregates; -using SourceFlow.Messaging.Events; - -namespace SourceFlow.Core.Tests.E2E.Events -{ - public class AccountCreated : Event - { - public AccountCreated(BankAccount payload) : base(payload) - { - } - } -} diff --git a/tests/SourceFlow.Core.Tests/E2E/Events/AccountUpdated.cs b/tests/SourceFlow.Core.Tests/E2E/Events/AccountUpdated.cs deleted file mode 100644 index 4fdf79ba..00000000 --- a/tests/SourceFlow.Core.Tests/E2E/Events/AccountUpdated.cs +++ /dev/null @@ -1,12 +0,0 @@ -using SourceFlow.Core.Tests.E2E.Aggregates; -using SourceFlow.Messaging.Events; - -namespace SourceFlow.Core.Tests.E2E.Events -{ - public class AccountUpdated : Event - { - public AccountUpdated(BankAccount payload) : base(payload) - { - } - } -} diff --git a/tests/SourceFlow.Core.Tests/E2E/Impl/InMemoryEntityStore.cs b/tests/SourceFlow.Core.Tests/E2E/Impl/InMemoryEntityStore.cs deleted file mode 100644 index d95737bc..00000000 --- a/tests/SourceFlow.Core.Tests/E2E/Impl/InMemoryEntityStore.cs +++ /dev/null @@ -1,45 +0,0 @@ -using System.Collections.Concurrent; - -namespace SourceFlow.Core.Tests.E2E.Impl -{ - public class InMemoryEntityStore : IEntityStore - { - private readonly ConcurrentDictionary _cache = new(); - - public Task Delete(TEntity entity) where TEntity : class, IEntity - { - if (entity?.Id == null) - throw new ArgumentNullException(nameof(entity)); - - _cache.TryRemove(entity.Id, out _); - - return Task.CompletedTask; - } - - public Task Get(int id) where TEntity : class, IEntity - { - if (id == 0) - throw new ArgumentNullException(nameof(id)); - - var success = _cache.TryGetValue(id, out var entity); - - if (!success || entity == null) - throw new InvalidOperationException($"Entity not found for ID: {id}"); - - return Task.FromResult((TEntity)entity); - } - - public Task Persist(TEntity entity) where TEntity : class, IEntity - { - if (entity?.Id == null) - throw new ArgumentNullException(nameof(entity)); - - if (entity.Id == 0) - entity.Id = new Random().Next(); - - _cache[entity.Id] = entity; - - return Task.FromResult(entity); - } - } -} diff --git a/tests/SourceFlow.Core.Tests/E2E/Impl/InMemoryEventStore.cs b/tests/SourceFlow.Core.Tests/E2E/Impl/InMemoryEventStore.cs deleted file mode 100644 index 6a5d76c2..00000000 --- a/tests/SourceFlow.Core.Tests/E2E/Impl/InMemoryEventStore.cs +++ /dev/null @@ -1,27 +0,0 @@ -using System.Collections.Concurrent; -using SourceFlow.Messaging.Commands; - -namespace SourceFlow.Core.Tests.E2E.Impl -{ - public class InMemoryEventStore : ICommandStore - { - private readonly ConcurrentDictionary> _store = new(); - - public Task Append(CommandData command) - { - if (!_store.ContainsKey(command.EntityId)) - _store[command.EntityId] = new List(); - - _store[command.EntityId].Add(command); - - return Task.CompletedTask; - } - - public async Task> Load(int entityId) - { - return await Task.FromResult(_store.TryGetValue(entityId, out var events) - ? events - : Enumerable.Empty()); - } - } -} diff --git a/tests/SourceFlow.Core.Tests/E2E/Impl/InMemoryViewModelStore.cs b/tests/SourceFlow.Core.Tests/E2E/Impl/InMemoryViewModelStore.cs deleted file mode 100644 index 2f7ba720..00000000 --- a/tests/SourceFlow.Core.Tests/E2E/Impl/InMemoryViewModelStore.cs +++ /dev/null @@ -1,49 +0,0 @@ -using System.Collections.Concurrent; -using SourceFlow.Projections; - -namespace SourceFlow.Core.Tests.E2E.Impl -{ - public class InMemoryViewModelStore : IViewModelStore - { - private readonly ConcurrentDictionary _cache = new(); - - public Task Get(int id) where TViewModel : class, IViewModel - { - if (id == 0) - throw new ArgumentNullException(nameof(id)); - - var success = _cache.TryGetValue(id, out var model); - - if (!success || model == null) - throw new InvalidOperationException($"ViewModel not found for ID: {id}"); - - return Task.FromResult((TViewModel)model); - } - - public Task Persist(TViewModel model) where TViewModel : class, IViewModel - { - if (model?.Id == null) - throw new ArgumentNullException(nameof(model)); - - if (model.Id == 0) - model.Id = new Random().Next(); - - _cache[model.Id] = model; - - return Task.FromResult(model); - } - - public Task Delete(TViewModel model) where TViewModel : class, IViewModel - { - if (model?.Id == null) - throw new ArgumentNullException(nameof(model)); - - var success = _cache.Remove(model.Id, out var rmodel); - - if (!success || rmodel == null) - throw new InvalidOperationException($"ViewModel not found for ID: {model.Id}"); - - return Task.CompletedTask; - } - } -} diff --git a/tests/SourceFlow.Core.Tests/E2E/Projections/AccountView.cs b/tests/SourceFlow.Core.Tests/E2E/Projections/AccountView.cs deleted file mode 100644 index 2c61d2bd..00000000 --- a/tests/SourceFlow.Core.Tests/E2E/Projections/AccountView.cs +++ /dev/null @@ -1,49 +0,0 @@ -using Microsoft.Extensions.Logging; -using SourceFlow.Core.Tests.E2E.Events; -using SourceFlow.Projections; - -namespace SourceFlow.Core.Tests.E2E.Projections -{ - public class AccountView : View, - IProjectOn, - IProjectOn - { - public AccountView(IViewModelStoreAdapter viewModelStore, ILogger logger) : base(viewModelStore, logger) - { - } - - public async Task On(AccountCreated @event) - { - var viewModel = new AccountViewModel - { - Id = @event.Payload.Id, - AccountName = @event.Payload.AccountName, - CurrentBalance = @event.Payload.Balance, - IsClosed = false, - CreatedDate = @event.Payload.CreatedOn, - LastUpdated = DateTime.UtcNow, - TransactionCount = 0, - ClosureReason = null!, - Version = 1 - }; - - return viewModel; - } - - public async Task On(AccountUpdated @event) - { - var viewModel = await Find(@event.Payload.Id); - - viewModel.CurrentBalance = @event.Payload.Balance; - viewModel.LastUpdated = DateTime.UtcNow; - viewModel.AccountName = @event.Payload.AccountName; - viewModel.IsClosed = @event.Payload.IsClosed; - viewModel.ClosureReason = @event.Payload.ClosureReason; - viewModel.ActiveOn = @event.Payload.ActiveOn; - viewModel.Version++; - viewModel.TransactionCount++; - - return viewModel; - } - } -} diff --git a/tests/SourceFlow.Core.Tests/E2E/Projections/AccountViewModel.cs b/tests/SourceFlow.Core.Tests/E2E/Projections/AccountViewModel.cs deleted file mode 100644 index ab2b07ab..00000000 --- a/tests/SourceFlow.Core.Tests/E2E/Projections/AccountViewModel.cs +++ /dev/null @@ -1,18 +0,0 @@ -using SourceFlow.Projections; - -namespace SourceFlow.Core.Tests.E2E.Projections -{ - public class AccountViewModel : IViewModel - { - public int Id { get; set; } - public string AccountName { get; set; } = string.Empty; - public decimal CurrentBalance { get; set; } - public DateTime CreatedDate { get; set; } - public DateTime LastUpdated { get; set; } - public int TransactionCount { get; set; } - public bool IsClosed { get; set; } - public string ClosureReason { get; set; } = string.Empty; - public int Version { get; set; } - public DateTime ActiveOn { get; set; } - } -} diff --git a/tests/SourceFlow.Core.Tests/E2E/Sagas/AccountSaga.cs b/tests/SourceFlow.Core.Tests/E2E/Sagas/AccountSaga.cs deleted file mode 100644 index 730aaf06..00000000 --- a/tests/SourceFlow.Core.Tests/E2E/Sagas/AccountSaga.cs +++ /dev/null @@ -1,113 +0,0 @@ -using Microsoft.Extensions.Logging; -using SourceFlow.Core.Tests.E2E.Aggregates; -using SourceFlow.Core.Tests.E2E.Commands; -using SourceFlow.Core.Tests.E2E.Events; -using SourceFlow.Messaging.Commands; -using SourceFlow.Messaging.Events; -using SourceFlow.Saga; - -namespace SourceFlow.Core.Tests.E2E.Sagas -{ - public class AccountSaga : Saga, - IHandlesWithEvent, - IHandlesWithEvent, - IHandlesWithEvent, - IHandlesWithEvent, - IHandles - { - public AccountSaga(Lazy commandPublisher, IEventQueue eventQueue, IEntityStoreAdapter repository, ILogger logger) : - base(commandPublisher, eventQueue, repository, logger) - { - } - - public Task Handle(IEntity entity, CreateAccount command) - { - logger.LogInformation("Action=Account_Created, Account={AccountId}, Holder={AccountName}, Initial_Balance={InitialBalance}", - command.Entity.Id, command.Payload.AccountName, command.Payload.InitialAmount); - - if (string.IsNullOrEmpty(command.Payload.AccountName)) - throw new ArgumentException("Account create requires account holder name.", nameof(command.Payload.AccountName)); - - if (command.Payload.InitialAmount <= 0) - throw new ArgumentException("Account create requires initial amount.", nameof(command.Payload.InitialAmount)); - - var account = (BankAccount)entity; - - account.AccountName = command.Payload.AccountName; - account.Balance = command.Payload.InitialAmount; - - return Task.FromResult(account); - } - - public Task Handle(IEntity entity, ActivateAccount command) - { - logger.LogInformation("Action=Account_Activate, ActivatedOn={ActiveOn}, Account={AccountId}", command.Payload.ActiveOn, command.Entity.Id); - - if (command.Payload.ActiveOn == DateTime.MinValue) - throw new ArgumentException("Deposit amount must be positive", nameof(command.Payload.ActiveOn)); - - var account = (BankAccount)entity; - - if (account.IsClosed) - throw new InvalidOperationException("Cannot deposit to a closed account"); - - account.ActiveOn = command.Payload.ActiveOn; - - return Task.FromResult(account); - } - - public Task Handle(IEntity entity, DepositMoney command) - { - logger.LogInformation("Action=Money_Deposited, Amount={Amount}, Account={AccountId}", command.Payload.Amount, command.Entity.Id); - - if (command.Payload.Amount <= 0) - throw new ArgumentException("Deposit amount must be positive", nameof(command.Payload.Amount)); - - var account = (BankAccount)entity; - - if (account.IsClosed) - throw new InvalidOperationException("Cannot deposit to a closed account"); - - command.Payload.CurrentBalance = account.Balance + command.Payload.Amount; - account.Balance = command.Payload.CurrentBalance; - - return Task.FromResult(account); - } - - public Task Handle(IEntity entity, WithdrawMoney command) - { - logger.LogInformation("Action=Money_Withdrawn, Amount={Amount}, Account={AccountId}", command.Payload.Amount, command.Entity.Id); - - if (command.Payload.Amount <= 0) - throw new ArgumentException("Withdrawal amount must be positive", nameof(command.Payload.Amount)); - - var account = (BankAccount)entity; - - if (account.IsClosed) - throw new InvalidOperationException("Cannot deposit to a closed account"); - - command.Payload.CurrentBalance = account.Balance - command.Payload.Amount; - account.Balance = command.Payload.CurrentBalance; - - return Task.FromResult(account); - } - - public Task Handle(IEntity entity, CloseAccount command) - { - logger.LogInformation("Action=Account_Closed, Account={AccountId}, Reason={Reason}", command.Entity.Id, command.Payload.ClosureReason); - - if (string.IsNullOrWhiteSpace(command.Payload.ClosureReason)) - throw new ArgumentException("Reason for closing cannot be empty", nameof(command.Payload.ClosureReason)); - - var account = (BankAccount)entity; - - if (account.IsClosed) - throw new InvalidOperationException("Cannot close account on a closed account"); - - account.ClosureReason = command.Payload.ClosureReason; - account.IsClosed = command.Payload.IsClosed = true; - - return Task.FromResult(account); - } - } -} diff --git a/tests/SourceFlow.Core.Tests/Impl/AggregateFactoryTests.cs b/tests/SourceFlow.Core.Tests/Impl/AggregateFactoryTests.cs deleted file mode 100644 index e47eb4ac..00000000 --- a/tests/SourceFlow.Core.Tests/Impl/AggregateFactoryTests.cs +++ /dev/null @@ -1,31 +0,0 @@ -using Moq; -using SourceFlow.Aggregate; -using SourceFlow.Impl; - -namespace SourceFlow.Core.Tests.Impl -{ - [TestFixture] - [Category("Unit")] - public class AggregateFactoryTests - { - [Test] - public void Constructor_SetsServiceProvider() - { - var sp = new Mock().Object; - var factory = new AggregateFactory(sp); - Assert.IsNotNull(factory); - } - - [Test] - public async Task Create_ReturnsAggregateInstance() - { - var aggregateMock = new Mock(); - var spMock = new Mock(); - spMock.Setup(sp => sp.GetService(typeof(IAggregate))).Returns(aggregateMock.Object); - var factory = new AggregateFactory(spMock.Object); - var result = await factory.Create(); - Assert.IsNotNull(result); - Assert.That(result, Is.SameAs(aggregateMock.Object)); - } - } -} diff --git a/tests/SourceFlow.Core.Tests/Impl/AggregateSubscriberTests.cs b/tests/SourceFlow.Core.Tests/Impl/AggregateSubscriberTests.cs deleted file mode 100644 index 3c679148..00000000 --- a/tests/SourceFlow.Core.Tests/Impl/AggregateSubscriberTests.cs +++ /dev/null @@ -1,49 +0,0 @@ -using Microsoft.Extensions.Logging; -using Moq; -using SourceFlow.Aggregate; -using SourceFlow.Messaging.Events; -using System.Linq; - -namespace SourceFlow.Core.Tests.Impl -{ - [TestFixture] - [Category("Unit")] - public class AggregateSubscriberTests - { - [Test] - public void Constructor_NullAggregates_ThrowsArgumentNullException() - { - var loggerMock = new Mock>(); - Assert.Throws(() => new Aggregate.EventSubscriber(null, loggerMock.Object, Enumerable.Empty())); - } - - [Test] - public void Constructor_NullLogger_ThrowsArgumentNullException() - { - var aggregates = new List(); - Assert.Throws(() => new Aggregate.EventSubscriber(aggregates, null, Enumerable.Empty())); - } - - [Test] - public async Task Dispatch_ValidEvent_LogsInformation() - { - var loggerMock = new Mock>(); - var aggregateMock = new Mock(); - // Make the aggregate implement ISubscribes so it gets called - aggregateMock.As>() - .Setup(a => a.On(It.IsAny())) - .Returns(Task.CompletedTask); - var aggregates = new List { aggregateMock.Object }; - var dispatcher = new Aggregate.EventSubscriber(aggregates, loggerMock.Object, Enumerable.Empty()); - var eventMock = new DummyEvent(); - await dispatcher.Subscribe(eventMock); - loggerMock.Verify(l => l.Log( - It.IsAny(), - It.IsAny(), - It.IsAny(), - It.IsAny(), - (Func)It.IsAny()), - Times.AtLeastOnce); - } - } -} diff --git a/tests/SourceFlow.Core.Tests/Impl/CommandBusTests.cs b/tests/SourceFlow.Core.Tests/Impl/CommandBusTests.cs deleted file mode 100644 index e7076d6f..00000000 --- a/tests/SourceFlow.Core.Tests/Impl/CommandBusTests.cs +++ /dev/null @@ -1,379 +0,0 @@ -using Microsoft.Extensions.Logging; -using Moq; -using SourceFlow.Messaging; -using SourceFlow.Messaging.Bus; -using SourceFlow.Messaging.Bus.Impl; -using SourceFlow.Messaging.Commands; -using SourceFlow.Observability; - -namespace SourceFlow.Core.Tests.Impl -{ - [TestFixture] - [Category("Unit")] - public class CommandBusTests - { - private Mock commandStoreMock; - private Mock> loggerMock; - private Mock commandDispatcherMock; - private Mock telemetryMock; - private CommandBus commandBus; - - [SetUp] - public void Setup() - { - commandStoreMock = new Mock(); - loggerMock = new Mock>(); - commandDispatcherMock = new Mock(); - telemetryMock = new Mock(); - - // Setup telemetry mock to execute operations directly - telemetryMock.Setup(t => t.TraceAsync(It.IsAny(), It.IsAny>(), It.IsAny>())) - .Returns((string name, Func operation, Action enrich) => operation()); - - commandBus = new CommandBus( - new[] { commandDispatcherMock.Object }, - commandStoreMock.Object, - loggerMock.Object, - telemetryMock.Object, - Enumerable.Empty()); - } - - [Test] - public void Constructor_NullCommandStore_ThrowsArgumentNullException() - { - Assert.Throws(() => - new CommandBus(new[] { commandDispatcherMock.Object }, null, loggerMock.Object, telemetryMock.Object, Enumerable.Empty())); - } - - [Test] - public void Constructor_NullLogger_ThrowsArgumentNullException() - { - Assert.Throws(() => - new CommandBus(new[] { commandDispatcherMock.Object }, commandStoreMock.Object, null, telemetryMock.Object, Enumerable.Empty())); - } - - [Test] - public void Constructor_NullCommandDispatcher_ThrowsArgumentNullException() - { - Assert.Throws(() => - new CommandBus(null, commandStoreMock.Object, loggerMock.Object, telemetryMock.Object, Enumerable.Empty())); - } - - [Test] - public void Constructor_NullMiddleware_ThrowsArgumentNullException() - { - Assert.Throws(() => - new CommandBus(new[] { commandDispatcherMock.Object }, commandStoreMock.Object, loggerMock.Object, telemetryMock.Object, null)); - } - - [Test] - public void Constructor_SetsDependencies() - { - Assert.That(commandBus.commandDispatchers.ElementAt(0), Is.EqualTo(commandDispatcherMock.Object)); - } - - [Test] - public async Task Publish_NullCommand_ThrowsArgumentNullException() - { - ICommandBus bus = commandBus; - Assert.ThrowsAsync(async () => - await bus.Publish(null!)); - } - - [Test] - public async Task Publish_ValidCommand_SetsSequenceNumber() - { - // Arrange - var command = new DummyCommand(); - commandStoreMock.Setup(cs => cs.GetNextSequenceNo(It.IsAny())) - .ReturnsAsync(42); - - // Act - ICommandBus bus = commandBus; - await bus.Publish(command); - - // Assert - Assert.That(command.Metadata.SequenceNo, Is.EqualTo(42)); - } - - [Test] - public async Task Publish_ValidCommand_DispatchesToCommandDispatcher() - { - // Arrange - var command = new DummyCommand(); - commandStoreMock.Setup(cs => cs.GetNextSequenceNo(It.IsAny())) - .ReturnsAsync(1); - - // Act - ICommandBus bus = commandBus; - await bus.Publish(command); - - // Assert - commandDispatcherMock.Verify(cd => cd.Dispatch(command), Times.Once); - } - - [Test] - public async Task Publish_ValidCommand_LogsInformation() - { - // Arrange - var command = new DummyCommand(); - commandStoreMock.Setup(cs => cs.GetNextSequenceNo(It.IsAny())) - .ReturnsAsync(1); - - // Act - ICommandBus bus = commandBus; - await bus.Publish(command); - - // Assert - loggerMock.Verify(l => l.Log( - It.IsAny(), - It.IsAny(), - It.IsAny(), - It.IsAny(), - (Func)It.IsAny()), - Times.AtLeastOnce); - } - - [Test] - public async Task Publish_ValidCommand_AppendsToStore() - { - // Arrange - var command = new DummyCommand(); - commandStoreMock.Setup(cs => cs.GetNextSequenceNo(It.IsAny())) - .ReturnsAsync(1); - - // Act - ICommandBus bus = commandBus; - await bus.Publish(command); - - // Assert - commandStoreMock.Verify(cs => cs.Append(command), Times.Once); - } - - [Test] - public async Task Publish_ReplayCommand_DoesNotSetSequenceNumber() - { - // Arrange - var command = new DummyCommand(); - command.Metadata.IsReplay = true; - command.Metadata.SequenceNo = 99; - - // Act - ICommandBus bus = commandBus; - await bus.Publish(command); - - // Assert - Assert.That(command.Metadata.SequenceNo, Is.EqualTo(99)); - commandStoreMock.Verify(cs => cs.GetNextSequenceNo(It.IsAny()), Times.Never); - } - - [Test] - public async Task Publish_ReplayCommand_DoesNotAppendToStore() - { - // Arrange - var command = new DummyCommand(); - command.Metadata.IsReplay = true; - - // Act - ICommandBus bus = commandBus; - await bus.Publish(command); - - // Assert - commandStoreMock.Verify(cs => cs.Append(It.IsAny()), Times.Never); - } - - [Test] - public async Task Replay_NoCommands_DoesNotDispatch() - { - // Arrange - commandStoreMock.Setup(cs => cs.Load(It.IsAny())) - .ReturnsAsync((IEnumerable)null!); - - // Act - ICommandBus bus = commandBus; - await bus.Replay(1); - - // Assert - commandDispatcherMock.Verify(cd => cd.Dispatch(It.IsAny()), Times.Never); - } - - [Test] - public async Task Replay_WithCommands_DispatchesAllCommands() - { - // Arrange - var commands = new List - { - new DummyCommand { Metadata = new Metadata() }, - new DummyCommand { Metadata = new Metadata() }, - new DummyCommand { Metadata = new Metadata() } - }; - commandStoreMock.Setup(cs => cs.Load(It.IsAny())) - .ReturnsAsync(commands); - - // Act - ICommandBus bus = commandBus; - await bus.Replay(1); - - // Assert - commandDispatcherMock.Verify(cd => cd.Dispatch(It.IsAny()), Times.Exactly(3)); - } - - [Test] - public async Task Replay_WithCommands_MarksCommandsAsReplay() - { - // Arrange - var commands = new List - { - new DummyCommand { Metadata = new Metadata() }, - new DummyCommand { Metadata = new Metadata() } - }; - commandStoreMock.Setup(cs => cs.Load(It.IsAny())) - .ReturnsAsync(commands); - - // Act - ICommandBus bus = commandBus; - await bus.Replay(1); - - // Assert - Assert.That(commands.All(c => c.Metadata.IsReplay), Is.True); - } - - [Test] - public async Task Replay_WithCommands_DoesNotAppendToStore() - { - // Arrange - var commands = new List - { - new DummyCommand { Metadata = new Metadata() } - }; - commandStoreMock.Setup(cs => cs.Load(It.IsAny())) - .ReturnsAsync(commands); - - // Act - ICommandBus bus = commandBus; - await bus.Replay(1); - - // Assert - commandStoreMock.Verify(cs => cs.Append(It.IsAny()), Times.Never); - } - - [Test] - public async Task Publish_WithMiddleware_ExecutesMiddlewareAroundCoreLogic() - { - // Arrange - var callOrder = new List(); - var middlewareMock = new Mock(); - middlewareMock - .Setup(m => m.InvokeAsync(It.IsAny(), It.IsAny>())) - .Returns>(async (cmd, next) => - { - callOrder.Add("middleware-before"); - await next(cmd); - callOrder.Add("middleware-after"); - }); - - commandDispatcherMock.Setup(cd => cd.Dispatch(It.IsAny())) - .Callback(() => callOrder.Add("dispatch")) - .Returns(Task.CompletedTask); - - commandStoreMock.Setup(cs => cs.GetNextSequenceNo(It.IsAny())).ReturnsAsync(1); - - var bus = new CommandBus( - new[] { commandDispatcherMock.Object }, - commandStoreMock.Object, - loggerMock.Object, - telemetryMock.Object, - new[] { middlewareMock.Object }); - - // Act - await ((ICommandBus)bus).Publish(new DummyCommand()); - - // Assert - Assert.That(callOrder[0], Is.EqualTo("middleware-before")); - Assert.That(callOrder[1], Is.EqualTo("dispatch")); - Assert.That(callOrder[2], Is.EqualTo("middleware-after")); - } - - [Test] - public async Task Publish_WithMultipleMiddleware_ExecutesInRegistrationOrder() - { - // Arrange - var callOrder = new List(); - - var middleware1 = new Mock(); - middleware1 - .Setup(m => m.InvokeAsync(It.IsAny(), It.IsAny>())) - .Returns>(async (cmd, next) => - { - callOrder.Add("m1-before"); - await next(cmd); - callOrder.Add("m1-after"); - }); - - var middleware2 = new Mock(); - middleware2 - .Setup(m => m.InvokeAsync(It.IsAny(), It.IsAny>())) - .Returns>(async (cmd, next) => - { - callOrder.Add("m2-before"); - await next(cmd); - callOrder.Add("m2-after"); - }); - - commandStoreMock.Setup(cs => cs.GetNextSequenceNo(It.IsAny())).ReturnsAsync(1); - - var bus = new CommandBus( - new[] { commandDispatcherMock.Object }, - commandStoreMock.Object, - loggerMock.Object, - telemetryMock.Object, - new ICommandDispatchMiddleware[] { middleware1.Object, middleware2.Object }); - - // Act - await ((ICommandBus)bus).Publish(new DummyCommand()); - - // Assert - Assert.That(callOrder, Is.EqualTo(new[] { "m1-before", "m2-before", "m2-after", "m1-after" })); - } - - [Test] - public async Task Publish_MiddlewareShortCircuits_DoesNotCallCoreLogic() - { - // Arrange - var middlewareMock = new Mock(); - middlewareMock - .Setup(m => m.InvokeAsync(It.IsAny(), It.IsAny>())) - .Returns(Task.CompletedTask); // Does NOT call next - - var bus = new CommandBus( - new[] { commandDispatcherMock.Object }, - commandStoreMock.Object, - loggerMock.Object, - telemetryMock.Object, - new[] { middlewareMock.Object }); - - // Act - await ((ICommandBus)bus).Publish(new DummyCommand()); - - // Assert - commandDispatcherMock.Verify(cd => cd.Dispatch(It.IsAny()), Times.Never); - commandStoreMock.Verify(cs => cs.Append(It.IsAny()), Times.Never); - } - - [Test] - public async Task Publish_NoMiddleware_ExecutesCoreLogicDirectly() - { - // Arrange - commandStoreMock.Setup(cs => cs.GetNextSequenceNo(It.IsAny())).ReturnsAsync(1); - var command = new DummyCommand(); - - // Act - ICommandBus bus = commandBus; - await bus.Publish(command); - - // Assert - commandDispatcherMock.Verify(cd => cd.Dispatch(command), Times.Once); - commandStoreMock.Verify(cs => cs.Append(command), Times.Once); - } - } -} diff --git a/tests/SourceFlow.Core.Tests/Impl/CommandPublisherTests.cs b/tests/SourceFlow.Core.Tests/Impl/CommandPublisherTests.cs deleted file mode 100644 index 0c5b5849..00000000 --- a/tests/SourceFlow.Core.Tests/Impl/CommandPublisherTests.cs +++ /dev/null @@ -1,53 +0,0 @@ -using Moq; -using SourceFlow.Messaging; -using SourceFlow.Messaging.Bus; -using SourceFlow.Messaging.Commands; -using SourceFlow.Messaging.Commands.Impl; - -namespace SourceFlow.Core.Tests.Impl -{ - [TestFixture] - [Category("Unit")] - public class CommandPublisherTests - { - [Test] - public void Constructor_SetsCommandBus() - { - var bus = new Mock().Object; - var publisher = new CommandPublisher(bus); - Assert.IsNotNull(publisher); - } - - [Test] - public void Publish_NullCommand_ThrowsArgumentNullException() - { - var bus = new Mock().Object; - var publisher = (ICommandPublisher)new CommandPublisher(bus); - Assert.ThrowsAsync(async () => await publisher.Publish(null!)); - } - - [Test] - public void Publish_NullPayloadId_ThrowsInvalidOperationException() - { - var bus = new Mock().Object; - var publisher = (ICommandPublisher)new CommandPublisher(bus); - var commandMock = new Mock(); - commandMock.Setup(c => c.Payload).Returns((IPayload?)null!); - Assert.ThrowsAsync(async () => await publisher.Publish(commandMock.Object)); - } - - [Test] - public async Task Publish_ValidCommand_DelegatesToCommandBus() - { - var busMock = new Mock(); - busMock.Setup(b => b.Publish(It.IsAny())).Returns(Task.CompletedTask); - var publisher = (ICommandPublisher)new CommandPublisher(busMock.Object); - var payloadMock = new Mock(); - var commandMock = new Mock(); - commandMock.Setup(c => c.Payload).Returns(payloadMock.Object); - commandMock.Setup(p => p.Entity).Returns(new EntityRef { Id = 1 }); - await publisher.Publish(commandMock.Object); - busMock.Verify(b => b.Publish(commandMock.Object), Times.Once); - } - } -} diff --git a/tests/SourceFlow.Core.Tests/Impl/DummyCommand.cs b/tests/SourceFlow.Core.Tests/Impl/DummyCommand.cs deleted file mode 100644 index 6b5bab1e..00000000 --- a/tests/SourceFlow.Core.Tests/Impl/DummyCommand.cs +++ /dev/null @@ -1,26 +0,0 @@ -using SourceFlow.Messaging; -using SourceFlow.Messaging.Commands; - -namespace SourceFlow.Core.Tests.Impl -{ - public class DummyCommand : ICommand - { - public DummyCommand() - { - Payload = new DummyPayload(); - Name = "DummyCommand"; - Metadata = new Metadata(); - Entity = new EntityRef { Id = 0 }; - } - - public IPayload Payload { get; set; } - public string Name { get; set; } - public Metadata Metadata { get; set; } - public EntityRef Entity { get; set; } - } - - internal class DummyPayload : IPayload - { - public int EntityId { get; set; } - } -} diff --git a/tests/SourceFlow.Core.Tests/Impl/DummyEvent.cs b/tests/SourceFlow.Core.Tests/Impl/DummyEvent.cs deleted file mode 100644 index e54b5b77..00000000 --- a/tests/SourceFlow.Core.Tests/Impl/DummyEvent.cs +++ /dev/null @@ -1,23 +0,0 @@ -using SourceFlow.Messaging; -using SourceFlow.Messaging.Events; - -namespace SourceFlow.Core.Tests.Impl -{ - public class DummyEvent : IEvent - { - public DummyEvent() - { - Payload = new DummyEntity(); - Metadata = new Metadata(); - } - - public IEntity Payload { get; set; } - public string Name { get; set; } = "TestEvent"; - public Metadata Metadata { get; set; } - } - - public class DummyEntity : IEntity - { - public int Id { get; set; } = 1; - } -} diff --git a/tests/SourceFlow.Core.Tests/Impl/EventQueueTests.cs b/tests/SourceFlow.Core.Tests/Impl/EventQueueTests.cs deleted file mode 100644 index bff57e66..00000000 --- a/tests/SourceFlow.Core.Tests/Impl/EventQueueTests.cs +++ /dev/null @@ -1,254 +0,0 @@ -using Microsoft.Extensions.Logging; -using Moq; -using SourceFlow.Messaging.Events; -using SourceFlow.Messaging.Events.Impl; -using SourceFlow.Observability; - -namespace SourceFlow.Core.Tests.Impl -{ - [TestFixture] - [Category("Unit")] - public class EventQueueTests - { - private Mock> loggerMock; - private Mock eventDispatcherMock; - private Mock telemetryMock; - private EventQueue eventQueue; - - [SetUp] - public void Setup() - { - loggerMock = new Mock>(); - eventDispatcherMock = new Mock(); - telemetryMock = new Mock(); - - // Setup telemetry mock to execute operations directly - telemetryMock.Setup(t => t.TraceAsync(It.IsAny(), It.IsAny>(), It.IsAny>())) - .Returns((string name, Func operation, Action enrich) => operation()); - - eventQueue = new EventQueue( - new[] { eventDispatcherMock.Object }, - loggerMock.Object, - telemetryMock.Object, - Enumerable.Empty()); - } - - [Test] - public void Constructor_NullLogger_ThrowsArgumentNullException() - { - Assert.Throws(() => - new EventQueue(new[] { eventDispatcherMock.Object }, null, telemetryMock.Object, Enumerable.Empty())); - } - - [Test] - public void Constructor_NullEventDispatcher_ThrowsArgumentNullException() - { - Assert.Throws(() => - new EventQueue(null, loggerMock.Object, telemetryMock.Object, Enumerable.Empty())); - } - - [Test] - public void Constructor_NullMiddleware_ThrowsArgumentNullException() - { - Assert.Throws(() => - new EventQueue(new[] { eventDispatcherMock.Object }, loggerMock.Object, telemetryMock.Object, null)); - } - - [Test] - public void Constructor_SetsDependencies() - { - Assert.That(eventQueue.eventDispatchers.ElementAt(0), Is.EqualTo(eventDispatcherMock.Object)); - } - - [Test] - public async Task Enqueue_NullEvent_ThrowsArgumentNullException() - { - Assert.ThrowsAsync(async () => - await eventQueue.Enqueue(null!)); - } - - [Test] - public async Task Enqueue_ValidEvent_DispatchesToEventDispatcher() - { - // Arrange - var @event = new DummyEvent(); - - // Act - await eventQueue.Enqueue(@event); - - // Assert - eventDispatcherMock.Verify(ed => ed.Dispatch(@event), Times.Once); - } - - [Test] - public async Task Enqueue_ValidEvent_LogsInformation() - { - // Arrange - var @event = new DummyEvent(); - - // Act - await eventQueue.Enqueue(@event); - - // Assert - loggerMock.Verify(l => l.Log( - It.IsAny(), - It.IsAny(), - It.IsAny(), - It.IsAny(), - (Func)It.IsAny()), - Times.AtLeastOnce); - } - - [Test] - public async Task Enqueue_ValidEvent_DispatchesAfterLogging() - { - // Arrange - var @event = new DummyEvent(); - var callSequence = new System.Collections.Generic.List(); - - eventDispatcherMock.Setup(ed => ed.Dispatch(It.IsAny())) - .Callback(() => callSequence.Add("Dispatch")) - .Returns(Task.CompletedTask); - - loggerMock.Setup(l => l.Log( - It.IsAny(), - It.IsAny(), - It.IsAny(), - It.IsAny(), - It.IsAny>())) - .Callback(() => callSequence.Add("Log")); - - // Act - await eventQueue.Enqueue(@event); - - // Assert - Assert.That(callSequence[0], Is.EqualTo("Log")); - Assert.That(callSequence[1], Is.EqualTo("Dispatch")); - } - - [Test] - public async Task Enqueue_MultipleEvents_DispatchesAll() - { - // Arrange - var event1 = new DummyEvent(); - var event2 = new DummyEvent(); - var event3 = new DummyEvent(); - - // Act - await eventQueue.Enqueue(event1); - await eventQueue.Enqueue(event2); - await eventQueue.Enqueue(event3); - - // Assert - eventDispatcherMock.Verify(ed => ed.Dispatch(It.IsAny()), Times.Exactly(3)); - } - - [Test] - public async Task Enqueue_WithMiddleware_ExecutesMiddlewareAroundCoreLogic() - { - // Arrange - var callOrder = new List(); - var middlewareMock = new Mock(); - middlewareMock - .Setup(m => m.InvokeAsync(It.IsAny(), It.IsAny>())) - .Returns>(async (evt, next) => - { - callOrder.Add("middleware-before"); - await next(evt); - callOrder.Add("middleware-after"); - }); - - eventDispatcherMock.Setup(ed => ed.Dispatch(It.IsAny())) - .Callback(() => callOrder.Add("dispatch")) - .Returns(Task.CompletedTask); - - var queue = new EventQueue( - new[] { eventDispatcherMock.Object }, - loggerMock.Object, - telemetryMock.Object, - new[] { middlewareMock.Object }); - - // Act - await queue.Enqueue(new DummyEvent()); - - // Assert - Assert.That(callOrder[0], Is.EqualTo("middleware-before")); - Assert.That(callOrder[1], Is.EqualTo("dispatch")); - Assert.That(callOrder[2], Is.EqualTo("middleware-after")); - } - - [Test] - public async Task Enqueue_WithMultipleMiddleware_ExecutesInRegistrationOrder() - { - // Arrange - var callOrder = new List(); - - var middleware1 = new Mock(); - middleware1 - .Setup(m => m.InvokeAsync(It.IsAny(), It.IsAny>())) - .Returns>(async (evt, next) => - { - callOrder.Add("m1-before"); - await next(evt); - callOrder.Add("m1-after"); - }); - - var middleware2 = new Mock(); - middleware2 - .Setup(m => m.InvokeAsync(It.IsAny(), It.IsAny>())) - .Returns>(async (evt, next) => - { - callOrder.Add("m2-before"); - await next(evt); - callOrder.Add("m2-after"); - }); - - var queue = new EventQueue( - new[] { eventDispatcherMock.Object }, - loggerMock.Object, - telemetryMock.Object, - new IEventDispatchMiddleware[] { middleware1.Object, middleware2.Object }); - - // Act - await queue.Enqueue(new DummyEvent()); - - // Assert - Assert.That(callOrder, Is.EqualTo(new[] { "m1-before", "m2-before", "m2-after", "m1-after" })); - } - - [Test] - public async Task Enqueue_MiddlewareShortCircuits_DoesNotCallCoreLogic() - { - // Arrange - var middlewareMock = new Mock(); - middlewareMock - .Setup(m => m.InvokeAsync(It.IsAny(), It.IsAny>())) - .Returns(Task.CompletedTask); // Does NOT call next - - var queue = new EventQueue( - new[] { eventDispatcherMock.Object }, - loggerMock.Object, - telemetryMock.Object, - new[] { middlewareMock.Object }); - - // Act - await queue.Enqueue(new DummyEvent()); - - // Assert - eventDispatcherMock.Verify(ed => ed.Dispatch(It.IsAny()), Times.Never); - } - - [Test] - public async Task Enqueue_NoMiddleware_ExecutesCoreLogicDirectly() - { - // Arrange - var @event = new DummyEvent(); - - // Act - await eventQueue.Enqueue(@event); - - // Assert - eventDispatcherMock.Verify(ed => ed.Dispatch(@event), Times.Once); - } - } -} diff --git a/tests/SourceFlow.Core.Tests/Impl/ProjectionSubscriberTests.cs b/tests/SourceFlow.Core.Tests/Impl/ProjectionSubscriberTests.cs deleted file mode 100644 index 13dbb5d2..00000000 --- a/tests/SourceFlow.Core.Tests/Impl/ProjectionSubscriberTests.cs +++ /dev/null @@ -1,91 +0,0 @@ -using Microsoft.Extensions.Logging; -using Moq; -using SourceFlow.Messaging; -using SourceFlow.Messaging.Events; -using SourceFlow.Projections; -using System.Linq; - -namespace SourceFlow.Core.Tests.Impl -{ - [TestFixture] - [Category("Unit")] - public class ProjectionSubscriberTests - { - [Test] - public void Constructor_NullProjections_ThrowsArgumentNullException() - { - var logger = new Mock>().Object; - Assert.Throws(() => new SourceFlow.Projections.EventSubscriber(null, logger, Enumerable.Empty())); - } - - [Test] - public void Constructor_NullLogger_ThrowsArgumentNullException() - { - var projections = new List(); - Assert.Throws(() => new SourceFlow.Projections.EventSubscriber(projections, null, Enumerable.Empty())); - } - - [Test] - public async Task Dispatch_ValidEvent_LogsInformation() - { - var loggerMock = new Mock>(); - - // Create a concrete test event implementation instead of a mock - var metadata = new Metadata { SequenceNo = 1 }; - var payload = new TestEntity { Id = 1 }; - var testEvent = new TestEvent - { - Name = "TestEvent", - Metadata = metadata, - Payload = payload - }; - - // Create a concrete test projection instead of a mock - var testProjection = new TestProjection(); - var projections = new List { testProjection }; - - var dispatcher = new SourceFlow.Projections.EventSubscriber(projections, loggerMock.Object, Enumerable.Empty()); - await dispatcher.Subscribe(testEvent); - - loggerMock.Verify(l => l.Log( - It.IsAny(), - It.IsAny(), - It.IsAny(), - It.IsAny(), - (Func)It.IsAny()), - Times.AtLeastOnce); - } - - // Test entity implementation - private class TestEntity : IEntity - { - public int Id { get; set; } - } - - // Test event implementation - private class TestEvent : IEvent - { - public string Name { get; set; } = string.Empty; - public IEntity Payload { get; set; } = null!; - public Metadata Metadata { get; set; } = null!; - } - - // Test projection implementation - private class TestProjection : View, IProjectOn - { - public TestProjection() : base(new Mock().Object, new Mock>().Object) - { - } - - public Task On(TestEvent @event) - { - return Task.FromResult(new TestProjectionViewModel { Id = 1 }); - } - } - - private class TestProjectionViewModel : IViewModel - { - public int Id { get; set; } - } - } -} diff --git a/tests/SourceFlow.Core.Tests/Impl/SagaDispatcherTests.cs b/tests/SourceFlow.Core.Tests/Impl/SagaDispatcherTests.cs deleted file mode 100644 index f0044779..00000000 --- a/tests/SourceFlow.Core.Tests/Impl/SagaDispatcherTests.cs +++ /dev/null @@ -1,42 +0,0 @@ -using Microsoft.Extensions.Logging; -using Moq; -using SourceFlow.Messaging.Commands; -using SourceFlow.Saga; -using System.Linq; - -namespace SourceFlow.Core.Tests.Impl -{ - [TestFixture] - [Category("Unit")] - public class SagaDispatcherTests - { - [Test] - public void Constructor_SetsLogger() - { - var logger = new Mock>().Object; - var sagas = new Mock>().Object; - var dispatcher = new CommandSubscriber(sagas, logger, Enumerable.Empty()); - Assert.IsNotNull(dispatcher); - } - - [Test] - public async Task Dispatch_WithNoSagas_LogsInformation() - { - var loggerMock = new Mock>(); - // Use an empty list instead of a mock to avoid null reference issues - var sagas = new List(); - - var dispatcher = new CommandSubscriber(sagas, loggerMock.Object, Enumerable.Empty()); - var commandMock = new DummyCommand(); - - await dispatcher.Subscribe(commandMock); - loggerMock.Verify(l => l.Log( - It.IsAny(), - It.IsAny(), - It.IsAny(), - It.IsAny(), - (Func)It.IsAny()), - Times.AtLeastOnce); - } - } -} diff --git a/tests/SourceFlow.Core.Tests/Interfaces/IViewModelRepositoryTests.cs b/tests/SourceFlow.Core.Tests/Interfaces/IViewModelRepositoryTests.cs deleted file mode 100644 index 3137260a..00000000 --- a/tests/SourceFlow.Core.Tests/Interfaces/IViewModelRepositoryTests.cs +++ /dev/null @@ -1,29 +0,0 @@ -using Moq; -using SourceFlow.Projections; - -namespace SourceFlow.Core.Tests.Interfaces -{ - public class IViewModelRepositoryTests - { - public class DummyViewModel : IViewModel - { public int Id { get; set; } } - - [Test] - public async Task GetByIdAsync_ReturnsModel() - { - var mock = new Mock(); - mock.Setup(r => r.Find(1)).ReturnsAsync(new DummyViewModel { Id = 1 }); - var result = await mock.Object.Find(1); - Assert.That(result, Is.Not.Null); - Assert.That(result.Id, Is.EqualTo(1)); - } - - [Test] - public async Task PersistAsync_DoesNotThrow() - { - var mock = new Mock(); - mock.Setup(r => r.Persist(It.IsAny())).Returns(vm => Task.FromResult(vm)); - Assert.DoesNotThrowAsync(async () => await mock.Object.Persist(new DummyViewModel())); - } - } -} diff --git a/tests/SourceFlow.Core.Tests/Ioc/DummyCommandStore.cs b/tests/SourceFlow.Core.Tests/Ioc/DummyCommandStore.cs deleted file mode 100644 index 4f30577b..00000000 --- a/tests/SourceFlow.Core.Tests/Ioc/DummyCommandStore.cs +++ /dev/null @@ -1,25 +0,0 @@ -using SourceFlow.Messaging.Commands; - -namespace SourceFlow.Core.Tests.Ioc -{ - public class DummyCommandStore : ICommandStoreAdapter - { - public Task Append(ICommand command) - { - // Simulate appending command - return Task.CompletedTask; - } - - public Task> Load(int aggregateId) - { - // Simulate loading commands - return Task.FromResult>(null!); - } - - public Task GetNextSequenceNo(int aggregateId) - { - // Simulate getting next sequence number - return Task.FromResult(1); - } - } -} diff --git a/tests/SourceFlow.Core.Tests/Ioc/IocExtensionsTests.cs b/tests/SourceFlow.Core.Tests/Ioc/IocExtensionsTests.cs deleted file mode 100644 index 8870b97b..00000000 --- a/tests/SourceFlow.Core.Tests/Ioc/IocExtensionsTests.cs +++ /dev/null @@ -1,282 +0,0 @@ -using Microsoft.Extensions.DependencyInjection; -using SourceFlow.Aggregate; -using SourceFlow.Messaging.Bus; -using SourceFlow.Messaging.Commands; -using SourceFlow.Messaging.Events; -using SourceFlow.Projections; - -namespace SourceFlow.Tests.Ioc -{ - // Test implementations for required interfaces - public class TestRepository : IEntityStoreAdapter - { - public Task Get(int id) where TEntity : class, IEntity - { - return Task.FromResult(null!); - } - - public Task Persist(TEntity entity) where TEntity : class, IEntity - { - return Task.FromResult(entity); - } - - public Task Delete(TEntity entity) where TEntity : class, IEntity - { - return Task.CompletedTask; - } - } - - public class TestCommandStore : ICommandStoreAdapter - { - public Task Append(ICommand command) - { - return Task.CompletedTask; - } - - public Task> Load(int aggregateId) - { - return Task.FromResult>(new List()); - } - - public Task GetNextSequenceNo(int aggregateId) - { - return Task.FromResult(0); - } - } - - public class TestViewProvider : IViewModelStoreAdapter - { - public Task Find(int id) where TViewModel : class, IViewModel - { - return Task.FromResult(null!); - } - - public Task Persist(TViewModel model) where TViewModel : class, IViewModel - { - return Task.FromResult(model); - } - - public Task Delete(TViewModel model) where TViewModel : class, IViewModel - { - return Task.CompletedTask; - } - } - - [TestFixture] - [Category("Unit")] - public class IocExtensionsTests - { - private ServiceCollection _services = null!; - private ServiceProvider _serviceProvider = null!; - - [SetUp] - public void SetUp() - { - _services = new ServiceCollection(); - _services.AddLogging(); // Add logging services - - // Register test implementations for required interfaces - _services.AddSingleton(); - _services.AddSingleton(); - _services.AddSingleton(); - } - - [TearDown] - public void TearDown() - { - _serviceProvider?.Dispose(); - } - - [Test] - public void UseSourceFlow_RegistersMultipleEventSubscribers() - { - // Arrange - // Test implementations already registered in SetUp - - // Act - _services.UseSourceFlow(); - - // Assert - _serviceProvider = _services.BuildServiceProvider(); - var eventSubscribers = _serviceProvider.GetServices(); - - // Should have at least 2 event subscribers (Aggregate and Projections) - Assert.That(eventSubscribers, Is.Not.Null); - Assert.That(eventSubscribers.Count(), Is.GreaterThanOrEqualTo(2), - "Should have at least 2 event subscribers (Aggregate and Projections)"); - } - - [Test] - public void UseSourceFlow_RegistersCommandSubscriber() - { - // Arrange - // Test implementations already registered in SetUp - - // Act - _services.UseSourceFlow(); - - // Assert - _serviceProvider = _services.BuildServiceProvider(); - var commandSubscriber = _serviceProvider.GetService(); - - Assert.That(commandSubscriber, Is.Not.Null, "ICommandSubscriber should be registered"); - } - - [Test] - public void UseSourceFlow_RegistersCommandDispatcher() - { - // Arrange - // Test implementations already registered in SetUp - - // Act - _services.UseSourceFlow(); - - // Assert - _serviceProvider = _services.BuildServiceProvider(); - var commandDispatcher = _serviceProvider.GetService(); - - Assert.That(commandDispatcher, Is.Not.Null, "ICommandDispatcher should be registered"); - } - - [Test] - public void UseSourceFlow_RegistersCommandBus() - { - // Arrange - // Test implementations already registered in SetUp - - // Act - _services.UseSourceFlow(); - - // Assert - _serviceProvider = _services.BuildServiceProvider(); - var commandBus = _serviceProvider.GetService(); - - Assert.That(commandBus, Is.Not.Null, "ICommandBus should be registered"); - } - - [Test] - public void UseSourceFlow_RegistersCommandPublisher() - { - // Arrange - // Test implementations already registered in SetUp - - // Act - _services.UseSourceFlow(); - - // Assert - _serviceProvider = _services.BuildServiceProvider(); - var commandPublisher = _serviceProvider.GetService(); - - Assert.That(commandPublisher, Is.Not.Null, "ICommandPublisher should be registered"); - } - - [Test] - public void UseSourceFlow_RegistersEventDispatcher() - { - // Arrange - // Test implementations already registered in SetUp - - // Act - _services.UseSourceFlow(); - - // Assert - _serviceProvider = _services.BuildServiceProvider(); - var eventDispatcher = _serviceProvider.GetService(); - - Assert.That(eventDispatcher, Is.Not.Null, "IEventDispatcher should be registered"); - } - - [Test] - public void UseSourceFlow_RegistersEventQueue() - { - // Arrange - // Test implementations already registered in SetUp - - // Act - _services.UseSourceFlow(); - - // Assert - _serviceProvider = _services.BuildServiceProvider(); - var eventQueue = _serviceProvider.GetService(); - - Assert.That(eventQueue, Is.Not.Null, "IEventQueue should be registered"); - } - - [Test] - public void UseSourceFlow_RegistersRequiredInfrastructureServices() - { - // Arrange - // Test implementations already registered in SetUp - - // Act - _services.UseSourceFlow(); - - // Assert - _serviceProvider = _services.BuildServiceProvider(); - - // Check that all infrastructure services are registered - Assert.That(_serviceProvider.GetService(), Is.Not.Null, "IEntityStore should be registered"); - Assert.That(_serviceProvider.GetService(), Is.Not.Null, "ICommandStore should be registered"); - Assert.That(_serviceProvider.GetService(), Is.Not.Null, "IViewModelStore should be registered"); - } - - [Test] - public void UseSourceFlow_RegistersAggregateFactory() - { - // Arrange - // Test implementations already registered in SetUp - - // Act - _services.UseSourceFlow(); - - // Assert - _serviceProvider = _services.BuildServiceProvider(); - var aggregateFactory = _serviceProvider.GetService(); - - Assert.That(aggregateFactory, Is.Not.Null, "IAggregateFactory should be registered"); - } - - [Test] - public void UseSourceFlow_RegistersAllServices_WithoutThrowing() - { - // Arrange - // Test implementations already registered in SetUp - - // Act & Assert - should not throw - Assert.DoesNotThrow(() => - { - _services.UseSourceFlow(); - _serviceProvider = _services.BuildServiceProvider(); - - // Try to resolve all major services to ensure they can be created - _ = _serviceProvider.GetService(); - _ = _serviceProvider.GetService(); - _ = _serviceProvider.GetService(); - _ = _serviceProvider.GetService(); - _ = _serviceProvider.GetService(); - _ = _serviceProvider.GetService(); - _ = _serviceProvider.GetService(); - _ = _serviceProvider.GetService(); - _ = _serviceProvider.GetService(); - }); - } - - [Test] - public void UseSourceFlow_RegistersEventSubscribersAsEnumerable() - { - // Arrange - // Test implementations already registered in SetUp - - // Act - _services.UseSourceFlow(); - - // Assert - _serviceProvider = _services.BuildServiceProvider(); - var eventSubscribers = _serviceProvider.GetServices(); - - Assert.That(eventSubscribers, Is.Not.Null, "IEventSubscriber enumerable should not be null"); - Assert.That(eventSubscribers.Count(), Is.GreaterThanOrEqualTo(2), - "Should have at least 2 IEventSubscriber implementations"); - } - } -} diff --git a/tests/SourceFlow.Core.Tests/Ioc/TestImplementations.cs b/tests/SourceFlow.Core.Tests/Ioc/TestImplementations.cs deleted file mode 100644 index e8daf481..00000000 --- a/tests/SourceFlow.Core.Tests/Ioc/TestImplementations.cs +++ /dev/null @@ -1,85 +0,0 @@ -using Microsoft.Extensions.Logging; -using Moq; -using SourceFlow.Aggregate; -using SourceFlow.Messaging; -using SourceFlow.Messaging.Commands; -using SourceFlow.Messaging.Events; -using SourceFlow.Projections; -using SourceFlow.Saga; - -namespace SourceFlow.Tests.Ioc -{ - public class TestEntity : IEntity - { - public int Id { get; set; } - } - - public class TestPayload : IPayload - { - // Empty implementation for test - } - - public class TestCommand : ICommand, IName, IMetadata - { - public string Name { get; set; } = "TestCommand"; - public EntityRef Entity { get; set; } = new EntityRef { Id = 1, IsNew = false }; - public IPayload Payload { get; set; } = new TestPayload(); - public Metadata Metadata { get; set; } = new Metadata(); - } - - public class TestEvent : IEvent, IName, IMetadata - { - public string Name { get; set; } = "TestEvent"; - public IEntity Payload { get; set; } = new TestEntity(); - public Metadata Metadata { get; set; } = new Metadata(); - } - - internal class TestAggregate : Aggregate, ITestAggregate, IHandles - { - public TestAggregate(Lazy commandPublisher, ILogger logger) - : base(commandPublisher, logger) { } - - public Task Handle(IEntity entity, TestCommand command) - { - // Implementation not needed for test - return Task.FromResult(entity); - } - } - - internal class TestSaga : Saga, ITestSaga, IHandles - { - public TestSaga(Lazy commandPublisher, IEventQueue eventQueue, - IEntityStoreAdapter repository, ILogger logger) - : base(commandPublisher, eventQueue, repository, logger) { } - - public Task Handle(IEntity entity, TestCommand command) - { - // Implementation not needed for test - return Task.FromResult(entity); - } - } - - public interface ITestAggregate - { } - - public interface ITestSaga - { } - - public class TestProjection : View, IProjectOn - { - public TestProjection() : base(new Mock().Object, new Mock>().Object) - { - } - - public Task On(TestEvent @event) - { - // Implementation not needed for test - return Task.FromResult(new TestViewModel { Id = 1 }); - } - } - - public class TestViewModel : IViewModel - { - public int Id { get; set; } - } -} diff --git a/tests/SourceFlow.Core.Tests/Messaging/CommandTests.cs b/tests/SourceFlow.Core.Tests/Messaging/CommandTests.cs deleted file mode 100644 index 01a74a98..00000000 --- a/tests/SourceFlow.Core.Tests/Messaging/CommandTests.cs +++ /dev/null @@ -1,43 +0,0 @@ -using SourceFlow.Messaging; -using SourceFlow.Messaging.Commands; - -namespace SourceFlow.Core.Tests.Messaging -{ - public class DummyPayload : IPayload - { - public int EntityId { get; set; } - } - - public class DummyCommand : Command - { - public DummyCommand(int entityId, DummyPayload payload) : base(entityId, payload) - { - } - } - -[TestFixture] - [Category("Unit")] - public class CommandTests - { - [Test] - public void Constructor_InitializesProperties() - { - var payload = new DummyPayload { EntityId = 42 }; - var command = new DummyCommand(42, payload); - Assert.IsNotNull(command.Metadata); - Assert.That(command.Name, Is.EqualTo("DummyCommand")); - Assert.That(command.Payload, Is.SameAs(payload)); - } - - [Test] - public void ICommandPayload_GetSet_WorksCorrectly() - { - var payload = new DummyPayload { EntityId = 7 }; - var command = new DummyCommand(7, new DummyPayload()); - ((ICommand)command).Payload = payload; - Assert.That(command.Payload, Is.SameAs(payload)); - Assert.That(((ICommand)command).Payload, Is.SameAs(payload)); - } - } - -} diff --git a/tests/SourceFlow.Core.Tests/Messaging/EventTests.cs b/tests/SourceFlow.Core.Tests/Messaging/EventTests.cs deleted file mode 100644 index 5d4a371e..00000000 --- a/tests/SourceFlow.Core.Tests/Messaging/EventTests.cs +++ /dev/null @@ -1,31 +0,0 @@ -using SourceFlow.Messaging.Events; - -namespace SourceFlow.Core.Tests.Messaging -{ - public class DummyEntity : IEntity - { - public int Id { get; set; } - } - - public class DummyEvent : Event - { - public DummyEvent(DummyEntity payload) : base(payload) - { - } - } - -[TestFixture] - [Category("Unit")] - public class EventTests - { - [Test] - public void Constructor_InitializesProperties() - { - var entity = new DummyEntity { Id = 42 }; - var @event = new DummyEvent(entity); - Assert.IsNotNull(@event.Metadata); - Assert.That(@event.Name, Is.EqualTo("DummyEvent")); - } - } - -} diff --git a/tests/SourceFlow.Core.Tests/Messaging/MetadataTests.cs b/tests/SourceFlow.Core.Tests/Messaging/MetadataTests.cs deleted file mode 100644 index 152c86a0..00000000 --- a/tests/SourceFlow.Core.Tests/Messaging/MetadataTests.cs +++ /dev/null @@ -1,38 +0,0 @@ -using SourceFlow.Messaging; - -namespace SourceFlow.Core.Tests.Messaging -{ - [TestFixture] - [Category("Unit")] - public class MetadataTests - { - [Test] - public void Constructor_InitializesProperties() - { - var metadata = new Metadata(); - Assert.That(metadata.EventId, Is.Not.EqualTo(Guid.Empty)); - Assert.That(metadata.OccurredOn, Is.Not.EqualTo(default(DateTime))); - Assert.IsFalse(metadata.IsReplay); - Assert.IsNotNull(metadata.Properties); - Assert.IsInstanceOf>(metadata.Properties); - } - - [Test] - public void Properties_CanBeSetAndGet() - { - var metadata = new Metadata(); - var guid = Guid.NewGuid(); - var now = DateTime.UtcNow; - metadata.EventId = guid; - metadata.IsReplay = true; - metadata.OccurredOn = now; - metadata.SequenceNo = 42; - metadata.Properties["foo"] = 123; - Assert.That(metadata.EventId, Is.EqualTo(guid)); - Assert.IsTrue(metadata.IsReplay); - Assert.That(metadata.OccurredOn, Is.EqualTo(now)); - Assert.That(metadata.SequenceNo, Is.EqualTo(42)); - Assert.That(metadata.Properties["foo"], Is.EqualTo(123)); - } - } -} diff --git a/tests/SourceFlow.Core.Tests/Middleware/CommandDispatchMiddlewareTests.cs b/tests/SourceFlow.Core.Tests/Middleware/CommandDispatchMiddlewareTests.cs deleted file mode 100644 index 2641fe47..00000000 --- a/tests/SourceFlow.Core.Tests/Middleware/CommandDispatchMiddlewareTests.cs +++ /dev/null @@ -1,266 +0,0 @@ -using Microsoft.Extensions.Logging; -using Moq; -using SourceFlow.Messaging; -using SourceFlow.Messaging.Bus; -using SourceFlow.Messaging.Bus.Impl; -using SourceFlow.Messaging.Commands; -using SourceFlow.Observability; -using SourceFlow.Core.Tests.Impl; - -namespace SourceFlow.Core.Tests.Middleware -{ - [TestFixture] - [Category("Unit")] - public class CommandDispatchMiddlewareTests - { - private Mock commandStoreMock; - private Mock> loggerMock; - private Mock commandDispatcherMock; - private Mock telemetryMock; - - [SetUp] - public void Setup() - { - commandStoreMock = new Mock(); - loggerMock = new Mock>(); - commandDispatcherMock = new Mock(); - telemetryMock = new Mock(); - - telemetryMock.Setup(t => t.TraceAsync(It.IsAny(), It.IsAny>(), It.IsAny>())) - .Returns((string name, Func operation, Action enrich) => operation()); - - commandStoreMock.Setup(cs => cs.GetNextSequenceNo(It.IsAny())).ReturnsAsync(1); - } - - private CommandBus CreateBus(params ICommandDispatchMiddleware[] middlewares) - { - return new CommandBus( - new[] { commandDispatcherMock.Object }, - commandStoreMock.Object, - loggerMock.Object, - telemetryMock.Object, - middlewares); - } - - [Test] - public async Task Middleware_ReceivesSameCommandInstance() - { - // Arrange - DummyCommand capturedCommand = null; - var middleware = new Mock(); - middleware - .Setup(m => m.InvokeAsync(It.IsAny(), It.IsAny>())) - .Returns>(async (cmd, next) => - { - capturedCommand = cmd; - await next(cmd); - }); - - var bus = CreateBus(middleware.Object); - var command = new DummyCommand(); - - // Act - await ((ICommandBus)bus).Publish(command); - - // Assert - Assert.That(capturedCommand, Is.SameAs(command)); - } - - [Test] - public async Task ThreeMiddleware_ExecuteInCorrectNestingOrder() - { - // Arrange - var callOrder = new List(); - - var m1 = CreateTracingMiddleware(callOrder, "m1"); - var m2 = CreateTracingMiddleware(callOrder, "m2"); - var m3 = CreateTracingMiddleware(callOrder, "m3"); - - var bus = CreateBus(m1, m2, m3); - - // Act - await ((ICommandBus)bus).Publish(new DummyCommand()); - - // Assert - Assert.That(callOrder, Is.EqualTo(new[] - { - "m1-before", "m2-before", "m3-before", - "m3-after", "m2-after", "m1-after" - })); - } - - [Test] - public async Task SecondMiddleware_ShortCircuits_ThirdNeverCalled() - { - // Arrange - var callOrder = new List(); - var m1 = CreateTracingMiddleware(callOrder, "m1"); - - var m2 = new Mock(); - m2.Setup(m => m.InvokeAsync(It.IsAny(), It.IsAny>())) - .Returns>((cmd, next) => - { - callOrder.Add("m2-shortcircuit"); - return Task.CompletedTask; // Does NOT call next - }); - - var m3 = CreateTracingMiddleware(callOrder, "m3"); - - var bus = CreateBus(m1, m2.Object, m3); - - // Act - await ((ICommandBus)bus).Publish(new DummyCommand()); - - // Assert - Assert.That(callOrder, Is.EqualTo(new[] { "m1-before", "m2-shortcircuit", "m1-after" })); - commandDispatcherMock.Verify(cd => cd.Dispatch(It.IsAny()), Times.Never); - } - - [Test] - public async Task Middleware_ExceptionPropagates() - { - // Arrange - var middleware = new Mock(); - middleware - .Setup(m => m.InvokeAsync(It.IsAny(), It.IsAny>())) - .ThrowsAsync(new InvalidOperationException("middleware error")); - - var bus = CreateBus(middleware.Object); - - // Act & Assert - var ex = Assert.ThrowsAsync(async () => - await ((ICommandBus)bus).Publish(new DummyCommand())); - Assert.That(ex.Message, Is.EqualTo("middleware error")); - } - - [Test] - public async Task Middleware_CanCatchAndHandleExceptionFromNext() - { - // Arrange - Exception caughtException = null; - - commandDispatcherMock - .Setup(cd => cd.Dispatch(It.IsAny())) - .ThrowsAsync(new InvalidOperationException("dispatch error")); - - var middleware = new Mock(); - middleware - .Setup(m => m.InvokeAsync(It.IsAny(), It.IsAny>())) - .Returns>(async (cmd, next) => - { - try - { - await next(cmd); - } - catch (Exception ex) - { - caughtException = ex; - // Swallow the exception - } - }); - - var bus = CreateBus(middleware.Object); - - // Act - should not throw because middleware caught it - await ((ICommandBus)bus).Publish(new DummyCommand()); - - // Assert - Assert.That(caughtException, Is.Not.Null); - Assert.That(caughtException.Message, Is.EqualTo("dispatch error")); - } - - [Test] - public async Task Middleware_CanModifyCommandMetadataBeforeNext() - { - // Arrange - var middleware = new Mock(); - middleware - .Setup(m => m.InvokeAsync(It.IsAny(), It.IsAny>())) - .Returns>(async (cmd, next) => - { - cmd.Metadata.Properties = new Dictionary { { "enriched", true } }; - await next(cmd); - }); - - DummyCommand dispatchedCommand = null; - commandDispatcherMock - .Setup(cd => cd.Dispatch(It.IsAny())) - .Callback(cmd => dispatchedCommand = cmd) - .Returns(Task.CompletedTask); - - var bus = CreateBus(middleware.Object); - var command = new DummyCommand(); - - // Act - await ((ICommandBus)bus).Publish(command); - - // Assert - Assert.That(dispatchedCommand.Metadata.Properties.ContainsKey("enriched"), Is.True); - } - - [Test] - public async Task Middleware_CalledOnReplayedCommands() - { - // Arrange - var middlewareCalled = false; - var middleware = new Mock(); - middleware - .Setup(m => m.InvokeAsync(It.IsAny(), It.IsAny>())) - .Returns>(async (cmd, next) => - { - middlewareCalled = true; - await next(cmd); - }); - - var replayCommand = new DummyCommand(); - replayCommand.Metadata.IsReplay = true; - replayCommand.Metadata.SequenceNo = 5; - - commandStoreMock.Setup(cs => cs.Load(It.IsAny())) - .ReturnsAsync(new List { replayCommand }); - - var bus = CreateBus(middleware.Object); - - // Act - await ((ICommandBus)bus).Replay(1); - - // Assert - Assert.That(middlewareCalled, Is.True); - } - - [Test] - public async Task Middleware_CallingNextTwice_DispatchesTwice() - { - // Arrange - var middleware = new Mock(); - middleware - .Setup(m => m.InvokeAsync(It.IsAny(), It.IsAny>())) - .Returns>(async (cmd, next) => - { - await next(cmd); - await next(cmd); - }); - - var bus = CreateBus(middleware.Object); - - // Act - await ((ICommandBus)bus).Publish(new DummyCommand()); - - // Assert - commandDispatcherMock.Verify(cd => cd.Dispatch(It.IsAny()), Times.Exactly(2)); - } - - private ICommandDispatchMiddleware CreateTracingMiddleware(List callOrder, string name) - { - var mock = new Mock(); - mock.Setup(m => m.InvokeAsync(It.IsAny(), It.IsAny>())) - .Returns>(async (cmd, next) => - { - callOrder.Add($"{name}-before"); - await next(cmd); - callOrder.Add($"{name}-after"); - }); - return mock.Object; - } - } -} diff --git a/tests/SourceFlow.Core.Tests/Middleware/CommandSubscribeMiddlewareTests.cs b/tests/SourceFlow.Core.Tests/Middleware/CommandSubscribeMiddlewareTests.cs deleted file mode 100644 index 3412ddd7..00000000 --- a/tests/SourceFlow.Core.Tests/Middleware/CommandSubscribeMiddlewareTests.cs +++ /dev/null @@ -1,263 +0,0 @@ -using Microsoft.Extensions.Logging; -using Moq; -using SourceFlow.Messaging; -using SourceFlow.Messaging.Commands; -using SourceFlow.Saga; - -namespace SourceFlow.Core.Tests.Middleware -{ - public class MiddlewareTestCommand : Command - { - public MiddlewareTestCommand(MiddlewareTestPayload payload) : base(true, payload) - { - } - } - - public class MiddlewareTestPayload : IPayload - { - public int Id { get; set; } - } - - public class MiddlewareTestSaga : ISaga, IHandles - { - public bool Handled { get; private set; } = false; - - public Task Handle(TCommand command) where TCommand : ICommand - { - if (this is IHandles) - Handled = true; - return Task.CompletedTask; - } - - public Task Handle(IEntity entity, MiddlewareTestCommand command) - { - Handled = true; - return Task.FromResult(entity); - } - } - - [TestFixture] - [Category("Unit")] - public class CommandSubscribeMiddlewareTests - { - private Mock> loggerMock; - private MiddlewareTestCommand testCommand; - - [SetUp] - public void Setup() - { - loggerMock = new Mock>(); - testCommand = new MiddlewareTestCommand(new MiddlewareTestPayload { Id = 1 }); - } - - private CommandSubscriber CreateSubscriber(IEnumerable sagas, params ICommandSubscribeMiddleware[] middlewares) - { - return new CommandSubscriber(sagas.ToList(), loggerMock.Object, middlewares); - } - - [Test] - public async Task Middleware_ReceivesSameCommandInstance() - { - // Arrange - MiddlewareTestCommand capturedCommand = null; - var middleware = new Mock(); - middleware - .Setup(m => m.InvokeAsync(It.IsAny(), It.IsAny>())) - .Returns>(async (cmd, next) => - { - capturedCommand = cmd; - await next(cmd); - }); - - var subscriber = CreateSubscriber(new[] { new MiddlewareTestSaga() }, middleware.Object); - - // Act - await subscriber.Subscribe(testCommand); - - // Assert - Assert.That(capturedCommand, Is.SameAs(testCommand)); - } - - [Test] - public async Task ThreeMiddleware_ExecuteInCorrectNestingOrder() - { - // Arrange - var callOrder = new List(); - var saga = new MiddlewareTestSaga(); - - var m1 = CreateTracingMiddleware(callOrder, "m1"); - var m2 = CreateTracingMiddleware(callOrder, "m2"); - var m3 = CreateTracingMiddleware(callOrder, "m3"); - - var subscriber = CreateSubscriber(new[] { saga }, m1, m2, m3); - - // Act - await subscriber.Subscribe(testCommand); - - // Assert - Assert.That(callOrder, Is.EqualTo(new[] - { - "m1-before", "m2-before", "m3-before", - "m3-after", "m2-after", "m1-after" - })); - Assert.That(saga.Handled, Is.True); - } - - [Test] - public async Task SecondMiddleware_ShortCircuits_ThirdNeverCalledAndSagaNotHandled() - { - // Arrange - var callOrder = new List(); - var saga = new MiddlewareTestSaga(); - - var m1 = CreateTracingMiddleware(callOrder, "m1"); - - var m2 = new Mock(); - m2.Setup(m => m.InvokeAsync(It.IsAny(), It.IsAny>())) - .Returns>((cmd, next) => - { - callOrder.Add("m2-shortcircuit"); - return Task.CompletedTask; - }); - - var m3 = CreateTracingMiddleware(callOrder, "m3"); - - var subscriber = CreateSubscriber(new[] { saga }, m1, m2.Object, m3); - - // Act - await subscriber.Subscribe(testCommand); - - // Assert - Assert.That(callOrder, Is.EqualTo(new[] { "m1-before", "m2-shortcircuit", "m1-after" })); - Assert.That(saga.Handled, Is.False); - } - - [Test] - public async Task Middleware_ExceptionPropagates() - { - // Arrange - var middleware = new Mock(); - middleware - .Setup(m => m.InvokeAsync(It.IsAny(), It.IsAny>())) - .ThrowsAsync(new InvalidOperationException("middleware error")); - - var subscriber = CreateSubscriber(new[] { new MiddlewareTestSaga() }, middleware.Object); - - // Act & Assert - var ex = Assert.ThrowsAsync(async () => - await subscriber.Subscribe(testCommand)); - Assert.That(ex.Message, Is.EqualTo("middleware error")); - } - - [Test] - public async Task Middleware_CanCatchAndHandleExceptionFromSaga() - { - // Arrange - Exception caughtException = null; - var faultySaga = new Mock(); - faultySaga.Setup(s => s.Handle(It.IsAny())) - .ThrowsAsync(new InvalidOperationException("saga error")); - - // Make faultySaga look like it handles MiddlewareTestCommand via Saga.CanHandle - // We need to use a real saga that throws - var throwingSaga = new ThrowingTestSaga(); - - var middleware = new Mock(); - middleware - .Setup(m => m.InvokeAsync(It.IsAny(), It.IsAny>())) - .Returns>(async (cmd, next) => - { - try - { - await next(cmd); - } - catch (Exception ex) - { - caughtException = ex; - } - }); - - var subscriber = CreateSubscriber(new ISaga[] { throwingSaga }, middleware.Object); - - // Act - await subscriber.Subscribe(testCommand); - - // Assert - Assert.That(caughtException, Is.Not.Null); - Assert.That(caughtException.Message, Is.EqualTo("saga error")); - } - - [Test] - public async Task Middleware_WithEmptySagas_StillExecutes() - { - // Arrange - var middlewareCalled = false; - var middleware = new Mock(); - middleware - .Setup(m => m.InvokeAsync(It.IsAny(), It.IsAny>())) - .Returns>(async (cmd, next) => - { - middlewareCalled = true; - await next(cmd); - }); - - var subscriber = CreateSubscriber(Enumerable.Empty(), middleware.Object); - - // Act - await subscriber.Subscribe(testCommand); - - // Assert - Assert.That(middlewareCalled, Is.True); - } - - [Test] - public async Task Middleware_CanModifyCommandMetadataBeforeNext() - { - // Arrange - var saga = new MiddlewareTestSaga(); - var middleware = new Mock(); - middleware - .Setup(m => m.InvokeAsync(It.IsAny(), It.IsAny>())) - .Returns>(async (cmd, next) => - { - cmd.Metadata.Properties = new Dictionary { { "enriched", true } }; - await next(cmd); - }); - - var subscriber = CreateSubscriber(new[] { saga }, middleware.Object); - - // Act - await subscriber.Subscribe(testCommand); - - // Assert - Assert.That(testCommand.Metadata.Properties.ContainsKey("enriched"), Is.True); - Assert.That(saga.Handled, Is.True); - } - - private ICommandSubscribeMiddleware CreateTracingMiddleware(List callOrder, string name) - { - var mock = new Mock(); - mock.Setup(m => m.InvokeAsync(It.IsAny(), It.IsAny>())) - .Returns>(async (cmd, next) => - { - callOrder.Add($"{name}-before"); - await next(cmd); - callOrder.Add($"{name}-after"); - }); - return mock.Object; - } - } - - public class ThrowingTestSaga : ISaga, IHandles - { - public Task Handle(TCommand command) where TCommand : ICommand - { - throw new InvalidOperationException("saga error"); - } - - public Task Handle(IEntity entity, MiddlewareTestCommand command) - { - throw new InvalidOperationException("saga error"); - } - } -} diff --git a/tests/SourceFlow.Core.Tests/Middleware/EventDispatchMiddlewareTests.cs b/tests/SourceFlow.Core.Tests/Middleware/EventDispatchMiddlewareTests.cs deleted file mode 100644 index 742ceae1..00000000 --- a/tests/SourceFlow.Core.Tests/Middleware/EventDispatchMiddlewareTests.cs +++ /dev/null @@ -1,228 +0,0 @@ -using Microsoft.Extensions.Logging; -using Moq; -using SourceFlow.Messaging.Events; -using SourceFlow.Messaging.Events.Impl; -using SourceFlow.Observability; -using SourceFlow.Core.Tests.Impl; - -namespace SourceFlow.Core.Tests.Middleware -{ - [TestFixture] - [Category("Unit")] - public class EventDispatchMiddlewareTests - { - private Mock> loggerMock; - private Mock eventDispatcherMock; - private Mock telemetryMock; - - [SetUp] - public void Setup() - { - loggerMock = new Mock>(); - eventDispatcherMock = new Mock(); - telemetryMock = new Mock(); - - telemetryMock.Setup(t => t.TraceAsync(It.IsAny(), It.IsAny>(), It.IsAny>())) - .Returns((string name, Func operation, Action enrich) => operation()); - } - - private EventQueue CreateQueue(params IEventDispatchMiddleware[] middlewares) - { - return new EventQueue( - new[] { eventDispatcherMock.Object }, - loggerMock.Object, - telemetryMock.Object, - middlewares); - } - - [Test] - public async Task Middleware_ReceivesSameEventInstance() - { - // Arrange - DummyEvent capturedEvent = null; - var middleware = new Mock(); - middleware - .Setup(m => m.InvokeAsync(It.IsAny(), It.IsAny>())) - .Returns>(async (evt, next) => - { - capturedEvent = evt; - await next(evt); - }); - - var queue = CreateQueue(middleware.Object); - var @event = new DummyEvent(); - - // Act - await queue.Enqueue(@event); - - // Assert - Assert.That(capturedEvent, Is.SameAs(@event)); - } - - [Test] - public async Task ThreeMiddleware_ExecuteInCorrectNestingOrder() - { - // Arrange - var callOrder = new List(); - - var m1 = CreateTracingMiddleware(callOrder, "m1"); - var m2 = CreateTracingMiddleware(callOrder, "m2"); - var m3 = CreateTracingMiddleware(callOrder, "m3"); - - var queue = CreateQueue(m1, m2, m3); - - // Act - await queue.Enqueue(new DummyEvent()); - - // Assert - Assert.That(callOrder, Is.EqualTo(new[] - { - "m1-before", "m2-before", "m3-before", - "m3-after", "m2-after", "m1-after" - })); - } - - [Test] - public async Task SecondMiddleware_ShortCircuits_ThirdNeverCalled() - { - // Arrange - var callOrder = new List(); - var m1 = CreateTracingMiddleware(callOrder, "m1"); - - var m2 = new Mock(); - m2.Setup(m => m.InvokeAsync(It.IsAny(), It.IsAny>())) - .Returns>((evt, next) => - { - callOrder.Add("m2-shortcircuit"); - return Task.CompletedTask; - }); - - var m3 = CreateTracingMiddleware(callOrder, "m3"); - - var queue = CreateQueue(m1, m2.Object, m3); - - // Act - await queue.Enqueue(new DummyEvent()); - - // Assert - Assert.That(callOrder, Is.EqualTo(new[] { "m1-before", "m2-shortcircuit", "m1-after" })); - eventDispatcherMock.Verify(ed => ed.Dispatch(It.IsAny()), Times.Never); - } - - [Test] - public async Task Middleware_ExceptionPropagates() - { - // Arrange - var middleware = new Mock(); - middleware - .Setup(m => m.InvokeAsync(It.IsAny(), It.IsAny>())) - .ThrowsAsync(new InvalidOperationException("middleware error")); - - var queue = CreateQueue(middleware.Object); - - // Act & Assert - var ex = Assert.ThrowsAsync(async () => - await queue.Enqueue(new DummyEvent())); - Assert.That(ex.Message, Is.EqualTo("middleware error")); - } - - [Test] - public async Task Middleware_CanCatchAndHandleExceptionFromNext() - { - // Arrange - Exception caughtException = null; - - eventDispatcherMock - .Setup(ed => ed.Dispatch(It.IsAny())) - .ThrowsAsync(new InvalidOperationException("dispatch error")); - - var middleware = new Mock(); - middleware - .Setup(m => m.InvokeAsync(It.IsAny(), It.IsAny>())) - .Returns>(async (evt, next) => - { - try - { - await next(evt); - } - catch (Exception ex) - { - caughtException = ex; - } - }); - - var queue = CreateQueue(middleware.Object); - - // Act - await queue.Enqueue(new DummyEvent()); - - // Assert - Assert.That(caughtException, Is.Not.Null); - Assert.That(caughtException.Message, Is.EqualTo("dispatch error")); - } - - [Test] - public async Task Middleware_CanModifyEventMetadataBeforeNext() - { - // Arrange - var middleware = new Mock(); - middleware - .Setup(m => m.InvokeAsync(It.IsAny(), It.IsAny>())) - .Returns>(async (evt, next) => - { - evt.Metadata.Properties = new Dictionary { { "enriched", true } }; - await next(evt); - }); - - DummyEvent dispatchedEvent = null; - eventDispatcherMock - .Setup(ed => ed.Dispatch(It.IsAny())) - .Callback(evt => dispatchedEvent = evt) - .Returns(Task.CompletedTask); - - var queue = CreateQueue(middleware.Object); - var @event = new DummyEvent(); - - // Act - await queue.Enqueue(@event); - - // Assert - Assert.That(dispatchedEvent.Metadata.Properties.ContainsKey("enriched"), Is.True); - } - - [Test] - public async Task Middleware_CallingNextTwice_DispatchesTwice() - { - // Arrange - var middleware = new Mock(); - middleware - .Setup(m => m.InvokeAsync(It.IsAny(), It.IsAny>())) - .Returns>(async (evt, next) => - { - await next(evt); - await next(evt); - }); - - var queue = CreateQueue(middleware.Object); - - // Act - await queue.Enqueue(new DummyEvent()); - - // Assert - eventDispatcherMock.Verify(ed => ed.Dispatch(It.IsAny()), Times.Exactly(2)); - } - - private IEventDispatchMiddleware CreateTracingMiddleware(List callOrder, string name) - { - var mock = new Mock(); - mock.Setup(m => m.InvokeAsync(It.IsAny(), It.IsAny>())) - .Returns>(async (evt, next) => - { - callOrder.Add($"{name}-before"); - await next(evt); - callOrder.Add($"{name}-after"); - }); - return mock.Object; - } - } -} diff --git a/tests/SourceFlow.Core.Tests/Middleware/EventSubscribeMiddlewareTests.cs b/tests/SourceFlow.Core.Tests/Middleware/EventSubscribeMiddlewareTests.cs deleted file mode 100644 index 41eeac41..00000000 --- a/tests/SourceFlow.Core.Tests/Middleware/EventSubscribeMiddlewareTests.cs +++ /dev/null @@ -1,435 +0,0 @@ -using Microsoft.Extensions.Logging; -using Moq; -using SourceFlow.Aggregate; -using SourceFlow.Messaging.Events; -using SourceFlow.Projections; - -namespace SourceFlow.Core.Tests.Middleware -{ - public class MiddlewareTestEntity : IEntity - { - public int Id { get; set; } - } - - public class MiddlewareTestEvent : Event - { - public MiddlewareTestEvent(MiddlewareTestEntity payload) : base(payload) - { - } - } - - public class MiddlewareTestAggregate : IAggregate, ISubscribes - { - public bool Handled { get; private set; } = false; - - public Task On(MiddlewareTestEvent @event) - { - Handled = true; - return Task.CompletedTask; - } - } - - public class MiddlewareTestViewModel : IViewModel - { - public int Id { get; set; } - } - - public class MiddlewareTestProjection : View, IProjectOn - { - public MiddlewareTestProjection() : base(new Mock().Object, new Mock>().Object) - { - } - - public bool Applied { get; private set; } = false; - - public Task On(MiddlewareTestEvent @event) - { - Applied = true; - return Task.FromResult(new MiddlewareTestViewModel { Id = 1 }); - } - } - - [TestFixture] - [Category("Unit")] - public class AggregateEventSubscribeMiddlewareTests - { - private Mock> loggerMock; - private MiddlewareTestEvent testEvent; - - [SetUp] - public void Setup() - { - loggerMock = new Mock>(); - testEvent = new MiddlewareTestEvent(new MiddlewareTestEntity { Id = 1 }); - } - - private Aggregate.EventSubscriber CreateSubscriber(IEnumerable aggregates, params IEventSubscribeMiddleware[] middlewares) - { - return new Aggregate.EventSubscriber(aggregates.ToList(), loggerMock.Object, middlewares); - } - - [Test] - public async Task Middleware_ReceivesSameEventInstance() - { - // Arrange - MiddlewareTestEvent capturedEvent = null; - var middleware = new Mock(); - middleware - .Setup(m => m.InvokeAsync(It.IsAny(), It.IsAny>())) - .Returns>(async (evt, next) => - { - capturedEvent = evt; - await next(evt); - }); - - var subscriber = CreateSubscriber(new[] { new MiddlewareTestAggregate() }, middleware.Object); - - // Act - await subscriber.Subscribe(testEvent); - - // Assert - Assert.That(capturedEvent, Is.SameAs(testEvent)); - } - - [Test] - public async Task ThreeMiddleware_ExecuteInCorrectNestingOrder() - { - // Arrange - var callOrder = new List(); - var aggregate = new MiddlewareTestAggregate(); - - var m1 = CreateTracingMiddleware(callOrder, "m1"); - var m2 = CreateTracingMiddleware(callOrder, "m2"); - var m3 = CreateTracingMiddleware(callOrder, "m3"); - - var subscriber = CreateSubscriber(new[] { aggregate }, m1, m2, m3); - - // Act - await subscriber.Subscribe(testEvent); - - // Assert - Assert.That(callOrder, Is.EqualTo(new[] - { - "m1-before", "m2-before", "m3-before", - "m3-after", "m2-after", "m1-after" - })); - Assert.That(aggregate.Handled, Is.True); - } - - [Test] - public async Task SecondMiddleware_ShortCircuits_ThirdNeverCalledAndAggregateNotHandled() - { - // Arrange - var callOrder = new List(); - var aggregate = new MiddlewareTestAggregate(); - - var m1 = CreateTracingMiddleware(callOrder, "m1"); - - var m2 = new Mock(); - m2.Setup(m => m.InvokeAsync(It.IsAny(), It.IsAny>())) - .Returns>((evt, next) => - { - callOrder.Add("m2-shortcircuit"); - return Task.CompletedTask; - }); - - var m3 = CreateTracingMiddleware(callOrder, "m3"); - - var subscriber = CreateSubscriber(new[] { aggregate }, m1, m2.Object, m3); - - // Act - await subscriber.Subscribe(testEvent); - - // Assert - Assert.That(callOrder, Is.EqualTo(new[] { "m1-before", "m2-shortcircuit", "m1-after" })); - Assert.That(aggregate.Handled, Is.False); - } - - [Test] - public async Task Middleware_ExceptionPropagates() - { - // Arrange - var middleware = new Mock(); - middleware - .Setup(m => m.InvokeAsync(It.IsAny(), It.IsAny>())) - .ThrowsAsync(new InvalidOperationException("middleware error")); - - var subscriber = CreateSubscriber(new[] { new MiddlewareTestAggregate() }, middleware.Object); - - // Act & Assert - var ex = Assert.ThrowsAsync(async () => - await subscriber.Subscribe(testEvent)); - Assert.That(ex.Message, Is.EqualTo("middleware error")); - } - - [Test] - public async Task Middleware_CanCatchAndHandleExceptionFromAggregate() - { - // Arrange - Exception caughtException = null; - var throwingAggregate = new ThrowingTestAggregate(); - - var middleware = new Mock(); - middleware - .Setup(m => m.InvokeAsync(It.IsAny(), It.IsAny>())) - .Returns>(async (evt, next) => - { - try - { - await next(evt); - } - catch (Exception ex) - { - caughtException = ex; - } - }); - - var subscriber = CreateSubscriber(new IAggregate[] { throwingAggregate }, middleware.Object); - - // Act - await subscriber.Subscribe(testEvent); - - // Assert - Assert.That(caughtException, Is.Not.Null); - Assert.That(caughtException.Message, Is.EqualTo("aggregate error")); - } - - [Test] - public async Task Middleware_WithEmptyAggregates_StillExecutes() - { - // Arrange - var middlewareCalled = false; - var middleware = new Mock(); - middleware - .Setup(m => m.InvokeAsync(It.IsAny(), It.IsAny>())) - .Returns>(async (evt, next) => - { - middlewareCalled = true; - await next(evt); - }); - - var subscriber = CreateSubscriber(Enumerable.Empty(), middleware.Object); - - // Act - await subscriber.Subscribe(testEvent); - - // Assert - Assert.That(middlewareCalled, Is.True); - } - - private IEventSubscribeMiddleware CreateTracingMiddleware(List callOrder, string name) - { - var mock = new Mock(); - mock.Setup(m => m.InvokeAsync(It.IsAny(), It.IsAny>())) - .Returns>(async (evt, next) => - { - callOrder.Add($"{name}-before"); - await next(evt); - callOrder.Add($"{name}-after"); - }); - return mock.Object; - } - } - - public class ThrowingTestAggregate : IAggregate, ISubscribes - { - public Task On(MiddlewareTestEvent @event) - { - throw new InvalidOperationException("aggregate error"); - } - } - - [TestFixture] - [Category("Unit")] - public class ProjectionEventSubscribeMiddlewareTests - { - private Mock> loggerMock; - private MiddlewareTestEvent testEvent; - - [SetUp] - public void Setup() - { - loggerMock = new Mock>(); - testEvent = new MiddlewareTestEvent(new MiddlewareTestEntity { Id = 1 }); - } - - private SourceFlow.Projections.EventSubscriber CreateSubscriber(IEnumerable views, params IEventSubscribeMiddleware[] middlewares) - { - return new SourceFlow.Projections.EventSubscriber(views.ToList(), loggerMock.Object, middlewares); - } - - [Test] - public async Task Middleware_ReceivesSameEventInstance() - { - // Arrange - MiddlewareTestEvent capturedEvent = null; - var middleware = new Mock(); - middleware - .Setup(m => m.InvokeAsync(It.IsAny(), It.IsAny>())) - .Returns>(async (evt, next) => - { - capturedEvent = evt; - await next(evt); - }); - - var subscriber = CreateSubscriber(new IView[] { new MiddlewareTestProjection() }, middleware.Object); - - // Act - await subscriber.Subscribe(testEvent); - - // Assert - Assert.That(capturedEvent, Is.SameAs(testEvent)); - } - - [Test] - public async Task ThreeMiddleware_ExecuteInCorrectNestingOrder() - { - // Arrange - var callOrder = new List(); - var projection = new MiddlewareTestProjection(); - - var m1 = CreateTracingMiddleware(callOrder, "m1"); - var m2 = CreateTracingMiddleware(callOrder, "m2"); - var m3 = CreateTracingMiddleware(callOrder, "m3"); - - var subscriber = CreateSubscriber(new IView[] { projection }, m1, m2, m3); - - // Act - await subscriber.Subscribe(testEvent); - - // Assert - Assert.That(callOrder, Is.EqualTo(new[] - { - "m1-before", "m2-before", "m3-before", - "m3-after", "m2-after", "m1-after" - })); - Assert.That(projection.Applied, Is.True); - } - - [Test] - public async Task SecondMiddleware_ShortCircuits_ThirdNeverCalledAndProjectionNotApplied() - { - // Arrange - var callOrder = new List(); - var projection = new MiddlewareTestProjection(); - - var m1 = CreateTracingMiddleware(callOrder, "m1"); - - var m2 = new Mock(); - m2.Setup(m => m.InvokeAsync(It.IsAny(), It.IsAny>())) - .Returns>((evt, next) => - { - callOrder.Add("m2-shortcircuit"); - return Task.CompletedTask; - }); - - var m3 = CreateTracingMiddleware(callOrder, "m3"); - - var subscriber = CreateSubscriber(new IView[] { projection }, m1, m2.Object, m3); - - // Act - await subscriber.Subscribe(testEvent); - - // Assert - Assert.That(callOrder, Is.EqualTo(new[] { "m1-before", "m2-shortcircuit", "m1-after" })); - Assert.That(projection.Applied, Is.False); - } - - [Test] - public async Task Middleware_ExceptionPropagates() - { - // Arrange - var middleware = new Mock(); - middleware - .Setup(m => m.InvokeAsync(It.IsAny(), It.IsAny>())) - .ThrowsAsync(new InvalidOperationException("middleware error")); - - var subscriber = CreateSubscriber(new IView[] { new MiddlewareTestProjection() }, middleware.Object); - - // Act & Assert - var ex = Assert.ThrowsAsync(async () => - await subscriber.Subscribe(testEvent)); - Assert.That(ex.Message, Is.EqualTo("middleware error")); - } - - [Test] - public async Task Middleware_WithEmptyViews_StillExecutes() - { - // Arrange - var middlewareCalled = false; - var middleware = new Mock(); - middleware - .Setup(m => m.InvokeAsync(It.IsAny(), It.IsAny>())) - .Returns>(async (evt, next) => - { - middlewareCalled = true; - await next(evt); - }); - - var subscriber = CreateSubscriber(Enumerable.Empty(), middleware.Object); - - // Act - await subscriber.Subscribe(testEvent); - - // Assert - Assert.That(middlewareCalled, Is.True); - } - - [Test] - public async Task Middleware_CanCatchAndHandleExceptionFromProjection() - { - // Arrange - Exception caughtException = null; - var throwingProjection = new ThrowingTestProjection(); - - var middleware = new Mock(); - middleware - .Setup(m => m.InvokeAsync(It.IsAny(), It.IsAny>())) - .Returns>(async (evt, next) => - { - try - { - await next(evt); - } - catch (Exception ex) - { - caughtException = ex; - } - }); - - var subscriber = CreateSubscriber(new IView[] { throwingProjection }, middleware.Object); - - // Act - await subscriber.Subscribe(testEvent); - - // Assert - Assert.That(caughtException, Is.Not.Null); - Assert.That(caughtException.Message, Is.EqualTo("projection error")); - } - - private IEventSubscribeMiddleware CreateTracingMiddleware(List callOrder, string name) - { - var mock = new Mock(); - mock.Setup(m => m.InvokeAsync(It.IsAny(), It.IsAny>())) - .Returns>(async (evt, next) => - { - callOrder.Add($"{name}-before"); - await next(evt); - callOrder.Add($"{name}-after"); - }); - return mock.Object; - } - } - - public class ThrowingTestProjection : View, IProjectOn - { - public ThrowingTestProjection() : base(new Mock().Object, new Mock>().Object) - { - } - - public Task On(MiddlewareTestEvent @event) - { - throw new InvalidOperationException("projection error"); - } - } -} diff --git a/tests/SourceFlow.Core.Tests/Projections/EventSubscriberTests.cs b/tests/SourceFlow.Core.Tests/Projections/EventSubscriberTests.cs deleted file mode 100644 index 35c8d3f5..00000000 --- a/tests/SourceFlow.Core.Tests/Projections/EventSubscriberTests.cs +++ /dev/null @@ -1,269 +0,0 @@ -using Microsoft.Extensions.Logging; -using Moq; -using SourceFlow.Messaging.Events; -using SourceFlow.Projections; - -namespace SourceFlow.Core.Tests.Projections -{ - public class DummyProjectionEntity : IEntity - { - public int Id { get; set; } - } - - public class DummyProjectionEvent : Event - { - public DummyProjectionEvent(DummyProjectionEntity payload) : base(payload) - { - } - } - - public class TestProjection : View, IProjectOn - { - public TestProjection() : base(new Mock().Object, new Mock>().Object) - { - } - - public bool Applied { get; private set; } = false; - - public Task On(DummyProjectionEvent @event) - { - Applied = true; - return Task.FromResult(new TestProjectionViewModel { Id = 1 }); - } - } - - public class TestProjectionViewModel : IViewModel - { - public int Id { get; set; } - } - - public class NonMatchingProjection : View - { - public NonMatchingProjection() : base(new Mock().Object, new Mock>().Object) - { - } - - // This projection does not implement IProjectOn so won't handle DummyProjectionEvent - } - - [TestFixture] - [Category("Unit")] - public class EventSubscriberTests - { - private Mock> _mockLogger; - private DummyProjectionEvent _testEvent; - - [SetUp] - public void SetUp() - { - _mockLogger = new Mock>(); - _testEvent = new DummyProjectionEvent(new DummyProjectionEntity { Id = 1 }); - } - - [Test] - public void Constructor_WithNullProjections_ThrowsArgumentNullException() - { - // Arrange - IEnumerable nullProjections = null!; - - // Act & Assert - Assert.Throws(() => - new EventSubscriber(nullProjections, _mockLogger.Object, Enumerable.Empty())); - } - - [Test] - public void Constructor_WithNullLogger_ThrowsArgumentNullException() - { - // Arrange - var projections = new List { new TestProjection() }; - - // Act & Assert - Assert.Throws(() => - new EventSubscriber(projections, null, Enumerable.Empty())); - } - - [Test] - public void Constructor_NullMiddleware_ThrowsArgumentNullException() - { - // Arrange - var projections = new List { new TestProjection() }; - - // Act & Assert - Assert.Throws(() => - new EventSubscriber(projections, _mockLogger.Object, null)); - } - - [Test] - public void Constructor_WithValidParameters_Succeeds() - { - // Arrange - var projections = new List { new TestProjection() }; - - // Act - var subscriber = new EventSubscriber(projections, _mockLogger.Object, Enumerable.Empty()); - - // Assert - Assert.IsNotNull(subscriber); - } - - [Test] - public async Task Subscribe_WithMatchingProjection_AppliesProjection() - { - // Arrange - var testProjection = new TestProjection(); - var projections = new List { testProjection }; - var subscriber = new EventSubscriber(projections, _mockLogger.Object, Enumerable.Empty()); - - // Act - await subscriber.Subscribe(_testEvent); - - // Assert - Assert.IsTrue(testProjection.Applied); - } - - [Test] - public async Task Subscribe_WithNonMatchingProjection_DoesNotApplyProjection() - { - // Arrange - var nonMatchingProjection = new NonMatchingProjection(); - var projections = new List { nonMatchingProjection }; - var subscriber = new EventSubscriber(projections, _mockLogger.Object, Enumerable.Empty()); - - // Act - await subscriber.Subscribe(_testEvent); - - // Assert - // We can't directly test this, but we know that non-matching projections won't be applied - // since they don't implement IProjectOn - } - - [Test] - public async Task Subscribe_WithMultipleProjections_AppliesMatchingProjectionsOnly() - { - // Arrange - var matchingProjection1 = new TestProjection(); - var matchingProjection2 = new TestProjection(); - var nonMatchingProjection = new NonMatchingProjection(); - var projections = new List { matchingProjection1, nonMatchingProjection, matchingProjection2 }; - var subscriber = new EventSubscriber(projections, _mockLogger.Object, Enumerable.Empty()); - - // Act - await subscriber.Subscribe(_testEvent); - - // Assert - Assert.IsTrue(matchingProjection1.Applied); - Assert.IsTrue(matchingProjection2.Applied); - } - - [Test] - public async Task Subscribe_WithNoMatchingProjections_DoesNotThrow() - { - // Arrange - var nonMatchingProjection = new NonMatchingProjection(); - var projections = new List { nonMatchingProjection }; - var subscriber = new EventSubscriber(projections, _mockLogger.Object, Enumerable.Empty()); - - // Act & Assert - Assert.DoesNotThrowAsync(async () => await subscriber.Subscribe(_testEvent)); - } - - [Test] - public async Task Subscribe_WithEmptyProjectionsCollection_DoesNotThrow() - { - // Arrange - var projections = new List(); - var subscriber = new EventSubscriber(projections, _mockLogger.Object, Enumerable.Empty()); - - // Act & Assert - Assert.DoesNotThrowAsync(async () => await subscriber.Subscribe(_testEvent)); - } - - [Test] - public async Task Subscribe_WithMiddleware_ExecutesMiddlewareAroundCoreLogic() - { - // Arrange - var callOrder = new List(); - var testProjection = new TestProjection(); - var projections = new List { testProjection }; - - var middlewareMock = new Mock(); - middlewareMock - .Setup(m => m.InvokeAsync(It.IsAny(), It.IsAny>())) - .Returns>(async (evt, next) => - { - callOrder.Add("middleware-before"); - await next(evt); - callOrder.Add("middleware-after"); - }); - - var subscriber = new EventSubscriber(projections, _mockLogger.Object, new[] { middlewareMock.Object }); - - // Act - await subscriber.Subscribe(_testEvent); - - // Assert - Assert.That(callOrder[0], Is.EqualTo("middleware-before")); - Assert.That(callOrder[1], Is.EqualTo("middleware-after")); - Assert.IsTrue(testProjection.Applied); - } - - [Test] - public async Task Subscribe_WithMultipleMiddleware_ExecutesInRegistrationOrder() - { - // Arrange - var callOrder = new List(); - var testProjection = new TestProjection(); - var projections = new List { testProjection }; - - var middleware1 = new Mock(); - middleware1 - .Setup(m => m.InvokeAsync(It.IsAny(), It.IsAny>())) - .Returns>(async (evt, next) => - { - callOrder.Add("m1-before"); - await next(evt); - callOrder.Add("m1-after"); - }); - - var middleware2 = new Mock(); - middleware2 - .Setup(m => m.InvokeAsync(It.IsAny(), It.IsAny>())) - .Returns>(async (evt, next) => - { - callOrder.Add("m2-before"); - await next(evt); - callOrder.Add("m2-after"); - }); - - var subscriber = new EventSubscriber(projections, _mockLogger.Object, - new IEventSubscribeMiddleware[] { middleware1.Object, middleware2.Object }); - - // Act - await subscriber.Subscribe(_testEvent); - - // Assert - Assert.That(callOrder, Is.EqualTo(new[] { "m1-before", "m2-before", "m2-after", "m1-after" })); - } - - [Test] - public async Task Subscribe_MiddlewareShortCircuits_DoesNotCallCoreLogic() - { - // Arrange - var testProjection = new TestProjection(); - var projections = new List { testProjection }; - - var middlewareMock = new Mock(); - middlewareMock - .Setup(m => m.InvokeAsync(It.IsAny(), It.IsAny>())) - .Returns(Task.CompletedTask); // Does NOT call next - - var subscriber = new EventSubscriber(projections, _mockLogger.Object, new[] { middlewareMock.Object }); - - // Act - await subscriber.Subscribe(_testEvent); - - // Assert - projection was never reached - Assert.IsFalse(testProjection.Applied); - } - } -} diff --git a/tests/SourceFlow.Core.Tests/Sagas/CommandSubscriberTests.cs b/tests/SourceFlow.Core.Tests/Sagas/CommandSubscriberTests.cs deleted file mode 100644 index 1e4c8882..00000000 --- a/tests/SourceFlow.Core.Tests/Sagas/CommandSubscriberTests.cs +++ /dev/null @@ -1,257 +0,0 @@ -using Microsoft.Extensions.Logging; -using Moq; -using SourceFlow.Messaging; -using SourceFlow.Messaging.Commands; -using SourceFlow.Saga; - -namespace SourceFlow.Core.Tests.Sagas -{ - public class DummyCommandPayload : IPayload - { - public int Id { get; set; } - public string Data { get; set; } = string.Empty; - } - - public class DummyCommand : Command - { - public DummyCommand(DummyCommandPayload payload) : base(true, payload) - { - } - } - - public class TestSaga : ISaga, IHandles - { - public bool Handled { get; private set; } = false; - public Type LastHandledCommandType { get; private set; } = null!; - public DummyCommand LastHandledCommand { get; private set; } = null!; - - public Task Handle(TCommand command) where TCommand : ICommand - { - if (this is IHandles handles) - { - Handled = true; - LastHandledCommandType = typeof(TCommand); - if (command is DummyCommand dummyCommand) - { - LastHandledCommand = dummyCommand; - } - } - return Task.CompletedTask; - } - - public Task Handle(IEntity entity, DummyCommand command) - { - Handled = true; - LastHandledCommandType = typeof(DummyCommand); - LastHandledCommand = command; - return Task.FromResult(entity); - } - } - - public class NonHandlingSaga : ISaga - { - public bool Handled { get; private set; } = false; - - public Task Handle(TCommand command) where TCommand : ICommand - { - // This saga doesn't implement IHandles, so it won't handle the command - // But we still want to track if this method was called - Handled = true; // This will be true if the ISaga.On method is called - return Task.CompletedTask; - } - } - - [TestFixture] - [Category("Unit")] - public class CommandSubscriberTests - { - private Mock> _mockLogger; - private DummyCommand _testCommand; - - [SetUp] - public void SetUp() - { - _mockLogger = new Mock>(); - _testCommand = new DummyCommand(new DummyCommandPayload { Id = 1, Data = "Test" }); - } - - [Test] - public void Constructor_WithValidParameters_Succeeds() - { - // Arrange - var sagas = new List { new TestSaga() }; - - // Act - var subscriber = new CommandSubscriber(sagas, _mockLogger.Object, Enumerable.Empty()); - - // Assert - Assert.IsNotNull(subscriber); - } - - [Test] - public void Constructor_NullMiddleware_ThrowsArgumentNullException() - { - // Arrange - var sagas = new List { new TestSaga() }; - - // Act & Assert - Assert.Throws(() => - new CommandSubscriber(sagas, _mockLogger.Object, null)); - } - - [Test] - public async Task Subscribe_WithMatchingSaga_HandlesCommand() - { - // Arrange - var testSaga = new TestSaga(); - var sagas = new List { testSaga }; - var subscriber = new CommandSubscriber(sagas, _mockLogger.Object, Enumerable.Empty()); - - // Act - await subscriber.Subscribe(_testCommand); - - // Assert - Assert.IsTrue(testSaga.Handled); - Assert.That(testSaga.LastHandledCommandType, Is.EqualTo(typeof(DummyCommand))); - } - - [Test] - public async Task Subscribe_WithEmptySagasCollection_DoesNotThrow() - { - // Arrange - var sagas = new List(); - - // Act - var subscriber = new CommandSubscriber(sagas, _mockLogger.Object, Enumerable.Empty()); - - // Assert - Assert.IsNotNull(subscriber); - - // Act & Assert - should not throw and should just return early - Assert.DoesNotThrowAsync(async () => await subscriber.Subscribe(_testCommand)); - } - - [Test] - public async Task Subscribe_WithMultipleSagas_HandlesCommandInAllMatchingSagas() - { - // Arrange - var testSaga1 = new TestSaga(); - var testSaga2 = new TestSaga(); - var nonHandlingSaga = new NonHandlingSaga(); - var sagas = new List { testSaga1, nonHandlingSaga, testSaga2 }; - var subscriber = new CommandSubscriber(sagas, _mockLogger.Object, Enumerable.Empty()); - - // Act - await subscriber.Subscribe(_testCommand); - - // Assert - Assert.IsTrue(testSaga1.Handled); - Assert.IsTrue(testSaga2.Handled); - Assert.IsFalse(nonHandlingSaga.Handled); // This saga doesn't implement IHandles - Assert.That(testSaga1.LastHandledCommandType, Is.EqualTo(typeof(DummyCommand))); - Assert.That(testSaga2.LastHandledCommandType, Is.EqualTo(typeof(DummyCommand))); - } - - [Test] - public async Task Subscribe_NullSagas_StillCreatesSubscriber() - { - // Arrange & Act - var subscriber = new CommandSubscriber(null, _mockLogger.Object, Enumerable.Empty()); - - // Assert - Assert.IsNotNull(subscriber); - - // Note: The CommandSubscriber constructor doesn't validate null sagas, - // so we just test that it doesn't throw during construction. - // During Subscribe(), it would check sagas.Any() which would handle null. - } - - [Test] - public async Task Subscribe_WithMiddleware_ExecutesMiddlewareAroundCoreLogic() - { - // Arrange - var callOrder = new List(); - var testSaga = new TestSaga(); - var sagas = new List { testSaga }; - - var middlewareMock = new Mock(); - middlewareMock - .Setup(m => m.InvokeAsync(It.IsAny(), It.IsAny>())) - .Returns>(async (cmd, next) => - { - callOrder.Add("middleware-before"); - await next(cmd); - callOrder.Add("middleware-after"); - }); - - var subscriber = new CommandSubscriber(sagas, _mockLogger.Object, new[] { middlewareMock.Object }); - - // Act - await subscriber.Subscribe(_testCommand); - - // Assert - Assert.That(callOrder[0], Is.EqualTo("middleware-before")); - Assert.That(callOrder[1], Is.EqualTo("middleware-after")); - Assert.IsTrue(testSaga.Handled); - } - - [Test] - public async Task Subscribe_WithMultipleMiddleware_ExecutesInRegistrationOrder() - { - // Arrange - var callOrder = new List(); - var testSaga = new TestSaga(); - var sagas = new List { testSaga }; - - var middleware1 = new Mock(); - middleware1 - .Setup(m => m.InvokeAsync(It.IsAny(), It.IsAny>())) - .Returns>(async (cmd, next) => - { - callOrder.Add("m1-before"); - await next(cmd); - callOrder.Add("m1-after"); - }); - - var middleware2 = new Mock(); - middleware2 - .Setup(m => m.InvokeAsync(It.IsAny(), It.IsAny>())) - .Returns>(async (cmd, next) => - { - callOrder.Add("m2-before"); - await next(cmd); - callOrder.Add("m2-after"); - }); - - var subscriber = new CommandSubscriber(sagas, _mockLogger.Object, - new ICommandSubscribeMiddleware[] { middleware1.Object, middleware2.Object }); - - // Act - await subscriber.Subscribe(_testCommand); - - // Assert - Assert.That(callOrder, Is.EqualTo(new[] { "m1-before", "m2-before", "m2-after", "m1-after" })); - } - - [Test] - public async Task Subscribe_MiddlewareShortCircuits_DoesNotCallCoreLogic() - { - // Arrange - var testSaga = new TestSaga(); - var sagas = new List { testSaga }; - - var middlewareMock = new Mock(); - middlewareMock - .Setup(m => m.InvokeAsync(It.IsAny(), It.IsAny>())) - .Returns(Task.CompletedTask); // Does NOT call next - - var subscriber = new CommandSubscriber(sagas, _mockLogger.Object, new[] { middlewareMock.Object }); - - // Act - await subscriber.Subscribe(_testCommand); - - // Assert - saga was never reached - Assert.IsFalse(testSaga.Handled); - } - } -} diff --git a/tests/SourceFlow.Core.Tests/Sagas/SagaTests.cs b/tests/SourceFlow.Core.Tests/Sagas/SagaTests.cs deleted file mode 100644 index a99cdd68..00000000 --- a/tests/SourceFlow.Core.Tests/Sagas/SagaTests.cs +++ /dev/null @@ -1,110 +0,0 @@ -using Microsoft.Extensions.Logging; -using Moq; -using SourceFlow.Messaging; -using SourceFlow.Messaging.Commands; -using SourceFlow.Messaging.Events; -using SourceFlow.Saga; - -namespace SourceFlow.Core.Tests.Sagas -{ - [TestFixture] - [Category("Unit")] - public class SagaTests - { - public class TestSaga : Saga, IHandles - { - public TestSaga() : base(new Lazy(() => new Mock().Object), new Mock().Object, new Mock().Object, new Mock>().Object) - { - } - - public TestSaga(Lazy publisher, IEventQueue queue, IEntityStoreAdapter repo, ILogger logger) : base(publisher, queue, repo, logger) - { - commandPublisher = publisher; - eventQueue = queue; - entityStore = repo; - this.logger = logger; - } - - public Task Handle(IEntity entity, ICommand command) => Task.FromResult(entity); - - public Task TestPublish(ICommand command) => Publish(command); - - public Task TestRaise(IEvent @event) => Raise(@event); - } - - [Test] - public void CanHandle_ReturnsTrueForMatchingType() - { - var saga = new TestSaga(); - Assert.IsTrue(Saga.CanHandle(saga, typeof(ICommand))); - } - - [Test] - public void CanHandle_ReturnsFalseForNulls() - { - Assert.IsFalse(Saga.CanHandle(null, typeof(ICommand))); - var saga = new TestSaga(); - Assert.IsFalse(Saga.CanHandle(saga, null)); - } - - [Test] - public void Publish_NullCommand_ThrowsArgumentNullException() - { - var saga = new TestSaga(); - Assert.ThrowsAsync(async () => await saga.TestPublish(null!)); - } - - [Test] - public void Publish_NullPayload_ThrowsInvalidOperationException() - { - var saga = new TestSaga(); - var commandMock = new Mock(); - commandMock.Setup(c => c.Payload).Returns((IPayload?)null!); - Assert.ThrowsAsync(async () => await saga.TestPublish(commandMock.Object)); - } - - [Test] - public async Task Publish_ValidCommand_DelegatesToPublisher() - { - var publisherMock = new Mock(); - publisherMock.Setup(p => p.Publish(It.IsAny())).Returns(Task.CompletedTask); - var saga = new TestSaga(new Lazy(() => publisherMock.Object), new Mock().Object, new Mock().Object, new Mock>().Object); - var payloadMock = new Mock(); - - var commandMock = new Mock(); - commandMock.Setup(c => c.Payload).Returns(payloadMock.Object); - commandMock.Setup(p => p.Entity).Returns(new EntityRef { Id = 1 }); - await saga.TestPublish(commandMock.Object); - publisherMock.Verify(p => p.Publish(commandMock.Object), Times.Once); - } - - [Test] - public void Raise_NullEvent_ThrowsArgumentNullException() - { - var saga = new TestSaga(); - Assert.ThrowsAsync(async () => await saga.TestRaise(null!)); - } - - [Test] - public void Raise_NullPayload_ThrowsInvalidOperationException() - { - var saga = new TestSaga(); - var eventMock = new Mock(); - eventMock.Setup(e => e.Payload).Returns((IEntity?)null!); - Assert.ThrowsAsync(async () => await saga.TestRaise(eventMock.Object)); - } - - [Test] - public async Task Raise_ValidEvent_DelegatesToQueue() - { - var queueMock = new Mock(); - queueMock.Setup(q => q.Enqueue(It.IsAny())).Returns(Task.CompletedTask); - var saga = new TestSaga(new Lazy(() => new Mock().Object), queueMock.Object, new Mock().Object, new Mock>().Object); - var payloadMock = new Mock(); - var eventMock = new Mock(); - eventMock.Setup(e => e.Payload).Returns(payloadMock.Object); - await saga.TestRaise(eventMock.Object); - queueMock.Verify(q => q.Enqueue(eventMock.Object), Times.Once); - } - } -} diff --git a/tests/SourceFlow.Core.Tests/SourceFlow.Core.Tests.csproj b/tests/SourceFlow.Core.Tests/SourceFlow.Core.Tests.csproj deleted file mode 100644 index e0b6d1d8..00000000 --- a/tests/SourceFlow.Core.Tests/SourceFlow.Core.Tests.csproj +++ /dev/null @@ -1,34 +0,0 @@ - - - - net9.0 - latest - enable - enable - false - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/tests/SourceFlow.Stores.EntityFramework.Tests/Configutaion/ConnectionStringConfigurationTests.cs b/tests/SourceFlow.Stores.EntityFramework.Tests/Configutaion/ConnectionStringConfigurationTests.cs deleted file mode 100644 index 100a2c77..00000000 --- a/tests/SourceFlow.Stores.EntityFramework.Tests/Configutaion/ConnectionStringConfigurationTests.cs +++ /dev/null @@ -1,103 +0,0 @@ -#nullable enable - -using System.Collections.Generic; -using Microsoft.Extensions.Configuration; -using Microsoft.Extensions.DependencyInjection; -using NUnit.Framework; -using SourceFlow.Stores.EntityFramework.Extensions; - -namespace SourceFlow.Stores.EntityFramework.Tests.Configutaion -{ - [TestFixture] - [Category("Unit")] - public class ConnectionStringConfigurationTests - { - [Test] - public void AddSourceFlowEfStores_SingleConnectionString_RegistersCorrectly() - { - // Arrange - var services = new ServiceCollection(); - var connectionString = "DataSource=:memory:"; - - // Act - services.AddSourceFlowEfStores(connectionString); - - // Assert - Services should be registered without throwing exceptions - var serviceProvider = services.BuildServiceProvider(); - Assert.DoesNotThrow(() => serviceProvider.GetRequiredService()); - Assert.DoesNotThrow(() => serviceProvider.GetRequiredService()); - Assert.DoesNotThrow(() => serviceProvider.GetRequiredService()); - Assert.DoesNotThrow(() => serviceProvider.GetRequiredService()); - Assert.DoesNotThrow(() => serviceProvider.GetRequiredService()); - Assert.DoesNotThrow(() => serviceProvider.GetRequiredService()); - } - - [Test] - public void AddSourceFlowEfStores_SeparateConnectionStrings_RegistersCorrectly() - { - // Arrange - var services = new ServiceCollection(); - var cmdConnectionString = "DataSource=command.db"; - var entityConnectionString = "DataSource=entity.db"; - var viewModelConnectionString = "DataSource=viewModel.db"; - - // Act - services.AddSourceFlowEfStores( - cmdConnectionString, - entityConnectionString, - viewModelConnectionString); - - // Assert - Services should be registered without throwing exceptions - var serviceProvider = services.BuildServiceProvider(); - Assert.DoesNotThrow(() => serviceProvider.GetRequiredService()); - Assert.DoesNotThrow(() => serviceProvider.GetRequiredService()); - Assert.DoesNotThrow(() => serviceProvider.GetRequiredService()); - } - - [Test] - public void AddSourceFlowEfStores_WithConfiguration_RegistersCorrectly() - { - // Arrange - var config = new ConfigurationBuilder() - .AddInMemoryCollection(new Dictionary - { - {"ConnectionStrings:SourceFlow.Command", "DataSource=command.db"}, - {"ConnectionStrings:SourceFlow.Entity", "DataSource=entity.db"}, - {"ConnectionStrings:SourceFlow.ViewModel", "DataSource=viewModel.db"} - }) - .Build(); - - var services = new ServiceCollection(); - - // Act - services.AddSourceFlowEfStores(config); - - // Assert - Services should be registered without throwing exceptions - var serviceProvider = services.BuildServiceProvider(); - Assert.DoesNotThrow(() => serviceProvider.GetRequiredService()); - Assert.DoesNotThrow(() => serviceProvider.GetRequiredService()); - Assert.DoesNotThrow(() => serviceProvider.GetRequiredService()); - } - - [Test] - public void AddSourceFlowEfStores_WithOptionsAction_RegistersCorrectly() - { - // Arrange - var services = new ServiceCollection(); - - // Act - services.AddSourceFlowEfStores(options => - { - options.CommandConnectionString = "DataSource=command.db"; - options.EntityConnectionString = "DataSource=entity.db"; - options.ViewModelConnectionString = "DataSource=viewModel.db"; - }); - - // Assert - Services should be registered without throwing exceptions - var serviceProvider = services.BuildServiceProvider(); - Assert.DoesNotThrow(() => serviceProvider.GetRequiredService()); - Assert.DoesNotThrow(() => serviceProvider.GetRequiredService()); - Assert.DoesNotThrow(() => serviceProvider.GetRequiredService()); - } - } -} diff --git a/tests/SourceFlow.Stores.EntityFramework.Tests/E2E/Aggregates/AccountAggregate.cs b/tests/SourceFlow.Stores.EntityFramework.Tests/E2E/Aggregates/AccountAggregate.cs deleted file mode 100644 index 67d15941..00000000 --- a/tests/SourceFlow.Stores.EntityFramework.Tests/E2E/Aggregates/AccountAggregate.cs +++ /dev/null @@ -1,68 +0,0 @@ -using System; -using System.Threading.Tasks; -using Microsoft.Extensions.Logging; -using SourceFlow.Aggregate; -using SourceFlow.Messaging.Commands; -using SourceFlow.Stores.EntityFramework.Tests.E2E.Commands; -using SourceFlow.Stores.EntityFramework.Tests.E2E.Events; - -namespace SourceFlow.Stores.EntityFramework.Tests.E2E.Aggregates -{ - public class AccountAggregate : Aggregate, - ISubscribes, IAccountAggregate - { - public AccountAggregate(Lazy commandPublisher, ILogger logger) : - base(commandPublisher, logger) - { - } - - public Task CreateAccount(int accountId, string holder, decimal amount) - { - var command = new CreateAccount(accountId, new Payload - { - AccountName = holder, - InitialAmount = amount - }); - - return Send(command); - } - - public Task Deposit(int accountId, decimal amount) - { - return Send(new DepositMoney(accountId, new TransactPayload - { - Amount = amount, - Type = TransactionType.Deposit - })); - } - - public Task Withdraw(int accountId, decimal amount) - { - return Send(new WithdrawMoney(accountId, new TransactPayload - { - Amount = amount, - Type = TransactionType.Withdrawal - })); - } - - public Task CloseAccount(int accountId, string reason) - { - return Send(new CloseAccount(accountId, new ClosurePayload - { - ClosureReason = reason - })); - } - - public Task On(AccountCreated @event) - { - // To prevent infinite loops, this method does nothing - // Activation should happen through commands, not through event handling cycles - return Task.CompletedTask; - } - - public Task RepayHistory(int accountId) - { - return ReplayCommands(accountId); - } - } -} diff --git a/tests/SourceFlow.Stores.EntityFramework.Tests/E2E/Aggregates/BankAccount.cs b/tests/SourceFlow.Stores.EntityFramework.Tests/E2E/Aggregates/BankAccount.cs deleted file mode 100644 index f4003efa..00000000 --- a/tests/SourceFlow.Stores.EntityFramework.Tests/E2E/Aggregates/BankAccount.cs +++ /dev/null @@ -1,15 +0,0 @@ -using System; - -namespace SourceFlow.Stores.EntityFramework.Tests.E2E.Aggregates -{ - public class BankAccount : IEntity - { - public int Id { get; set; } - public DateTime CreatedOn { get; set; } = DateTime.UtcNow; - public string AccountName { get; set; } = string.Empty; - public decimal Balance { get; set; } - public bool IsClosed { get; set; } - public string ClosureReason { get; internal set; } - public DateTime ActiveOn { get; internal set; } - } -} diff --git a/tests/SourceFlow.Stores.EntityFramework.Tests/E2E/Aggregates/IAccountAggregate.cs b/tests/SourceFlow.Stores.EntityFramework.Tests/E2E/Aggregates/IAccountAggregate.cs deleted file mode 100644 index 95e190c7..00000000 --- a/tests/SourceFlow.Stores.EntityFramework.Tests/E2E/Aggregates/IAccountAggregate.cs +++ /dev/null @@ -1,20 +0,0 @@ -using System.Threading.Tasks; -using SourceFlow.Stores.EntityFramework.Tests.E2E.Events; - -namespace SourceFlow.Stores.EntityFramework.Tests.E2E.Aggregates -{ - public interface IAccountAggregate - { - Task CloseAccount(int accountId, string reason); - - Task CreateAccount(int accountId, string holder, decimal amount); - - Task Deposit(int accountId, decimal amount); - - Task On(AccountCreated @event); - - Task Withdraw(int accountId, decimal amount); - - Task RepayHistory(int accountId); - } -} diff --git a/tests/SourceFlow.Stores.EntityFramework.Tests/E2E/Aggregates/TransactionType.cs b/tests/SourceFlow.Stores.EntityFramework.Tests/E2E/Aggregates/TransactionType.cs deleted file mode 100644 index 4b59448a..00000000 --- a/tests/SourceFlow.Stores.EntityFramework.Tests/E2E/Aggregates/TransactionType.cs +++ /dev/null @@ -1,8 +0,0 @@ -namespace SourceFlow.Stores.EntityFramework.Tests.E2E.Aggregates -{ - public enum TransactionType - { - Deposit, - Withdrawal - } -} diff --git a/tests/SourceFlow.Stores.EntityFramework.Tests/E2E/Commands/ActivateAccount.cs b/tests/SourceFlow.Stores.EntityFramework.Tests/E2E/Commands/ActivateAccount.cs deleted file mode 100644 index 46a1b1e4..00000000 --- a/tests/SourceFlow.Stores.EntityFramework.Tests/E2E/Commands/ActivateAccount.cs +++ /dev/null @@ -1,16 +0,0 @@ -using SourceFlow.Messaging.Commands; - -namespace SourceFlow.Stores.EntityFramework.Tests.E2E.Commands -{ - public class ActivateAccount : Command - { - // Parameterless constructor for deserialization - public ActivateAccount() : base() - { - } - - public ActivateAccount(int entityId, ActivationPayload payload) : base(entityId, payload) - { - } - } -} diff --git a/tests/SourceFlow.Stores.EntityFramework.Tests/E2E/Commands/CloseAccount.cs b/tests/SourceFlow.Stores.EntityFramework.Tests/E2E/Commands/CloseAccount.cs deleted file mode 100644 index 3223ee30..00000000 --- a/tests/SourceFlow.Stores.EntityFramework.Tests/E2E/Commands/CloseAccount.cs +++ /dev/null @@ -1,16 +0,0 @@ -using SourceFlow.Messaging.Commands; - -namespace SourceFlow.Stores.EntityFramework.Tests.E2E.Commands -{ - public class CloseAccount : Command - { - // Parameterless constructor for deserialization - public CloseAccount() : base() - { - } - - public CloseAccount(int entityId, ClosurePayload payload) : base(entityId, payload) - { - } - } -} diff --git a/tests/SourceFlow.Stores.EntityFramework.Tests/E2E/Commands/CreateAccount.cs b/tests/SourceFlow.Stores.EntityFramework.Tests/E2E/Commands/CreateAccount.cs deleted file mode 100644 index b6399595..00000000 --- a/tests/SourceFlow.Stores.EntityFramework.Tests/E2E/Commands/CreateAccount.cs +++ /dev/null @@ -1,16 +0,0 @@ -using SourceFlow.Messaging.Commands; - -namespace SourceFlow.Stores.EntityFramework.Tests.E2E.Commands -{ - public class CreateAccount : Command - { - // Parameterless constructor for deserialization - public CreateAccount() : base() - { - } - - public CreateAccount(int entityId, Payload payload) : base(entityId, true, payload) - { - } - } -} diff --git a/tests/SourceFlow.Stores.EntityFramework.Tests/E2E/Commands/DepositMoney.cs b/tests/SourceFlow.Stores.EntityFramework.Tests/E2E/Commands/DepositMoney.cs deleted file mode 100644 index 809e4cfa..00000000 --- a/tests/SourceFlow.Stores.EntityFramework.Tests/E2E/Commands/DepositMoney.cs +++ /dev/null @@ -1,16 +0,0 @@ -using SourceFlow.Messaging.Commands; - -namespace SourceFlow.Stores.EntityFramework.Tests.E2E.Commands -{ - public class DepositMoney : Command - { - // Parameterless constructor for deserialization - public DepositMoney() : base() - { - } - - public DepositMoney(int entityId, TransactPayload payload) : base(entityId, payload) - { - } - } -} diff --git a/tests/SourceFlow.Stores.EntityFramework.Tests/E2E/Commands/Payload.cs b/tests/SourceFlow.Stores.EntityFramework.Tests/E2E/Commands/Payload.cs deleted file mode 100644 index c3a4df77..00000000 --- a/tests/SourceFlow.Stores.EntityFramework.Tests/E2E/Commands/Payload.cs +++ /dev/null @@ -1,34 +0,0 @@ -using System; -using SourceFlow.Messaging; -using SourceFlow.Stores.EntityFramework.Tests.E2E.Aggregates; - -namespace SourceFlow.Stores.EntityFramework.Tests.E2E.Commands -{ - public class ActivationPayload : IPayload - { - public int Id { get; set; } - public DateTime ActiveOn { get; set; } - } - - public class Payload : IPayload - { - public int Id { get; set; } - public decimal InitialAmount { get; set; } - public string AccountName { get; set; } - } - - public class TransactPayload : IPayload - { - public int Id { get; set; } - public TransactionType Type { get; set; } - public decimal Amount { get; set; } - public decimal CurrentBalance { get; set; } - } - - public class ClosurePayload : IPayload - { - public int Id { get; set; } - public bool IsClosed { get; set; } - public string ClosureReason { get; set; } = string.Empty; - } -} diff --git a/tests/SourceFlow.Stores.EntityFramework.Tests/E2E/Commands/WithdrawMoney.cs b/tests/SourceFlow.Stores.EntityFramework.Tests/E2E/Commands/WithdrawMoney.cs deleted file mode 100644 index e87c9bf1..00000000 --- a/tests/SourceFlow.Stores.EntityFramework.Tests/E2E/Commands/WithdrawMoney.cs +++ /dev/null @@ -1,16 +0,0 @@ -using SourceFlow.Messaging.Commands; - -namespace SourceFlow.Stores.EntityFramework.Tests.E2E.Commands -{ - public class WithdrawMoney : Command - { - // Parameterless constructor for deserialization - public WithdrawMoney() : base() - { - } - - public WithdrawMoney(int entityId, TransactPayload payload) : base(entityId, payload) - { - } - } -} diff --git a/tests/SourceFlow.Stores.EntityFramework.Tests/E2E/E2E.Tests.cs b/tests/SourceFlow.Stores.EntityFramework.Tests/E2E/E2E.Tests.cs deleted file mode 100644 index b788e74c..00000000 --- a/tests/SourceFlow.Stores.EntityFramework.Tests/E2E/E2E.Tests.cs +++ /dev/null @@ -1,134 +0,0 @@ -using System; -using System.Reflection; -using System.Threading.Tasks; -using Microsoft.EntityFrameworkCore; -using Microsoft.Extensions.DependencyInjection; -using Microsoft.Extensions.Logging; -using NUnit.Framework; -using SourceFlow.Saga; -using SourceFlow.Stores.EntityFramework.Extensions; -using SourceFlow.Stores.EntityFramework.Tests.E2E.Aggregates; -using SourceFlow.Stores.EntityFramework.Tests.E2E.Projections; - -namespace SourceFlow.Stores.EntityFramework.Tests.E2E -{ - [TestFixture] - [Category("Integration")] - public class ProgramIntegrationTests - { - private ServiceProvider _serviceProvider; - private IAccountAggregate _accountAggregate; - private ISaga _saga; - private ILogger _logger; - private IViewModelStoreAdapter _viewRepository; - private int _accountId = 999; - - [SetUp] - public void SetUp() - { - // Clear any previous registrations - EntityDbContext.ClearRegistrations(); - ViewModelDbContext.ClearRegistrations(); - - // Register the test assembly for scanning - EntityDbContext.RegisterAssembly(typeof(BankAccount).Assembly); - ViewModelDbContext.RegisterAssembly(typeof(AccountViewModel).Assembly); - - var services = new ServiceCollection(); - - // Register logging with console provider - services.AddLogging(builder => - { - builder.AddConsole(); - builder.SetMinimumLevel(LogLevel.Information); - }); - - // Register SourceFlow and all required services - // Pass the test assembly so it can discover E2E aggregates, sagas, and projections - services.UseSourceFlow(Assembly.GetExecutingAssembly()); - // Register EF store implementations with SQLite with sensitive data logging. - services.AddSourceFlowEfStoresWithCustomProvider(options => - options.UseSqlite("DataSource=sourceflow.db") - .EnableSensitiveDataLogging() - .LogTo(Console.WriteLine, Microsoft.Extensions.Logging.LogLevel.Information)); - - _serviceProvider = services.BuildServiceProvider(); - - // Ensure all database schemas are created fresh for each test - // Delete the database once (all contexts share the same database file) - var commandContext = _serviceProvider.GetRequiredService(); - commandContext.Database.EnsureDeleted(); - - // Create all tables for each context - commandContext.Database.EnsureCreated(); - - var entityContext = _serviceProvider.GetRequiredService(); - entityContext.Database.EnsureCreated(); - entityContext.ApplyMigrations(); // On migrations for registered entity types - - var viewModelContext = _serviceProvider.GetRequiredService(); - viewModelContext.Database.EnsureCreated(); - viewModelContext.ApplyMigrations(); // On migrations for registered view model types - - _saga = _serviceProvider.GetRequiredService(); - _accountAggregate = _serviceProvider.GetRequiredService(); - - _logger = _serviceProvider.GetRequiredService>(); - _viewRepository = _serviceProvider.GetRequiredService(); - } - - [TearDown] - public void TearDown() - { - if (_serviceProvider is not null) - _serviceProvider.Dispose(); - } - - [Test] - public async Task EndToEnd_AccountLifecycle_WorksAsExpected() - { - // Create account - await _accountAggregate.CreateAccount(_accountId, "John Doe", 1000m); - _logger.LogInformation("Action=Test_Create_Account, Account: {accountId}", _accountId); - - // Perform deposit - var amount = 500m; - _logger.LogInformation("Action=Test_Deposit, Amount={Amount}", amount); - await _accountAggregate.Deposit(_accountId, amount); - - // Perform withdraw - amount = 200m; - _logger.LogInformation("Action=Test_Withdraw, Amount={Amount}", amount); - await _accountAggregate.Withdraw(_accountId, amount); - - // Perform another deposit - amount = 100m; - _logger.LogInformation("Action=Test_Deposit, Amount={Amount}", amount); - await _accountAggregate.Deposit(_accountId, amount); - - // Get current state and assertions - var account = await _viewRepository.Find(_accountId); - Assert.That(account, Is.Not.Null); - Assert.That(_accountId, Is.EqualTo(account.Id)); - Assert.That(account.AccountName, Is.EqualTo("John Doe")); - Assert.That(account.CurrentBalance, Is.EqualTo(1000m + 500m - 200m + 100m)); - Assert.That(account.TransactionCount, Is.GreaterThanOrEqualTo(3)); - Assert.That(account.IsClosed, Is.False); - - // Replay account history (should not throw) - Assert.DoesNotThrowAsync(async () => await _accountAggregate.RepayHistory(_accountId)); - - // Fetch state again, should be the same - var replayedAccount = await _viewRepository.Find(_accountId); - Assert.That(account.CurrentBalance, Is.EqualTo(replayedAccount.CurrentBalance)); - Assert.That(account.TransactionCount, Is.EqualTo(replayedAccount.TransactionCount)); - - // CloseAccount account - Assert.DoesNotThrowAsync(async () => await _accountAggregate.CloseAccount(_accountId, "Customer account close request")); - - // Final state - var closedAccount = await _viewRepository.Find(_accountId); - Assert.That(closedAccount.IsClosed, Is.True); - } - } -} diff --git a/tests/SourceFlow.Stores.EntityFramework.Tests/E2E/Events/AccountCreated.cs b/tests/SourceFlow.Stores.EntityFramework.Tests/E2E/Events/AccountCreated.cs deleted file mode 100644 index dfe0c990..00000000 --- a/tests/SourceFlow.Stores.EntityFramework.Tests/E2E/Events/AccountCreated.cs +++ /dev/null @@ -1,12 +0,0 @@ -using SourceFlow.Messaging.Events; -using SourceFlow.Stores.EntityFramework.Tests.E2E.Aggregates; - -namespace SourceFlow.Stores.EntityFramework.Tests.E2E.Events -{ - public class AccountCreated : Event - { - public AccountCreated(BankAccount payload) : base(payload) - { - } - } -} diff --git a/tests/SourceFlow.Stores.EntityFramework.Tests/E2E/Events/AccountUpdated.cs b/tests/SourceFlow.Stores.EntityFramework.Tests/E2E/Events/AccountUpdated.cs deleted file mode 100644 index 003b2d86..00000000 --- a/tests/SourceFlow.Stores.EntityFramework.Tests/E2E/Events/AccountUpdated.cs +++ /dev/null @@ -1,12 +0,0 @@ -using SourceFlow.Messaging.Events; -using SourceFlow.Stores.EntityFramework.Tests.E2E.Aggregates; - -namespace SourceFlow.Stores.EntityFramework.Tests.E2E.Events -{ - public class AccountUpdated : Event - { - public AccountUpdated(BankAccount payload) : base(payload) - { - } - } -} diff --git a/tests/SourceFlow.Stores.EntityFramework.Tests/E2E/Projections/AccountView.cs b/tests/SourceFlow.Stores.EntityFramework.Tests/E2E/Projections/AccountView.cs deleted file mode 100644 index b83b200b..00000000 --- a/tests/SourceFlow.Stores.EntityFramework.Tests/E2E/Projections/AccountView.cs +++ /dev/null @@ -1,51 +0,0 @@ -using System; -using System.Threading.Tasks; -using Microsoft.Extensions.Logging; -using SourceFlow.Projections; -using SourceFlow.Stores.EntityFramework.Tests.E2E.Events; - -namespace SourceFlow.Stores.EntityFramework.Tests.E2E.Projections -{ - public class AccountView : View, - IProjectOn, - IProjectOn - { - public AccountView(IViewModelStoreAdapter viewModelStore, ILogger logger) : base(viewModelStore, logger) - { - } - - public async Task On(AccountCreated @event) - { - var view = new AccountViewModel - { - Id = @event.Payload.Id, - AccountName = @event.Payload.AccountName, - CurrentBalance = @event.Payload.Balance, - IsClosed = false, - CreatedDate = @event.Payload.CreatedOn, - LastUpdated = DateTime.UtcNow, - TransactionCount = 0, - ClosureReason = null!, - Version = 1 - }; - - return await viewModelStore.Persist(view); - } - - public async Task On(AccountUpdated @event) - { - var view = await viewModelStore.Find(@event.Payload.Id); - - view.CurrentBalance = @event.Payload.Balance; - view.LastUpdated = DateTime.UtcNow; - view.AccountName = @event.Payload.AccountName; - view.IsClosed = @event.Payload.IsClosed; - view.ClosureReason = @event.Payload.ClosureReason; - view.ActiveOn = @event.Payload.ActiveOn; - view.Version++; - view.TransactionCount++; - - return await viewModelStore.Persist(view); - } - } -} diff --git a/tests/SourceFlow.Stores.EntityFramework.Tests/E2E/Projections/AccountViewModel.cs b/tests/SourceFlow.Stores.EntityFramework.Tests/E2E/Projections/AccountViewModel.cs deleted file mode 100644 index 3acddaf4..00000000 --- a/tests/SourceFlow.Stores.EntityFramework.Tests/E2E/Projections/AccountViewModel.cs +++ /dev/null @@ -1,19 +0,0 @@ -using System; -using SourceFlow.Projections; - -namespace SourceFlow.Stores.EntityFramework.Tests.E2E.Projections -{ - public class AccountViewModel : IViewModel - { - public int Id { get; set; } - public string AccountName { get; set; } = string.Empty; - public decimal CurrentBalance { get; set; } - public DateTime CreatedDate { get; set; } - public DateTime LastUpdated { get; set; } - public int TransactionCount { get; set; } - public bool IsClosed { get; set; } - public string ClosureReason { get; set; } - public int Version { get; set; } - public DateTime ActiveOn { get; set; } - } -} diff --git a/tests/SourceFlow.Stores.EntityFramework.Tests/E2E/Sagas/AccountSaga.cs b/tests/SourceFlow.Stores.EntityFramework.Tests/E2E/Sagas/AccountSaga.cs deleted file mode 100644 index 23af612f..00000000 --- a/tests/SourceFlow.Stores.EntityFramework.Tests/E2E/Sagas/AccountSaga.cs +++ /dev/null @@ -1,115 +0,0 @@ -using System; -using System.Threading.Tasks; -using Microsoft.Extensions.Logging; -using SourceFlow.Messaging.Commands; -using SourceFlow.Messaging.Events; -using SourceFlow.Saga; -using SourceFlow.Stores.EntityFramework.Tests.E2E.Aggregates; -using SourceFlow.Stores.EntityFramework.Tests.E2E.Commands; -using SourceFlow.Stores.EntityFramework.Tests.E2E.Events; - -namespace SourceFlow.Stores.EntityFramework.Tests.E2E.Sagas -{ - public class AccountSaga : Saga, - IHandlesWithEvent, - IHandlesWithEvent, - IHandlesWithEvent, - IHandlesWithEvent, - IHandles - { - public AccountSaga(Lazy commandPublisher, IEventQueue eventQueue, IEntityStoreAdapter repository, ILogger logger) : - base(commandPublisher, eventQueue, repository, logger) - { - } - - public Task Handle(IEntity entity, CreateAccount command) - { - logger.LogInformation("Action=Account_Created, Account={AccountId}, Holder={AccountName}, Initial_Balance={InitialBalance}", - command.Entity.Id, command.Payload.AccountName, command.Payload.InitialAmount); - - if (string.IsNullOrEmpty(command.Payload.AccountName)) - throw new ArgumentException("Account create requires account holder name.", nameof(command.Payload.AccountName)); - - if (command.Payload.InitialAmount <= 0) - throw new ArgumentException("Account create requires initial amount.", nameof(command.Payload.InitialAmount)); - - var account = (BankAccount)entity; - - account.AccountName = command.Payload.AccountName; - account.Balance = command.Payload.InitialAmount; - - return Task.FromResult(account); - } - - public Task Handle(IEntity entity, ActivateAccount command) - { - logger.LogInformation("Action=Account_Activate, ActivatedOn={ActiveOn}, Account={AccountId}", command.Payload.ActiveOn, command.Entity.Id); - - if (command.Payload.ActiveOn == DateTime.MinValue) - throw new ArgumentException("Deposit amount must be positive", nameof(command.Payload.ActiveOn)); - - var account = (BankAccount)entity; - - if (account.IsClosed) - throw new InvalidOperationException("Cannot deposit to a closed account"); - - account.ActiveOn = command.Payload.ActiveOn; - - return Task.FromResult(account); - } - - public Task Handle(IEntity entity, DepositMoney command) - { - logger.LogInformation("Action=Money_Deposited, Amount={Amount}, Account={AccountId}", command.Payload.Amount, command.Entity.Id); - - if (command.Payload.Amount <= 0) - throw new ArgumentException("Deposit amount must be positive", nameof(command.Payload.Amount)); - - var account = (BankAccount)entity; - - if (account.IsClosed) - throw new InvalidOperationException("Cannot deposit to a closed account"); - - command.Payload.CurrentBalance = account.Balance + command.Payload.Amount; - account.Balance = command.Payload.CurrentBalance; - - return Task.FromResult(account); - } - - public Task Handle(IEntity entity, WithdrawMoney command) - { - logger.LogInformation("Action=Money_Withdrawn, Amount={Amount}, Account={AccountId}", command.Payload.Amount, command.Entity.Id); - - if (command.Payload.Amount <= 0) - throw new ArgumentException("Withdrawal amount must be positive", nameof(command.Payload.Amount)); - - var account = (BankAccount)entity; - - if (account.IsClosed) - throw new InvalidOperationException("Cannot deposit to a closed account"); - - command.Payload.CurrentBalance = account.Balance - command.Payload.Amount; - account.Balance = command.Payload.CurrentBalance; - - return Task.FromResult(account); - } - - public Task Handle(IEntity entity, CloseAccount command) - { - logger.LogInformation("Action=Account_Closed, Account={AccountId}, Reason={Reason}", command.Entity.Id, command.Payload.ClosureReason); - - if (string.IsNullOrWhiteSpace(command.Payload.ClosureReason)) - throw new ArgumentException("Reason for closing cannot be empty", nameof(command.Payload.ClosureReason)); - - var account = (BankAccount)entity; - - if (account.IsClosed) - throw new InvalidOperationException("Cannot close account on a closed account"); - - account.ClosureReason = command.Payload.ClosureReason; - account.IsClosed = command.Payload.IsClosed = true; - - return Task.FromResult(account); - } - } -} diff --git a/tests/SourceFlow.Stores.EntityFramework.Tests/SourceFlow.Stores.EntityFramework.Tests.csproj b/tests/SourceFlow.Stores.EntityFramework.Tests/SourceFlow.Stores.EntityFramework.Tests.csproj deleted file mode 100644 index fc291e37..00000000 --- a/tests/SourceFlow.Stores.EntityFramework.Tests/SourceFlow.Stores.EntityFramework.Tests.csproj +++ /dev/null @@ -1,28 +0,0 @@ - - - - net9.0 - false - true - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/tests/SourceFlow.Stores.EntityFramework.Tests/Stores/EfCommandStoreIntegrationTests.cs b/tests/SourceFlow.Stores.EntityFramework.Tests/Stores/EfCommandStoreIntegrationTests.cs deleted file mode 100644 index 20b02392..00000000 --- a/tests/SourceFlow.Stores.EntityFramework.Tests/Stores/EfCommandStoreIntegrationTests.cs +++ /dev/null @@ -1,275 +0,0 @@ -#nullable enable - -using System; -using System.Linq; -using System.Threading.Tasks; -using Microsoft.EntityFrameworkCore; -using Microsoft.Extensions.DependencyInjection; -using NUnit.Framework; -using SourceFlow.Messaging; -using SourceFlow.Messaging.Commands; -using SourceFlow.Stores.EntityFramework.Options; -using SourceFlow.Stores.EntityFramework.Services; -using SourceFlow.Stores.EntityFramework.Stores; -using SourceFlow.Stores.EntityFramework.Tests.TestModels; - -namespace SourceFlow.Stores.EntityFramework.Tests.Stores -{ - [TestFixture] - [Category("Integration")] - public class EfCommandStoreIntegrationTests - { - private ServiceProvider? _serviceProvider; - private ICommandStore? _store; - private CommandDbContext? _context; - - [SetUp] - public void Setup() - { - // Clear any previous registrations - EntityDbContext.ClearRegistrations(); - ViewModelDbContext.ClearRegistrations(); - - // Register the test assembly for scanning - EntityDbContext.RegisterAssembly(typeof(TestEntity).Assembly); - ViewModelDbContext.RegisterAssembly(typeof(TestViewModel).Assembly); - - // Create a shared in-memory SQLite connection for all contexts to share the same database - var connection = new Microsoft.Data.Sqlite.SqliteConnection("DataSource=:memory:"); - connection.Open(); - - var services = new ServiceCollection(); - - // Configure and register the specific DbContext instances with shared connection - // Use EnableServiceProviderCaching(false) to avoid EF Core 9.0 multiple provider conflicts - services.AddDbContext(options => - options.UseSqlite(connection) - .EnableServiceProviderCaching(false)); - - services.AddDbContext(options => - options.UseSqlite(connection) - .EnableServiceProviderCaching(false)); - - services.AddDbContext(options => - options.UseSqlite(connection) - .EnableServiceProviderCaching(false)); - - // Register SourceFlowEfOptions with resilience and observability disabled for tests - var options = new SourceFlowEfOptions - { - Resilience = { Enabled = false }, - Observability = { Enabled = false } - }; - services.AddSingleton(options); - - // Register required services (resilience policy and telemetry service) - services.AddScoped(); - services.AddScoped(); - - // Register the stores that will use these specific DbContext instances - services.AddScoped(); - services.AddScoped(); - services.AddScoped(); - - _serviceProvider = services.BuildServiceProvider(); - - // Create and open the in-memory database - schema needs to be created for all contexts - var commandContext = _serviceProvider.GetRequiredService(); - commandContext.Database.EnsureCreated(); // This creates the Commands schema - - var entityContext = _serviceProvider.GetRequiredService(); - entityContext.Database.EnsureCreated(); // This creates the Entities schema - entityContext.ApplyMigrations(); // On migrations for registered entity types - - var viewModelContext = _serviceProvider.GetRequiredService(); - viewModelContext.Database.EnsureCreated(); // This creates the ViewModels schema - viewModelContext.ApplyMigrations(); // On migrations for registered view model types - - _context = commandContext; - _store = _serviceProvider.GetRequiredService(); - } - - [TearDown] - public void TearDown() - { - _context?.Database.CloseConnection(); - _context?.Dispose(); - _serviceProvider?.Dispose(); - } - - [Test] - public async Task Append_ValidCommand_StoresCommandInDatabase() - { - // Arrange - var commandData = new CommandData - { - EntityId = 1, - SequenceNo = 1, - CommandName = "TestCommand", - CommandType = typeof(TestCommand).AssemblyQualifiedName ?? string.Empty, - PayloadType = typeof(TestPayload).AssemblyQualifiedName ?? string.Empty, - PayloadData = System.Text.Json.JsonSerializer.Serialize(new TestPayload { Action = "Create", Data = "Test data" }), - Metadata = System.Text.Json.JsonSerializer.Serialize(new Metadata { SequenceNo = 1 }), - Timestamp = DateTime.UtcNow - }; - - // Act - await _store!.Append(commandData); - - // Assert - var commands = await _store.Load(1); - var commandsList = commands.ToList(); - - Assert.That(commandsList, Has.Count.EqualTo(1)); - Assert.That(commandsList[0].EntityId, Is.EqualTo(1)); - Assert.That(commandsList[0].SequenceNo, Is.EqualTo(1)); - } - - [Test] - public async Task Append_MultipleCommands_StoresAllCommandsInOrder() - { - // Arrange - var commandData1 = new CommandData - { - EntityId = 1, - SequenceNo = 1, - CommandName = "TestCommand", - CommandType = typeof(TestCommand).AssemblyQualifiedName ?? string.Empty, - PayloadType = typeof(TestPayload).AssemblyQualifiedName ?? string.Empty, - PayloadData = System.Text.Json.JsonSerializer.Serialize(new TestPayload { Action = "Create", Data = "First" }), - Metadata = System.Text.Json.JsonSerializer.Serialize(new Metadata { SequenceNo = 1 }), - Timestamp = DateTime.UtcNow - }; - - var commandData2 = new CommandData - { - EntityId = 1, - SequenceNo = 2, - CommandName = "TestCommand", - CommandType = typeof(TestCommand).AssemblyQualifiedName ?? string.Empty, - PayloadType = typeof(TestPayload).AssemblyQualifiedName ?? string.Empty, - PayloadData = System.Text.Json.JsonSerializer.Serialize(new TestPayload { Action = "Update", Data = "Second" }), - Metadata = System.Text.Json.JsonSerializer.Serialize(new Metadata { SequenceNo = 2 }), - Timestamp = DateTime.UtcNow - }; - - var commandData3 = new CommandData - { - EntityId = 1, - SequenceNo = 3, - CommandName = "TestCommand", - CommandType = typeof(TestCommand).AssemblyQualifiedName ?? string.Empty, - PayloadType = typeof(TestPayload).AssemblyQualifiedName ?? string.Empty, - PayloadData = System.Text.Json.JsonSerializer.Serialize(new TestPayload { Action = "Delete", Data = "Third" }), - Metadata = System.Text.Json.JsonSerializer.Serialize(new Metadata { SequenceNo = 3 }), - Timestamp = DateTime.UtcNow - }; - - // Act - await _store!.Append(commandData1); - await _store.Append(commandData2); - await _store.Append(commandData3); - - // Assert - var commands = await _store.Load(1); - var commandsList = commands.ToList(); - - Assert.That(commandsList, Has.Count.EqualTo(3)); - Assert.That(commandsList[0].SequenceNo, Is.EqualTo(1)); - Assert.That(commandsList[1].SequenceNo, Is.EqualTo(2)); - Assert.That(commandsList[2].SequenceNo, Is.EqualTo(3)); - } - - [Test] - public async Task Load_NonExistentEntity_ReturnsEmptyList() - { - // Act - var commands = await _store!.Load(999); - - // Assert - Assert.That(commands, Is.Empty); - } - - [Test] - public async Task Append_CommandsForDifferentEntities_StoresSeparately() - { - // Arrange - var commandData1 = new CommandData - { - EntityId = 1, - SequenceNo = 1, - CommandName = "TestCommand", - CommandType = typeof(TestCommand).AssemblyQualifiedName ?? string.Empty, - PayloadType = typeof(TestPayload).AssemblyQualifiedName ?? string.Empty, - PayloadData = System.Text.Json.JsonSerializer.Serialize(new TestPayload { Action = "Create", Data = "Entity 1" }), - Metadata = System.Text.Json.JsonSerializer.Serialize(new Metadata { SequenceNo = 1 }), - Timestamp = DateTime.UtcNow - }; - - var commandData2 = new CommandData - { - EntityId = 2, - SequenceNo = 1, - CommandName = "TestCommand", - CommandType = typeof(TestCommand).AssemblyQualifiedName ?? string.Empty, - PayloadType = typeof(TestPayload).AssemblyQualifiedName ?? string.Empty, - PayloadData = System.Text.Json.JsonSerializer.Serialize(new TestPayload { Action = "Create", Data = "Entity 2" }), - Metadata = System.Text.Json.JsonSerializer.Serialize(new Metadata { SequenceNo = 1 }), - Timestamp = DateTime.UtcNow - }; - - // Act - await _store!.Append(commandData1); - await _store.Append(commandData2); - - // Assert - var commands1 = await _store.Load(1); - var commands2 = await _store.Load(2); - - Assert.That(commands1.Count(), Is.EqualTo(1)); - Assert.That(commands2.Count(), Is.EqualTo(1)); - Assert.That(commands1.First().EntityId, Is.EqualTo(1)); - Assert.That(commands2.First().EntityId, Is.EqualTo(2)); - } - - [Test] - public void Append_NullCommand_ThrowsArgumentNullException() - { - // Act & Assert - Assert.ThrowsAsync(async () => - await _store!.Append(null!)); - } - - [Test] - public async Task Load_AfterMultipleAppends_ReturnsCommandsInCorrectOrder() - { - // Arrange - for (int i = 1; i <= 10; i++) - { - var commandData = new CommandData - { - EntityId = 1, - SequenceNo = i, - CommandName = "TestCommand", - CommandType = typeof(TestCommand).AssemblyQualifiedName ?? string.Empty, - PayloadType = typeof(TestPayload).AssemblyQualifiedName ?? string.Empty, - PayloadData = System.Text.Json.JsonSerializer.Serialize(new TestPayload { Action = $"Action{i}", Data = $"Data{i}" }), - Metadata = System.Text.Json.JsonSerializer.Serialize(new Metadata { SequenceNo = i }), - Timestamp = DateTime.UtcNow - }; - await _store!.Append(commandData); - } - - // Act - var commands = await _store!.Load(1); - var commandsList = commands.ToList(); - - // Assert - Assert.That(commandsList, Has.Count.EqualTo(10)); - for (int i = 0; i < 10; i++) - { - Assert.That(commandsList[i].SequenceNo, Is.EqualTo(i + 1)); - } - } - } -} diff --git a/tests/SourceFlow.Stores.EntityFramework.Tests/Stores/EfEntityStoreIntegrationTests.cs b/tests/SourceFlow.Stores.EntityFramework.Tests/Stores/EfEntityStoreIntegrationTests.cs deleted file mode 100644 index 2530a70c..00000000 --- a/tests/SourceFlow.Stores.EntityFramework.Tests/Stores/EfEntityStoreIntegrationTests.cs +++ /dev/null @@ -1,268 +0,0 @@ -#nullable enable - -using System; -using System.Threading.Tasks; -using Microsoft.EntityFrameworkCore; -using Microsoft.Extensions.DependencyInjection; -using NUnit.Framework; -using SourceFlow.Stores.EntityFramework.Options; -using SourceFlow.Stores.EntityFramework.Services; -using SourceFlow.Stores.EntityFramework.Stores; -using SourceFlow.Stores.EntityFramework.Tests.TestModels; - -namespace SourceFlow.Stores.EntityFramework.Tests.Stores -{ - [TestFixture] - [Category("Integration")] - public class EfEntityStoreIntegrationTests - { - private ServiceProvider? _serviceProvider; - private IEntityStore? _store; - private EntityDbContext? _context; - - [SetUp] - public void Setup() - { - // Clear any previous registrations - EntityDbContext.ClearRegistrations(); - ViewModelDbContext.ClearRegistrations(); - - // Register the test assembly for scanning - EntityDbContext.RegisterAssembly(typeof(TestEntity).Assembly); - ViewModelDbContext.RegisterAssembly(typeof(TestViewModel).Assembly); - - // Create a shared in-memory SQLite connection for all contexts to share the same database - var connection = new Microsoft.Data.Sqlite.SqliteConnection("DataSource=:memory:"); - connection.Open(); - - var services = new ServiceCollection(); - - // Configure SQLite in-memory database for testing - using shared connection for all contexts - // Use EnableServiceProviderCaching(false) to avoid EF Core 9.0 multiple provider conflicts - services.AddDbContext(options => - options.UseSqlite(connection) - .EnableServiceProviderCaching(false)); - - // Register all contexts for testing (even though only EntityDbContext is used by the store) - services.AddDbContext(options => - options.UseSqlite(connection) - .EnableServiceProviderCaching(false)); - services.AddDbContext(options => - options.UseSqlite(connection) - .EnableServiceProviderCaching(false)); - - // Register SourceFlowEfOptions with default settings for tests - var efOptions = new SourceFlowEfOptions(); - services.AddSingleton(efOptions); - - // Register common services manually (don't use AddSourceFlowEfStores as it would add SQL Server) - services.AddScoped(); - services.AddScoped(); - services.AddScoped(); - services.AddScoped(); - services.AddScoped(); - - _serviceProvider = services.BuildServiceProvider(); - - // Create and open the in-memory database - ensure all contexts schemas are created - var commandContext = _serviceProvider.GetRequiredService(); - commandContext.Database.EnsureCreated(); // This creates the Commands schema - - _context = _serviceProvider.GetRequiredService(); - _context.Database.EnsureCreated(); // This creates the Entities schema - _context.ApplyMigrations(); // On migrations for registered entity types - - var viewModelContext = _serviceProvider.GetRequiredService(); - viewModelContext.Database.EnsureCreated(); // This creates the ViewModels schema - viewModelContext.ApplyMigrations(); // On migrations for registered view model types - - _store = _serviceProvider.GetRequiredService(); - } - - [TearDown] - public void TearDown() - { - _context?.Database.CloseConnection(); - _context?.Dispose(); - _serviceProvider?.Dispose(); - } - - [Test] - public async Task Persist_NewEntity_StoresEntityInDatabase() - { - // Arrange - var entity = new TestEntity - { - Id = 1, - Name = "Test Entity", - Description = "Test Description", - Value = 42 - }; - - // Act - await _store!.Persist(entity); - - // Assert - var retrieved = await _store.Get(1); - Assert.That(retrieved, Is.Not.Null); - Assert.That(retrieved.Id, Is.EqualTo(1)); - Assert.That(retrieved.Name, Is.EqualTo("Test Entity")); - Assert.That(retrieved.Description, Is.EqualTo("Test Description")); - Assert.That(retrieved.Value, Is.EqualTo(42)); - } - - [Test] - public async Task Persist_ExistingEntity_UpdatesEntity() - { - // Arrange - var entity = new TestEntity - { - Id = 1, - Name = "Original Name", - Description = "Original Description", - Value = 10 - }; - - await _store!.Persist(entity); - - // Act - Update the entity - entity.Name = "Updated Name"; - entity.Description = "Updated Description"; - entity.Value = 20; - await _store.Persist(entity); - - // Assert - var retrieved = await _store.Get(1); - Assert.That(retrieved.Name, Is.EqualTo("Updated Name")); - Assert.That(retrieved.Description, Is.EqualTo("Updated Description")); - Assert.That(retrieved.Value, Is.EqualTo(20)); - } - - [Test] - public async Task Get_NonExistentEntity_ThrowsInvalidOperationException() - { - // Act & Assert - var ex = Assert.ThrowsAsync(async () => - await _store!.Get(999)); - - Assert.That(ex!.Message, Does.Contain("not found")); - } - - [Test] - public async Task Delete_ExistingEntity_RemovesEntityFromDatabase() - { - // Arrange - var entity = new TestEntity - { - Id = 1, - Name = "Test Entity", - Description = "Test Description", - Value = 42 - }; - - await _store!.Persist(entity); - - // Act - await _store.Delete(entity); - - // Assert - Assert.ThrowsAsync(async () => - await _store.Get(1)); - } - - [Test] - public void Delete_NonExistentEntity_ThrowsInvalidOperationException() - { - // Arrange - var entity = new TestEntity { Id = 999, Name = "Non-existent" }; - - // Act & Assert - var ex = Assert.ThrowsAsync(async () => - await _store!.Delete(entity)); - - Assert.That(ex!.Message, Does.Contain("not found")); - } - - [Test] - public void Persist_EntityWithInvalidId_ThrowsArgumentException() - { - // Arrange - var entity = new TestEntity { Id = 0, Name = "Invalid" }; - - // Act & Assert - Assert.ThrowsAsync(async () => - await _store!.Persist(entity)); - } - - [Test] - public void Persist_NullEntity_ThrowsArgumentNullException() - { - // Act & Assert - Assert.ThrowsAsync(async () => - await _store!.Persist(null!)); - } - - [Test] - public void Get_InvalidId_ThrowsArgumentException() - { - // Act & Assert - Assert.ThrowsAsync(async () => - await _store!.Get(0)); - } - - [Test] - public async Task Persist_MultipleEntities_StoresAllEntities() - { - // Arrange & Act - for (int i = 1; i <= 5; i++) - { - var entity = new TestEntity - { - Id = i, - Name = $"Entity {i}", - Description = $"Description {i}", - Value = i * 10 - }; - await _store!.Persist(entity); - } - - // Assert - for (int i = 1; i <= 5; i++) - { - var retrieved = await _store!.Get(i); - Assert.That(retrieved.Id, Is.EqualTo(i)); - Assert.That(retrieved.Name, Is.EqualTo($"Entity {i}")); - Assert.That(retrieved.Value, Is.EqualTo(i * 10)); - } - } - - [Test] - public async Task Persist_SameIdDifferentOperations_MaintainsDataIntegrity() - { - // Arrange - var entity = new TestEntity - { - Id = 1, - Name = "First Version", - Description = "Description 1", - Value = 100 - }; - - // Act - Create - await _store!.Persist(entity); - var v1 = await _store.Get(1); - - // Act - Update - entity.Name = "Second Version"; - entity.Value = 200; - await _store.Persist(entity); - var v2 = await _store.Get(1); - - // Assert - Assert.That(v1.Name, Is.EqualTo("First Version")); - Assert.That(v1.Value, Is.EqualTo(100)); - Assert.That(v2.Name, Is.EqualTo("Second Version")); - Assert.That(v2.Value, Is.EqualTo(200)); - } - } -} diff --git a/tests/SourceFlow.Stores.EntityFramework.Tests/Stores/EfViewModelStoreIntegrationTests.cs b/tests/SourceFlow.Stores.EntityFramework.Tests/Stores/EfViewModelStoreIntegrationTests.cs deleted file mode 100644 index f48fa6ae..00000000 --- a/tests/SourceFlow.Stores.EntityFramework.Tests/Stores/EfViewModelStoreIntegrationTests.cs +++ /dev/null @@ -1,268 +0,0 @@ -#nullable enable - -using System; -using System.Threading.Tasks; -using Microsoft.EntityFrameworkCore; -using Microsoft.Extensions.DependencyInjection; -using NUnit.Framework; -using SourceFlow.Stores.EntityFramework.Options; -using SourceFlow.Stores.EntityFramework.Services; -using SourceFlow.Stores.EntityFramework.Stores; -using SourceFlow.Stores.EntityFramework.Tests.TestModels; - -namespace SourceFlow.Stores.EntityFramework.Tests.Stores -{ - [TestFixture] - [Category("Integration")] - public class EfViewModelStoreIntegrationTests - { - private ServiceProvider? _serviceProvider; - private IViewModelStore? _store; - private ViewModelDbContext? _context; - - [SetUp] - public void Setup() - { - // Clear any previous registrations - ViewModelDbContext.ClearRegistrations(); - EntityDbContext.ClearRegistrations(); - - // Register the test assembly for scanning - ViewModelDbContext.RegisterAssembly(typeof(TestViewModel).Assembly); - EntityDbContext.RegisterAssembly(typeof(TestEntity).Assembly); - - // Create a shared in-memory SQLite connection for all contexts to share the same database - var connection = new Microsoft.Data.Sqlite.SqliteConnection("DataSource=:memory:"); - connection.Open(); - - var services = new ServiceCollection(); - - // Configure SQLite in-memory database for testing - using shared connection for all contexts - // Use EnableServiceProviderCaching(false) to avoid EF Core 9.0 multiple provider conflicts - services.AddDbContext(options => - options.UseSqlite(connection) - .EnableServiceProviderCaching(false)); - - // Register all contexts for testing (even though only ViewModelDbContext is used by the store) - services.AddDbContext(options => - options.UseSqlite(connection) - .EnableServiceProviderCaching(false)); - services.AddDbContext(options => - options.UseSqlite(connection) - .EnableServiceProviderCaching(false)); - - // Register SourceFlowEfOptions with default settings for tests - var efOptions = new SourceFlowEfOptions(); - services.AddSingleton(efOptions); - - // Register common services manually (don't use AddSourceFlowEfStores as it would add SQL Server) - services.AddScoped(); - services.AddScoped(); - services.AddScoped(); - services.AddScoped(); - services.AddScoped(); - - _serviceProvider = services.BuildServiceProvider(); - - // Create and open the in-memory database - ensure all contexts schemas are created - var commandContext = _serviceProvider.GetRequiredService(); - commandContext.Database.EnsureCreated(); // This creates the Commands schema - - var entityContext = _serviceProvider.GetRequiredService(); - entityContext.Database.EnsureCreated(); // This creates the Entities schema - entityContext.ApplyMigrations(); // On migrations for registered entity types - - _context = _serviceProvider.GetRequiredService(); - _context.Database.EnsureCreated(); // This creates the ViewModels schema - _context.ApplyMigrations(); // On migrations for registered view model types - - _store = _serviceProvider.GetRequiredService(); - } - - [TearDown] - public void TearDown() - { - _context?.Database.CloseConnection(); - _context?.Dispose(); - _serviceProvider?.Dispose(); - } - - [Test] - public async Task Persist_NewViewModel_StoresViewModelInDatabase() - { - // Arrange - var viewModel = new TestViewModel - { - Id = 1, - Name = "Test ViewModel", - Data = "Test Data", - Count = 42 - }; - - // Act - await _store!.Persist(viewModel); - - // Assert - var retrieved = await _store.Get(1); - Assert.That(retrieved, Is.Not.Null); - Assert.That(retrieved.Id, Is.EqualTo(1)); - Assert.That(retrieved.Name, Is.EqualTo("Test ViewModel")); - Assert.That(retrieved.Data, Is.EqualTo("Test Data")); - Assert.That(retrieved.Count, Is.EqualTo(42)); - } - - [Test] - public async Task Persist_ExistingViewModel_UpdatesViewModel() - { - // Arrange - var viewModel = new TestViewModel - { - Id = 1, - Name = "Original Name", - Data = "Original Data", - Count = 10 - }; - - await _store!.Persist(viewModel); - - // Act - Update the view model - viewModel.Name = "Updated Name"; - viewModel.Data = "Updated Data"; - viewModel.Count = 20; - await _store.Persist(viewModel); - - // Assert - var retrieved = await _store.Get(1); - Assert.That(retrieved.Name, Is.EqualTo("Updated Name")); - Assert.That(retrieved.Data, Is.EqualTo("Updated Data")); - Assert.That(retrieved.Count, Is.EqualTo(20)); - } - - [Test] - public async Task Get_NonExistentViewModel_ThrowsInvalidOperationException() - { - // Act & Assert - var ex = Assert.ThrowsAsync(async () => - await _store!.Get(999)); - - Assert.That(ex!.Message, Does.Contain("not found")); - } - - [Test] - public async Task Delete_ExistingViewModel_RemovesViewModelFromDatabase() - { - // Arrange - var viewModel = new TestViewModel - { - Id = 1, - Name = "Test ViewModel", - Data = "Test Data", - Count = 42 - }; - - await _store!.Persist(viewModel); - - // Act - await _store.Delete(viewModel); - - // Assert - Assert.ThrowsAsync(async () => - await _store.Get(1)); - } - - [Test] - public void Delete_NonExistentViewModel_ThrowsInvalidOperationException() - { - // Arrange - var viewModel = new TestViewModel { Id = 999, Name = "Non-existent" }; - - // Act & Assert - var ex = Assert.ThrowsAsync(async () => - await _store!.Delete(viewModel)); - - Assert.That(ex!.Message, Does.Contain("not found")); - } - - [Test] - public void Persist_ViewModelWithInvalidId_ThrowsArgumentException() - { - // Arrange - var viewModel = new TestViewModel { Id = 0, Name = "Invalid" }; - - // Act & Assert - Assert.ThrowsAsync(async () => - await _store!.Persist(viewModel)); - } - - [Test] - public void Persist_NullViewModel_ThrowsArgumentNullException() - { - // Act & Assert - Assert.ThrowsAsync(async () => - await _store!.Persist(null!)); - } - - [Test] - public void Get_InvalidId_ThrowsArgumentException() - { - // Act & Assert - Assert.ThrowsAsync(async () => - await _store!.Get(0)); - } - - [Test] - public async Task Persist_MultipleViewModels_StoresAllViewModels() - { - // Arrange & Act - for (int i = 1; i <= 5; i++) - { - var viewModel = new TestViewModel - { - Id = i, - Name = $"ViewModel {i}", - Data = $"Data {i}", - Count = i * 10 - }; - await _store!.Persist(viewModel); - } - - // Assert - for (int i = 1; i <= 5; i++) - { - var retrieved = await _store!.Get(i); - Assert.That(retrieved.Id, Is.EqualTo(i)); - Assert.That(retrieved.Name, Is.EqualTo($"ViewModel {i}")); - Assert.That(retrieved.Count, Is.EqualTo(i * 10)); - } - } - - [Test] - public async Task Persist_SameIdDifferentOperations_MaintainsDataIntegrity() - { - // Arrange - var viewModel = new TestViewModel - { - Id = 1, - Name = "First Version", - Data = "Data 1", - Count = 100 - }; - - // Act - Create - await _store!.Persist(viewModel); - var v1 = await _store.Get(1); - - // Act - Update - viewModel.Name = "Second Version"; - viewModel.Count = 200; - await _store.Persist(viewModel); - var v2 = await _store.Get(1); - - // Assert - Assert.That(v1.Name, Is.EqualTo("First Version")); - Assert.That(v1.Count, Is.EqualTo(100)); - Assert.That(v2.Name, Is.EqualTo("Second Version")); - Assert.That(v2.Count, Is.EqualTo(200)); - } - } -} diff --git a/tests/SourceFlow.Stores.EntityFramework.Tests/TestModels/TestModels.cs b/tests/SourceFlow.Stores.EntityFramework.Tests/TestModels/TestModels.cs deleted file mode 100644 index 7a643305..00000000 --- a/tests/SourceFlow.Stores.EntityFramework.Tests/TestModels/TestModels.cs +++ /dev/null @@ -1,44 +0,0 @@ -using SourceFlow.Messaging; -using SourceFlow.Messaging.Commands; -using SourceFlow.Projections; - -namespace SourceFlow.Stores.EntityFramework.Tests.TestModels -{ - public class TestEntity : IEntity - { - public int Id { get; set; } - public string Name { get; set; } = string.Empty; - public string Description { get; set; } = string.Empty; - public int Value { get; set; } - } - - public class TestPayload : IPayload - { - public string Action { get; set; } = string.Empty; - public string Data { get; set; } = string.Empty; - } - - public class TestCommand : Command - { - // Parameterless constructor for EF and JSON deserialization - public TestCommand() : base(false, new TestPayload()) - { - } - - public TestCommand(int entityId, TestPayload payload) : base(entityId, payload) - { - } - - public TestCommand(bool newEntity, TestPayload payload) : base(newEntity, payload) - { - } - } - - public class TestViewModel : IViewModel - { - public int Id { get; set; } - public string Name { get; set; } = string.Empty; - public string Data { get; set; } = string.Empty; - public int Count { get; set; } - } -} diff --git a/tests/SourceFlow.Stores.EntityFramework.Tests/Unit/EfIdempotencyServiceTests.cs b/tests/SourceFlow.Stores.EntityFramework.Tests/Unit/EfIdempotencyServiceTests.cs deleted file mode 100644 index 77f9ae11..00000000 --- a/tests/SourceFlow.Stores.EntityFramework.Tests/Unit/EfIdempotencyServiceTests.cs +++ /dev/null @@ -1,165 +0,0 @@ -using System; -using System.Threading.Tasks; -using Microsoft.EntityFrameworkCore; -using Microsoft.Extensions.Logging.Abstractions; -using NUnit.Framework; -using SourceFlow.Stores.EntityFramework; -using SourceFlow.Stores.EntityFramework.Services; - -namespace SourceFlow.Stores.EntityFramework.Tests.Unit; - -[TestFixture] -[Category("Unit")] -public class EfIdempotencyServiceTests -{ - private IdempotencyDbContext _context = null!; - private EfIdempotencyService _service = null!; - - [SetUp] - public void Setup() - { - var options = new DbContextOptionsBuilder() - .UseInMemoryDatabase(databaseName: Guid.NewGuid().ToString()) - .Options; - - _context = new IdempotencyDbContext(options); - _service = new EfIdempotencyService(_context, NullLogger.Instance); - } - - [TearDown] - public void TearDown() - { - _context?.Dispose(); - } - - [Test] - public async Task HasProcessedAsync_ReturnsFalse_WhenKeyDoesNotExist() - { - // Arrange - var key = "test-key-1"; - - // Act - var result = await _service.HasProcessedAsync(key); - - // Assert - Assert.That(result, Is.False); - } - - [Test] - public async Task HasProcessedAsync_ReturnsTrue_WhenKeyExists() - { - // Arrange - var key = "test-key-2"; - await _service.MarkAsProcessedAsync(key, TimeSpan.FromMinutes(5)); - - // Act - var result = await _service.HasProcessedAsync(key); - - // Assert - Assert.That(result, Is.True); - } - - [Test] - public async Task HasProcessedAsync_ReturnsFalse_WhenKeyExpired() - { - // Arrange - var key = "test-key-3"; - await _service.MarkAsProcessedAsync(key, TimeSpan.FromMilliseconds(-100)); - - // Act - var result = await _service.HasProcessedAsync(key); - - // Assert - Assert.That(result, Is.False); - } - - [Test] - public async Task MarkAsProcessedAsync_CreatesNewRecord() - { - // Arrange - var key = "test-key-4"; - var ttl = TimeSpan.FromMinutes(10); - - // Act - await _service.MarkAsProcessedAsync(key, ttl); - - // Assert - var record = await _context.IdempotencyRecords.FindAsync(key); - Assert.That(record, Is.Not.Null); - Assert.That(record!.IdempotencyKey, Is.EqualTo(key)); - Assert.That(record.ExpiresAt, Is.GreaterThan(DateTime.UtcNow)); - } - - [Test] - public async Task MarkAsProcessedAsync_UpdatesExistingRecord() - { - // Arrange - var key = "test-key-5"; - await _service.MarkAsProcessedAsync(key, TimeSpan.FromMinutes(5)); - var firstRecord = await _context.IdempotencyRecords.FindAsync(key); - var firstProcessedAt = firstRecord!.ProcessedAt; - - await Task.Delay(100); // Small delay to ensure different timestamp - - // Act - await _service.MarkAsProcessedAsync(key, TimeSpan.FromMinutes(10)); - - // Assert - var updatedRecord = await _context.IdempotencyRecords.FindAsync(key); - Assert.That(updatedRecord, Is.Not.Null); - Assert.That(updatedRecord!.ProcessedAt, Is.GreaterThanOrEqualTo(firstProcessedAt)); - } - - [Test] - public async Task RemoveAsync_DeletesRecord() - { - // Arrange - var key = "test-key-6"; - await _service.MarkAsProcessedAsync(key, TimeSpan.FromMinutes(5)); - - // Act - await _service.RemoveAsync(key); - - // Assert - var record = await _context.IdempotencyRecords.FindAsync(key); - Assert.That(record, Is.Null); - } - - [Test] - public async Task GetStatisticsAsync_ReturnsCorrectCounts() - { - // Arrange - await _service.MarkAsProcessedAsync("key-1", TimeSpan.FromMinutes(5)); - await _service.MarkAsProcessedAsync("key-2", TimeSpan.FromMinutes(5)); - await _service.HasProcessedAsync("key-1"); // Duplicate - await _service.HasProcessedAsync("key-3"); // New - - // Act - var stats = await _service.GetStatisticsAsync(); - - // Assert - Assert.That(stats.CacheSize, Is.EqualTo(2)); - Assert.That(stats.TotalChecks, Is.EqualTo(2)); - Assert.That(stats.DuplicatesDetected, Is.EqualTo(1)); - Assert.That(stats.UniqueMessages, Is.EqualTo(1)); - } - - [Test] - public async Task CleanupExpiredRecordsAsync_RemovesExpiredRecords() - { - // Arrange - await _service.MarkAsProcessedAsync("expired-1", TimeSpan.FromMilliseconds(-100)); - await _service.MarkAsProcessedAsync("expired-2", TimeSpan.FromMilliseconds(-100)); - await _service.MarkAsProcessedAsync("valid-1", TimeSpan.FromMinutes(10)); - - // Act - await _service.CleanupExpiredRecordsAsync(); - - // Assert - var remainingCount = await _context.IdempotencyRecords.CountAsync(); - Assert.That(remainingCount, Is.EqualTo(1)); - - var validRecord = await _context.IdempotencyRecords.FindAsync("valid-1"); - Assert.That(validRecord, Is.Not.Null); - } -} diff --git a/tests/SourceFlow.Stores.EntityFramework.Tests/Unit/SourceFlowEfOptionsTests.cs b/tests/SourceFlow.Stores.EntityFramework.Tests/Unit/SourceFlowEfOptionsTests.cs deleted file mode 100644 index b8a73d0d..00000000 --- a/tests/SourceFlow.Stores.EntityFramework.Tests/Unit/SourceFlowEfOptionsTests.cs +++ /dev/null @@ -1,101 +0,0 @@ -using System; -using NUnit.Framework; -using SourceFlow.Stores.EntityFramework.Options; - -namespace SourceFlow.Stores.EntityFramework.Tests.Unit -{ - [TestFixture] - [Category("Unit")] - public class SourceFlowEfOptionsTests - { - [Test] - public void GetConnectionString_WithCommandStoreTypeAndCommandConnectionString_ReturnsCommandConnectionString() - { - // Arrange - var options = new SourceFlowEfOptions - { - CommandConnectionString = "Command Connection", - EntityConnectionString = "Entity Connection", - ViewModelConnectionString = "ViewModel Connection" - }; - - // Act - var result = options.GetConnectionString(StoreType.Command); - - // Assert - Assert.That(result, Is.EqualTo("Command Connection")); - } - - [Test] - public void GetConnectionString_WithEntityStoreTypeAndEntityConnectionString_ReturnsEntityConnectionString() - { - // Arrange - var options = new SourceFlowEfOptions - { - CommandConnectionString = "Command Connection", - EntityConnectionString = "Entity Connection", - ViewModelConnectionString = "ViewModel Connection" - }; - - // Act - var result = options.GetConnectionString(StoreType.Entity); - - // Assert - Assert.That(result, Is.EqualTo("Entity Connection")); - } - - [Test] - public void GetConnectionString_WithViewModelStoreTypeAndViewModelConnectionString_ReturnsViewModelConnectionString() - { - // Arrange - var options = new SourceFlowEfOptions - { - CommandConnectionString = "Command Connection", - EntityConnectionString = "Entity Connection", - ViewModelConnectionString = "ViewModel Connection" - }; - - // Act - var result = options.GetConnectionString(StoreType.ViewModel); - - // Assert - Assert.That(result, Is.EqualTo("ViewModel Connection")); - } - - [Test] - public void GetConnectionString_WithCommandStoreTypeAndNoCommandConnectionStringButDefault_ReturnsDefaultConnectionString() - { - // Arrange - var options = new SourceFlowEfOptions - { - DefaultConnectionString = "Default Connection" - }; - - // Act - var result = options.GetConnectionString(StoreType.Command); - - // Assert - Assert.That(result, Is.EqualTo("Default Connection")); - } - - [Test] - public void GetConnectionString_WithUnknownStoreType_ThrowsArgumentException() - { - // Arrange - var options = new SourceFlowEfOptions(); - - // Act & Assert - Assert.Throws(() => options.GetConnectionString((StoreType)999)); - } - - [Test] - public void GetConnectionString_WithNoConnectionStrings_ThrowsInvalidOperationException() - { - // Arrange - var options = new SourceFlowEfOptions(); - - // Act & Assert - Assert.Throws(() => options.GetConnectionString(StoreType.Command)); - } - } -} diff --git a/tests/Storage/SourceFlow.Storage.Tests/EntityFrameworkCore/EfGenerationTests.cs b/tests/Storage/SourceFlow.Storage.Tests/EntityFrameworkCore/EfGenerationTests.cs new file mode 100644 index 00000000..3a61dc4d --- /dev/null +++ b/tests/Storage/SourceFlow.Storage.Tests/EntityFrameworkCore/EfGenerationTests.cs @@ -0,0 +1,138 @@ +using Bank.Accounts; +using Bank.Contracts; +using Microsoft.EntityFrameworkCore; +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.Hosting; +using Npgsql; +using SourceFlow.Hosting; +using SourceFlow.Messaging; +using SourceFlow.Runtime; +using SourceFlow.Storage.EntityFrameworkCore; +using SourceFlow.Storage.PostgreSQL; +using SourceFlow.Storage.Tests.PostgreSql; + +namespace SourceFlow.Storage.Tests.EntityFrameworkCore; + +/// UT-EF-11..13: EF Core read models with a schema per generation, rebuilt blue/green on PostgreSQL (doc 06 §6, ADR-032). +[Collection(PostgreSqlCollection.Name)] +[Trait("Category", "Integration")] +[Trait("Provider", "EfCore")] +[Trait("Requires", "Docker")] +public sealed class EfGenerationTests(PostgreSqlServer server) : PostgreSqlTest(server) +{ + private static CancellationToken Ct => TestContext.Current.CancellationToken; + + [Fact] + [Trait("Id", "UT-EF-11")] + [Trait("Covers", "doc 06 6")] + public void DefaultSchema_IsALowerCaseIdentifierPerGeneration() + { + EfGenerations.DefaultSchema(new ReadModelGeneration("Account-Activity", 2, 1)).ShouldBe("account_activity_v2"); + EfGenerations.DefaultSchema(new ReadModelGeneration("account.activity", 1, 3)).ShouldBe("account_activity_v1_3"); + } + + [Fact] + [Trait("Id", "UT-EF-12")] + [Trait("Id", "UT-EF-13")] + [Trait("Covers", "doc 06 6;ADR-032")] + public async Task SchemaPerGeneration_FirstBuildCreatesItsSchema_ARebuildFillsANewOne_AndTheRetiredSchemaIsDropped() + { + string prefix = "rm" + Guid.CreateVersion7().ToString("N")[..12]; + var generations = new EfGenerationOptions { Schema = g => prefix + "_" + EfGenerations.DefaultSchema(g) }; + string first = prefix + "_account_activity_v1"; + string rebuilt = prefix + "_account_activity_v1_2"; + using IHost host = await StartAsync(generations); + ICommandSender commands = host.Services.GetRequiredService(); + PostgreSqlStore store = host.Services.GetRequiredService(); + var ada = AccountId.New(); + await commands.SendAsync(new OpenAccount(ada, "Ada", 10m), null, Ct); + await commands.SendAsync(new Deposit(ada, 5m), null, Ct); + + // The first generation creates its schema from the EF model and claims the alias. + await EventuallyAsync(async () => (await ActivityAsync(host, ada)) is { Balance: 15m }, "the first generation's row"); + await EventuallyAsync(async () => (await store.ListAliasesAsync(Ct)).Any(a => a.Alias == "account-activity" && a.Target == "account-activity@1"), "the alias claim"); + (await SchemaExistsAsync(first)).ShouldBeTrue(); + + // A rebuild (dotnet sourceflow projection rebuild) builds @1.2 in its own schema while @1 keeps serving. + await store.RequestAsync("account-activity", "account-activity@1", "account-activity@1.2", Ct); + await EventuallyAsync(async () => (await store.ListAliasesAsync(Ct)).Any(a => a.Alias == "account-activity" && a.Target == "account-activity@1.2"), "the switch to @1.2"); + (await SchemaExistsAsync(rebuilt)).ShouldBeTrue(); + IReadModelResolver resolver = host.Services.GetRequiredService(); + (await resolver.ResolveAsync("account-activity", Ct)).ShouldBe(new ReadModelGeneration("account-activity", 1, 2)); + (await ActivityAsync(host, ada)).ShouldNotBeNull().Balance.ShouldBe(15m); // read through the resolver: the rebuilt schema + + // RetainPreviousFor is zero here: the retired generation's schema is dropped at the next retention check. + // Retention drops the schema, then forgets the previous generation: wait for both, not for the first alone. + await EventuallyAsync( + async () => !await SchemaExistsAsync(first) && (await store.ListAliasesAsync(Ct)).Single(a => a.Alias == "account-activity").Previous is null, + "the retired schema to be dropped and forgotten"); + } + + private async Task StartAsync(EfGenerationOptions generations) + { + string schema = PostgreSqlServer.NewSchema(); + HostApplicationBuilder builder = Host.CreateApplicationBuilder(new HostApplicationBuilderSettings { EnvironmentName = Environments.Development, DisableDefaults = true }); + builder.Services.AddSourceFlow(sf => + { + sf.ServiceName = "accounts"; + sf.AddModule(); + sf.AddModule(); + sf.AddModule(); + sf.Projections(p => p.Add().Async()); + sf.Configure(o => + { + o.PollInterval = TimeSpan.FromMilliseconds(50); + o.RetainPreviousFor = TimeSpan.Zero; + o.RetentionInterval = TimeSpan.FromSeconds(1); + }); + sf.UsePostgreSql(o => + { + o.DataSource = Server.DataSource; + o.Schema = schema; + }); + sf.UseEntityFrameworkProjections(ReportingDbContext.Configure, (o, s) => new ReportingDbContext(o, s), generations); + sf.UseInMemoryTransport(); + }); + IHost host = builder.Build(); + await host.StartAsync(Ct); + return host; + } + + // Reads the generation serving reads, as an application would: resolve it, then open a context for its schema. + private async Task ActivityAsync(IHost host, AccountId id) + { + ReadModelGeneration generation = await host.Services.GetRequiredService().ResolveAsync("account-activity", Ct); + EfSessionContextFactory factory = host.Services.GetRequiredService>(); + await using NpgsqlConnection connection = await Server.DataSource.OpenConnectionAsync(Ct); + await using ReportingDbContext db = factory.CreateForGeneration(connection, generation); + try + { + return await db.Activity.AsNoTracking().SingleOrDefaultAsync(a => a.AccountId == id.Value, Ct); + } + catch (PostgresException e) when (e.SqlState == PostgresErrorCodes.UndefinedTable) + { + return null; // the generation's schema is not created yet + } + } + + private async Task SchemaExistsAsync(string schema) + { + await using NpgsqlCommand command = Server.DataSource.CreateCommand("SELECT to_regnamespace(@s) IS NOT NULL"); + command.Parameters.AddWithValue("s", schema); + return await command.ExecuteScalarAsync(Ct) is true; + } + + private static async Task EventuallyAsync(Func> condition, string what) + { + DateTimeOffset deadline = TimeProvider.System.GetUtcNow() + TimeSpan.FromSeconds(30); + while (!await condition()) + { + if (TimeProvider.System.GetUtcNow() > deadline) + { + throw new TimeoutException($"Timed out waiting for: {what}."); + } + + await RealClock.WaitAsync(TimeSpan.FromMilliseconds(50)); + } + } +} diff --git a/tests/Storage/SourceFlow.Storage.Tests/EntityFrameworkCore/EfProjectionTests.cs b/tests/Storage/SourceFlow.Storage.Tests/EntityFrameworkCore/EfProjectionTests.cs new file mode 100644 index 00000000..1a70fd07 --- /dev/null +++ b/tests/Storage/SourceFlow.Storage.Tests/EntityFrameworkCore/EfProjectionTests.cs @@ -0,0 +1,277 @@ +using Bank.Accounts; +using Bank.Contracts; +using Microsoft.EntityFrameworkCore; +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.Hosting; +using SourceFlow.Hosting; +using SourceFlow.Messaging; +using SourceFlow.Runtime; +using SourceFlow.Storage.EntityFrameworkCore; +using SourceFlow.Storage.InMemory; +using SourceFlow.Storage.PostgreSQL; +using SourceFlow.Storage.Tests.PostgreSql; +using SourceFlow.Testing.Conformance; + +namespace SourceFlow.Storage.Tests.EntityFrameworkCore; + +/// UT-EF: EF Core projection wiring that needs no database (WP-2.7). +[Trait("Category", "Unit")] +[Trait("Provider", "EfCore")] +public sealed class EfProjectionUnitTests +{ + [Fact] + [Trait("Id", "UT-EF-01")] + public void SessionProjection_WithoutItsUnitOfWork_FailsAtStartup() + { + var services = new ServiceCollection(); + services.AddSourceFlow(sf => + { + sf.ServiceName = "reporting"; + sf.AddModule(); + sf.AddModule(); + sf.Projections(p => p.Add().Inline()); + sf.UseInMemoryStorage(); + }); + using ServiceProvider provider = services.BuildServiceProvider(); + + Should.Throw(() => provider.GetRequiredService()) + .Message.ShouldContain("UseEntityFrameworkProjections"); + } + + [Fact] + [Trait("Id", "UT-EF-02")] + public async Task EfContext_NeedsARelationalSession() + { + var store = new InMemoryStore(); + var factory = new EfSessionContextFactory(ReportingDbContext.Configure, ReportingDbContext.Create); + await using IStorageSession session = await store.BeginAsync(MessageEnvelope.DefaultTenant, TestContext.Current.CancellationToken); + + (await Should.ThrowAsync(() => factory.CreateAsync(session, TestContext.Current.CancellationToken).AsTask())) + .Message.ShouldContain("relational store"); + } + + [Fact] + [Trait("Id", "UT-EF-03")] + public void SessionProjection_IsRegisteredByItsModule_AsASessionProjection() + { + var model = new SourceFlowModelBuilder(); + ReportingModule.Register(model); + AccountsModule.Register(model); + + ProjectionDescriptor projection = model.Build().Projections + .Single(p => p.ProjectionType == typeof(AccountActivityProjection)); + projection.ShouldNotBeAssignableTo(); + projection.Collection.ShouldBe("account-activity@1"); + projection.HandledEvents.ShouldBe([typeof(AccountOpened), typeof(MoneyDeposited), typeof(MoneyWithdrawn)], ignoreOrder: true); + } +} + +/// SCK-61..64 and UT-EF-04..07: EF Core read models in the storage transaction, on PostgreSQL (doc 05 §10). +[Collection(PostgreSqlCollection.Name)] +[Trait("Category", "Integration")] +[Trait("Provider", "EfCore")] +[Trait("Requires", "Docker")] +public sealed class EfProjectionTests(PostgreSqlServer server) : PostgreSqlTest(server) +{ + private static CancellationToken Ct => TestContext.Current.CancellationToken; + + public override async ValueTask InitializeAsync() + { + await base.InitializeAsync(); + await ReportingDbContext.EnsureCreatedAsync(Server.DataSource); + } + + [Fact] + [Trait("Id", "SCK-61")] + [Trait("Covers", "doc 05 8.1")] + [Trait("Id", "UT-EF-05")] + [Trait("Id", "UT-EF-06")] + public async Task InlineEfProjection_CommitsWithTheEvents() + { + using IHost host = await StartAsync(ProjectionMode.Inline); + ICommandSender commands = host.Services.GetRequiredService(); + var id = AccountId.New(); + + await commands.SendAsync(new OpenAccount(id, "Ada", 100m), null, Ct); + await commands.SendAsync(new Deposit(id, 50m), null, Ct); + await commands.SendAsync(new Withdraw(id, 30m), null, Ct); + (await commands.SendAsync(new Withdraw(id, 1_000m), null, Ct)).Status.ShouldBe(CommandStatus.Rejected); + + AccountActivity row = (await ActivityAsync(id))!; + row.Holder.ShouldBe("Ada"); + row.Balance.ShouldBe(120m); + row.Movements.ShouldBe(2); + row.Version.ShouldBe(3); + } + + [Fact] + [Trait("Id", "SCK-62")] + [Trait("Covers", "ADR-008")] + [Trait("Id", "UT-EF-07")] + public async Task InlineEfProjection_ConflictingAttempts_LeaveNoTrace() + { + using IHost host = await StartAsync(ProjectionMode.Inline, sf => sf.Configure(o => o.MaxConcurrencyRetries = 50)); + ICommandSender commands = host.Services.GetRequiredService(); + var id = AccountId.New(); + await commands.SendAsync(new OpenAccount(id, "Ada", 1m), null, Ct); + + CommandResult[] results = await Task.WhenAll(Enumerable.Range(0, 12) + .Select(_ => Task.Run(async () => await commands.SendAsync(new Deposit(id, 1m), null, Ct)))); + + results.ShouldAllBe(r => r.Status == CommandStatus.Accepted); + AccountActivity row = (await ActivityAsync(id))!; + row.Balance.ShouldBe(13m); + row.Movements.ShouldBe(12); + row.Version.ShouldBe(13); + } + + [Fact] + [Trait("Id", "SCK-62")] + [Trait("Covers", "ES-R1")] + [Trait("Id", "UT-EF-08")] + public async Task Flush_SendsTheAppendFirst_SoAConflictSurfacesBeforeAnyEfWrite() + { + await using PostgreSqlStore store = await Server.CreateStoreAsync(); + var stream = new StreamId("bank-account-flush"); + await AppendAsync(store, stream); + + await using IStorageSession session = await store.BeginAsync(MessageEnvelope.DefaultTenant, Ct); + session.Append(stream, "account", ExpectedVersion.NoStream, [StorageConformance.Event()]); + + await Should.ThrowAsync(() => session.FlushAsync(Ct).AsTask()); + Should.Throw(() => session.EnqueueOutbox(null!)); + } + + [Fact] + [Trait("Id", "SCK-63")] + [Trait("Covers", "ADR-016")] + [Trait("Id", "UT-EF-09")] + public async Task LostLease_RollsBackTheEfChanges() + { + await using PostgreSqlStore store = await Server.CreateStoreAsync(); + var factory = new EfSessionContextFactory(ReportingDbContext.Configure, ReportingDbContext.Create); + LeaseToken lease = (await store.TryAcquireAsync("sub:account-activity:0", "node-1", TimeSpan.FromSeconds(30), Ct))!; + var id = Guid.CreateVersion7(); + + await using (IStorageSession session = await store.BeginAsync(MessageEnvelope.DefaultTenant, Ct)) + { + await using ReportingDbContext db = await factory.CreateAsync(session, Ct); + db.Activity.Add(new AccountActivity { AccountId = id, Holder = "Ada", Version = 1 }); + await db.SaveChangesAsync(Ct); + session.SaveCheckpoint("projection:account-activity@1", 0, new GlobalPosition(9, 1), lease with { Token = lease.Token + 1 }); + + await Should.ThrowAsync(() => session.CommitAsync(Ct).AsTask()); + } + + (await ActivityAsync(new AccountId(id))).ShouldBeNull(); + } + + [Fact] + [Trait("Id", "SCK-64")] + [Trait("Covers", "ADR-016")] + [Trait("Id", "UT-EF-10")] + public async Task AsyncEfProjection_CatchesUpThroughFencedCheckpoints() + { + using IHost host = await StartAsync(ProjectionMode.Async, sf => sf.Configure(o => o.SubscriptionPartitions = 2)); + ICommandSender commands = host.Services.GetRequiredService(); + AccountId[] ids = [.. Enumerable.Range(0, 6).Select(_ => AccountId.New())]; + foreach (AccountId id in ids) + { + await commands.SendAsync(new OpenAccount(id, "Grace", 10m), null, Ct); + await commands.SendAsync(new Deposit(id, 5m), null, Ct); + } + + foreach (AccountId id in ids) + { + await EventuallyAsync(async () => (await ActivityAsync(id)) is { Balance: 15m, Version: 2 }, $"activity of {id}"); + } + + // Streams are spread over the two partitions by hash: six random accounts can all land in one of them, so the + // checkpoint of at least one partition moved, in the same transaction as the rows it wrote. + PostgreSqlStore store = host.Services.GetRequiredService(); + GlobalPosition[] checkpoints = [await store.GetAsync("projection:account-activity@1", 0, Ct), await store.GetAsync("projection:account-activity@1", 1, Ct)]; + checkpoints.ShouldContain(c => c > GlobalPosition.Start); + } + + [Fact] + [Trait("Id", "UT-EF-04")] + public async Task IdempotentUpsert_IgnoresOlderAndEqualVersions() + { + var options = new DbContextOptionsBuilder().UseNpgsql(Server.DataSource).Options; + var id = Guid.CreateVersion7(); + await using (var db = new ReportingDbContext(options)) + { + (await db.Activity.UpsertAsync(id, 5, _ => new AccountActivity { AccountId = id, Balance = 5m }, Ct)).ShouldBeTrue(); + await db.SaveChangesAsync(Ct); + } + + await using (var db = new ReportingDbContext(options)) + { + (await db.Activity.UpsertAsync(id, 4, row => { row!.Balance = 4m; return row; }, Ct)).ShouldBeFalse(); + (await db.Activity.UpsertAsync(id, 5, row => { row!.Balance = 99m; return row; }, Ct)).ShouldBeFalse(); + (await db.Activity.UpsertAsync(id, 6, row => new AccountActivity { AccountId = id, Balance = 6m }, Ct)).ShouldBeTrue(); + await db.SaveChangesAsync(Ct); + } + + AccountActivity stored = (await ActivityAsync(new AccountId(id)))!; + stored.Balance.ShouldBe(6m); + stored.Version.ShouldBe(6); + } + + private async Task StartAsync(ProjectionMode mode, Action? configure = null) + { + string schema = PostgreSqlServer.NewSchema(); + HostApplicationBuilder builder = Host.CreateApplicationBuilder(new HostApplicationBuilderSettings { EnvironmentName = Environments.Development, DisableDefaults = true }); + builder.Services.AddSourceFlow(sf => + { + sf.ServiceName = "accounts"; + sf.AddModule(); + sf.AddModule(); + sf.AddModule(); + sf.Projections(p => + { + ProjectionModeBuilder activity = p.Add(); + _ = mode == ProjectionMode.Inline ? activity.Inline() : activity.Async(); + }); + sf.UsePostgreSql(o => + { + o.DataSource = Server.DataSource; + o.Schema = schema; + }); + sf.UseEntityFrameworkProjections(ReportingDbContext.Configure, ReportingDbContext.Create); + sf.UseInMemoryTransport(); + configure?.Invoke(sf); + }); + IHost host = builder.Build(); + await host.StartAsync(Ct); + return host; + } + + private async Task ActivityAsync(AccountId id) + { + var options = new DbContextOptionsBuilder().UseNpgsql(Server.DataSource).Options; + await using var db = new ReportingDbContext(options); + return await db.Activity.AsNoTracking().SingleOrDefaultAsync(a => a.AccountId == id.Value, Ct); + } + + private static async Task AppendAsync(PostgreSqlStore store, StreamId stream) + { + await using IStorageSession session = await store.BeginAsync(MessageEnvelope.DefaultTenant, Ct); + session.Append(stream, "account", ExpectedVersion.NoStream, [StorageConformance.Event()]); + await session.CommitAsync(Ct); + } + + private static async Task EventuallyAsync(Func> condition, string what) + { + DateTimeOffset deadline = TimeProvider.System.GetUtcNow() + TimeSpan.FromSeconds(30); + while (!await condition()) + { + if (TimeProvider.System.GetUtcNow() > deadline) + { + throw new TimeoutException($"Timed out waiting for: {what}."); + } + + await RealClock.WaitAsync(TimeSpan.FromMilliseconds(50)); + } + } +} diff --git a/tests/Storage/SourceFlow.Storage.Tests/EntityFrameworkCore/Reporting.cs b/tests/Storage/SourceFlow.Storage.Tests/EntityFrameworkCore/Reporting.cs new file mode 100644 index 00000000..e125e4e0 --- /dev/null +++ b/tests/Storage/SourceFlow.Storage.Tests/EntityFrameworkCore/Reporting.cs @@ -0,0 +1,123 @@ +using Bank.Accounts; +using Microsoft.EntityFrameworkCore; +using Npgsql; +using SourceFlow.Storage.EntityFrameworkCore; + +namespace SourceFlow.Storage.Tests.EntityFrameworkCore; + +/// A relational read model: one row per account. +public sealed class AccountActivity : IVersionedReadModel +{ + public Guid AccountId { get; set; } + + public string Holder { get; set; } = string.Empty; + + public decimal Balance { get; set; } + + public int Movements { get; set; } + + public long Version { get; set; } +} + +/// +/// The reporting context; its tables live in the shared reporting schema, keyed by unique account ids, or in a +/// schema per read-model generation (UT-EF-11..13). +/// +public sealed class ReportingDbContext(DbContextOptions options, string schema) : DbContext(options), IGenerationSchemaContext +{ + public const string SharedSchema = "reporting"; + + public ReportingDbContext(DbContextOptions options) + : this(options, SharedSchema) + { + } + + public string Schema { get; } = schema; + + public DbSet Activity => Set(); + + protected override void OnModelCreating(ModelBuilder modelBuilder) + { + modelBuilder.HasDefaultSchema(Schema); + modelBuilder.Entity(e => + { + e.ToTable("account_activity"); + e.HasKey(a => a.AccountId); + }); + } + + public static ReportingDbContext Create(DbContextOptions options) + { + return new ReportingDbContext(options); + } + + public static void Configure(DbContextOptionsBuilder options, System.Data.Common.DbConnection connection) + { + options.UseNpgsql(connection); + } + + private static readonly SemaphoreSlim Gate = new(1, 1); + private static readonly HashSet Created = []; + + /// Creates the reporting tables once per server. + public static async Task EnsureCreatedAsync(NpgsqlDataSource dataSource) + { + await Gate.WaitAsync(); + try + { + if (!Created.Add(dataSource.ConnectionString)) + { + return; + } + + var options = new DbContextOptionsBuilder().UseNpgsql(dataSource).Options; + await using var db = new ReportingDbContext(options); + await using NpgsqlCommand exists = dataSource.CreateCommand("SELECT to_regclass('reporting.account_activity') IS NOT NULL"); + if (await exists.ExecuteScalarAsync() is not true) + { + // EF's own DDL for the model (no user input). + await using NpgsqlCommand create = dataSource.CreateCommand("CREATE SCHEMA IF NOT EXISTS reporting;\n" + db.Database.GenerateCreateScript()); + await create.ExecuteNonQueryAsync(); + } + } + finally + { + Gate.Release(); + } + } +} + +/// An EF Core projection of the Bank accounts (doc 03 §6.3), version-guarded for replays. +[Projection("account-activity")] +public sealed partial class AccountActivityProjection : IEfProjection +{ + public async ValueTask When(AccountOpened e, ReportingDbContext db, EventContext ctx, CancellationToken ct) + { + await db.Activity.UpsertAsync(e.AccountId.Value, ctx.StreamVersion.Value, + _ => new AccountActivity { AccountId = e.AccountId.Value, Holder = e.Holder, Balance = e.InitialDeposit }, ct); + } + + public async ValueTask When(MoneyDeposited e, ReportingDbContext db, EventContext ctx, CancellationToken ct) + { + await db.Activity.UpsertAsync(e.AccountId.Value, ctx.StreamVersion.Value, row => Move(row, e.AccountId, e.BalanceAfter), ct); + } + + public async Task When(MoneyWithdrawn e, ReportingDbContext db, EventContext ctx, CancellationToken ct) + { + await db.Activity.UpsertAsync(e.AccountId.Value, ctx.StreamVersion.Value, row => Move(row, e.AccountId, e.BalanceAfter), ct); + } + + private static AccountActivity Move(AccountActivity? row, AccountId id, decimal balance) + { + row ??= new AccountActivity { AccountId = id.Value }; + row.Balance = balance; + row.Movements++; + return row; + } +} + +/// The reporting module: registers the EF projection (generated). +// The generator registers every annotated type of this assembly in each module: the clinic test domain (PersonalData/) +// comes along, so this module carries its JSON metadata. +[SourceFlowModule(typeof(SourceFlow.Storage.Tests.PersonalData.ClinicJsonContext))] +public sealed partial class ReportingModule; diff --git a/tests/Storage/SourceFlow.Storage.Tests/Migration/V2Database.cs b/tests/Storage/SourceFlow.Storage.Tests/Migration/V2Database.cs new file mode 100644 index 00000000..0d02f935 --- /dev/null +++ b/tests/Storage/SourceFlow.Storage.Tests/Migration/V2Database.cs @@ -0,0 +1,266 @@ +using System.Data.Common; +using System.Globalization; +using System.Text; +using Bank.Accounts; +using SourceFlow.Migration; + +namespace SourceFlow.Storage.Tests.Migration; + +/// +/// A seeded v2 database (plan 06 §6): the v2 EF CommandRecord DDL and entity tables, with rows replaying the v2 E2E +/// account scenario as SQL (no v2 code is referenced). One schema per test; the archive schema is per test too. +/// +public sealed class V2Database +{ + /// The v2 E2E command types, as v2 stored them (assembly-qualified, with version). + public const string Commands = "SourceFlow.Core.Tests.E2E.Commands."; + + public const string Assembly = ", SourceFlow.Core.Tests, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null"; + + /// A command type v2 could not rebuild (GAP-04: no public parameterless constructor). + public const string ApplyInterest = "Legacy.Banking.ApplyInterest, Legacy.Banking, Version=2.0.0.0, Culture=neutral, PublicKeyToken=null"; + + /// A command of another v2 entity type that shares the command table (ids overlap per type). + public const string PlaceOrder = "Shop.Commands.PlaceOrder, Shop, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null"; + + /// The generated accounts: ids 2000..2039. + public const int Generated = 40; + + private V2Database(DbDataSource dataSource, V2Dialect dialect, string schema, string connectionString) + { + DataSource = dataSource; + Dialect = dialect; + Schema = schema; + ConnectionString = connectionString; + ArchiveSchema = schema + "_archive"; + Source = new V2Source(dataSource, dialect) { Schema = schema, ArchiveSchema = ArchiveSchema }; + } + + public DbDataSource DataSource { get; } + + public V2Dialect Dialect { get; } + + public string Schema { get; } + + public string ArchiveSchema { get; } + + public string ConnectionString { get; } + + public V2Source Source { get; } + + /// The --v2-* options of the global tool for this database. + public string[] ToolOptions => + [ + "--v2-connection", ConnectionString, "--v2-provider", Dialect == V2Dialect.SqlServer ? "sqlserver" : "postgresql", + "--v2-schema", Schema, "--v2-archive-schema", ArchiveSchema, + ]; + + /// Every v2 account: id, name, balance, closed. + public static IReadOnlyList<(int Id, string Name, decimal Balance, bool Closed)> Accounts { get; } = + [ + (999, "John Doe", 1400m, true), + (1000, "Jane Roe", 250m, false), + (1001, "Ada Lovelace", 520.5m, false), + .. Enumerable.Range(0, Generated).Select(i => (2000 + i, "Customer " + i.ToString(CultureInfo.InvariantCulture), 10m * (i + 1), i % 7 == 0)), + ]; + + public static async Task CreateAsync(DbDataSource dataSource, V2Dialect dialect, string schema, string connectionString) + { + var database = new V2Database(dataSource, dialect, schema, connectionString); + await database.ExecuteAsync(database.Ddl()); + await database.ExecuteAsync(database.Seed()); + return database; + } + + public string Q(string identifier) + { + return Dialect == V2Dialect.SqlServer ? "[" + identifier + "]" : "\"" + identifier + "\""; + } + + public string T(string table) + { + return Q(Schema) + "." + Q(table); + } + + public async Task ExecuteAsync(string sql) + { + await using DbConnection connection = await DataSource.OpenConnectionAsync(TestContext.Current.CancellationToken); + await using DbCommand command = connection.CreateCommand(); + command.CommandText = sql; + await command.ExecuteNonQueryAsync(TestContext.Current.CancellationToken); + } + + public async Task ScalarAsync(string sql) + { + await using DbConnection connection = await DataSource.OpenConnectionAsync(TestContext.Current.CancellationToken); + await using DbCommand command = connection.CreateCommand(); + command.CommandText = sql; + return Convert.ToInt64(await command.ExecuteScalarAsync(TestContext.Current.CancellationToken), CultureInfo.InvariantCulture); + } + + // The v2 EF model: CommandRecordConfiguration (unique EntityId+SequenceNo, indexes on EntityId and Timestamp) and the + // entity table EF creates for the v2 E2E BankAccount; plus a v2 view-model table, which holds no entities. + private string Ddl() + { + bool sql = Dialect == V2Dialect.SqlServer; + string text = sql ? "nvarchar(max)" : "text"; + string name = sql ? "nvarchar(500)" : "varchar(500)"; + string time = sql ? "datetime2" : "timestamp"; + string identity = sql ? "bigint IDENTITY(1,1)" : "bigint GENERATED BY DEFAULT AS IDENTITY"; + string boolean = sql ? "bit" : "boolean"; + string createSchema = sql ? $"EXEC(N'CREATE SCHEMA {Q(Schema)}');" : $"CREATE SCHEMA {Q(Schema)};"; + return $""" + {createSchema} + CREATE TABLE {T("CommandRecord")} ( + {Q("Id")} {identity} NOT NULL PRIMARY KEY, + {Q("EntityId")} int NOT NULL, + {Q("SequenceNo")} int NOT NULL, + {Q("CommandName")} {name} NOT NULL, + {Q("CommandType")} {name} NOT NULL, + {Q("PayloadType")} {name} NOT NULL, + {Q("PayloadData")} {text} NOT NULL, + {Q("Metadata")} {text} NOT NULL, + {Q("Timestamp")} {time} NOT NULL, + {Q("CreatedAt")} {time} NOT NULL, + {Q("UpdatedAt")} {time} NOT NULL); + CREATE UNIQUE INDEX {Q("IX_CommandRecord_EntityId_SequenceNo")} ON {T("CommandRecord")} ({Q("EntityId")}, {Q("SequenceNo")}); + CREATE INDEX {Q("IX_CommandRecord_EntityId")} ON {T("CommandRecord")} ({Q("EntityId")}); + CREATE INDEX {Q("IX_CommandRecord_Timestamp")} ON {T("CommandRecord")} ({Q("Timestamp")}); + CREATE TABLE {T("BankAccount")} ( + {Q("Id")} int NOT NULL PRIMARY KEY, + {Q("CreatedOn")} {time} NOT NULL, + {Q("AccountName")} {text} NULL, + {Q("Balance")} decimal(18,2) NOT NULL, + {Q("IsClosed")} {boolean} NOT NULL, + {Q("ClosureReason")} {text} NULL, + {Q("ActiveOn")} {time} NOT NULL); + CREATE TABLE {T("AccountViewModel")} ( + {Q("Id")} int NOT NULL PRIMARY KEY, + {Q("AccountName")} {text} NULL, + {Q("CurrentBalance")} decimal(18,2) NOT NULL, + {Q("TransactionCount")} int NOT NULL); + """; + } + + private string Seed() + { + var sql = new StringBuilder(); + string True = Dialect == V2Dialect.SqlServer ? "1" : "true"; + string False = Dialect == V2Dialect.SqlServer ? "0" : "false"; + foreach ((int id, string name, decimal balance, bool closed) in Accounts) + { + string reason = closed ? "'Customer account close request'" : "''"; + sql.AppendLine(CultureInfo.InvariantCulture, $"INSERT INTO {T("BankAccount")} VALUES ({id}, '2025-01-10T09:00:00', '{name}', {balance.ToString(CultureInfo.InvariantCulture)}, {(closed ? True : False)}, {reason}, '2025-01-11T09:00:00');"); + sql.AppendLine(CultureInfo.InvariantCulture, $"INSERT INTO {T("AccountViewModel")} VALUES ({id}, '{name}', {balance.ToString(CultureInfo.InvariantCulture)}, 1);"); + } + + // Account 999 (the v2 E2E scenario, caller-assigned id): create, activate, deposit 500, withdraw 200, deposit 100, close. + Command(sql, 999, 1, "CreateAccount", "Payload", "{\"id\":999,\"initialAmount\":1000,\"accountName\":\"John Doe\"}"); + Command(sql, 999, 2, "ActivateAccount", "ActivationPayload", "{\"id\":999,\"activeOn\":\"2025-01-11T09:00:00Z\"}"); + Command(sql, 999, 3, "DepositMoney", "TransactPayload", "{\"id\":999,\"type\":1,\"amount\":500}"); + Command(sql, 999, 4, "WithdrawMoney", "TransactPayload", "{\"id\":999,\"type\":2,\"amount\":200}"); + Command(sql, 999, 5, "DepositMoney", "TransactPayload", "{\"id\":999,\"type\":1,\"amount\":100}"); + Command(sql, 999, 6, "CloseAccount", "ClosurePayload", "{\"id\":999,\"isClosed\":true,\"closureReason\":\"Customer account close request\"}"); + + // Another entity type shares the table and numbering (v2 sequences per entity id): not an account command. + Command(sql, 999, 7, "PlaceOrder", "OrderPayload", "{\"id\":999}", PlaceOrder); + + // GAP-20: two accounts created without a caller-assigned id are logged under entity id 0. + Command(sql, 0, 1, "CreateAccount", "Payload", "{\"id\":0,\"initialAmount\":200,\"accountName\":\"Jane Roe\"}"); + Command(sql, 0, 2, "CreateAccount", "Payload", "{\"id\":0,\"initialAmount\":500,\"accountName\":\"Ada Lovelace\"}"); + Command(sql, 1000, 1, "ActivateAccount", "ActivationPayload", "{\"id\":1000}"); + Command(sql, 1000, 2, "DepositMoney", "TransactPayload", "{\"id\":1000,\"type\":1,\"amount\":50}"); + + // GAP-04: a command type v2 couldn't rebuild, and a row with an empty payload. + Command(sql, 1001, 1, "ActivateAccount", "ActivationPayload", "{\"id\":1001}"); + Command(sql, 1001, 2, "ApplyInterest", "InterestPayload", "{\"rate\":0.041}", ApplyInterest); + Command(sql, 1001, 3, "DepositMoney", "TransactPayload", string.Empty); + + for (int i = 0; i < Generated; i++) + { + Command(sql, 2000 + i, 1, "CreateAccount", "Payload", "{\"id\":" + (2000 + i).ToString(CultureInfo.InvariantCulture) + "}"); + } + + return sql.ToString(); + } + + /// The v2 commands: 7 for account 999 (one of them an order), 2 under id 0, 2 for 1000, 3 for 1001, 1 per generated account. + public static int CommandCount => 7 + 2 + 2 + 3 + Generated; + + private void Command(StringBuilder sql, int entityId, int sequence, string name, string payload, string data, string? type = null) + { + type ??= Commands + name + Assembly; + string payloadType = Commands + payload + Assembly; + string columns = string.Join(", ", new[] { "EntityId", "SequenceNo", "CommandName", "CommandType", "PayloadType", "PayloadData", "Metadata", "Timestamp", "CreatedAt", "UpdatedAt" }.Select(Q)); + string time = "'2025-01-1" + Math.Min(sequence, 9).ToString(CultureInfo.InvariantCulture) + "T10:00:00'"; + sql.AppendLine(CultureInfo.InvariantCulture, + $"INSERT INTO {T("CommandRecord")} ({columns}) VALUES ({entityId}, {sequence}, '{name}', '{type}', '{payloadType}', '{data}', '{{\"sequenceNo\":{sequence}}}', {time}, {time}, {time});"); + } +} + +/// A row of the v2 BankAccount table, as migrate v2 scaffold generates it. +public sealed record V2BankAccount(int Id, DateTime CreatedOn, string? AccountName, decimal Balance, bool IsClosed, string? ClosureReason, DateTime ActiveOn) : IV2Entity +{ + public static string TableName => "BankAccount"; + + public static V2BankAccount Read(V2Row row) + { + return new( + row.Int32("Id"), + row.DateTime("CreatedOn"), + row.String("AccountName"), + row.Decimal("Balance"), + row.Boolean("IsClosed"), + row.String("ClosureReason"), + row.DateTime("ActiveOn")); + } +} + +/// +/// Imports v2 accounts into the Bank sample's aggregate: the current state as (the balance +/// as the opening amount) and, for closed accounts, . +/// +public sealed class BankAccountImport : IV2Import +{ + /// Simulates an interruption: the import fails on this v2 id. + public int? FailOn { get; set; } + + public AccountId MapId(V2BankAccount entity) + { + return V2Ids.FromLegacy(entity.Id); + } + + public IEnumerable ToEvents(V2BankAccount entity, V2ImportContext context) + { + if (entity.Id == FailOn) + { + throw new InvalidOperationException($"Interrupted at v2 account {entity.Id}."); + } + + AccountId id = MapId(entity); + yield return new AccountOpened(id, entity.AccountName ?? string.Empty, entity.Balance, new DateTimeOffset(entity.CreatedOn, TimeSpan.Zero)); + if (entity.IsClosed) + { + yield return new AccountClosed(id, entity.ClosureReason ?? string.Empty, context.ImportedAt); + } + } + + public IEnumerable Compare(V2BankAccount entity, BankAccount state) + { + if (state.Balance != entity.Balance) + { + yield return $"Balance: v2 {entity.Balance.ToString(CultureInfo.InvariantCulture)}, v3 {state.Balance.ToString(CultureInfo.InvariantCulture)}"; + } + + AccountStatus expected = entity.IsClosed ? AccountStatus.Closed : AccountStatus.Open; + if (state.Status != expected) + { + yield return $"Status: v2 {expected}, v3 {state.Status}"; + } + } + + public bool OwnsCommand(string commandType) + { + return !commandType.StartsWith("Shop.", StringComparison.Ordinal); + } +} diff --git a/tests/Storage/SourceFlow.Storage.Tests/Migration/V2MigrationTests.cs b/tests/Storage/SourceFlow.Storage.Tests/Migration/V2MigrationTests.cs new file mode 100644 index 00000000..74ad75c2 --- /dev/null +++ b/tests/Storage/SourceFlow.Storage.Tests/Migration/V2MigrationTests.cs @@ -0,0 +1,375 @@ +using System.Text.Json; +using Bank.Accounts; +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.Hosting; +using Npgsql; +using SourceFlow.Hosting; +using SourceFlow.Migration; +using SourceFlow.Runtime; +using SourceFlow.Storage.PostgreSQL; +using SourceFlow.Storage.SqlServer; +using SourceFlow.Storage.Tests.PostgreSql; +using SourceFlow.Storage.Tests.SqlServer; +using SourceFlow.Tool; + +namespace SourceFlow.Storage.Tests.Migration; + +/// MIG-01..09 (plan 06 §6, WP-5.4) with the v2 database and the v3 store on PostgreSQL. +[Collection(PostgreSqlCollection.Name)] +[Trait("Category", "EndToEnd")] +[Trait("Provider", "PostgreSQL")] +[Trait("Requires", "Docker")] +public sealed class PostgreSqlV2MigrationTests(PostgreSqlServer server) : V2MigrationScenarios +{ + public override Task EnsureStartedAsync() + { + return server.EnsureStartedAsync(); + } + + protected override Task CreateV2Async() + { + return V2Database.CreateAsync(server.DataSource, V2Dialect.PostgreSql, PostgreSqlServer.NewSchema("v2"), server.ConnectionString); + } + + protected override void UseV3Storage(SourceFlowBuilder sf, string schema) + { + sf.UsePostgreSql(o => + { + o.DataSource = server.DataSource; + o.Schema = schema; + }); + } + + protected override string NewV3Schema() + { + return PostgreSqlServer.NewSchema("v3"); + } +} + +/// MIG-01..09 with the v2 database and the v3 store on SQL Server (v2's default EF provider). +[Collection(SqlServerCollection.Name)] +[Trait("Category", "EndToEnd")] +[Trait("Provider", "SqlServer")] +[Trait("Requires", "Docker")] +public sealed class SqlServerV2MigrationTests(SqlServerServer server) : V2MigrationScenarios, IDisposable +{ + private Microsoft.Data.SqlClient.SqlClientFactory? _factory; + private System.Data.Common.DbDataSource? _dataSource; + + public override Task EnsureStartedAsync() + { + return server.EnsureStartedAsync(); + } + + protected override Task CreateV2Async() + { + _factory = Microsoft.Data.SqlClient.SqlClientFactory.Instance; + _dataSource = _factory.CreateDataSource(server.ConnectionString); + return V2Database.CreateAsync(_dataSource, V2Dialect.SqlServer, SqlServerServer.NewSchema("v2"), server.ConnectionString); + } + + protected override void UseV3Storage(SourceFlowBuilder sf, string schema) + { + sf.UseSqlServer(server.ConnectionString, o => o.Schema = schema); + } + + protected override string NewV3Schema() + { + return SqlServerServer.NewSchema("v3"); + } + + public void Dispose() + { + _dataSource?.Dispose(); + } +} + +/// +/// The v2 data migration (doc 12 §3) against a seeded v2 database: the Bank sample's account aggregate imported from the +/// v2 E2E BankAccount table, through dotnet sourceflow migrate v2 … inside the service and as the global +/// tool. +/// +public abstract class V2MigrationScenarios : IAsyncLifetime +{ + private readonly List _hosts = []; + + private static CancellationToken Ct => TestContext.Current.CancellationToken; + + public abstract Task EnsureStartedAsync(); + + protected abstract Task CreateV2Async(); + + protected abstract void UseV3Storage(SourceFlowBuilder sf, string schema); + + protected abstract string NewV3Schema(); + + public async ValueTask InitializeAsync() + { + await EnsureStartedAsync(); + } + + public async ValueTask DisposeAsync() + { + foreach (IHost host in _hosts) + { + await host.StopAsync(CancellationToken.None); + host.Dispose(); + } + + GC.SuppressFinalize(this); + } + + // ================================================================ plan (MIG-01..02) + + [Fact] + [Trait("Id", "MIG-01")] + [Trait("Id", "MIG-02")] + [Trait("Covers", "doc 12 3;GAP-04;GAP-20")] + public async Task Plan_CountsEntitiesAndCommands_ReportsLostHistory_AndGatesOnTablesWithoutAnImport() + { + V2Database v2 = await CreateV2Async(); + (IHost host, _) = await StartAsync(v2); + + // MIG-01: entities and commands per type; the order command of account 999 isn't counted for accounts. + V2Plan plan = await host.Services.GetRequiredService().PlanAsync(Ct); + plan.Commands.ShouldBe(V2Database.CommandCount); + V2PlanEntity accounts = plan.Entities.ShouldHaveSingleItem(); + accounts.ShouldBe(new V2PlanEntity("BankAccount", BankAccount.AggregateName, nameof(BankAccountImport), V2Database.Accounts.Count, V2Database.CommandCount - 2 - 1)); + plan.CommandTypes.Single(t => t.CommandType.Contains(".DepositMoney,", StringComparison.Ordinal)).Commands.ShouldBe(4); + plan.EstimatedDuration.ShouldBeGreaterThan(TimeSpan.Zero); + plan.Ready.ShouldBeTrue(); + + // MIG-02: GAP-20 (two creates logged under id 0) and GAP-04 (a type v2 couldn't rebuild, and an empty payload). + plan.EntityIdZero.ShouldBe(2); + plan.NotRebuildable.ShouldBe(2); + plan.CommandTypes.Single(t => t.CommandType == V2Database.ApplyInterest).NotRebuildable.ShouldBe(1); + (int code, string output, _) = await CliAsync(host, "migrate", "v2", "plan"); + code.ShouldBe(0); + output.ShouldContain("GAP-20, logged under entity id 0: 2; GAP-04, not rebuildable: 2"); + output.ShouldContain($"BankAccount -> bank-account (BankAccountImport): {V2Database.Accounts.Count} stream(s)"); + + // The global tool has no imports: every v2 table lacks one, so the plan fails the gate. + (int gate, string tool, string error) = await CliAsync(null, ["migrate", "v2", "plan", .. v2.ToolOptions]); + gate.ShouldBe(1); + tool.ShouldContain($"v2 commands: {V2Database.CommandCount}"); + error.ShouldContain("AccountViewModel"); + error.ShouldContain("BankAccount"); + } + + // ================================================================ scaffold (MIG-03) + + [Fact] + [Trait("Id", "MIG-03")] + [Trait("Covers", "doc 12 3")] + public async Task Scaffold_GeneratesTheRowType_AndAnImportStub_PerTable() + { + V2Database v2 = await CreateV2Async(); + (IHost host, _) = await StartAsync(v2); + + // In the service, the aggregate named like the table is filled in. + (int code, string output, _) = await CliAsync(host, "migrate", "v2", "scaffold", "--table", "BankAccount", "--namespace", "Legacy.Import"); + code.ShouldBe(0); + output.ShouldContain("namespace Legacy.Import;"); + output.ShouldContain("public sealed record V2BankAccount(int Id, DateTime CreatedOn, string? AccountName, decimal Balance, bool IsClosed, string? ClosureReason, DateTime ActiveOn) : IV2Entity"); + output.ShouldContain("public static string TableName => \"BankAccount\";"); + output.ShouldContain("row.Decimal(\"Balance\")"); + output.ShouldContain("row.Boolean(\"IsClosed\")"); + output.ShouldContain("public sealed class BankAccountImport : IV2Import"); + output.ShouldContain("return V2Ids.FromLegacy(entity.Id);"); + output.ShouldNotContain("#warning"); + + // The global tool scaffolds every table into files; without a model the stub names placeholders. + string directory = Path.Combine(Path.GetTempPath(), "sf-scaffold-" + Guid.CreateVersion7().ToString("N")); + try + { + (int written, _, _) = await CliAsync(null, ["migrate", "v2", "scaffold", "--output", directory, .. v2.ToolOptions]); + written.ShouldBe(0); + Directory.GetFiles(directory).Select(Path.GetFileName).Order().ShouldBe(["AccountViewModelImport.cs", "BankAccountImport.cs"]); + string stub = await File.ReadAllTextAsync(Path.Combine(directory, "AccountViewModelImport.cs"), Ct); + stub.ShouldContain("#warning No v3 aggregate is named like the v2 table 'AccountViewModel'"); + stub.ShouldContain("IV2Import"); + stub.ShouldContain("int TransactionCount"); + } + finally + { + if (Directory.Exists(directory)) + { + Directory.Delete(directory, recursive: true); + } + } + } + + // ================================================================ import (MIG-04..06) + + [Fact] + [Trait("Id", "MIG-04")] + [Trait("Id", "MIG-06")] + [Trait("Covers", "doc 12 3;ES-R2")] + public async Task Import_IsIdempotent_OneSessionPerStream_WithMigrationMetadata_AndProjectsInline() + { + V2Database v2 = await CreateV2Async(); + (IHost host, _) = await StartAsync(v2); + V2Migration migration = host.Services.GetRequiredService(); + + V2ImportResult first = await migration.ImportAsync(new V2ImportOptions { BatchSize = 7 }, Ct); + first.Complete.ShouldBeTrue(); + first.Imported.ShouldBe(V2Database.Accounts.Count); + first.Skipped.ShouldBe(0); + + // MIG-04: a second run appends nothing (ExpectedVersion.NoStream). + (int code, string output, _) = await CliAsync(host, "migrate", "v2", "import", "--batch", "5"); + code.ShouldBe(0); + output.ShouldContain($"Imported 0 stream(s); {V2Database.Accounts.Count} already existed."); + + // MIG-06: each stream holds its genesis events with the migration headers and deterministic ids. + SourceFlowRuntime runtime = host.Services.GetRequiredService(); + StreamId closed = StreamId.For(BankAccount.AggregateName, V2Ids.FromLegacy(999)); + StreamSlice events = await runtime.Storage.Events.ReadStreamAsync(runtime.Options.DefaultTenant, closed, new StreamVersion(1), 10, Ct); + events.Events.Select(e => e.Type).ShouldBe(["bank.account.opened", "bank.account.closed"]); + events.Events.Select(e => e.StreamVersion.Value).ShouldBe([1L, 2L]); + foreach (StoredEvent stored in events.Events) + { + stored.Metadata.Actor.ShouldBe(V2Migration.Actor); + stored.Metadata.Headers[V2Migration.MigratedFromHeader].ShouldBe("v2"); + stored.Metadata.Headers[V2Migration.CommandCountHeader].ShouldBe("6"); // the order command is another entity's + stored.Metadata.Headers[V2Migration.LastSequenceNoHeader].ShouldBe("6"); + stored.Metadata.Headers[V2Migration.V2IdHeader].ShouldBe("999"); + } + + StoredEvent ada = (await runtime.Storage.Events.ReadStreamAsync(runtime.Options.DefaultTenant, StreamId.For(BankAccount.AggregateName, V2Ids.FromLegacy(1001)), new StreamVersion(1), 10, Ct)).Events.ShouldHaveSingleItem(); + ada.Metadata.Headers[V2Migration.CommandCountHeader].ShouldBe("3"); + ada.EventId.ShouldBe(Messaging.MessageIds.FromKey("sourceflow-v2-import", runtime.Options.DefaultTenant + "\n" + ada.StreamId.Value + "\n1")); + + // Step 5: the inline summary is built from the imported events. + (await SummaryAsync(host, V2Ids.FromLegacy(999)))!.ShouldBe(new AccountSummary(V2Ids.FromLegacy(999), "John Doe", 1400m, AccountStatus.Closed, 2)); + (await SummaryAsync(host, V2Ids.FromLegacy(1001)))!.Balance.ShouldBe(520.5m); + + // An imported account takes v3 commands like any other. + ICommandSender commands = host.Services.GetRequiredService(); + (await commands.SendAsync(new Deposit(V2Ids.FromLegacy(1000), 50m), null, Ct)).Version.ShouldBe(new StreamVersion(2)); + } + + [Fact] + [Trait("Id", "MIG-05")] + [Trait("Covers", "doc 12 3")] + public async Task Import_ResumesAfterAnInterruption_AndAfterALimitedWave() + { + V2Database v2 = await CreateV2Async(); + var import = new BankAccountImport { FailOn = 2010 }; + (IHost host, _) = await StartAsync(v2, import); + V2Migration migration = host.Services.GetRequiredService(); + + // Interrupted at v2 account 2010: the 13 streams before it (999, 1000, 1001, 2000..2009) are committed. + await Should.ThrowAsync(async () => await migration.ImportAsync(new V2ImportOptions { BatchSize = 4 }, Ct)); + import.FailOn = null; + + // A limited wave continues from there... + V2ImportResult wave = await migration.ImportAsync(new V2ImportOptions { BatchSize = 4, Limit = 10 }, Ct); + wave.Complete.ShouldBeFalse(); + wave.Imported.ShouldBe(10); + wave.Skipped.ShouldBe(13); + + // ...and the next run finishes, repeating nothing. + (int code, string output, _) = await CliAsync(host, "migrate", "v2", "import"); + code.ShouldBe(0); + output.ShouldContain($"Imported {V2Database.Accounts.Count - 23} stream(s); 23 already existed."); + (await migration.VerifyAsync(cancellationToken: Ct)).Passed.ShouldBeTrue(); + } + + // ================================================================ archive (MIG-07) + + [Fact] + [Trait("Id", "MIG-07")] + [Trait("Covers", "doc 12 3")] + public async Task Archive_CopiesTheCommandTable_ToAReadOnlyAuditCopy() + { + V2Database v2 = await CreateV2Async(); + + (int code, string output, _) = await CliAsync(null, ["migrate", "v2", "archive", .. v2.ToolOptions]); + code.ShouldBe(0); + output.ShouldContain($"Archived {V2Database.CommandCount} command(s); {v2.ArchiveSchema}.commands holds {V2Database.CommandCount} of {V2Database.CommandCount}."); + + // Re-running copies only new rows. + await v2.ExecuteAsync($"INSERT INTO {v2.T("CommandRecord")} ({v2.Q("EntityId")}, {v2.Q("SequenceNo")}, {v2.Q("CommandName")}, {v2.Q("CommandType")}, {v2.Q("PayloadType")}, {v2.Q("PayloadData")}, {v2.Q("Metadata")}, {v2.Q("Timestamp")}, {v2.Q("CreatedAt")}, {v2.Q("UpdatedAt")}) " + + "VALUES (1000, 3, 'DepositMoney', 'x', 'y', '{}', '{}', '2025-02-01T00:00:00', '2025-02-01T00:00:00', '2025-02-01T00:00:00')"); + V2ArchiveResult again = await V2Migration.ForSource(v2.Source).ArchiveAsync(Ct); + again.ShouldBe(new V2ArchiveResult(1, V2Database.CommandCount + 1, V2Database.CommandCount + 1)); + + // Same columns and values as the source; updates and deletes are refused. + string archive = v2.Q(v2.ArchiveSchema) + "." + v2.Q("commands"); + (await v2.ScalarAsync($"SELECT COUNT(*) FROM {archive} a JOIN {v2.T("CommandRecord")} c ON c.{v2.Q("Id")} = a.{v2.Q("Id")} AND c.{v2.Q("CommandType")} = a.{v2.Q("CommandType")} AND c.{v2.Q("PayloadData")} = a.{v2.Q("PayloadData")} AND c.{v2.Q("SequenceNo")} = a.{v2.Q("SequenceNo")}")) + .ShouldBe(V2Database.CommandCount + 1); + await Should.ThrowAsync(async () => await v2.ExecuteAsync($"UPDATE {archive} SET {v2.Q("PayloadData")} = 'tampered'")); + await Should.ThrowAsync(async () => await v2.ExecuteAsync($"DELETE FROM {archive}")); + (await v2.ScalarAsync($"SELECT COUNT(*) FROM {archive} WHERE {v2.Q("PayloadData")} = 'tampered'")).ShouldBe(0); + } + + // ================================================================ verify (MIG-08..09) + + [Fact] + [Trait("Id", "MIG-08")] + [Trait("Id", "MIG-09")] + [Trait("Covers", "doc 12 3")] + public async Task Verify_PassesAfterTheImport_AndAMismatchReportFailsTheExitCode() + { + V2Database v2 = await CreateV2Async(); + (IHost host, _) = await StartAsync(v2); + await host.Services.GetRequiredService().ImportAsync(cancellationToken: Ct); + + // MIG-08: the rebuilt v3 state matches every v2 row. + (int code, string output, _) = await CliAsync(host, "migrate", "v2", "verify"); + code.ShouldBe(0); + output.ShouldContain($"Verified {V2Database.Accounts.Count} entities: no mismatches."); + + // MIG-09: v2 changed after the import (a write during the cut-over), and an account the import never saw. + await v2.ExecuteAsync($"UPDATE {v2.T("BankAccount")} SET {v2.Q("Balance")} = 275 WHERE {v2.Q("Id")} = 1000"); + await v2.ExecuteAsync($"INSERT INTO {v2.T("BankAccount")} VALUES (3000, '2025-03-01T00:00:00', 'Late Comer', 5, {(v2.Dialect == V2Dialect.SqlServer ? "0" : "false")}, NULL, '2025-03-01T00:00:00')"); + (int failed, string summary, string report) = await CliAsync(host, "migrate", "v2", "verify"); + failed.ShouldBe(1); + summary.ShouldContain($"Verified {V2Database.Accounts.Count + 1} entities: 2 mismatch(es)."); + report.ShouldContain("MISMATCH BankAccount 1000"); + report.ShouldContain("Balance: v2 275.00, v3 250.00"); + report.ShouldContain("MISMATCH BankAccount 3000"); + report.ShouldContain("not imported"); + } + + // ================================================================ plumbing + + private async Task<(IHost Host, string Schema)> StartAsync(V2Database v2, BankAccountImport? import = null) + { + string schema = NewV3Schema(); + HostApplicationBuilder builder = Host.CreateApplicationBuilder(new HostApplicationBuilderSettings { EnvironmentName = Environments.Development, DisableDefaults = true }); + builder.Services.AddSourceFlow(sf => + { + sf.ServiceName = "accounts"; + sf.AddModule(); + sf.Projections(p => p.Add().Inline()); + UseV3Storage(sf, schema); + sf.MigrateFromV2(m => m + .From(v2.Source) + .Import(import ?? new BankAccountImport()) + .Ignore("AccountViewModel") + .NotRebuildable("Legacy.Banking.ApplyInterest, Legacy.Banking")); + }); + IHost host = builder.Build(); + await host.StartAsync(Ct); + _hosts.Add(host); + return (host, schema); + } + + private static async Task<(int Code, string Output, string Error)> CliAsync(IHost? host, params string[] args) + { + using var output = new StringWriter(); + using var error = new StringWriter(); + int code = await SourceFlowCli.RunAsync(args, host?.Services, output, error, Ct); + return (code, output.ToString(), error.ToString()); + } + + private static async Task SummaryAsync(IHost host, AccountId id) + { + SourceFlowRuntime runtime = host.Services.GetRequiredService(); + ProjectionDescriptor projection = runtime.Model.Projections.Single(p => p.ProjectionType == typeof(AccountSummaryProjection)); + StoredDocument? stored = await runtime.Storage.Documents.GetAsync(runtime.Options.DefaultTenant, projection.Collection, id.ToStreamSegment(), Ct); + return stored is null ? null : (AccountSummary?)JsonSerializer.Deserialize(stored.Data.Span, runtime.Model.JsonTypeInfoFor(typeof(AccountSummary))); + } +} diff --git a/tests/Storage/SourceFlow.Storage.Tests/PersonalData/ClinicDomain.cs b/tests/Storage/SourceFlow.Storage.Tests/PersonalData/ClinicDomain.cs new file mode 100644 index 00000000..77279bc1 --- /dev/null +++ b/tests/Storage/SourceFlow.Storage.Tests/PersonalData/ClinicDomain.cs @@ -0,0 +1,92 @@ +using System.Text.Json.Serialization; + +namespace SourceFlow.Storage.Tests.PersonalData; + +// A small domain for crypto-shredding on real databases (doc 10 §4, E2E-29..31): a client belongs to a customer, the +// subject of its personal data. +[StronglyTypedId] +public readonly partial record struct ClientId(Guid Value); + +[MessageType("clinic.client.register", 1)] +public sealed record RegisterClient(ClientId ClientId, string Customer, string Name, decimal Balance) : ICommand; + +[MessageType("clinic.client.registered", 1)] +public sealed record ClientRegistered( + ClientId ClientId, + string Customer, + [property: PersonalData(Subject = nameof(ClientRegistered.Customer))] string Name, + decimal Balance) : IEvent; + +[Aggregate("clinic-client", SnapshotEvery = 1)] +public sealed partial record Client : IAggregate +{ + public static Client Initial { get; } = new(); + + public string Customer { get; init; } = string.Empty; + + [PersonalData(Subject = nameof(Customer))] + public string Name { get; init; } = string.Empty; + + public Decision Decide(RegisterClient c, DecisionContext ctx) + { + return Decision.Accept(new ClientRegistered(c.ClientId, c.Customer, c.Name, c.Balance)); + } + + private Client When(ClientRegistered e) + { + return this with { Customer = e.Customer, Name = e.Name }; + } +} + +public sealed record ClientCard(ClientId Id, string Customer, [property: PersonalData(Subject = nameof(ClientCard.Customer))] string Name, decimal Balance); + +// Hand-registered (no [Projection], no [SourceFlowModule]): this assembly's generated ReportingModule registers every +// annotated type, and must not get this projection. +public sealed class ClientCardsProjection : IDocumentProjectionRuntime +{ + private static readonly Type[] Handled = [typeof(ClientRegistered)]; + + public static string ProjectionName => "clinic-client-cards"; + + public static int ProjectionVersion => 1; + + public static IReadOnlyList HandledEvents => Handled; + + public static bool TryGetKey(IEvent @event, in EventContext context, out ClientId key) + { + key = @event is ClientRegistered e ? e.ClientId : default; + return @event is ClientRegistered; + } + + public static string FormatKey(ClientId key) + { + return key.ToStreamSegment(); + } + + public ClientCard? Apply(IEvent @event, ClientCard? current, in EventContext context) + { + return @event is ClientRegistered e ? new ClientCard(e.ClientId, e.Customer, e.Name, e.Balance) : current; + } +} + +public sealed class ClinicModule : ISourceFlowModule +{ + public static string ModuleName => "ClinicModule"; + + public static void Register(ISourceFlowModuleBuilder builder) + { + ArgumentNullException.ThrowIfNull(builder); + builder.AddJsonTypeInfoResolver(ClinicJsonContext.Default); + builder.AddMessage("clinic.client.register", 1); + builder.AddMessage("clinic.client.registered", 1); + builder.AddAggregate(); + builder.AddProjection(); + } +} + +[JsonSerializable(typeof(RegisterClient))] +[JsonSerializable(typeof(ClientRegistered))] +[JsonSerializable(typeof(Client))] +[JsonSerializable(typeof(ClientCard))] +[JsonSourceGenerationOptions(PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase)] +public sealed partial class ClinicJsonContext : JsonSerializerContext; diff --git a/tests/Storage/SourceFlow.Storage.Tests/PersonalData/PersonalDataStorageTests.cs b/tests/Storage/SourceFlow.Storage.Tests/PersonalData/PersonalDataStorageTests.cs new file mode 100644 index 00000000..71916531 --- /dev/null +++ b/tests/Storage/SourceFlow.Storage.Tests/PersonalData/PersonalDataStorageTests.cs @@ -0,0 +1,158 @@ +using System.Text; +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.Hosting; +using SourceFlow.Hosting; +using SourceFlow.Query; +using SourceFlow.Runtime; +using SourceFlow.Security; +using SourceFlow.Storage.PostgreSQL; +using SourceFlow.Storage.SqlServer; +using SourceFlow.Storage.Tests.PostgreSql; +using SourceFlow.Storage.Tests.SqlServer; +using SourceFlow.Testing.Conformance; + +namespace SourceFlow.Storage.Tests.PersonalData; + +/// +/// Crypto-shredding on PostgreSQL (doc 10 §4, WP-5.2): E2E-29 (erase → events read [erased]), E2E-30 (the document +/// is scrubbed and the snapshot deleted), E2E-31 (an SFQL filter on personal data is rejected), and the key store contract. +/// +[Collection(PostgreSqlCollection.Name)] +[Trait("Category", "EndToEnd")] +[Trait("Provider", "PostgreSQL")] +[Trait("Requires", "Docker")] +public sealed class PostgreSqlPersonalDataTests(PostgreSqlServer server) : PostgreSqlTest(server) +{ + private static CancellationToken Ct => TestContext.Current.CancellationToken; + + [Fact] + [Trait("Id", "UT-PII-19")] + [Trait("Covers", "doc 10 4")] + public async Task KeyStore_Conformance() + { + PostgreSqlStore store = await Server.CreateStoreAsync(); + await PersonalDataKeyStoreConformance.RunAsync(store, TimeProvider.System.GetUtcNow(), Ct); + } + + [Fact] + [Trait("Id", "E2E-29")] + [Trait("Id", "E2E-30")] + [Trait("Id", "E2E-31")] + [Trait("Covers", "doc 10 4;doc 14 8")] + public async Task Erase_OnPostgreSql_EventsReadErased_DocumentScrubbed_SnapshotDeleted_PiiFiltersRejected() + { + using var keys = new LocalKeyProvider(); + string schema = PostgreSqlServer.NewSchema("pii"); + using IHost host = await PersonalDataScenario.StartAsync(keys, sf => sf.UsePostgreSql(o => + { + o.DataSource = Server.DataSource; + o.Schema = schema; + })); + await PersonalDataScenario.RunAsync(host); + } +} + +/// The same scenario and key store contract on SQL Server (WP-5.2). +[Collection(SqlServerCollection.Name)] +[Trait("Category", "EndToEnd")] +[Trait("Provider", "SqlServer")] +[Trait("Requires", "Docker")] +public sealed class SqlServerPersonalDataTests(SqlServerServer server) : SqlServerTest(server) +{ + private static CancellationToken Ct => TestContext.Current.CancellationToken; + + [Fact] + [Trait("Id", "UT-PII-20")] + [Trait("Covers", "doc 10 4")] + public async Task KeyStore_Conformance() + { + SqlServerStore store = await Server.CreateStoreAsync(); + await PersonalDataKeyStoreConformance.RunAsync(store, TimeProvider.System.GetUtcNow(), Ct); + } + + [Fact] + [Trait("Id", "E2E-29")] + [Trait("Covers", "doc 10 4")] + public async Task Erase_OnSqlServer() + { + using var keys = new LocalKeyProvider(); + string schema = SqlServerServer.NewSchema("pii"); + using IHost host = await PersonalDataScenario.StartAsync(keys, sf => sf.UseSqlServer(Server.ConnectionString, o => o.Schema = schema)); + await PersonalDataScenario.RunAsync(host); + } +} + +internal static class PersonalDataScenario +{ + private static CancellationToken Ct => TestContext.Current.CancellationToken; + + public static async Task StartAsync(LocalKeyProvider keys, Action storage) + { + HostApplicationBuilder builder = Host.CreateApplicationBuilder(new HostApplicationBuilderSettings { EnvironmentName = Environments.Development, DisableDefaults = true }); + builder.Services.AddSourceFlow(sf => + { + sf.ServiceName = "clinic"; + sf.AddModule(); + sf.Projections(p => p.Add().Inline()); + sf.Security(s => s.UseKeyProvider(keys).EncryptPersonalData()); + storage(sf); + sf.UseInMemoryTransport(); + }); + IHost host = builder.Build(); + await host.StartAsync(Ct); + return host; + } + + public static async Task RunAsync(IHost host) + { + SourceFlowRuntime runtime = host.Services.GetRequiredService(); + ICommandSender commands = host.Services.GetRequiredService(); + var erased = ClientId.New(); + var kept = ClientId.New(); + await commands.SendAsync(new RegisterClient(erased, "cust-erase", "Ada Lovelace", 10m), null, Ct); + await commands.SendAsync(new RegisterClient(kept, "cust-keep", "Grace Hopper", 20m), null, Ct); + StreamId stream = StreamId.For(Client.AggregateName, erased); + + // At rest, the name is ciphertext. + StoredEvent raw = (await runtime.Storage.Events.ReadStreamAsync("-", stream, new StreamVersion(1), 1, Ct)).Events[0]; + Encoding.UTF8.GetString(raw.Data.Span).ShouldNotContain("Lovelace"); + await EventuallyAsync(async () => await runtime.Storage.Snapshots.GetAsync("-", stream, Ct) is not null, "the snapshot (SnapshotEvery = 1)"); + + ErasureResult result = await host.Services.GetRequiredService().EraseSubjectAsync("cust-erase", cancellationToken: Ct); + + // E2E-29: events read [erased]; the other subject is untouched. + result.Streams.ShouldBe(1); + IAggregateReader reader = host.Services.GetRequiredService(); + (await reader.LoadAsync(erased, cancellationToken: Ct)).State.Name.ShouldBe(PersonalDataProtector.Erased); + (await reader.LoadAsync(kept, cancellationToken: Ct)).State.Name.ShouldBe("Grace Hopper"); + + // E2E-30: the document is scrubbed, the snapshot deleted. + ProjectionDescriptor projection = runtime.Model.Projections.Single(p => p.ProjectionType == typeof(ClientCardsProjection)); + StoredDocument card = (await runtime.Storage.Documents.GetAsync("-", projection.Collection, erased.ToStreamSegment(), Ct))!; + Encoding.UTF8.GetString(card.Data.Span).ShouldContain("\"name\":\"[erased]\""); + Encoding.UTF8.GetString(card.Data.Span).ShouldContain("\"balance\":10"); + (await runtime.Storage.Snapshots.GetAsync("-", stream, Ct)).ShouldBeNull(); + result.DocumentsScrubbed.ShouldBe(1); + + // E2E-31: SFQL rejects filters on personal data. + QueryException rejected = await Should.ThrowAsync(async () => + await host.Services.GetRequiredService().QueryPageAsync("from readmodel \"clinic-client-cards\" | where name = 'Ada Lovelace'", cancellationToken: Ct)); + rejected.Code.ShouldBe("SFQ0301"); + + await host.StopAsync(Ct); + } + + private static async Task EventuallyAsync(Func> condition, string what) + { + DateTimeOffset deadline = TimeProvider.System.GetUtcNow() + TimeSpan.FromSeconds(20); + while (!await condition()) + { + if (TimeProvider.System.GetUtcNow() > deadline) + { + throw new TimeoutException($"Timed out waiting for: {what}."); + } + + await Task.Delay(TimeSpan.FromMilliseconds(50), TimeProvider.System, Ct); + } + } +} diff --git a/tests/Storage/SourceFlow.Storage.Tests/PostgreSql/PostgreSqlBankTests.cs b/tests/Storage/SourceFlow.Storage.Tests/PostgreSql/PostgreSqlBankTests.cs new file mode 100644 index 00000000..75370597 --- /dev/null +++ b/tests/Storage/SourceFlow.Storage.Tests/PostgreSql/PostgreSqlBankTests.cs @@ -0,0 +1,248 @@ +using System.Text.Json; +using Bank.Accounts; +using Bank.Contracts; +using Bank.Transfers; +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.Hosting; +using SourceFlow.Hosting; +using SourceFlow.Messaging; +using SourceFlow.Runtime; +using SourceFlow.Storage.PostgreSQL; + +namespace SourceFlow.Storage.Tests.PostgreSql; + +/// +/// The Bank sample on PostgreSQL with the real clock (plan 06 §4, PostgreSQL leg): commands, inline and async +/// projections, the outbox relay, the transfer process manager, subscriptions with fenced checkpoints, and +/// re-decide on real conflicts. +/// +[Collection(PostgreSqlCollection.Name)] +[Trait("Category", "EndToEnd")] +[Trait("Provider", "PostgreSQL")] +[Trait("Requires", "Docker")] +public sealed class PostgreSqlBankTests(PostgreSqlServer server) : PostgreSqlTest(server) +{ + private static readonly TimeSpan Patience = TimeSpan.FromSeconds(30); + + private static CancellationToken Ct => TestContext.Current.CancellationToken; + + [Fact] + [Trait("Id", "E2E-01")] + [Trait("Covers", "ADR-002;ADR-009")] + public async Task AccountLifecycle_InlineSummary() + { + using IHost host = await StartAsync(inlineSummary: true); + ICommandSender commands = host.Services.GetRequiredService(); + AccountId id = AccountId.New(); + + (await commands.SendAsync(new OpenAccount(id, "Ada", 100m), null, Ct)).Status.ShouldBe(CommandStatus.Accepted); + (await commands.SendAsync(new Deposit(id, 50m), null, Ct)).Version.ShouldBe(new StreamVersion(2)); + (await commands.SendAsync(new Withdraw(id, 30m), null, Ct)).Version.ShouldBe(new StreamVersion(3)); + CommandResult rejected = await commands.SendAsync(new Withdraw(id, 1000m), null, Ct); + + rejected.Status.ShouldBe(CommandStatus.Rejected); + (await SummaryAsync(host, id))!.ShouldBe(new AccountSummary(id, "Ada", 120m, AccountStatus.Open, 3)); + } + + [Fact] + [Trait("Id", "E2E-03")] + [Trait("Covers", "ADR-006")] + public async Task IdempotencyKey_IsDeduplicatedByTheInbox() + { + using IHost host = await StartAsync(inlineSummary: true); + ICommandSender commands = host.Services.GetRequiredService(); + AccountId id = AccountId.New(); + await commands.SendAsync(new OpenAccount(id, "Ada", 1m), null, Ct); + var options = new SendOptions { IdempotencyKey = "pg-deposit-1" }; + + CommandResult first = await commands.SendAsync(new Deposit(id, 5m), options, Ct); + CommandResult second = await commands.SendAsync(new Deposit(id, 5m), options, Ct); + + second.Status.ShouldBe(CommandStatus.Duplicate); + second.Version.ShouldBe(first.Version); + (await SummaryAsync(host, id))!.Balance.ShouldBe(6m); + } + + [Fact] + [Trait("Id", "E2E-04")] + [Trait("Covers", "ADR-008;GAP-05")] + public async Task ParallelDeposits_ReDecideOnRealConflicts() + { + using IHost host = await StartAsync(inlineSummary: true, configure: sf => sf.Configure(o => o.MaxConcurrencyRetries = 50)); + ICommandSender commands = host.Services.GetRequiredService(); + AccountId id = AccountId.New(); + await commands.SendAsync(new OpenAccount(id, "Ada", 0.01m), null, Ct); + + CommandResult[] results = await Task.WhenAll(Enumerable.Range(0, 20) + .Select(_ => Task.Run(async () => await commands.SendAsync(new Deposit(id, 1m), null, Ct)))); + + results.ShouldAllBe(r => r.Status == CommandStatus.Accepted); + results.Select(r => r.Version.Value).Distinct().Count().ShouldBe(20); + (await SummaryAsync(host, id))!.Balance.ShouldBe(20.01m); + } + + [Theory] + [Trait("Id", "UT-SNAP-06")] + [Trait("Covers", "doc 05 8.2")] + [InlineData(AggregateCacheMode.ReadTail)] + [InlineData(AggregateCacheMode.Optimistic)] + public async Task ParallelDeposits_WithTheAggregateCache_StayExact(AggregateCacheMode mode) + { + using IHost host = await StartAsync(inlineSummary: true, configure: sf => sf.Configure(o => + { + o.MaxConcurrencyRetries = 50; + o.AggregateCache = mode; + })); + ICommandSender commands = host.Services.GetRequiredService(); + AccountId id = AccountId.New(); + await commands.SendAsync(new OpenAccount(id, "Ada", 1m), null, Ct); + + CommandResult[] results = await Task.WhenAll(Enumerable.Range(0, 20) + .Select(_ => Task.Run(async () => await commands.SendAsync(new Deposit(id, 1m), null, Ct)))); + CommandResult tooMuch = await commands.SendAsync(new Withdraw(id, 22m), null, Ct); + CommandResult exact = await commands.SendAsync(new Withdraw(id, 21m), null, Ct); + + results.ShouldAllBe(r => r.Status == CommandStatus.Accepted); + tooMuch.Status.ShouldBe(CommandStatus.Rejected); + exact.Status.ShouldBe(CommandStatus.Accepted); + (await SummaryAsync(host, id))!.Balance.ShouldBe(0m); + } + + [Fact] + [Trait("Id", "E2E-06")] + [Trait("Covers", "ADR-010;ADR-016")] + public async Task AsyncProjection_CatchesUpThroughFencedCheckpoints() + { + using IHost host = await StartAsync(inlineSummary: false, configure: sf => sf.Configure(o => o.SubscriptionPartitions = 4)); + ICommandSender commands = host.Services.GetRequiredService(); + AccountId[] ids = [.. Enumerable.Range(0, 8).Select(_ => AccountId.New())]; + foreach (AccountId id in ids) + { + await commands.SendAsync(new OpenAccount(id, "Ada", 10m), null, Ct); + await commands.SendAsync(new Deposit(id, 5m), null, Ct); + } + + foreach (AccountId id in ids) + { + await EventuallyAsync(async () => (await SummaryAsync(host, id))?.Balance == 15m, $"summary of {id}"); + } + } + + [Fact] + [Trait("Id", "E2E-13")] + [Trait("Covers", "ADR-006;ADR-020")] + public async Task MoneyTransfer_ProcessManagerCompletesThroughTheOutbox() + { + using IHost host = await StartAsync(inlineSummary: true); + ICommandSender commands = host.Services.GetRequiredService(); + AccountId from = AccountId.New(); + AccountId to = AccountId.New(); + await commands.SendAsync(new OpenAccount(from, "Ada", 100m), null, Ct); + await commands.SendAsync(new OpenAccount(to, "Grace", 0.5m), null, Ct); + + var transfer = TransferId.New(); + (await commands.SendAsync(new RequestTransfer(transfer, from, to, 40m), null, Ct)).Status.ShouldBe(CommandStatus.Accepted); + + await EventuallyAsync(async () => (await SummaryAsync(host, from))?.Balance == 60m && (await SummaryAsync(host, to))?.Balance == 40.5m, "transfer applied"); + PostgreSqlStore store = host.Services.GetRequiredService(); + // The process manager completes the transfer after the deposit; wait for that before looking at the outbox. + await EventuallyAsync(async () => (await store.ReadStreamAsync(MessageEnvelope.DefaultTenant, StreamId.For(Transfer.AggregateName, transfer), new StreamVersion(1), 10, Ct)) + .Events.Any(e => e.Type == "bank.transfer.completed"), "transfer completed"); + // The process manager's timeout stays scheduled in the outbox until it is due; nothing else is left. + await EventuallyAsync(async () => await store.DueOutboxCountAsync(Ct) == 0, "due outbox drained"); + (await store.CountAsync(Ct)).ShouldBe(1); + } + + [Fact] + [Trait("Id", "E2E-13")] + [Trait("Covers", "ADR-022")] + public async Task MoneyTransfer_UnderRowLevelSecurity_WithAnAsyncProjection() + { + using IHost host = await StartAsync(inlineSummary: false, rowLevelSecurity: true); + ICommandSender commands = host.Services.GetRequiredService(); + AccountId from = AccountId.New(); + AccountId to = AccountId.New(); + await commands.SendAsync(new OpenAccount(from, "Ada", 100m), null, Ct); + (await commands.SendAsync(new OpenAccount(to, "Grace", 1m), null, Ct)).Status.ShouldBe(CommandStatus.Accepted); + + (await commands.SendAsync(new RequestTransfer(TransferId.New(), from, to, 25m), null, Ct)).Status.ShouldBe(CommandStatus.Accepted); + + await EventuallyAsync(async () => (await SummaryAsync(host, from))?.Balance == 75m && (await SummaryAsync(host, to))?.Balance == 26m, "transfer applied under RLS"); + } + + private async Task StartAsync(bool inlineSummary, Action? configure = null, bool rowLevelSecurity = false) + { + string schema = PostgreSqlServer.NewSchema(); + if (rowLevelSecurity) + { + // The owner migrates; the host runs as the DML-only application role and only verifies the schema. + await new PostgreSqlSchemaMigrator(Server.DataSource, schema, TenantIsolation.RowLevelSecurity).MigrateAsync(Ct); + await Server.GrantAsync(schema); + } + + HostApplicationBuilder builder = Host.CreateApplicationBuilder(new HostApplicationBuilderSettings { EnvironmentName = Environments.Development, DisableDefaults = true }); + builder.Services.AddSourceFlow(sf => + { + sf.ServiceName = "accounts"; + sf.AddModule(); + sf.AddModule(); + sf.AddModule(); + sf.Projections(p => + { + ProjectionModeBuilder summary = p.Add(); + if (inlineSummary) + { + summary.Inline(); + } + else + { + summary.Async(); + } + }); + sf.UsePostgreSql(o => + { + o.Schema = schema; + if (rowLevelSecurity) + { + PostgreSqlStorageOptions rls = Server.RowLevelSecurityOptions(schema); + o.ConnectionString = rls.ConnectionString; + o.SystemConnectionString = rls.SystemConnectionString; + o.TenantIsolation = TenantIsolation.RowLevelSecurity; + o.AutoMigrate = false; + } + else + { + o.DataSource = Server.DataSource; + } + }); + sf.UseInMemoryTransport(); + configure?.Invoke(sf); + }); + IHost host = builder.Build(); + await host.StartAsync(Ct); + return host; + } + + private static async Task SummaryAsync(IHost host, AccountId id) + { + RuntimeModel model = host.Services.GetRequiredService(); + ProjectionDescriptor projection = model.Projections.Single(p => p.ProjectionType == typeof(AccountSummaryProjection)); + StoredDocument? stored = await host.Services.GetRequiredService() + .ToPorts().Documents.GetAsync(Messaging.MessageEnvelope.DefaultTenant, projection.Collection, id.ToStreamSegment(), Ct); + return stored is null ? null : (AccountSummary?)JsonSerializer.Deserialize(stored.Data.Span, model.JsonTypeInfoFor(typeof(AccountSummary))); + } + + private static async Task EventuallyAsync(Func> condition, string what) + { + DateTimeOffset deadline = TimeProvider.System.GetUtcNow() + Patience; + while (!await condition()) + { + if (TimeProvider.System.GetUtcNow() > deadline) + { + throw new TimeoutException($"Timed out waiting for: {what}."); + } + + await RealClock.WaitAsync(TimeSpan.FromMilliseconds(50)); + } + } +} diff --git a/tests/Storage/SourceFlow.Storage.Tests/PostgreSql/PostgreSqlCliTests.cs b/tests/Storage/SourceFlow.Storage.Tests/PostgreSql/PostgreSqlCliTests.cs new file mode 100644 index 00000000..012fd540 --- /dev/null +++ b/tests/Storage/SourceFlow.Storage.Tests/PostgreSql/PostgreSqlCliTests.cs @@ -0,0 +1,333 @@ +using Bank.Accounts; +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.Hosting; +using SourceFlow.Hosting; +using SourceFlow.Messaging; +using SourceFlow.Runtime; +using SourceFlow.Storage.PostgreSQL; +using SourceFlow.Tool; +using SourceFlow.Workflows; + +namespace SourceFlow.Storage.Tests.PostgreSql; + +/// E2E-25..28 (plan 06): dotnet sourceflow against PostgreSQL, as the global tool and inside a service. +[Collection(PostgreSqlCollection.Name)] +[Trait("Category", "EndToEnd")] +[Trait("Provider", "PostgreSQL")] +[Trait("Requires", "Docker")] +public sealed class PostgreSqlCliTests(PostgreSqlServer server) : PostgreSqlTest(server) +{ + private static CancellationToken Ct => TestContext.Current.CancellationToken; + + [Fact] + [Trait("Id", "E2E-25")] + [Trait("Covers", "doc 04 9.3")] + public async Task GlobalTool_MigratesTheSchema_AndReplaysADeadLetterThroughTheOutbox() + { + string schema = PostgreSqlServer.NewSchema("cli"); + (int migrated, string first, _) = await RunAsync(null, "db", "migrate", "--connection", Server.ConnectionString, "--schema", schema); + (int again, string second, _) = await RunAsync(null, "db", "migrate", "--connection", Server.ConnectionString, "--schema", schema); + + migrated.ShouldBe(0); + first.ShouldContain("Applied V001"); + again.ShouldBe(0); + second.ShouldContain("up to date"); + + await using var store = new PostgreSqlStore(new PostgreSqlStorageOptions { DataSource = Server.DataSource, Schema = schema }); + var envelope = new MessageEnvelope + { + MessageId = MessageIds.New(TimeProvider.System), + Type = "bank.account.open", + TypeVersion = 1, + Source = "accounts", + Time = TimeProvider.System.GetUtcNow(), + Body = "{}"u8.ToArray(), + }; + var id = Guid.CreateVersion7(); + await store.ParkAsync(new DeadLetter + { + Id = id, + Consumer = "accounts", + Source = "receive", + Envelope = envelope, + Destination = "accounts", + Reason = "PermanentFailure", + FirstFailedAt = envelope.Time, + ParkedAt = envelope.Time, + }, Ct); + + (int listed, string list, _) = await RunAsync(null, "dlq", "list", "--connection", Server.ConnectionString, "--schema", schema); + (int replayed, _, _) = await RunAsync(null, "dlq", "replay", id.ToString(), "--connection", Server.ConnectionString, "--schema", schema, "--note", "fixed"); + + listed.ShouldBe(0); + list.ShouldContain(id.ToString()); + replayed.ShouldBe(0); + (await store.GetAsync(id, Ct))!.Status.ShouldBe(DeadLetterStatus.Replayed); + (await store.DueOutboxCountAsync(Ct)).ShouldBe(1); // the service's relay sends it + } + + [Fact] + [Trait("Id", "E2E-26")] + [Trait("Covers", "doc 06 6")] + public async Task GlobalTool_RebuildsAProjectionInPlace_TheServiceReplaysIt() + { + string schema = PostgreSqlServer.NewSchema("cli"); + var id = AccountId.New(); + using (IHost running = await StartAsync(schema)) + { + await running.Services.GetRequiredService().SendAsync(new OpenAccount(id, "Ada", 5m), null, Ct); + await EventuallyAsync(running, id, exists: true); + await running.StopAsync(Ct); // releases the subscription leases + } + + (int rebuilt, string output, _) = await RunAsync(null, "projection", "rebuild", "account-summary@1", "--in-place", "--connection", Server.ConnectionString, "--schema", schema); + + rebuilt.ShouldBe(0); + output.ShouldContain("dropped 1 document(s)"); + using IHost restarted = await StartAsync(schema); + await EventuallyAsync(restarted, id, exists: true); + } + + [Fact] + [Trait("Id", "E2E-08")] + [Trait("Id", "E2E-26")] + [Trait("Covers", "doc 06 6;ADR-032")] + public async Task GlobalTool_RebuildsBlueGreen_WhileTheServiceRuns_AndQueriesFollowTheAlias() + { + string schema = PostgreSqlServer.NewSchema("cli"); + var ada = AccountId.New(); + using IHost host = await StartAsync(schema); + await host.Services.GetRequiredService().SendAsync(new OpenAccount(ada, "Ada", 5m), null, Ct); + await EventuallyAsync(host, ada, exists: true); + PostgreSqlStore store = host.Services.GetRequiredService(); + await AliasAsync(store, "account-summary@1"); + + (int rebuilt, string output, _) = await RunAsync(null, "projection", "rebuild", "account-summary@1", "--connection", Server.ConnectionString, "--schema", schema); + rebuilt.ShouldBe(0); + output.ShouldContain("building account-summary@1.2 beside account-summary@1"); + await AliasAsync(store, "account-summary@1.2"); + + // The service's queries now read the rebuilt generation (the compiler binds the collection as a parameter). + (await ((IDocumentReader)store).GetAsync(MessageEnvelope.DefaultTenant, "account-summary@1.2", ada.ToStreamSegment(), Ct)).ShouldNotBeNull(); + await store.DropCollectionAsync("account-summary@1", Ct); // what the retention would do later + Query.QueryPage page = await host.Services.GetRequiredService() + .QueryPageAsync("from readmodel \"account-summary\" | where holder = @h | project holder, balance", new Dictionary { ["h"] = "Ada" }, cancellationToken: Ct); + page.Rows.ShouldHaveSingleItem()["balance"].ShouldBe(5m); + (int listed, string generations, _) = await RunAsync(null, "projection", "generations", "--connection", Server.ConnectionString, "--schema", schema); + listed.ShouldBe(0); + generations.ShouldContain("account-summary serving account-summary@1.2 building - previous account-summary@1"); + } + + [Fact] + [Trait("Id", "E2E-27")] + [Trait("Id", "E2E-28")] + [Trait("Covers", "doc 07;doc 14 7.3")] + public async Task InsideTheService_TopologyValidates_AndExplainShowsTheParameterisedSql() + { + using IHost host = await StartAsync(PostgreSqlServer.NewSchema("cli")); + + (int valid, string validated, _) = await RunAsync(host.Services, "topology", "validate"); + (int explained, string plan, _) = await RunAsync(host.Services, "query", "from readmodel \"account-summary\" | where holder = @h", "--param", "h=Ada", "--explain"); + + valid.ShouldBe(0); + validated.ShouldContain("in place"); + explained.ShouldBe(0); + plan.ShouldContain("engine: postgresql"); + plan.ShouldContain("$1::text"); + plan.ShouldNotContain("Ada"); // values are parameters, never in the statement (I-3) + } + + [Fact] + [Trait("Id", "E2E-25")] + [Trait("Covers", "ADR-022")] + public async Task InsideTheService_DbMigrate_KeepsTheServicesTenantIsolation() + { + string schema = PostgreSqlServer.NewSchema("cli"); + await new PostgreSqlSchemaMigrator(Server.DataSource, schema, TenantIsolation.RowLevelSecurity).MigrateAsync(Ct); + using (IHost rls = await StartAsync(schema, TenantIsolation.RowLevelSecurity)) + { + (int migrated, string output, string error) = await RunAsync(rls.Services, "db", "migrate"); // no --rls + + migrated.ShouldBe(0, error); + output.ShouldContain("up to date"); + } + + // The policies are still in place: the schema verifies as row-level security, not as runtime isolation. + await new PostgreSqlSchemaMigrator(Server.DataSource, schema, TenantIsolation.RowLevelSecurity).VerifyAsync(Ct); + await Should.ThrowAsync(() => new PostgreSqlSchemaMigrator(Server.DataSource, schema, TenantIsolation.Runtime).VerifyAsync(Ct)); + + using IHost runtime = await StartAsync(PostgreSqlServer.NewSchema("cli")); + (int refused, _, string conflict) = await RunAsync(runtime.Services, "db", "migrate", "--rls"); + refused.ShouldBe(1); + conflict.ShouldContain("--rls conflicts"); + } + + [Fact] + [Trait("Id", "E2E-25")] + [Trait("Covers", "doc 06 3;doc 15 5.6")] + public async Task GlobalTool_SkipsAStoppedSubscriptionsEvent_AndSendsWorkflowControlThroughTheOutbox() + { + string schema = PostgreSqlServer.NewSchema("cli"); + string[] target = ["--connection", Server.ConnectionString, "--schema", schema]; + using (IHost host = await StartAsync(schema)) + { + var id = AccountId.New(); + await host.Services.GetRequiredService().SendAsync(new OpenAccount(id, "Ada", 5m), null, Ct); + await EventuallyAsync(host, id, exists: true); + await host.StopAsync(Ct); + } + + // A subscription no service runs starts at the beginning of the log: the tool skips its next event, then the + // one after, until the partition has none left. + const string Stopped = "projection:archive@1"; + (int skipped, string skip, string skipError) = await RunAsync(null, ["projection", "skip", Stopped, "--reason", "bad data", .. target]); + skipped.ShouldBe(0, skipError); + skip.ShouldContain("Skipped the event at"); + string error = string.Empty; + for (int i = 0; i < 20 && !error.Contains("no event to skip", StringComparison.Ordinal); i++) + { + (_, _, error) = await RunAsync(null, ["projection", "skip", Stopped, "--reason", "drain", .. target]); + } + + error.ShouldContain("The partition has no event to skip."); + (int listed, string discarded, _) = await RunAsync(null, ["dlq", "list", "--status", "discarded", "--consumer", Stopped, .. target]); + listed.ShouldBe(0); + discarded.ShouldContain("Skipped"); + + // An instance in manual intervention: without the service, the control message goes to the owner's endpoint + // through the outbox, which the service's relay sends. + await using var store = new PostgreSqlStore(new PostgreSqlStorageOptions { DataSource = Server.DataSource, Schema = schema }); + DateTimeOffset now = TimeProvider.System.GetUtcNow(); + var summary = new WorkflowInstanceSummary("trip-booking", 1, "booking-1", nameof(WorkflowStatus.ManualIntervention), "confirm-reservation", 1, + "hotels.hold_lost", "The hold expired.", "confirm-reservation", 1, now, now); + await using (IStorageSession session = await store.BeginAsync(MessageEnvelope.DefaultTenant, Ct)) + { + session.Documents.Upsert(WorkflowInstanceSummary.Collection, WorkflowInstanceSummary.DocumentId(summary.ProcessName, summary.Instance), 1, WorkflowRuntime.SerializeSummary(summary)); + await session.CommitAsync(Ct); + } + + (int noEndpoint, _, string endpointError) = await RunAsync(null, ["workflow", "resume", "trip-booking@1", "booking-1", .. target]); + (int resumed, string sent, string resumeError) = await RunAsync(null, ["workflow", "resume", "trip-booking@1", "booking-1", "--endpoint", "bookings", "--note", "rebooked", .. target]); + + noEndpoint.ShouldBe(1); + endpointError.ShouldContain("--endpoint"); + resumed.ShouldBe(0, resumeError); + sent.ShouldContain("Sent resume to trip-booking@1 booking-1"); + (await store.DueOutboxCountAsync(Ct)).ShouldBe(1); + } + + [Fact] + [Trait("Id", "E2E-27")] + [Trait("Covers", "doc 14 7.2;doc 05 9")] + public async Task InsideTheService_IndexSyncPlansThenApplies_AndPartitionCommandsNeedAPartitionedTable() + { + using IHost host = await StartAsync(PostgreSqlServer.NewSchema("cli")); + + (int planned, string plan, _) = await RunAsync(host.Services, "db", "index", "sync"); + (int applied, string apply, string applyError) = await RunAsync(host.Services, "db", "index", "sync", "--apply"); + (int again, string inSync, _) = await RunAsync(host.Services, "db", "index", "sync"); + (int partitions, _, string notPartitioned) = await RunAsync(host.Services, "db", "partitions", "list"); + + planned.ShouldBe(0); + plan.ShouldContain("create "); + applied.ShouldBe(0, applyError); + apply.ShouldContain("created "); + again.ShouldBe(0); + inSync.ShouldNotContain("create"); + inSync.ShouldNotContain("0 unchanged"); + partitions.ShouldBe(1); + notPartitioned.ShouldContain("not partitioned"); + } + + private async Task StartAsync(string schema, TenantIsolation isolation = TenantIsolation.Runtime) + { + HostApplicationBuilder builder = Host.CreateApplicationBuilder(new HostApplicationBuilderSettings { EnvironmentName = Environments.Development, DisableDefaults = true }); + builder.Services.AddSourceFlow(sf => + { + sf.ServiceName = "accounts"; + sf.AddModule(); + sf.AddModule(); + sf.Projections(p => p.Add().Async()); + sf.Configure(o => o.PollInterval = TimeSpan.FromMilliseconds(50)); + sf.UsePostgreSql(o => + { + o.DataSource = Server.DataSource; + o.Schema = schema; + o.TenantIsolation = isolation; + if (isolation == TenantIsolation.RowLevelSecurity) + { + o.SystemDataSource = Server.DataSource; + } + }); + sf.UseInMemoryTransport(); + }); + IHost host = builder.Build(); + await host.StartAsync(Ct); + return host; + } + + private static async Task AliasAsync(PostgreSqlStore store, string target) + { + for (int i = 0; i < 300; i++) + { + if ((await store.ListAliasesAsync(Ct)).Any(a => a.Alias == "account-summary" && a.Target == target)) + { + return; + } + + await RealClock.WaitAsync(TimeSpan.FromMilliseconds(50)); + } + + throw new TimeoutException($"account-summary did not switch to {target}."); + } + + private static async Task EventuallyAsync(IHost host, AccountId id, bool exists) + { + IDocumentReader reader = host.Services.GetRequiredService(); + for (int i = 0; i < 300; i++) + { + if ((await reader.GetAsync(MessageEnvelope.DefaultTenant, "account-summary@1", id.ToStreamSegment(), Ct) is not null) == exists) + { + return; + } + + await RealClock.WaitAsync(TimeSpan.FromMilliseconds(50)); + } + + throw new TimeoutException("The account summary didn't appear."); + } + + [Fact] + [Trait("Id", "SCK-67")] + [Trait("Covers", "doc 05 9")] + public async Task GlobalTool_PartitionsTheEventsTable_AndManagesPartitions() + { + string schema = PostgreSqlServer.NewSchema("cli"); + string[] target = ["--connection", Server.ConnectionString, "--schema", schema]; + + (int migrated, _, _) = await RunAsync(null, ["db", "migrate", "--partition-events", .. target]); + (int listed, string list, _) = await RunAsync(null, ["db", "partitions", "list", .. target]); + (int ensured, string ensure, _) = await RunAsync(null, ["db", "partitions", "ensure", .. target]); + (int refused, _, string error) = await RunAsync(null, ["db", "partitions", "detach", "events_initial", .. target]); + (int scripted, string script, _) = await RunAsync(null, "db", "script", "--schema", "sales", "--partition-events"); + + migrated.ShouldBe(0); + listed.ShouldBe(0); + list.ShouldContain("events_initial (start)"); + list.Split('\n', StringSplitOptions.RemoveEmptyEntries).Length.ShouldBe(1 + PostgreSqlPartitioning.MigratorMonthsAhead); + ensured.ShouldBe(0); + ensure.ShouldContain("Created 0 partition(s)."); + refused.ShouldBe(1); + error.ShouldContain("not in the past"); + scripted.ShouldBe(0); + script.ShouldContain("PARTITION BY RANGE (created_at)"); + } + + private static async Task<(int Code, string Output, string Error)> RunAsync(IServiceProvider? services, params string[] args) + { + using var output = new StringWriter(); + using var error = new StringWriter(); + int code = await SourceFlowCli.RunAsync(args, services, output, error, Ct); + return (code, output.ToString(), error.ToString()); + } +} diff --git a/tests/Storage/SourceFlow.Storage.Tests/PostgreSql/PostgreSqlGrantsTests.cs b/tests/Storage/SourceFlow.Storage.Tests/PostgreSql/PostgreSqlGrantsTests.cs new file mode 100644 index 00000000..b9ad46a4 --- /dev/null +++ b/tests/Storage/SourceFlow.Storage.Tests/PostgreSql/PostgreSqlGrantsTests.cs @@ -0,0 +1,147 @@ +using System.Text; +using Bank.Accounts; +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.Hosting; +using Npgsql; +using SourceFlow.Hosting; +using SourceFlow.Storage.PostgreSQL; +using SourceFlow.Tool; + +namespace SourceFlow.Storage.Tests.PostgreSql; + +/// +/// SEC-REV-01 (WP-5.5 security review, doc 10 §1 "events edited in the database"): with the grants from +/// db script --grants, the runtime role runs the service but can't update, delete or truncate events, on a plain +/// or a partitioned events table, including partitions the owner creates later. QRY-65 (WP-C.12, CR-23): with the grants from +/// db script --query-role, SFQL queries run as a role that can only read. +/// +[Collection(PostgreSqlCollection.Name)] +[Trait("Category", "EndToEnd")] +[Trait("Provider", "PostgreSQL")] +[Trait("Requires", "Docker")] +public sealed class PostgreSqlGrantsTests(PostgreSqlServer server) : PostgreSqlTest(server) +{ + private static CancellationToken Ct => TestContext.Current.CancellationToken; + + [Theory] + [Trait("Id", "SEC-REV-01")] + [Trait("Covers", "doc 10 1")] + [InlineData(false)] + [InlineData(true)] + public async Task RuntimeRole_RunsTheService_ButEventsAreAppendOnly(bool partitioned) + { + string schema = PostgreSqlServer.NewSchema("grants"); + string role = "sf_rt_" + Guid.CreateVersion7().ToString("N")[^12..]; + var migrator = new PostgreSqlSchemaMigrator(Server.DataSource, schema, partitionEvents: partitioned); + await migrator.MigrateAsync(Ct); + await Server.ExecuteAsync($"CREATE ROLE \"{role}\" LOGIN PASSWORD '{role}'"); + + // The script the CLI prints is the one applied. + using var output = new StringWriter(); + (await SourceFlowCli.RunAsync(["db", "script", "--schema", schema, "--grants", role], output: output, cancellationToken: Ct)).ShouldBe(0); + output.ToString().ShouldContain("REVOKE UPDATE, DELETE, TRUNCATE"); + await Server.ExecuteAsync(migrator.GrantsScript(role)); + + // The service runs as the runtime role: commands, inline projection, outbox. + using IHost host = await StartAsync(schema, Server.ConnectionStringFor(role), partitioned); + ICommandSender commands = host.Services.GetRequiredService(); + AccountId id = AccountId.New(); + (await commands.SendAsync(new OpenAccount(id, "Ada", 10m), null, Ct)).Status.ShouldBe(CommandStatus.Accepted); + (await commands.SendAsync(new Deposit(id, 5m), null, Ct)).Status.ShouldBe(CommandStatus.Accepted); + await host.StopAsync(Ct); + + // History can't be edited, deleted or truncated through the table or a partition. + await using var runtime = NpgsqlDataSource.Create(Server.ConnectionStringFor(role)); + await DeniedAsync(runtime, $"UPDATE \"{schema}\".events SET event_type = 'tampered'"); + await DeniedAsync(runtime, $"DELETE FROM \"{schema}\".events"); + await DeniedAsync(runtime, $"TRUNCATE \"{schema}\".events"); + if (partitioned) + { + await DeniedAsync(runtime, $"UPDATE \"{schema}\".events_initial SET event_type = 'tampered'"); + + // A partition the owner creates later is append-only for the role too. + await Server.ExecuteAsync($"SELECT \"{schema}\".sf_ensure_event_partitions(now() + interval '6 months', 1)"); + string later = (string)(await ScalarAsync(Server.DataSource, $"SELECT max(name) FROM \"{schema}\".event_partitions WHERE name <> 'events_initial'"))!; + await DeniedAsync(runtime, $"DELETE FROM \"{schema}\".{later}"); + (await ScalarAsync(runtime, $"SELECT count(*) FROM \"{schema}\".{later}")).ShouldBe(0L); + } + + (await ScalarAsync(runtime, $"SELECT count(*) FROM \"{schema}\".events WHERE event_type <> 'tampered'")).ShouldBe(2L); + } + + [Fact] + [Trait("Id", "QRY-65")] + [Trait("Covers", "doc 14 7.1;Q-R2")] + public async Task QueryRole_ReadsThroughSfql_ButCantWrite() + { + string schema = PostgreSqlServer.NewSchema("qrole"); + string suffix = Guid.CreateVersion7().ToString("N")[^12..]; + string runtimeRole = "sf_rt_" + suffix; + string queryRole = "sf_q_" + suffix; + var migrator = new PostgreSqlSchemaMigrator(Server.DataSource, schema); + await migrator.MigrateAsync(Ct); + await Server.ExecuteAsync($"CREATE ROLE \"{runtimeRole}\" LOGIN PASSWORD '{runtimeRole}'"); + await Server.ExecuteAsync($"CREATE ROLE \"{queryRole}\" LOGIN PASSWORD '{queryRole}'"); + + using var output = new StringWriter(); + (await SourceFlowCli.RunAsync(["db", "script", "--schema", schema, "--query-role", queryRole], output: output, cancellationToken: Ct)).ShouldBe(0); + output.ToString().ShouldContain($"GRANT SELECT ON ALL TABLES IN SCHEMA \"{schema}\" TO \"{queryRole}\""); + await Server.ExecuteAsync(migrator.GrantsScript(runtimeRole)); + await Server.ExecuteAsync(migrator.QueryGrantsScript(queryRole)); + + // The service writes as the runtime role and queries as the query role. + using IHost host = await StartAsync(schema, Server.ConnectionStringFor(runtimeRole), partitioned: false, Server.ConnectionStringFor(queryRole)); + AccountId id = AccountId.New(); + (await host.Services.GetRequiredService().SendAsync(new OpenAccount(id, "Ada", 10m), null, Ct)).Status.ShouldBe(CommandStatus.Accepted); + SourceFlow.Query.QueryPage page = await host.Services.GetRequiredService() + .QueryPageAsync("from readmodel \"account-summary\" | project holder", cancellationToken: Ct); + page.Rows.Select(r => (string?)r[0]).ShouldBe(["Ada"]); + await host.StopAsync(Ct); + + // The query role can read, and nothing else. + await using var query = NpgsqlDataSource.Create(Server.ConnectionStringFor(queryRole)); + (await ScalarAsync(query, $"SELECT count(*) FROM \"{schema}\".events")).ShouldBe(1L); + await DeniedAsync(query, $"INSERT INTO \"{schema}\".documents (tenant_id, collection, id, version, data) VALUES ('-', 'x', 'y', 1, '{{}}')"); + await DeniedAsync(query, $"UPDATE \"{schema}\".documents SET version = version + 1"); + await DeniedAsync(query, $"DELETE FROM \"{schema}\".events"); + await DeniedAsync(query, $"DELETE FROM \"{schema}\".outbox"); + } + + private async Task StartAsync(string schema, string connectionString, bool partitioned, string? queryConnectionString = null) + { + HostApplicationBuilder builder = Host.CreateApplicationBuilder(new HostApplicationBuilderSettings { EnvironmentName = Environments.Development, DisableDefaults = true }); + builder.Services.AddSourceFlow(sf => + { + sf.ServiceName = "accounts"; + sf.AddModule(); + sf.Projections(p => p.Add().Inline()); + sf.UsePostgreSql(o => + { + o.ConnectionString = connectionString; + o.Schema = schema; + o.AutoMigrate = false; + o.PartitionEvents = partitioned; + o.QueryConnectionString = queryConnectionString; + }); + }); + IHost host = builder.Build(); + await host.StartAsync(Ct); + return host; + } + + private static async Task DeniedAsync(NpgsqlDataSource dataSource, string sql) + { + PostgresException denied = await Should.ThrowAsync(async () => + { + await using NpgsqlCommand command = dataSource.CreateCommand(sql); + await command.ExecuteNonQueryAsync(Ct); + }); + denied.SqlState.ShouldBe(PostgresErrorCodes.InsufficientPrivilege, new StringBuilder(sql).Append(": ").Append(denied.MessageText).ToString()); + } + + private static async Task ScalarAsync(NpgsqlDataSource dataSource, string sql) + { + await using NpgsqlCommand command = dataSource.CreateCommand(sql); + return await command.ExecuteScalarAsync(Ct); + } +} diff --git a/tests/Storage/SourceFlow.Storage.Tests/PostgreSql/PostgreSqlMigrationTests.cs b/tests/Storage/SourceFlow.Storage.Tests/PostgreSql/PostgreSqlMigrationTests.cs new file mode 100644 index 00000000..8dd46401 --- /dev/null +++ b/tests/Storage/SourceFlow.Storage.Tests/PostgreSql/PostgreSqlMigrationTests.cs @@ -0,0 +1,198 @@ +using Bank.Accounts; +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.Hosting; +using Npgsql; +using SourceFlow.Hosting; +using SourceFlow.Storage.PostgreSQL; +using SourceFlow.Testing.Conformance; + +namespace SourceFlow.Storage.Tests.PostgreSql; + +/// SCK-M01..M06: schema management (doc 05 §11, WP-2.1). +[Collection(PostgreSqlCollection.Name)] +[Trait("Category", "Integration")] +[Trait("Provider", "PostgreSQL")] +[Trait("Requires", "Docker")] +public sealed class PostgreSqlMigrationTests(PostgreSqlServer server) : PostgreSqlTest(server) +{ + private static readonly string[] Tables = + [ + "checkpoints", "collection_aliases", "data_keys", "dead_letters", "documents", "events", "inbox", "leases", "nodes", + "outbox", "process_instances", "schema_history", "schemas", "snapshots", "streams", "subject_streams", "subscription_partitions", + ]; + + private static CancellationToken Ct => TestContext.Current.CancellationToken; + + [Fact] + [Trait("Id", "SCK-M01")] + [Trait("Covers", "GAP-04")] + public async Task FreshInstall_CreatesEveryTable_AndRecordsHistory() + { + string schema = PostgreSqlServer.NewSchema(); + var migrator = new PostgreSqlSchemaMigrator(Server.DataSource, schema); + + IReadOnlyList applied = await migrator.MigrateAsync(Ct); + + applied.ShouldBe([1, 2, 3, 4, 5, 6, 7, 8, 9]); + (await migrator.GetAppliedVersionsAsync(Ct)).ShouldBe([1, 2, 3, 4, 5, 6, 7, 8, 9]); + (await TablesAsync(schema)).ShouldBe(Tables); + await migrator.VerifyAsync(Ct); + } + + [Fact] + [Trait("Id", "SCK-M02")] + public async Task Upgrade_AppliesOnlyPendingScripts_AndIsIdempotent() + { + string schema = PostgreSqlServer.NewSchema(); + MigrationScript v1 = PostgreSqlSchemaMigrator.EmbeddedScripts[0]; + var v2 = new MigrationScript(2, "extra", "CREATE TABLE {schema}.extra (id int PRIMARY KEY);"); + await new PostgreSqlSchemaMigrator(Server.DataSource, schema, [v1]).MigrateAsync(Ct); + var upgraded = new PostgreSqlSchemaMigrator(Server.DataSource, schema, [v1, v2]); + + (await upgraded.MigrateAsync(Ct)).ShouldBe([2]); + (await upgraded.MigrateAsync(Ct)).ShouldBeEmpty(); + (await upgraded.GetAppliedVersionsAsync(Ct)).ShouldBe([1, 2]); + (await TablesAsync(schema)).ShouldContain("extra"); + } + + [Fact] + [Trait("Id", "SCK-M02")] + public async Task ModifiedAppliedScript_IsRejected_AndVerifyReportsMissingVersions() + { + string schema = PostgreSqlServer.NewSchema(); + MigrationScript v1 = PostgreSqlSchemaMigrator.EmbeddedScripts[0]; + await new PostgreSqlSchemaMigrator(Server.DataSource, schema, [v1]).MigrateAsync(Ct); + + var tampered = new PostgreSqlSchemaMigrator(Server.DataSource, schema, [v1 with { Sql = v1.Sql + "\n-- edited" }]); + var newer = new PostgreSqlSchemaMigrator(Server.DataSource, schema, [v1, new MigrationScript(2, "extra", "SELECT 1;")]); + + (await Should.ThrowAsync(() => tampered.MigrateAsync(Ct))).Message.ShouldContain("modified"); + (await Should.ThrowAsync(() => newer.VerifyAsync(Ct))).Message.ShouldContain("V002"); + (await Should.ThrowAsync(() => new PostgreSqlSchemaMigrator(Server.DataSource, PostgreSqlServer.NewSchema()).VerifyAsync(Ct))) + .Message.ShouldContain("not installed"); + } + + [Fact] + [Trait("Id", "SCK-M03")] + public async Task ConcurrentMigrators_Serialise_ExactlyOneApplies() + { + string schema = PostgreSqlServer.NewSchema(); + + IReadOnlyList[] results = await Task.WhenAll(Enumerable.Range(0, 8) + .Select(_ => Task.Run(() => new PostgreSqlSchemaMigrator(Server.DataSource, schema).MigrateAsync(Ct)))); + + results.Sum(r => r.Count).ShouldBe(PostgreSqlSchemaMigrator.EmbeddedScripts.Count); + results.Count(r => r.Count > 0).ShouldBe(1); + (await TablesAsync(schema)).ShouldBe(Tables); + } + + [Fact] + [Trait("Id", "SCK-M04")] + public async Task AutoMigrate_IsOffOutsideDevelopment_AndOnInDevelopment() + { + string schema = PostgreSqlServer.NewSchema(); + + using IHost production = BuildHost(Environments.Production, schema); + (await Should.ThrowAsync(() => production.StartAsync(Ct))).Message.ShouldContain("not installed"); + (await TablesAsync(schema)).ShouldBeEmpty(); + + using IHost development = BuildHost(Environments.Development, schema); + await development.StartAsync(Ct); + (await TablesAsync(schema)).ShouldBe(Tables); + await development.StopAsync(Ct); + + using IHost productionAfterMigrate = BuildHost(Environments.Production, schema); + await productionAfterMigrate.StartAsync(Ct); + await productionAfterMigrate.StopAsync(Ct); + } + + [Fact] + [Trait("Id", "SCK-M05")] + public async Task RuntimeRole_WithDmlOnly_PassesTheCoreConformanceCases() + { + string role = "r_" + Guid.CreateVersion7().ToString("N"); + await Server.ExecuteAsync($"CREATE ROLE \"{role}\" LOGIN PASSWORD 'runtime'"); + string connectionString = new NpgsqlConnectionStringBuilder(Server.ConnectionString) { Username = role, Password = "runtime" }.ConnectionString; + string[] cases = ["SCK-02", "SCK-05", "SCK-21", "SCK-30", "SCK-35", "SCK-38", "SCK-47", "SCK-49", "SCK-51", "SCK-58"]; + + foreach (ConformanceCase @case in StorageConformance.Cases.Where(c => cases.Contains(c.Id))) + { + // A fresh schema per case keeps the cases independent; the role is granted on each. + string caseSchema = PostgreSqlServer.NewSchema(); + await new PostgreSqlSchemaMigrator(Server.DataSource, caseSchema).MigrateAsync(Ct); + await Server.ExecuteAsync($""" + GRANT USAGE ON SCHEMA "{caseSchema}" TO "{role}"; + GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA "{caseSchema}" TO "{role}"; + """); + await using var fixture = new PostgreSqlStorageFixture(new PostgreSqlStore(new PostgreSqlStorageOptions { ConnectionString = connectionString, Schema = caseSchema })); + await @case.Run(fixture, Ct); + } + + // ... and it cannot change the schema. + await using NpgsqlDataSource runtime = NpgsqlDataSource.Create(connectionString); + await Should.ThrowAsync(() => new PostgreSqlSchemaMigrator(runtime, PostgreSqlServer.NewSchema()).MigrateAsync(Ct)); + } + + [Fact] + [Trait("Id", "SCK-M06")] + public async Task DbScript_ProducesTheSameSchemaAsMigrate() + { + string migrated = PostgreSqlServer.NewSchema(); + string scripted = PostgreSqlServer.NewSchema(); + await new PostgreSqlSchemaMigrator(Server.DataSource, migrated).MigrateAsync(Ct); + + var scripter = new PostgreSqlSchemaMigrator(Server.DataSource, scripted); + await Server.ExecuteAsync(scripter.Script()); + + (await ColumnsAsync(scripted)).ShouldBe(await ColumnsAsync(migrated)); + (await scripter.GetAppliedVersionsAsync(Ct)).ShouldBe([1, 2, 3, 4, 5, 6, 7, 8, 9]); + await scripter.VerifyAsync(Ct); + (await scripter.MigrateAsync(Ct)).ShouldBeEmpty(); + } + + private IHost BuildHost(string environment, string schema) + { + HostApplicationBuilder builder = Host.CreateApplicationBuilder(new HostApplicationBuilderSettings { EnvironmentName = environment, DisableDefaults = true }); + builder.Services.AddSourceFlow(sf => + { + sf.ServiceName = "accounts"; + sf.AddModule(); + sf.UsePostgreSql(o => + { + o.DataSource = Server.DataSource; + o.Schema = schema; + }); + sf.UseInMemoryTransport(); + }); + return builder.Build(); + } + + private async Task TablesAsync(string schema) + { + await using NpgsqlCommand command = Server.DataSource.CreateCommand("SELECT table_name FROM information_schema.tables WHERE table_schema = $1 ORDER BY table_name"); + command.Parameters.Add(new NpgsqlParameter { TypedValue = schema }); + await using NpgsqlDataReader reader = await command.ExecuteReaderAsync(Ct); + var tables = new List(); + while (await reader.ReadAsync(Ct)) + { + tables.Add(reader.GetString(0)); + } + + return [.. tables]; + } + + private async Task ColumnsAsync(string schema) + { + await using NpgsqlCommand command = Server.DataSource.CreateCommand( + "SELECT table_name || '.' || column_name || ':' || data_type || ':' || is_nullable FROM information_schema.columns WHERE table_schema = $1 ORDER BY table_name, ordinal_position"); + command.Parameters.Add(new NpgsqlParameter { TypedValue = schema }); + await using NpgsqlDataReader reader = await command.ExecuteReaderAsync(Ct); + var columns = new List(); + while (await reader.ReadAsync(Ct)) + { + columns.Add(reader.GetString(0)); + } + + return [.. columns]; + } +} diff --git a/tests/Storage/SourceFlow.Storage.Tests/PostgreSql/PostgreSqlMonitorTests.cs b/tests/Storage/SourceFlow.Storage.Tests/PostgreSql/PostgreSqlMonitorTests.cs new file mode 100644 index 00000000..9e8ab0d8 --- /dev/null +++ b/tests/Storage/SourceFlow.Storage.Tests/PostgreSql/PostgreSqlMonitorTests.cs @@ -0,0 +1,129 @@ +using Bank.Accounts; +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.Diagnostics.HealthChecks; +using Microsoft.Extensions.Hosting; +using Npgsql; +using SourceFlow.Hosting; +using SourceFlow.Messaging; +using SourceFlow.Storage.PostgreSQL; + +namespace SourceFlow.Storage.Tests.PostgreSql; + +/// The PostgreSQL monitor readings behind the health checks and gauges (doc 08 §3.2, §5; WP-4.3). +[Collection(PostgreSqlCollection.Name)] +[Trait("Category", "Integration")] +[Trait("Provider", "PostgreSQL")] +[Trait("Requires", "Docker")] +public sealed class PostgreSqlMonitorTests(PostgreSqlServer server) : PostgreSqlTest(server) +{ + private static CancellationToken Ct => TestContext.Current.CancellationToken; + + [Fact] + [Trait("Id", "UT-HC-02")] + [Trait("Covers", "doc 08 5")] + public async Task Probe_ReportsTheSchema_AndFailsOnAnUnmigratedOne() + { + await using PostgreSqlStore migrated = await Server.CreateStoreAsync(); + await using var unmigrated = new PostgreSqlStore(new PostgreSqlStorageOptions { DataSource = Server.DataSource, Schema = PostgreSqlServer.NewSchema("empty") }); + + StoreProbe current = await migrated.ProbeAsync(Ct); + StoreProbe missing = await unmigrated.ProbeAsync(Ct); + + current.SchemaCurrent.ShouldBeTrue(current.Detail); + missing.SchemaCurrent.ShouldBeFalse(); + missing.Detail.ShouldContain("not installed"); + } + + [Fact] + [Trait("Id", "UT-HC-10")] + [Trait("Covers", "doc 08 3.2")] + public async Task Readings_CountTheOutbox_DeadLetters_Events_AndProcesses() + { + using IHost host = await StartAsync(sf => + { + sf.Roles = SourceFlowRoles.Api; // nothing relays or projects: the backlog stays + sf.Routing(r => r.Publish().AsIs().To("accounts.events")); + }); + PostgreSqlStore store = host.Services.GetRequiredService(); + ICommandSender commands = host.Services.GetRequiredService(); + await commands.SendAsync(new OpenAccount(AccountId.New(), "Ada", 1m), null, Ct); + await commands.SendAsync(new OpenAccount(AccountId.New(), "Bob", 2m), null, Ct); + StoredEvent first = (await store.ReadAsync(GlobalPosition.Start, BucketRange.All, 1, Ct)).Events.ShouldHaveSingleItem(); + await store.ParkAsync(new DeadLetter + { + Id = Guid.CreateVersion7(TimeProvider.System.GetUtcNow()), + Consumer = "accounts", + Source = "test", + Envelope = first.ToEnvelope(), + Reason = "test", + Attempts = 1, + FirstFailedAt = TimeProvider.System.GetUtcNow().AddMinutes(-1), + ParkedAt = TimeProvider.System.GetUtcNow(), + }, Ct); + + IReadOnlyList outbox = await store.GetOutboxBacklogAsync(Ct); + IReadOnlyDictionary deadLetters = await store.CountParkedDeadLettersAsync(Ct); + long all = await store.CountEventsAfterAsync(GlobalPosition.Start, BucketRange.All, 1000, Ct); + long capped = await store.CountEventsAfterAsync(GlobalPosition.Start, BucketRange.All, 1, Ct); + long afterFirst = await store.CountEventsAfterAsync(first.Position, BucketRange.All, 1000, Ct); + + outbox.Sum(o => o.Pending).ShouldBe(2); + outbox.ShouldAllBe(o => o.OldestDueAt != null && o.OldestDueAt <= TimeProvider.System.GetUtcNow().AddSeconds(5)); + deadLetters["accounts"].ShouldBe(1); + all.ShouldBe(2); + capped.ShouldBe(1, "counting stops at the cap"); + afterFirst.ShouldBe(1); + (await store.CountActiveProcessesAsync(Ct)).ShouldBeEmpty(); + } + + [Fact] + [Trait("Id", "UT-HC-07")] + [Trait("Covers", "doc 05 5.4;doc 08 5")] + public async Task AHeldWritingTransaction_DegradesTheSubscriptionsCheck() + { + using IHost host = await StartAsync(sf => sf.Configure(o => + { + o.Health.HorizonAgeDegraded = TimeSpan.FromSeconds(1); + o.MonitorInterval = TimeSpan.FromMilliseconds(200); + })); + HealthCheckService health = host.Services.GetRequiredService(); + + await using NpgsqlConnection holder = await Server.DataSource.OpenConnectionAsync(Ct); + await using NpgsqlTransaction transaction = await holder.BeginTransactionAsync(Ct); + await using (var xid = new NpgsqlCommand("SELECT pg_current_xact_id()", holder, transaction)) + { + await xid.ExecuteScalarAsync(Ct); // a writing transaction: it has a transaction id + } + + await RealClock.WaitAsync(TimeSpan.FromSeconds(1.6)); + HealthReportEntry held = (await health.CheckHealthAsync(c => c.Name == "sourceflow.subscriptions", Ct)).Entries["sourceflow.subscriptions"]; + await transaction.RollbackAsync(Ct); + await RealClock.WaitAsync(TimeSpan.FromMilliseconds(600)); + HealthReportEntry released = (await health.CheckHealthAsync(c => c.Name == "sourceflow.subscriptions", Ct)).Entries["sourceflow.subscriptions"]; + + held.Status.ShouldBe(HealthStatus.Degraded, held.Description); + held.Description!.ShouldContain("horizon"); + released.Status.ShouldBe(HealthStatus.Healthy, released.Description); + } + + private async Task StartAsync(Action configure) + { + string schema = PostgreSqlServer.NewSchema(); + HostApplicationBuilder builder = Host.CreateApplicationBuilder(new HostApplicationBuilderSettings { EnvironmentName = Environments.Development, DisableDefaults = true }); + builder.Services.AddHealthChecks().AddSourceFlow(); + builder.Services.AddSourceFlow(sf => + { + sf.ServiceName = "accounts"; + sf.AddModule(); + sf.UsePostgreSql(o => + { + o.DataSource = Server.DataSource; + o.Schema = schema; + }); + configure(sf); + }); + IHost host = builder.Build(); + await host.StartAsync(Ct); + return host; + } +} diff --git a/tests/Storage/SourceFlow.Storage.Tests/PostgreSql/PostgreSqlOptionsTests.cs b/tests/Storage/SourceFlow.Storage.Tests/PostgreSql/PostgreSqlOptionsTests.cs new file mode 100644 index 00000000..f3c3da7c --- /dev/null +++ b/tests/Storage/SourceFlow.Storage.Tests/PostgreSql/PostgreSqlOptionsTests.cs @@ -0,0 +1,56 @@ +using SourceFlow.Storage.PostgreSQL; + +namespace SourceFlow.Storage.Tests.PostgreSql; + +/// Option validation and embedded scripts; no server needed. +[Trait("Category", "Unit")] +[Trait("Provider", "PostgreSQL")] +public sealed class PostgreSqlOptionsTests +{ + [Theory] + [Trait("Id", "UT-PG-01")] + [InlineData("Public")] + [InlineData("x; DROP TABLE y")] + [InlineData("")] + [InlineData("a-b")] + public void SchemaName_MustBeAPlainIdentifier(string schema) + { + Should.Throw(() => new PostgreSqlStore(new PostgreSqlStorageOptions { ConnectionString = "Host=x", Schema = schema })); + } + + [Fact] + [Trait("Id", "UT-PG-02")] + public void ConnectionStringOrDataSource_IsRequired_AndTheChannelIsValidated() + { + Should.Throw(() => new PostgreSqlStore(new PostgreSqlStorageOptions())); + Should.Throw(() => new PostgreSqlStore(new PostgreSqlStorageOptions { ConnectionString = "Host=x", NotificationChannel = "bad channel" })); + Should.Throw(() => new PostgreSqlStore(new PostgreSqlStorageOptions { ConnectionString = "Host=x", ListenReconnectDelay = TimeSpan.Zero })); + } + + [Fact] + [Trait("Id", "UT-PG-04")] + [Trait("Covers", "ADR-022")] + public void RowLevelSecurity_RequiresASystemConnection_ForTheCrossTenantLog() + { + var options = new PostgreSqlStorageOptions { ConnectionString = "Host=x", TenantIsolation = TenantIsolation.RowLevelSecurity }; + + Should.Throw(() => new PostgreSqlStore(options)).Message.ShouldContain("BYPASSRLS"); + options.SystemConnectionString = "Host=x;Username=system"; + Should.NotThrow(() => new PostgreSqlStore(options).DisposeAsync().AsTask().GetAwaiter().GetResult()); + } + + [Fact] + [Trait("Id", "UT-PG-03")] + public void EmbeddedScripts_AreVersionedAndChecksummed_IndependentOfLineEndings() + { + PostgreSqlSchemaMigrator.EmbeddedScripts.Select(s => $"V{s.Version:D3}__{s.Name}").ShouldBe(["V001__initial", "V002__tenant_policies", "V003__commit_assertions", "V004__read_model_generations", "V005__outbox_first_due", "V006__data_keys_per_tenant", "V007__data_keys_policy", "V008__document_position", "V009__subscription_partitions"]); + MigrationScript initial = PostgreSqlSchemaMigrator.EmbeddedScripts[0]; + initial.Version.ShouldBe(1); + initial.Name.ShouldBe("initial"); + initial.Checksum.Length.ShouldBe(64); + + string windows = initial.Sql.ReplaceLineEndings("\r\n"); + (initial with { Sql = windows }).Checksum.ShouldBe(initial.Checksum); + (initial with { Sql = initial.Sql + " " }).Checksum.ShouldNotBe(initial.Checksum); + } +} diff --git a/tests/Storage/SourceFlow.Storage.Tests/PostgreSql/PostgreSqlPartitionTests.cs b/tests/Storage/SourceFlow.Storage.Tests/PostgreSql/PostgreSqlPartitionTests.cs new file mode 100644 index 00000000..eb9a442e --- /dev/null +++ b/tests/Storage/SourceFlow.Storage.Tests/PostgreSql/PostgreSqlPartitionTests.cs @@ -0,0 +1,452 @@ +using System.Text; +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.Hosting; +using Npgsql; +using SourceFlow.Hosting; +using SourceFlow.Query; +using SourceFlow.Runtime; +using SourceFlow.Storage.PostgreSQL; +using SourceFlow.Storage.PostgreSQL.Query; +using SourceFlow.Testing.Conformance; + +namespace SourceFlow.Storage.Tests.PostgreSql; + +/// +/// SCK-65..68, 72: the partitioned events variant (, doc 05 §9, +/// doc 09 §5; WP-4.5). The store clock (a fake) decides created_at, so a test can write on both sides of a +/// partition boundary without waiting for a month to pass. +/// +[Collection(PostgreSqlCollection.Name)] +[Trait("Category", "Integration")] +[Trait("Provider", "PostgreSQL")] +[Trait("Requires", "Docker")] +public sealed class PostgreSqlPartitionTests(PostgreSqlServer server) : PostgreSqlTest(server) +{ + private const string Tenant = "-"; + + private static CancellationToken Ct => TestContext.Current.CancellationToken; + + [Fact] + [Trait("Id", "SCK-65")] + [Trait("Covers", "doc 05 9;doc 09 5")] + public async Task Append_AcrossAPartitionBoundary() + { + (PostgreSqlStore store, SettableTime time, DateTimeOffset boundary) = await PartitionedAsync(); + var stream = new StreamId("p-a-1"); + time.SetUtcNow(boundary - TimeSpan.FromSeconds(1)); + await AppendAsync(store, stream, ExpectedVersion.NoStream, 2); + time.SetUtcNow(boundary + TimeSpan.FromSeconds(1)); + await AppendAsync(store, stream, ExpectedVersion.Exact(new StreamVersion(2)), 2); + + StreamSlice slice = await store.ReadStreamAsync(Tenant, stream, new StreamVersion(1), 10, Ct); + + slice.Events.Select(e => e.StreamVersion.Value).ShouldBe([1L, 2L, 3L, 4L]); + (await PartitionsOfAsync(store, stream)).ShouldBe(["events_initial", "events_initial", PartitionName(boundary), PartitionName(boundary)]); + await Should.ThrowAsync(() => AppendAsync(store, stream, ExpectedVersion.Exact(new StreamVersion(2)), 1)); // the streams CAS still guards versions + } + + [Fact] + [Trait("Id", "SCK-66")] + [Trait("Covers", "ADR-010;doc 05 9")] + public async Task GlobalLog_IsInCommitOrder_AcrossPartitions() + { + (PostgreSqlStore store, SettableTime time, DateTimeOffset boundary) = await PartitionedAsync(); + DateTimeOffset[] times = [boundary.AddMonths(1).AddDays(3), boundary.AddDays(-3), boundary.AddDays(10), boundary.AddMonths(1).AddDays(1)]; + for (int i = 0; i < times.Length; i++) + { + time.SetUtcNow(times[i]); + await AppendAsync(store, new StreamId($"p-log-{i}"), ExpectedVersion.NoStream, 1); + } + + LogBatch log = await store.ReadAsync(GlobalPosition.Start, BucketRange.All, 100, Ct); + GlobalPosition horizon = await store.GetSafeHorizonAsync(Ct); + + log.Events.Select(e => e.StreamId.Value).ShouldBe(["p-log-0", "p-log-1", "p-log-2", "p-log-3"], "commit order, not created_at order"); + log.Events.Select(e => e.Position).ShouldBeInOrder(); + log.Events[^1].Position.CompareTo(horizon).ShouldBeLessThanOrEqualTo(0); + (await store.ReadAsync(log.Events[1].Position, BucketRange.All, 100, Ct)).Events.Select(e => e.StreamId.Value).ShouldBe(["p-log-2", "p-log-3"]); + (await store.CountEventsAfterAsync(log.Events[0].Position, BucketRange.All, 100, Ct)).ShouldBe(3); + } + + [Fact] + [Trait("Id", "SCK-67")] + [Trait("Covers", "doc 05 9")] + public async Task Maintenance_CreatesPartitionsAhead_Idempotently() + { + (PostgreSqlStore store, SettableTime time, DateTimeOffset boundary) = await PartitionedAsync(o => o.PartitionMonthsAhead = 2); + IReadOnlyList initial = await store.ListEventPartitionsAsync(Ct); + + initial[0].ShouldBe(new EventPartition("events_initial", null, boundary, null)); + Contiguous(initial); + + time.SetUtcNow(boundary.AddMonths(5).AddDays(2)); + int created = await store.EnsureEventPartitionsAsync(Ct); + int again = await store.EnsureEventPartitionsAsync(Ct); + IReadOnlyList later = await store.ListEventPartitionsAsync(Ct); + + created.ShouldBeGreaterThan(0); + again.ShouldBe(0); + Contiguous(later); + later[^1].To.ShouldBe(boundary.AddMonths(8), "the current month and two after it"); + await AppendAsync(store, new StreamId("p-ahead"), ExpectedVersion.NoStream, 1); // writes land in the new partitions + + // Concurrent maintenance (every node runs it) creates each partition once. + time.SetUtcNow(boundary.AddMonths(9)); + int[] concurrent = await Task.WhenAll(Enumerable.Range(0, 4).Select(_ => store.EnsureEventPartitionsAsync(Ct))); + concurrent.Sum().ShouldBe(4); + Contiguous(await store.ListEventPartitionsAsync(Ct)); + } + + [Fact] + [Trait("Id", "SCK-67")] + [Trait("Covers", "doc 05 9")] + public async Task UsePostgreSql_WithPartitionEvents_MigratesAndRunsTheMaintenanceJob() + { + string schema = PostgreSqlServer.NewSchema("pm"); + HostApplicationBuilder builder = Host.CreateApplicationBuilder(new HostApplicationBuilderSettings { EnvironmentName = Environments.Development, DisableDefaults = true }); + builder.Services.AddSourceFlow(sf => + { + sf.ServiceName = "accounts"; + sf.AddModule(); + sf.UsePostgreSql(o => + { + o.DataSource = Server.DataSource; + o.Schema = schema; + o.PartitionEvents = true; + o.PartitionMonthsAhead = 6; + }); + }); + using IHost host = builder.Build(); + await host.StartAsync(Ct); + PostgreSqlStore store = host.Services.GetRequiredService(); + + host.Services.GetServices().OfType().ShouldHaveSingleItem(); + await EventuallyAsync(async () => (await store.ListEventPartitionsAsync(Ct)).Count == 7); // initial + 6 ahead + (await host.Services.GetRequiredService().SendAsync(new Bank.Accounts.OpenAccount(Bank.Accounts.AccountId.New(), "Ada", 1m), null, Ct)) + .Status.ShouldBe(CommandStatus.Accepted); + await store.CreateMigrator().VerifyAsync(Ct); + await host.StopAsync(Ct); + } + + [Fact] + [Trait("Id", "SCK-68")] + [Trait("Covers", "doc 05 9")] + public async Task Detach_AnOldPartition_OnlyWhenEveryStreamInItIsArchived() + { + (PostgreSqlStore store, SettableTime time, DateTimeOffset boundary) = await PartitionedAsync(); + var archived = new StreamId("p-cold"); + var open = new StreamId("p-warm"); + time.SetUtcNow(boundary - TimeSpan.FromDays(1)); + await AppendAsync(store, archived, ExpectedVersion.NoStream, 3); + await AppendAsync(store, open, ExpectedVersion.NoStream, 1); + time.SetUtcNow(boundary + TimeSpan.FromDays(1)); + await AppendAsync(store, open, ExpectedVersion.Exact(new StreamVersion(1)), 1); + await store.ArchiveStreamAsync(Tenant, archived, Ct); + + (await Should.ThrowAsync(() => store.DetachEventPartitionAsync(PartitionName(boundary), Ct))).Message.ShouldContain("not in the past"); + (await Should.ThrowAsync(() => store.DetachEventPartitionAsync("events_initial", Ct))).Message.ShouldContain("1 stream(s)"); + (await Should.ThrowAsync(() => store.DetachEventPartitionAsync("events; DROP TABLE x", Ct))).Message.ShouldContain("not an events partition"); + + await store.ArchiveStreamAsync(Tenant, open, Ct); + await store.DetachEventPartitionAsync("events_initial", Ct); + + (await store.ListEventPartitionsAsync(Ct))[0].DetachedAt.ShouldNotBeNull(); + (await store.ReadStreamAsync(Tenant, archived, new StreamVersion(1), 10, Ct)).Events.ShouldBeEmpty("detached events leave the store"); + (await store.ReadAsync(GlobalPosition.Start, BucketRange.All, 100, Ct)).Events.ShouldHaveSingleItem().StreamId.ShouldBe(open); + (await Should.ThrowAsync(() => store.DetachEventPartitionAsync("events_initial", Ct))).Message.ShouldContain("already detached"); + await AppendAsync(store, new StreamId("p-new"), ExpectedVersion.NoStream, 1); // the table keeps working + long kept; + await using (NpgsqlCommand count = Server.DataSource.CreateCommand($"SELECT count(*) FROM \"{store.Options.Schema}\".events_initial")) + { + kept = (long)(await count.ExecuteScalarAsync(Ct))!; + } + + kept.ShouldBe(4, "the detached table keeps its rows for archiving"); + } + + [Fact] + [Trait("Id", "SCK-72")] + [Trait("Covers", "doc 05 9;doc 05 11")] + public async Task Converting_AnExistingStore_KeepsEveryEventAndPosition() + { + var time = new SettableTime(TimeProvider.System.GetUtcNow()); + PostgreSqlStore plain = await Server.CreateStoreAsync(time, o => o.PartitionEvents = false); + string schema = plain.Options.Schema; + for (int i = 0; i < 5; i++) + { + await AppendAsync(plain, new StreamId($"c-{i % 2}"), i < 2 ? ExpectedVersion.NoStream : ExpectedVersion.Any, 1); + } + + LogBatch before = await plain.ReadAsync(GlobalPosition.Start, BucketRange.All, 100, Ct); + await Should.ThrowAsync(() => new PostgreSqlSchemaMigrator(Server.DataSource, schema, partitionEvents: true).VerifyAsync(Ct)); + + var migrator = new PostgreSqlSchemaMigrator(Server.DataSource, schema, partitionEvents: true); + (await migrator.MigrateAsync(Ct)).ShouldBeEmpty(); // no new versions: the conversion is not a numbered script + await migrator.MigrateAsync(Ct); // and running it again changes nothing + await migrator.VerifyAsync(Ct); + await using var partitioned = new PostgreSqlStore(new PostgreSqlStorageOptions { DataSource = Server.DataSource, Schema = schema, PartitionEvents = true }, time); + + LogBatch after = await partitioned.ReadAsync(GlobalPosition.Start, BucketRange.All, 100, Ct); + after.Events.Select(e => (e.EventId, e.Position, e.StreamId, e.StreamVersion)).ShouldBe(before.Events.Select(e => (e.EventId, e.Position, e.StreamId, e.StreamVersion))); + CommitResult next = await AppendAsync(partitioned, new StreamId("c-0"), ExpectedVersion.Any, 1); + next.LastPosition!.Value.CompareTo(before.Events[^1].Position).ShouldBeGreaterThan(0); + (await partitioned.ReadStreamAsync(Tenant, new StreamId("c-0"), new StreamVersion(1), 10, Ct)).Events.Count.ShouldBe(4); + + // The event-id backstop still holds inside a partition. + EventToAppend duplicate = StorageConformance.Event() with { CreatedAt = time.GetUtcNow() }; + await AppendAsync(partitioned, new StreamId("c-dup-1"), ExpectedVersion.NoStream, [duplicate]); + await Should.ThrowAsync(() => AppendAsync(partitioned, new StreamId("c-dup-2"), ExpectedVersion.NoStream, [duplicate])); + + // Query-index sync builds on the partitioned table (without CONCURRENTLY). + QueryCatalog catalog = QueryCatalog.Build(new SourceFlowModelBuilder().AddModule().Build()); + QueryIndexPlan plan = await PostgreSqlIndexSync.ApplyAsync(Server.DataSource, catalog, schema, concurrently: true, Ct); + plan.Create.ShouldContain(i => i.Table == "events"); + (await PostgreSqlIndexSync.PlanAsync(Server.DataSource, catalog, schema, Ct)).Create.ShouldBeEmpty(); + + string script = new PostgreSqlSchemaMigrator(Server.DataSource, "sales", partitionEvents: true).Script(); + script.ShouldContain("PARTITION BY RANGE (created_at)"); + script.ShouldContain("SELECT \"sales\".sf_ensure_event_partitions(now(), 3);"); + } + + // ================================================================ row-level security on partitions (WP-C.2) + + [Fact] + [Trait("Id", "SCK-77")] + [Trait("Covers", "ADR-022;doc 05 9")] + public async Task RowLevelSecurity_CoversEveryPartition_EvenWhenQueriedDirectly() + { + string schema = PostgreSqlServer.NewSchema("rlsp"); + var time = new SettableTime(TimeProvider.System.GetUtcNow()); + var migrator = new PostgreSqlSchemaMigrator(Server.DataSource, schema, TenantIsolation.RowLevelSecurity, partitionEvents: true); + await migrator.MigrateAsync(Ct); + await using var owner = new PostgreSqlStore(new PostgreSqlStorageOptions { DataSource = Server.DataSource, Schema = schema, PartitionEvents = true }, time); + DateTimeOffset boundary = (await owner.ListEventPartitionsAsync(Ct))[0].To; + time.SetUtcNow(boundary.AddMonths(5)); + (await owner.EnsureEventPartitionsAsync(Ct)).ShouldBeGreaterThan(0); // partitions created by the maintenance job too + await Server.GrantAsync(schema); + PostgreSqlStorageOptions appOptions = Server.RowLevelSecurityOptions(schema); + appOptions.PartitionEvents = true; + await using var app = new PostgreSqlStore(appOptions, time); + + string[] partitions = ["events_initial", PartitionName(boundary), PartitionName(boundary.AddMonths(5))]; + DateTimeOffset[] at = [boundary.AddDays(-1), boundary.AddDays(1), boundary.AddMonths(5).AddDays(1)]; + for (int i = 0; i < at.Length; i++) + { + time.SetUtcNow(at[i]); + foreach (string tenant in new[] { "t1", "t2" }) + { + await using IStorageSession session = await app.BeginAsync(tenant, Ct); + session.Append(new StreamId($"rls-{tenant}-{i}"), "rls-test", ExpectedVersion.NoStream, [StorageConformance.Event() with { CreatedAt = at[i] }]); + await session.CommitAsync(Ct); + } + } + + await using NpgsqlDataSource appRole = NpgsqlDataSource.Create(Server.ConnectionStringFor(Server.AppRole)); + foreach (string partition in partitions) + { + (await TenantsInAsync(appRole, schema, partition, "t1")).ShouldBe(["t1"], partition); + (await TenantsInAsync(appRole, schema, partition, null)).ShouldBeEmpty($"{partition}: no tenant setting, no rows"); + } + + await migrator.VerifyAsync(Ct); + + // A partition that lost its protection is found by verification and repaired by the next migration. + await Server.ExecuteAsync($"ALTER TABLE \"{schema}\".\"{partitions[1]}\" NO FORCE ROW LEVEL SECURITY, DISABLE ROW LEVEL SECURITY; DROP POLICY tenant_isolation ON \"{schema}\".\"{partitions[1]}\""); + (await Should.ThrowAsync(() => migrator.VerifyAsync(Ct))).Message.ShouldContain(partitions[1]); + await migrator.MigrateAsync(Ct); + await migrator.VerifyAsync(Ct); + (await TenantsInAsync(appRole, schema, partitions[1], "t2")).ShouldBe(["t2"]); + } + + [Fact] + [Trait("Id", "SCK-78")] + [Trait("Covers", "ADR-022;doc 05 9")] + public async Task Detach_UnderRowLevelSecurity_SeesEveryTenantsOpenStreams() + { + // The upgrade path: row-level security first, partitioning later. events_initial keeps its forced policy, and the + // schema owner is an ordinary role, so a check that ran under the policy would see no rows and allow the detach. + string schema = PostgreSqlServer.NewSchema("rlsd"); + string ownerRole = "sf_owner_" + Guid.CreateVersion7().ToString("N")[..12]; + await Server.ExecuteAsync($"CREATE ROLE \"{ownerRole}\" LOGIN PASSWORD '{ownerRole}'; DO $g$ BEGIN EXECUTE format('GRANT CREATE ON DATABASE %I TO %I', current_database(), '{ownerRole}'); END $g$"); + await using NpgsqlDataSource ownerSource = NpgsqlDataSource.Create(Server.ConnectionStringFor(ownerRole)); + await new PostgreSqlSchemaMigrator(ownerSource, schema, TenantIsolation.RowLevelSecurity).MigrateAsync(Ct); + await Server.GrantAsync(schema); + + var time = new SettableTime(TimeProvider.System.GetUtcNow()); + PostgreSqlStorageOptions appOptions = Server.RowLevelSecurityOptions(schema); + appOptions.PartitionEvents = false; + await using (var app = new PostgreSqlStore(appOptions, time)) + { + await using IStorageSession session = await app.BeginAsync("t1", Ct); + session.Append(new StreamId("open-1"), "rls-test", ExpectedVersion.NoStream, [StorageConformance.Event() with { CreatedAt = time.GetUtcNow() }]); + await session.CommitAsync(Ct); + } + + await new PostgreSqlSchemaMigrator(ownerSource, schema, TenantIsolation.RowLevelSecurity, partitionEvents: true).MigrateAsync(Ct); + await Server.GrantAsync(schema); + await using var owner = new PostgreSqlStore(new PostgreSqlStorageOptions + { + DataSource = ownerSource, + SystemConnectionString = Server.ConnectionStringFor(Server.SystemRole), + Schema = schema, + TenantIsolation = TenantIsolation.RowLevelSecurity, + PartitionEvents = true, + }, time); + time.SetUtcNow((await owner.ListEventPartitionsAsync(Ct))[0].To.AddDays(1)); + + (await Should.ThrowAsync(() => owner.DetachEventPartitionAsync("events_initial", Ct))).Message.ShouldContain("1 stream(s)"); + (await owner.ListEventPartitionsAsync(Ct))[0].DetachedAt.ShouldBeNull(); + } + + [Fact] + [Trait("Id", "SCK-M08")] + [Trait("Covers", "doc 05 11;ADR-022")] + public async Task DbScript_AndDbMigrate_GiveTheSameSecurity() + { + string scripted = PostgreSqlServer.NewSchema("scr"); + string migrated = PostgreSqlServer.NewSchema("mig"); + await Server.ExecuteAsync(new PostgreSqlSchemaMigrator(Server.DataSource, scripted, TenantIsolation.RowLevelSecurity, partitionEvents: true).Script()); + await new PostgreSqlSchemaMigrator(Server.DataSource, migrated, TenantIsolation.RowLevelSecurity, partitionEvents: true).MigrateAsync(Ct); + + IReadOnlyList fromScript = await SecurityOfAsync(scripted); + IReadOnlyList fromMigrate = await SecurityOfAsync(migrated); + + fromScript.ShouldBe(fromMigrate); + fromScript.ShouldContain("events_initial rls=True forced=True policy=True"); + fromScript.ShouldContain("events rls=True forced=True policy=True"); + fromScript.ShouldContain("data_keys rls=True forced=True policy=True"); + await new PostgreSqlSchemaMigrator(Server.DataSource, scripted, TenantIsolation.RowLevelSecurity, partitionEvents: true).VerifyAsync(Ct); + } + + private static async Task TenantsInAsync(NpgsqlDataSource role, string schema, string table, string? tenant) + { + await using NpgsqlConnection connection = await role.OpenConnectionAsync(Ct); + await using var batch = new NpgsqlBatch(connection) + { + BatchCommands = + { + new NpgsqlBatchCommand("SELECT set_config('sourceflow.tenant', @t, true)") { Parameters = { new NpgsqlParameter("t", tenant ?? string.Empty) } }, + new NpgsqlBatchCommand($"SELECT DISTINCT tenant_id FROM \"{schema}\".\"{table}\" ORDER BY tenant_id"), + }, + }; + await using NpgsqlDataReader reader = await batch.ExecuteReaderAsync(Ct); + await reader.NextResultAsync(Ct); + var tenants = new List(); + while (await reader.ReadAsync(Ct)) + { + tenants.Add(reader.GetString(0)); + } + + return [.. tenants]; + } + + // Every table of the schema with its row-level security state and whether it has the tenant_isolation policy. + private async Task> SecurityOfAsync(string schema) + { + await using NpgsqlCommand command = Server.DataSource.CreateCommand( + """ + SELECT c.relname, c.relrowsecurity, c.relforcerowsecurity, + EXISTS (SELECT 1 FROM pg_policy p WHERE p.polrelid = c.oid AND p.polname = 'tenant_isolation') + FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace + WHERE n.nspname = @schema AND c.relkind IN ('r', 'p') + ORDER BY c.relname + """); + command.Parameters.Add(new NpgsqlParameter("schema", schema)); + await using NpgsqlDataReader reader = await command.ExecuteReaderAsync(Ct); + var rows = new List(); + while (await reader.ReadAsync(Ct)) + { + rows.Add($"{reader.GetString(0)} rls={reader.GetBoolean(1)} forced={reader.GetBoolean(2)} policy={reader.GetBoolean(3)}"); + } + + return rows; + } + + // ================================================================ helpers + + private async Task<(PostgreSqlStore Store, SettableTime Time, DateTimeOffset Boundary)> PartitionedAsync(Action? configure = null) + { + var time = new SettableTime(TimeProvider.System.GetUtcNow()); + PostgreSqlStore store = await Server.CreateStoreAsync(time, o => + { + o.PartitionEvents = true; + configure?.Invoke(o); + }); + DateTimeOffset boundary = (await store.ListEventPartitionsAsync(Ct))[0].To; + return (store, time, boundary); + } + + private static string PartitionName(DateTimeOffset from) + { + return "events_" + from.UtcDateTime.ToString("yyyy_MM", System.Globalization.CultureInfo.InvariantCulture); + } + + private static void Contiguous(IReadOnlyList partitions) + { + for (int i = 1; i < partitions.Count; i++) + { + partitions[i].From.ShouldBe(partitions[i - 1].To, partitions[i].Name); + partitions[i].Name.ShouldBe(PartitionName(partitions[i].From!.Value)); + } + } + + // Events are stamped with the store clock, as the runtime does: created_at decides the partition. + private static Task AppendAsync(PostgreSqlStore store, StreamId stream, ExpectedVersion expected, int count) + { + DateTimeOffset now = store.Time.GetUtcNow(); + return AppendAsync(store, stream, expected, [.. Enumerable.Range(0, count).Select(_ => StorageConformance.Event() with { CreatedAt = now })]); + } + + private static async Task AppendAsync(PostgreSqlStore store, StreamId stream, ExpectedVersion expected, IReadOnlyList events) + { + await using IStorageSession session = await store.BeginAsync(Tenant, Ct); + session.Append(stream, "partition-test", expected, events); + return await session.CommitAsync(Ct); + } + + private async Task PartitionsOfAsync(PostgreSqlStore store, StreamId stream) + { + await using NpgsqlCommand command = Server.DataSource.CreateCommand( + $"SELECT tableoid::regclass::text FROM \"{store.Options.Schema}\".events WHERE stream_id = @s ORDER BY stream_version"); + command.Parameters.Add(new NpgsqlParameter("s", stream.Value)); + var names = new List(); + await using NpgsqlDataReader reader = await command.ExecuteReaderAsync(Ct); + while (await reader.ReadAsync(Ct)) + { + string name = reader.GetString(0); + names.Add(name[(name.LastIndexOf('.') + 1)..].Trim('"')); + } + + return [.. names]; + } + + private static async Task EventuallyAsync(Func> condition) + { + DateTimeOffset deadline = TimeProvider.System.GetUtcNow() + TimeSpan.FromSeconds(20); + while (!await condition()) + { + if (TimeProvider.System.GetUtcNow() > deadline) + { + throw new TimeoutException("The condition was not met."); + } + + await Task.Delay(TimeSpan.FromMilliseconds(50), TimeProvider.System, Ct); + } + } +} + +/// A clock the test sets, forwards or backwards (created_at decides the partition). +internal sealed class SettableTime(DateTimeOffset now) : TimeProvider +{ + private DateTimeOffset _now = now; + + public void SetUtcNow(DateTimeOffset value) + { + _now = value; + } + + public override DateTimeOffset GetUtcNow() + { + return _now; + } +} diff --git a/tests/Storage/SourceFlow.Storage.Tests/PostgreSql/PostgreSqlQueryTests.cs b/tests/Storage/SourceFlow.Storage.Tests/PostgreSql/PostgreSqlQueryTests.cs new file mode 100644 index 00000000..043c4621 --- /dev/null +++ b/tests/Storage/SourceFlow.Storage.Tests/PostgreSql/PostgreSqlQueryTests.cs @@ -0,0 +1,432 @@ +using System.Globalization; +using Npgsql; +using System.Text; +using System.Text.Json; +using Bank.Accounts; +using CsCheck; +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.DependencyInjection.Extensions; +using Microsoft.Extensions.Hosting; +using SourceFlow.Hosting; +using SourceFlow.Messaging; +using SourceFlow.Query; +using SourceFlow.Runtime; +using SourceFlow.Storage.PostgreSQL; +using SourceFlow.Storage.PostgreSQL.Query; + +namespace SourceFlow.Storage.Tests.PostgreSql; + +/// +/// QRY-01..20, 40..60: the SFQL PostgreSQL compiler (doc 14 §7, §10, §12; WP-2.8). Every query runs twice over the same +/// PostgreSQL data, compiled to SQL and in the in-memory interpreter, and the rows must be identical (cross-provider +/// equivalence). Golden SQL, the injection corpus and the no-literal property cover ADR-026. +/// +[Collection(PostgreSqlCollection.Name)] +[Trait("Category", "Integration")] +[Trait("Provider", "PostgreSQL")] +[Trait("Requires", "Docker")] +public sealed class PostgreSqlQueryTests(PostgreSqlServer server) : PostgreSqlTest(server) +{ + private static readonly RuntimeModel Model = new SourceFlowModelBuilder().AddModule().Build(); + private static readonly QueryCatalog Catalog = QueryCatalog.Build(Model); + + private IHost _host = null!; + private string _schema = null!; + private ServiceProvider _reference = null!; + private readonly List _accounts = []; + private readonly List _results = []; + + private static CancellationToken Ct => TestContext.Current.CancellationToken; + + private IQueryService Compiled => _host.Services.GetRequiredService(); + + private IQueryService Interpreted => _reference.GetRequiredService(); + + public override async ValueTask InitializeAsync() + { + await base.InitializeAsync(); + string schema = _schema = PostgreSqlServer.NewSchema("q"); + HostApplicationBuilder builder = Host.CreateApplicationBuilder(new HostApplicationBuilderSettings { EnvironmentName = Environments.Development, DisableDefaults = true }); + builder.Services.AddSourceFlow(sf => Configure(sf, schema)); + _host = builder.Build(); + await _host.StartAsync(Ct); + + // The reference: the same schema through the interpreter (no provider engine). + var services = new ServiceCollection(); + services.AddSourceFlow(sf => Configure(sf, schema)); + services.RemoveAll(); + _reference = services.BuildServiceProvider(); + + ICommandSender commands = _host.Services.GetRequiredService(); + string[] holders = ["Ada", "Grace", "Linus", "Barbara", "Edsger", "adam", "Zed"]; + for (int i = 0; i < holders.Length; i++) + { + var id = AccountId.New(); + _accounts.Add(id); + _results.Add(await commands.SendAsync(new OpenAccount(id, holders[i], 100m + i), null, Ct)); + if (i is > 0 and < 5) + { + _results.Add(await commands.SendAsync(new Deposit(id, 150m * i + 0.25m), null, Ct)); + } + } + + _results.Add(await commands.SendAsync(new Withdraw(_accounts[1], 50m), null, Ct)); + _results.Add(await commands.SendAsync(new Deposit(_accounts[1], 50m), null, Ct)); + _results.Add(await commands.SendAsync(new CloseAccount(_accounts[4], "moved"), null, Ct)); + _results.ShouldAllBe(r => r.Status == CommandStatus.Accepted); + } + + public override async ValueTask DisposeAsync() + { + await _reference.DisposeAsync(); + await _host.StopAsync(CancellationToken.None); + _host.Dispose(); + await base.DisposeAsync(); + } + + public static TheoryData EquivalentQueries => new() + { + { "QRY-01", "from readmodel \"account-summary\" | where balance >= 250 | project holder, balance | order by balance desc" }, + { "QRY-02", "from readmodel \"account-summary\" | summarize n = count(), total = sum(balance), smallest = min(balance), biggest = max(balance)" }, + { "QRY-03", "from readmodel \"account-summary\" | project holder | order by holder" }, + { "QRY-04", "from readmodel \"account-summary\" | where holder like 'A%' or holder in ('Grace', 'Zed') | project holder | order by holder desc" }, + { "QRY-05", "from readmodel \"account-summary\" | where balance between 200 and 600 and not (holder = 'Linus') | project holder, status, version" }, + { "QRY-06", "from readmodel \"account-summary\" | project holder, doubled = balance * 2, third = round(balance / 3, 4), up = upper(holder), n = length(holder), tag = concat(holder, '-', status)" }, + { "QRY-07", "from readmodel \"account-summary\" | summarize n = count(), total = sum(balance) by status | order by status" }, + { "QRY-08", "from readmodel \"account-summary\" | summarize n = count() by status | where n > 1" }, + { "QRY-09", "from events of \"bank.account.deposited\", \"bank.account.withdrawn\" | where time >= ago(1d) | summarize n = count(), total = sum(data.amount), biggest = max(data.amount) by type | order by type" }, + { "QRY-10", "from events of \"bank.account.opened\" | where time >= ago(1d) | project stream, version, typeversion, holder = data.holder, deposit = data.initialDeposit" }, + { "QRY-11", "from events of \"bank.account.deposited\" | where time >= ago(1d) | project position, aggregatekey, amount = data.amount, after = data.balanceAfter | order by amount desc" }, + { "QRY-12", "from events of \"bank.account.opened\", \"bank.account.deposited\" | where time >= ago(1d) | summarize n = count(), missing = count(data.initialDeposit) by type" }, + { "QRY-13", "from events of \"bank.account.opened\" | where time >= ago(1d) | summarize n = count() by day = bin(time, 1d)" }, + { "QRY-14", "from readmodel \"account-summary\" as a | join events of \"bank.account.withdrawn\" as e on e.aggregatekey = a.id | project a.holder, e.data.amount" }, + { "QRY-15", "from readmodel \"account-summary\" as a | join kind=left events of \"bank.account.closed\" as e on e.aggregatekey = a.id | project a.holder, reason = e.data.reason | order by a.holder" }, + { "QRY-16", "from readmodel \"account-summary\" | where coalesce(null, balance) > 300 and holder is not null | project holder, b = coalesce(balance, 0)" }, + { "QRY-17", "from events of \"bank.account.deposited\" | where time >= ago(1d) and data.amount > 300 | project amount = data.amount, big = case when data.amount > 500 then 'big' else 'small' end" }, + { "QRY-18", "from events of \"bank.account.opened\" | where time >= ago(1d) and has_tag('vip') | project stream" }, + }; + + [Theory] + [Trait("Covers", "doc 14 12")] + [MemberData(nameof(EquivalentQueries))] + public async Task CompiledAndInterpreted_GiveTheSameRows(string id, string query) + { + _ = id; + IReadOnlyList compiled = await RowsAsync(Compiled, query); + IReadOnlyList interpreted = await RowsAsync(Interpreted, query); + + compiled.ShouldBe(interpreted, $"{id}: {query}"); + } + + [Fact] + [Trait("Id", "QRY-19")] + [Trait("Covers", "doc 14 12")] + public async Task SqlSyntax_Subqueries_AreEquivalent() + { + var sql = new QueryOptions { Language = QueryLanguage.Sql }; + string[] queries = + [ + "SELECT holder FROM readmodel.\"account-summary\" WHERE id IN (SELECT aggregatekey FROM events.\"bank.account.withdrawn\" WHERE time >= ago(7d)) ORDER BY holder", + "SELECT a.holder FROM readmodel.\"account-summary\" a WHERE NOT EXISTS (SELECT 1 FROM events.\"bank.account.deposited\" e WHERE e.aggregatekey = a.id) ORDER BY a.holder", + "SELECT DISTINCT status FROM readmodel.\"account-summary\" ORDER BY status", + "SELECT status, COUNT(*) AS n, SUM(balance) AS total FROM readmodel.\"account-summary\" GROUP BY status HAVING SUM(balance) > 100 ORDER BY total DESC", + ]; + + foreach (string query in queries) + { + IReadOnlyList compiled = await RowsAsync(Compiled, query, options: sql); + compiled.ShouldBe(await RowsAsync(Interpreted, query, options: sql), query); + compiled.ShouldNotBeEmpty(query); + } + + (await RowsAsync(Compiled, queries[0], options: sql)).ShouldBe(["Grace"]); + (await RowsAsync(Compiled, queries[1], options: sql)).ShouldBe(["Ada", "Zed", "adam"]); // ordinal: upper case first + } + + [Fact] + [Trait("Id", "QRY-20")] + [Trait("Covers", "doc 14 7.4")] + public async Task KeysetPages_AreInterchangeableBetweenEngines() + { + const string query = "from events of \"bank.account.opened\", \"bank.account.deposited\" | where time >= ago(1d) | project stream, type, version"; + var options = new QueryOptions { PageSize = 3 }; + var mixed = new List(); + string? continuation = null; + int page = 0; + do + { + // Alternate engines page by page: the continuation token is engine-neutral. + QueryPage result = await (page++ % 2 == 0 ? Compiled : Interpreted).QueryPageAsync(query, continuation: continuation, options: options, cancellationToken: Ct); + mixed.AddRange(result.Rows.Select(Render)); + continuation = result.Continuation; + } + while (continuation is not null); + + mixed.Count.ShouldBe(12); // 7 opened + 5 deposited + mixed.ShouldBe(await RowsAsync(Compiled, query, options: new QueryOptions { PageSize = 100 })); + } + + [Fact] + [Trait("Id", "QRY-40")] + [Trait("Covers", "doc 14 12")] + public async Task PositionAndStream_Predicates() + { + GlobalPosition middle = _results[5].Token.Position; + IReadOnlyDictionary parameters = new Dictionary { ["p"] = middle.ToString() }; + const string query = "from events of \"bank.account.deposited\" | where position > @p and time >= ago(1d) | project position, amount = data.amount"; + + IReadOnlyList compiled = await RowsAsync(Compiled, query, parameters); + compiled.ShouldBe(await RowsAsync(Interpreted, query, parameters)); + compiled.ShouldNotBeEmpty(); + + IReadOnlyDictionary stream = new Dictionary { ["s"] = StreamId.For(BankAccount.AggregateName, _accounts[1]).Value }; + const string streamQuery = "from stream @s | project version, type"; + (await RowsAsync(Compiled, streamQuery, stream)).ShouldBe(await RowsAsync(Interpreted, streamQuery, stream)); + (await RowsAsync(Compiled, streamQuery, stream)).Count.ShouldBe(4); + } + + [Fact] + [Trait("Id", "SCK-69")] + [Trait("Covers", "doc 05 9;doc 14 12")] + public async Task ArchivedStreams_AreLeftOut_UnlessIncludeArchived_InBothEngines() + { + await _host.Services.GetRequiredService().ArchiveStreamAsync(MessageEnvelope.DefaultTenant, StreamId.For(BankAccount.AggregateName, _accounts[2]), Ct); + string[] queries = + [ + "from events of \"bank.account.opened\", \"bank.account.deposited\" | where time >= ago(1d) | summarize n = count() by type | order by type", + "from events of \"bank.account.opened\", \"bank.account.deposited\" | where time >= ago(1d) | summarize n = count() by type | order by type options (include_archived = true)", + "from readmodel \"account-summary\" as a | join events of \"bank.account.deposited\" as e on e.aggregatekey = a.id | project a.holder, e.data.amount | order by holder", + ]; + + foreach (string query in queries) + { + (await RowsAsync(Compiled, query)).ShouldBe(await RowsAsync(Interpreted, query), query); + } + + (await RowsAsync(Compiled, queries[0])).ShouldBe(["bank.account.deposited | 4", "bank.account.opened | 6"]); + (await RowsAsync(Compiled, queries[1])).ShouldBe(["bank.account.deposited | 5", "bank.account.opened | 7"]); + (await RowsAsync(Compiled, queries[2])).ShouldNotContain(r => r.StartsWith("Linus", StringComparison.Ordinal)); + } + + [Fact] + [Trait("Id", "QRY-41")] + [Trait("Covers", "doc 14 8")] + public async Task Tenancy_And_ReadOnly() + { + var other = new QueryOptions { Tenant = "someone-else" }; + (await RowsAsync(Compiled, "from readmodel \"account-summary\"", options: other)).ShouldBeEmpty(); + (await RowsAsync(Compiled, "from events of \"bank.account.opened\" | where time >= ago(1d)", options: other)).ShouldBeEmpty(); + (await RowsAsync(Compiled, "from events of \"bank.account.opened\" | where time >= ago(1d) | summarize n = count() options (tenants = 'all')")).ShouldBe(["7"]); + } + + [Fact] + [Trait("Id", "QRY-42")] + [Trait("Covers", "ADR-026")] + public void GoldenSql_ReadModel() + { + CompiledQuery compiled = Compile( + "from readmodel \"account-summary\" | where status = 1 and balance < @below | project id, balance | order by balance | take 50", + new Dictionary { ["below"] = 0m }); + + compiled.Sql.ShouldBe( + "SELECT * FROM (SELECT t0.id AS o0, (t0.data->>'balance')::numeric AS o1, (t0.data->>'balance')::numeric AS k0, t0.id AS k1 " + + "FROM sf.documents t0 WHERE t0.tenant_id = $1::text AND t0.collection = $2::text " + + "AND ((((t0.data->>'status')::bigint) = ($3::bigint)) AND (((t0.data->>'balance')::numeric) < ($4::numeric)))) q " + + "ORDER BY q.k0 ASC NULLS LAST, q.k1 COLLATE \"C\" ASC NULLS LAST OFFSET $5::bigint LIMIT $6::bigint"); + compiled.Parameters.Select(p => p.Value).ShouldBe(["-", "account-summary@1", 1L, 0m, 0L, 51L]); + } + + [Fact] + [Trait("Id", "QRY-43")] + [Trait("Covers", "ADR-026")] + public void GoldenSql_EventsWithHorizonAndTieBreak() + { + CompiledQuery compiled = Compile("from events of \"bank.account.deposited\" | where data.amount >= @min and time >= ago(7d) | project stream, amount = data.amount | order by time desc", + new Dictionary { ["min"] = 10m }); + + compiled.Sql.ShouldContain("t0.event_type IN ($2::text)"); + compiled.Sql.ShouldContain("t0.tx_id < pg_snapshot_xmin(pg_current_snapshot())"); + compiled.Sql.ShouldContain("(t0.created_at) >= (($4::timestamptz - ($5::interval)))"); + compiled.Sql.ShouldContain("ORDER BY q.k0 DESC NULLS FIRST, q.k1_c ASC NULLS LAST, q.k1_s ASC NULLS LAST"); + } + + [Fact] + [Trait("Id", "QRY-44")] + [Trait("Covers", "ADR-026")] + public async Task InjectionCorpus_IsRejectedOrHarmless() + { + string[] rejected = + [ + "SELECT * FROM readmodel.\"account-summary\"; DROP TABLE x", + "SELECT * FROM readmodel.\"account-summary\" WHERE holder = 'a' -- ' OR 1=1", + "SELECT * FROM readmodel.\"account-summary\" /* x */", + "SELECT usename FROM pg_catalog.pg_user", + "SELECT * FROM information_schema.tables", + "UPDATE readmodel.\"account-summary\" SET balance = 0", + "SELECT * FROM readmodel.\"account-summary\" UNION SELECT * FROM readmodel.\"account-summary\"", + "SELECT pg_sleep(10)", + "SELECT * FROM readmodel.\"account-summary\" WHERE holder = 'a‮'", + "SELECT * FROM readmodel.\"account-summary\" WHERE holder = 'a\0'", + "SELECT * FROM \"q_x\".outbox", + ]; + foreach (string text in rejected) + { + QueryException e = await Should.ThrowAsync(async () => + await Compiled.QueryPageAsync(text, options: new QueryOptions { Language = QueryLanguage.Sql }, cancellationToken: Ct)); + e.Code.ShouldStartWith("SFQ0", customMessage: text); + int stage = int.Parse(e.Code.AsSpan(3, 2), CultureInfo.InvariantCulture); // SFQ01xx syntax, SFQ02xx bind + stage.ShouldBeInRange(1, 2, text); + } + + string[] payloads = + [ + "Open' OR '1'='1", + "'; DROP TABLE documents; --", + "\\'; SELECT pg_sleep(5); --", + "", + "%' OR 1=1 OR holder LIKE '%", + "Ada' UNION SELECT usename FROM pg_user --", + "Аda", + ]; + foreach (string payload in payloads) + { + var parameters = new Dictionary { ["h"] = payload }; + (await RowsAsync(Compiled, "from readmodel \"account-summary\" | where holder = @h or holder like @h", parameters)).ShouldBeEmpty(payload); + (await RowsAsync(Compiled, "from readmodel \"account-summary\" | where holder = @h", parameters)).ShouldBeEmpty(payload); + } + + // Stored markup is data: it is returned as a string, never interpreted. + (await RowsAsync(Compiled, "from readmodel \"account-summary\" | where holder = 'Ada' | project holder")).ShouldBe(["Ada"]); + } + + [Fact] + [Trait("Id", "QRY-45")] + [Trait("Covers", "doc 14 7.2")] + public async Task IndexSync_CreatesQueryableIndexes_Idempotently_AndThePlannerUsesThem() + { + QueryCatalog catalog = QueryCatalog.Build(_host.Services.GetRequiredService()); + + QueryIndexPlan first = await PostgreSqlIndexSync.ApplyAsync(Server.DataSource, catalog, _schema, concurrently: false, Ct); + QueryIndexPlan second = await PostgreSqlIndexSync.ApplyAsync(Server.DataSource, catalog, _schema, concurrently: true, Ct); + + first.Create.Select(i => i.Source).ShouldBe(["account-summary@1.status", "bank.account.deposited.accountId"]); + first.Create.ShouldAllBe(i => i.Name.StartsWith(PostgreSqlIndexSync.Prefix, StringComparison.Ordinal)); + second.Create.ShouldBeEmpty(); + second.Unchanged.Count.ShouldBe(2); + + // The compiled predicate matches the index expression: with sequential scans off, the plan uses it. + CompiledQuery compiled = Compile("from readmodel \"account-summary\" | where status = 1 | project holder", new Dictionary(), _schema); + await using NpgsqlConnection connection = await Server.DataSource.OpenConnectionAsync(Ct); + await using var batch = new NpgsqlBatch(connection); + batch.BatchCommands.Add(new NpgsqlBatchCommand("SET enable_seqscan = off")); + var explain = new NpgsqlBatchCommand("EXPLAIN " + compiled.Sql); + foreach (NpgsqlParameter parameter in compiled.Parameters) + { + explain.Parameters.Add(parameter); + } + batch.BatchCommands.Add(explain); + var plan = new StringBuilder(); + await using (NpgsqlDataReader reader = await batch.ExecuteReaderAsync(Ct)) + { + while (await reader.ReadAsync(Ct)) + { + plan.AppendLine(reader.GetString(0)); + } + } + + string index = first.Create.Single(i => i.Source == "account-summary@1.status").Name; + plan.ToString().ShouldContain(index); + } + + [Fact] + [Trait("Id", "QRY-60")] + [Trait("Category", "Property")] + [Trait("Covers", "ADR-026")] + public void NoLiteral_EverRequestValueIsAParameter() + { + string[] templates = + [ + "from readmodel \"account-summary\" | where holder = {0} | project holder", + "from readmodel \"account-summary\" | where holder like {0} or holder in ({0}, 'x') | project holder", + "from readmodel \"account-summary\" | project holder, tag = concat(holder, {0}) | order by tag", + "from events of \"bank.account.closed\" | where time >= ago(1d) and data.reason = {0}", + "from readmodel \"account-summary\" | where coalesce(holder, {0}) = {0} | summarize n = count() by status", + ]; + Gen.String[Gen.Char.AlphaNumeric, 6, 24] + .Select(Gen.Int[0, templates.Length - 1]) + .Sample((literal, template) => + { + string marker = "zq" + literal; + string text = string.Format(CultureInfo.InvariantCulture, templates[template], "'" + marker + "'"); + CompiledQuery compiled = Compile(text, new Dictionary()); + compiled.Sql.ShouldNotContain(marker); + compiled.Parameters.ShouldContain(p => Equals(p.Value, marker)); + }, iter: 200); + + // Opaque paths on untyped events come from the request too: the path is bound, never inlined (CR-37). + Gen.String[Gen.Char.AlphaNumeric, 6, 24].Sample(literal => + { + string marker = "zq" + literal; + foreach (string text in new[] { $"from events | where sfcorrelationid = @c and exists data.{marker}.inner", $"from events | where sfcorrelationid = @c and data.{marker} is null" }) + { + CompiledQuery compiled = Compile(text, new Dictionary { ["c"] = "x" }); + compiled.Sql.ShouldNotContain(marker, customMessage: text); + } + }, iter: 100); + } + + // ================================================================ helpers + + private void Configure(SourceFlowBuilder sf, string schema) + { + sf.ServiceName = "accounts"; + sf.AddModule(); + sf.Projections(p => p.Add().Inline()); + sf.UsePostgreSql(o => + { + o.Schema = schema; + o.DataSource = Server.DataSource; + }); + sf.UseInMemoryTransport(); + } + + private static CompiledQuery Compile(string text, IReadOnlyDictionary parameters, string schema = "sf") + { + ParseResult parsed = SfqlParser.Parse(text, QueryLanguage.Sfql, QueryLimits.Default); + parsed.Diagnostics.ShouldBeEmpty(); + BindResult bound = SfqlBinder.Bind(parsed.Query!, text, Catalog); + bound.Diagnostics.ShouldBeEmpty(); + var execution = new QueryExecution(bound.Query!, parameters, "-", new DateTimeOffset(2026, 11, 11, 0, 0, 0, TimeSpan.Zero), null, 0, 51, QueryPolicySettings.Default); + return PostgreSqlQueryCompiler.Compile(execution, schema); + } + + private static async Task> RowsAsync(IQueryService service, string query, IReadOnlyDictionary? parameters = null, QueryOptions? options = null) + { + var rows = new List(); + await foreach (QueryRow row in service.QueryAsync(query, parameters, options, Ct)) + { + rows.Add(Render(row)); + } + + return rows; + } + + private static string Render(QueryRow row) + { + return string.Join(" | ", row.Values.Select(Render)); + } + + private static string Render(object? value) + { + return value switch + { + null => "null", + decimal d => (d / 1.0000000000000000000000000000m).ToString(CultureInfo.InvariantCulture), + DateTimeOffset t => t.UtcDateTime.ToString("O", CultureInfo.InvariantCulture), + JsonElement e => e.GetRawText(), + string[] tags => "[" + string.Join(",", tags) + "]", + IFormattable f => f.ToString(null, CultureInfo.InvariantCulture), + _ => value.ToString() ?? string.Empty, + }; + } +} diff --git a/tests/Storage/SourceFlow.Storage.Tests/PostgreSql/PostgreSqlServer.cs b/tests/Storage/SourceFlow.Storage.Tests/PostgreSql/PostgreSqlServer.cs new file mode 100644 index 00000000..f3f73d3f --- /dev/null +++ b/tests/Storage/SourceFlow.Storage.Tests/PostgreSql/PostgreSqlServer.cs @@ -0,0 +1,193 @@ +using Npgsql; +using SourceFlow.Storage.PostgreSQL; +using SourceFlow.Storage.Tests.PostgreSql; +using Testcontainers.PostgreSql; + +[assembly: AssemblyFixture(typeof(PostgreSqlServer))] + +namespace SourceFlow.Storage.Tests.PostgreSql; + +/// +/// One PostgreSQL server per test run: a Testcontainers container, or the server in SOURCEFLOW_TEST_POSTGRES. +/// Tests isolate themselves with a fresh schema each (), so they never share state. +/// +public sealed class PostgreSqlServer : IAsyncLifetime +{ + /// The default image; the nightly matrix overrides it with SOURCEFLOW_TEST_POSTGRES_IMAGE (15, 16, 17). + public const string DefaultImage = "postgres:17-alpine"; + + private PostgreSqlContainer? _container; + + public string ConnectionString { get; private set; } = string.Empty; + + /// A pooled data source for the superuser, shared by every test store. + public NpgsqlDataSource DataSource { get; private set; } = null!; + + private readonly Lazy _started; + + public PostgreSqlServer() + { + _started = new Lazy(StartAsync); + } + + // The server starts on first use, so test runs that select no PostgreSQL test never need Docker. + public ValueTask InitializeAsync() + { + return ValueTask.CompletedTask; + } + + public Task EnsureStartedAsync() + { + return _started.Value; + } + + private async Task StartAsync() + { + string? external = Environment.GetEnvironmentVariable("SOURCEFLOW_TEST_POSTGRES"); + if (!string.IsNullOrWhiteSpace(external)) + { + ConnectionString = external; + } + else + { + string image = Environment.GetEnvironmentVariable("SOURCEFLOW_TEST_POSTGRES_IMAGE") is { Length: > 0 } custom ? custom : DefaultImage; + _container = new PostgreSqlBuilder(image).WithCommand("-c", "max_connections=300").Build(); + await _container.StartAsync(); + ConnectionString = _container.GetConnectionString(); + } + + DataSource = NpgsqlDataSource.Create(ConnectionString); + } + + public async ValueTask DisposeAsync() + { + if (DataSource is not null) + { + await DataSource.DisposeAsync(); + } + + if (_container is not null) + { + await _container.DisposeAsync(); + } + } + + /// A unique, valid schema name. + public static string NewSchema(string prefix = "t") + { + return prefix + "_" + Guid.CreateVersion7().ToString("N"); + } + + /// + /// True for the partitioned-events leg of the nightly matrix (SOURCEFLOW_TEST_DATABASE=postgres:17-partitioned): + /// every store this fixture creates then partitions its events table (doc 05 §9). + /// + public static bool PartitionedVariant { get; } = + Environment.GetEnvironmentVariable("SOURCEFLOW_TEST_DATABASE")?.EndsWith("-partitioned", StringComparison.Ordinal) == true; + + /// A store on a fresh, migrated schema. + public async Task CreateStoreAsync(TimeProvider? time = null, Action? configure = null) + { + var options = new PostgreSqlStorageOptions { DataSource = DataSource, Schema = NewSchema(), PartitionEvents = PartitionedVariant }; + configure?.Invoke(options); + var store = new PostgreSqlStore(options, time); + await store.CreateMigrator().MigrateAsync(TestContext.Current.CancellationToken); + return store; + } + + private readonly string _roleSuffix = Guid.CreateVersion7().ToString("N")[..12]; + private readonly SemaphoreSlim _rolesGate = new(1, 1); + private bool _rolesCreated; + + /// The application role: DML only, subject to row-level security (superusers always bypass it). + public string AppRole => "sf_app_" + _roleSuffix; + + /// The cross-tenant reader role: DML and BYPASSRLS (ADR-022). + public string SystemRole => "sf_system_" + _roleSuffix; + + /// The connection string of a role created by . + public string ConnectionStringFor(string role) + { + return new NpgsqlConnectionStringBuilder(ConnectionString) { Username = role, Password = role }.ConnectionString; + } + + /// + /// A store with on a fresh schema: migrated by the superuser (the owner), + /// used through , with for the global log. + /// + public async Task CreateRowLevelSecurityStoreAsync(TimeProvider? time = null, string? schema = null) + { + schema ??= NewSchema("rls"); + await new PostgreSqlSchemaMigrator(DataSource, schema, TenantIsolation.RowLevelSecurity, PartitionedVariant).MigrateAsync(TestContext.Current.CancellationToken); + await GrantAsync(schema); + return new PostgreSqlStore(RowLevelSecurityOptions(schema), time); + } + + /// Options for and on a schema (call first). + public PostgreSqlStorageOptions RowLevelSecurityOptions(string schema) + { + return new PostgreSqlStorageOptions + { + ConnectionString = ConnectionStringFor(AppRole), + SystemConnectionString = ConnectionStringFor(SystemRole), + Schema = schema, + TenantIsolation = TenantIsolation.RowLevelSecurity, + PartitionEvents = PartitionedVariant, + }; + } + + /// Grants both test roles DML on a migrated schema. + public async Task GrantAsync(string schema) + { + await _rolesGate.WaitAsync(TestContext.Current.CancellationToken); + try + { + if (!_rolesCreated) + { + await ExecuteAsync($"CREATE ROLE \"{AppRole}\" LOGIN PASSWORD '{AppRole}'"); + await ExecuteAsync($"CREATE ROLE \"{SystemRole}\" LOGIN BYPASSRLS PASSWORD '{SystemRole}'"); + _rolesCreated = true; + } + } + finally + { + _rolesGate.Release(); + } + + await ExecuteAsync($""" + GRANT USAGE ON SCHEMA "{schema}" TO "{AppRole}", "{SystemRole}"; + GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA "{schema}" TO "{AppRole}", "{SystemRole}"; + GRANT USAGE ON ALL SEQUENCES IN SCHEMA "{schema}" TO "{AppRole}", "{SystemRole}"; + """); + } + + /// Runs one SQL statement as the superuser. + public async Task ExecuteAsync(string sql) + { + await using NpgsqlCommand command = DataSource.CreateCommand(sql); + await command.ExecuteNonQueryAsync(TestContext.Current.CancellationToken); + } +} + +/// Base of PostgreSQL tests: starts the shared server before each test. +public abstract class PostgreSqlTest(PostgreSqlServer server) : IAsyncLifetime +{ + protected PostgreSqlServer Server { get; } = server; + + public virtual async ValueTask InitializeAsync() + { + await Server.EnsureStartedAsync(); + } + + public virtual ValueTask DisposeAsync() + { + return ValueTask.CompletedTask; + } +} + +/// PostgreSQL tests that assert on the global log run one at a time: the safe horizon is cluster-wide (doc 05 §5.4). +[CollectionDefinition(Name, DisableParallelization = true)] +public sealed class PostgreSqlCollection +{ + public const string Name = "PostgreSQL"; +} diff --git a/tests/Storage/SourceFlow.Storage.Tests/PostgreSql/PostgreSqlStorageConformanceTests.cs b/tests/Storage/SourceFlow.Storage.Tests/PostgreSql/PostgreSqlStorageConformanceTests.cs new file mode 100644 index 00000000..ab478f82 --- /dev/null +++ b/tests/Storage/SourceFlow.Storage.Tests/PostgreSql/PostgreSqlStorageConformanceTests.cs @@ -0,0 +1,91 @@ +using SourceFlow.Storage.PostgreSQL; +using SourceFlow.Testing.Conformance; + +namespace SourceFlow.Storage.Tests.PostgreSql; + +/// An over a PostgreSQL store on its own schema. +internal sealed class PostgreSqlStorageFixture(PostgreSqlStore store) : IStorageFixture +{ + public PostgreSqlStore Store { get; } = store; + + public IEventStore Events => Store; + + public IEventLogReader Log => Store; + + public IStorageSessionFactory Sessions => Store; + + public ICheckpointStore Checkpoints => Store; + + public ILeaseManager Leases => Store; + + public IOutboxStore Outbox => Store; + + public IDeadLetterStore DeadLetters => Store; + + public ISnapshotStore Snapshots => Store; + + public IDocumentReader Documents => Store; + + public IStoreNotifications Notifications => Store; + + // Leases use the database clock by design (doc 05 §7.4); the clock-controlled cases have PostgreSQL variants in PostgreSqlStoreTests. + public bool SupportsClockControl => false; + + public DateTimeOffset Now => TimeProvider.System.GetUtcNow(); + + public ValueTask AdvanceClockAsync(TimeSpan by) + { + throw new NotSupportedException("The PostgreSQL store uses the database clock for leases."); + } + + public ValueTask DisposeAsync() + { + return Store.DisposeAsync(); + } +} + +/// The storage conformance kit against PostgreSQL (SCK-01..58, plan 06 §2; WP-2.2–2.4, WP-2.9). +[Collection(PostgreSqlCollection.Name)] +[Trait("Category", "Integration")] +[Trait("Provider", "PostgreSQL")] +[Trait("Requires", "Docker")] +public sealed class PostgreSqlStorageConformanceTests(PostgreSqlServer server) : PostgreSqlTest(server) +{ + public static TheoryData CaseIds => new(StorageConformance.Cases.Select(c => c.Id)); + + [Theory] + [MemberData(nameof(CaseIds))] + [Trait("Covers", "ADR-008;ADR-009;ADR-010;ES-R1;ES-R2;GAP-15")] + public async Task Sck(string id) + { + ConformanceCase @case = StorageConformance.Cases.Single(c => c.Id == id); + if (@case.RequiresClockControl) + { + Assert.Skip("Needs a controllable store clock; PostgreSQL leases use the database clock (see PostgreSqlStoreTests)."); + } + + await using var fixture = new PostgreSqlStorageFixture(await Server.CreateStoreAsync()); + + await @case.Run(fixture, TestContext.Current.CancellationToken); + } + + [Fact] + [Trait("Id", "SCK-L01")] + [Trait("Category", "Property")] + [Trait("Covers", "ADR-006;ADR-008")] + public void AppendsAndOutbox_AreLinearizable() + { + SourceFlow.Tests.Shared.StorageLinearizability.AppendsAndOutbox( + () => new PostgreSqlStorageFixture(Server.CreateStoreAsync().GetAwaiter().GetResult()), iterations: 40, threads: 4); + } + + [Fact] + [Trait("Id", "SCK-L01")] + [Trait("Category", "Property")] + [Trait("Covers", "ADR-022")] + public void AppendsAndOutbox_AreLinearizable_UnderRowLevelSecurity() + { + SourceFlow.Tests.Shared.StorageLinearizability.AppendsAndOutbox( + () => new PostgreSqlStorageFixture(Server.CreateRowLevelSecurityStoreAsync().GetAwaiter().GetResult()), iterations: 20, threads: 4); + } +} diff --git a/tests/Storage/SourceFlow.Storage.Tests/PostgreSql/PostgreSqlStoreTests.cs b/tests/Storage/SourceFlow.Storage.Tests/PostgreSql/PostgreSqlStoreTests.cs new file mode 100644 index 00000000..a3e9987c --- /dev/null +++ b/tests/Storage/SourceFlow.Storage.Tests/PostgreSql/PostgreSqlStoreTests.cs @@ -0,0 +1,408 @@ +using System.Text; +using Microsoft.Extensions.Time.Testing; +using Npgsql; +using SourceFlow.Messaging; +using SourceFlow.Storage.PostgreSQL; +using SourceFlow.Testing.Conformance; + +namespace SourceFlow.Storage.Tests.PostgreSql; + +/// +/// PostgreSQL-specific behaviour (WP-2.2–2.4): the clock-controlled SCK cases with the real database clock, LISTEN across +/// processes, the xmin horizon (doc 05 §5), byte-exact payloads (ADR-028) and custom SQL in the session transaction. +/// +[Collection(PostgreSqlCollection.Name)] +[Trait("Category", "Integration")] +[Trait("Provider", "PostgreSQL")] +[Trait("Requires", "Docker")] +public sealed class PostgreSqlStoreTests(PostgreSqlServer server) : PostgreSqlTest(server) +{ + private const string Tenant = MessageEnvelope.DefaultTenant; + private static readonly StreamId Stream = new("pg-a-1"); + + private static CancellationToken Ct => TestContext.Current.CancellationToken; + + [Fact] + [Trait("Id", "SCK-33")] + public async Task OutboxDueTimes_FollowTheStoreClock() + { + var time = new FakeTimeProvider(new DateTimeOffset(2026, 6, 1, 0, 0, 0, TimeSpan.Zero)); + await using PostgreSqlStore store = await Server.CreateStoreAsync(time); + await EnqueueAsync(store, Row("timer", time.GetUtcNow().AddMinutes(5))); + LeaseToken lease = (await store.TryAcquireAsync("outbox:0", "node-1", TimeSpan.FromMinutes(1), Ct))!; + + (await store.ClaimAsync(0, lease, 10, Ct)).ShouldBeEmpty(); + (await store.DueOutboxCountAsync(Ct)).ShouldBe(0); + time.Advance(TimeSpan.FromMinutes(6)); + + (await store.ClaimAsync(0, lease, 10, Ct)).Count.ShouldBe(1); + (await store.DueOutboxCountAsync(Ct)).ShouldBe(1); + } + + [Fact] + [Trait("Id", "UT-SUB-10")] + [Trait("Covers", "doc 06 4")] + public async Task NodeRegistry_CountsLiveNodesWithTheRole_OnTheDatabaseClock() + { + await using PostgreSqlStore store = await Server.CreateStoreAsync(); + TimeSpan window = TimeSpan.FromSeconds(30); + + (await store.HeartbeatAsync("node-1", 4, window, Ct)).ShouldBe(1); + (await store.HeartbeatAsync("node-2", 4 | 1, window, Ct)).ShouldBe(2); + (await store.HeartbeatAsync("api-only", 0, window, Ct)).ShouldBe(1); // no shared role: counts only itself + (await store.HeartbeatAsync("node-1", 4, window, Ct)).ShouldBe(2); + (await store.HeartbeatAsync("node-1", 4, TimeSpan.FromTicks(1), Ct)).ShouldBe(1); // the others are outside a tiny window + + await store.LeaveAsync("node-2", Ct); + (await store.HeartbeatAsync("node-1", 4, window, Ct)).ShouldBe(1); + } + + [Fact] + [Trait("Id", "UT-CAT-04")] + [Trait("Covers", "doc 14 2.2")] + public async Task SchemaRegistry_IsIdempotent_AndReportsChangedFingerprints() + { + await using PostgreSqlStore store = await Server.CreateStoreAsync(); + var v1 = new SourceFlow.Catalog.SchemaEntry("t.e", 1, SourceFlow.Catalog.SchemaKind.Event, + new System.Text.Json.Nodes.JsonObject { ["type"] = "object", ["title"] = "E" }); + var changed = new SourceFlow.Catalog.SchemaEntry("t.e", 1, SourceFlow.Catalog.SchemaKind.Event, + new System.Text.Json.Nodes.JsonObject { ["type"] = "object", ["title"] = "E", ["required"] = new System.Text.Json.Nodes.JsonArray("id") }); + var v2 = new SourceFlow.Catalog.SchemaEntry("t.e", 2, SourceFlow.Catalog.SchemaKind.Event, + new System.Text.Json.Nodes.JsonObject { ["type"] = "object" }); + + (await store.RegisterAsync("svc", [v1], Ct)).ShouldBeEmpty(); + (await store.RegisterAsync("svc", [v1, v2], Ct)).ShouldBeEmpty(); + SourceFlow.Catalog.SchemaConflict conflict = (await store.RegisterAsync("other", [changed, v2], Ct)).ShouldHaveSingleItem(); + + conflict.ShouldBe(new SourceFlow.Catalog.SchemaConflict("t.e", 1, v1.Fingerprint, changed.Fingerprint)); + IReadOnlyList listed = await ((ISchemaStore)store).ListAsync(Ct); + listed.Select(e => (e.Type, e.Version, e.Fingerprint)).ShouldBe([("t.e", 1, v1.Fingerprint), ("t.e", 2, v2.Fingerprint)]); + } + + [Fact] + [Trait("Id", "UT-CAT-22")] + [Trait("Covers", "ADR-029 2")] + public async Task AFingerprintFromTheEarlierRule_IsReplaced_WhenTheStructureIsUnchanged() + { + await using PostgreSqlStore store = await Server.CreateStoreAsync(); + var v1 = new SourceFlow.Catalog.SchemaEntry("t.old", 1, SourceFlow.Catalog.SchemaKind.Event, + new System.Text.Json.Nodes.JsonObject { ["type"] = "object", ["title"] = "Old" }); + (await store.RegisterAsync("svc", [v1], Ct)).ShouldBeEmpty(); + await Server.ExecuteAsync($"UPDATE \"{store.Options.Schema}\".schemas SET fingerprint = 'sha256:earlier-rule' WHERE message_type = 't.old'"); + + SourceFlow.Catalog.SchemaConflict stale = (await store.RegisterAsync("svc", [v1], Ct)).ShouldHaveSingleItem(); + stale.RegisteredFingerprint.ShouldBe("sha256:earlier-rule"); + (await ((ISchemaStore)store).ListAsync(Ct)).Single(e => e.Type == "t.old").Fingerprint.ShouldBe(v1.Fingerprint, "recomputed from the stored schema, the structure is unchanged"); + await store.ReplaceAsync([v1], Ct); + + (await store.RegisterAsync("svc", [v1], Ct)).ShouldBeEmpty("re-registered once under the current rule"); + } + + [Fact] + [Trait("Id", "SCK-44")] + [Trait("Covers", "ADR-016")] + public async Task Leases_ExpireOnTheDatabaseClock_AndAStolenLeaseFencesTheOldOwner() + { + await using PostgreSqlStore store = await Server.CreateStoreAsync(); + LeaseToken first = (await store.TryAcquireAsync("sub:p:0", "node-1", TimeSpan.FromMilliseconds(300), Ct))!; + (await store.TryAcquireAsync("sub:p:0", "node-2", TimeSpan.FromSeconds(30), Ct)).ShouldBeNull(); + + await RealClock.WaitAsync(TimeSpan.FromMilliseconds(500)); + LeaseToken stolen = (await store.TryAcquireAsync("sub:p:0", "node-2", TimeSpan.FromSeconds(30), Ct))!; + + stolen.Token.ShouldBeGreaterThan(first.Token); + await using IStorageSession session = await store.BeginAsync(Tenant, Ct); + session.SaveCheckpoint("p", 0, new GlobalPosition(5, 1), first); + await Should.ThrowAsync(() => session.CommitAsync(Ct).AsTask()); + } + + [Fact] + [Trait("Id", "SCK-40")] + public async Task ExpiredLease_RejectsTheCheckpoint() + { + await using PostgreSqlStore store = await Server.CreateStoreAsync(); + LeaseToken lease = (await store.TryAcquireAsync("sub:p:0", "node-1", TimeSpan.FromMilliseconds(200), Ct))!; + await RealClock.WaitAsync(TimeSpan.FromMilliseconds(400)); + + await using IStorageSession session = await store.BeginAsync(Tenant, Ct); + session.SaveCheckpoint("p", 0, new GlobalPosition(5, 1), lease); + + await Should.ThrowAsync(() => session.CommitAsync(Ct).AsTask()); + } + + [Fact] + [Trait("Id", "SCK-20")] + [Trait("Covers", "doc 05 8.1")] + public async Task Commit_IsOneRoundTrip_WithEveryKindOfWrite() + { + await using PostgreSqlStore store = await Server.CreateStoreAsync(); + LeaseToken lease = (await store.TryAcquireAsync("sub:p:0", "node-1", TimeSpan.FromSeconds(30), Ct))!; + await using IStorageSession session = await store.BeginAsync(Tenant, Ct); + session.Append(Stream, "pg", ExpectedVersion.NoStream, [StorageConformance.Event(), StorageConformance.Event()]); + session.EnqueueOutbox(Row("k", DateTimeOffset.UnixEpoch)); + session.RecordInbox("pg", new MessageId(Guid.CreateVersion7()), new InboxResult(CommandStatus.Accepted, new StreamVersion(2), null)); + session.Documents.Upsert("docs", "1", 1, "{}"u8.ToArray()); + session.SaveProcessState("pm", "1", 0, "{}"u8.ToArray(), completed: false); + session.SaveCheckpoint("p", 0, new GlobalPosition(1, 1), lease); + + var seen = new List(); + int roundTrips = await CountRoundTripsAsync(() => session.CommitAsync(Ct).AsTask(), seen); + + roundTrips.ShouldBe(1, "the commit's statements: " + string.Join(" | ", seen)); + (await store.GetStreamInfoAsync(Tenant, Stream, Ct))!.Version.ShouldBe(new StreamVersion(2)); + (await store.GetAsync("p", 0, Ct)).ShouldBe(new GlobalPosition(1, 1)); + } + + [Fact] + [Trait("Id", "SCK-20")] + public async Task FailedCheck_InTheBatch_AbortsTheCommit_InOneRoundTrip() + { + await using PostgreSqlStore store = await Server.CreateStoreAsync(); + LeaseToken lease = (await store.TryAcquireAsync("sub:p:0", "node-1", TimeSpan.FromSeconds(30), Ct))!; + await using IStorageSession session = await store.BeginAsync(Tenant, Ct); + session.Documents.Upsert("docs", "1", 1, "{}"u8.ToArray()); + session.SaveCheckpoint("p", 0, new GlobalPosition(1, 1), lease with { Token = lease.Token + 5 }); + + await Should.ThrowAsync(() => session.CommitAsync(Ct).AsTask()); + (await ((IDocumentReader)store).GetAsync(Tenant, "docs", "1", Ct)).ShouldBeNull(); + } + + // Counts the Npgsql commands under the action. Npgsql's own catalog reads (type loading on a new physical connection) + // are not the session's round trips and are left out; what was counted is listed in seen. + private static async Task CountRoundTripsAsync(Func action, List? seen = null) + { + using var source = new System.Diagnostics.ActivitySource("SourceFlow.Tests.RoundTrips"); + int count = 0; + System.Diagnostics.Activity? parent = null; + using var listener = new System.Diagnostics.ActivityListener + { + ShouldListenTo = s => s.Name is "Npgsql" or "SourceFlow.Tests.RoundTrips", + Sample = (ref System.Diagnostics.ActivityCreationOptions _) => System.Diagnostics.ActivitySamplingResult.AllData, + ActivityStopped = a => + { + if (a.Source.Name == "Npgsql" && parent is not null && a.ParentSpanId == parent.SpanId) + { + string text = a.GetTagItem("db.query.text") as string ?? a.GetTagItem("db.statement") as string ?? a.DisplayName; + if (text.Contains("pg_catalog", StringComparison.Ordinal) || text.Contains("pg_type", StringComparison.Ordinal)) + { + return; + } + + if (seen is not null) + { + lock (seen) + { + seen.Add(text.Length > 120 ? text[..120] : text); + } + } + + Interlocked.Increment(ref count); + } + }, + }; + System.Diagnostics.ActivitySource.AddActivityListener(listener); + using (parent = source.StartActivity("commit")) + { + await action(); + } + + return count; + } + + [Fact] + [Trait("Id", "SCK-28")] + public async Task Listen_RelaysCommitsFromAnotherProcess() + { + await using PostgreSqlStore listener = await Server.CreateStoreAsync(); + await using var writer = new PostgreSqlStore(new PostgreSqlStorageOptions { DataSource = Server.DataSource, Schema = listener.Options.Schema }); + var signalled = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously); + using IDisposable subscription = listener.Subscribe(() => signalled.TrySetResult()); + await signalled.Task.WaitAsync(TimeSpan.FromSeconds(10), Ct); // the catch-up signal once LISTEN is active + signalled = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously); + + await AppendAsync(writer, Stream, ExpectedVersion.NoStream); + + await signalled.Task.WaitAsync(TimeSpan.FromSeconds(10), Ct); + } + + [Fact] + [Trait("Id", "SCK-28")] + [Trait("Covers", "doc 05 8.1")] + public async Task LostListenConnection_Reconnects_AndNoCommitIsMissed() + { + await using PostgreSqlStore listener = await Server.CreateStoreAsync(configure: o => o.ListenReconnectDelay = TimeSpan.FromMilliseconds(100)); + await using var writer = new PostgreSqlStore(new PostgreSqlStorageOptions { DataSource = Server.DataSource, Schema = listener.Options.Schema }); + int signals = 0; + var signalled = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously); + using IDisposable subscription = listener.Subscribe(() => + { + Interlocked.Increment(ref signals); + signalled.TrySetResult(); + }); + await signalled.Task.WaitAsync(TimeSpan.FromSeconds(10), Ct); // LISTEN is active + + // Kill the LISTEN backend; while it reconnects, another process commits. + string listen = "LISTEN \"" + listener.Options.Channel + "\""; + await Server.ExecuteAsync($"SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE query = '{listen}'"); + int beforeCommit = Volatile.Read(ref signals); + await AppendAsync(writer, Stream, ExpectedVersion.NoStream); + + // The reconnect raises a catch-up signal, so the commit made while disconnected is never missed. + DateTimeOffset deadline = TimeProvider.System.GetUtcNow() + TimeSpan.FromSeconds(10); + while (Volatile.Read(ref signals) == beforeCommit && TimeProvider.System.GetUtcNow() < deadline) + { + await RealClock.WaitAsync(TimeSpan.FromMilliseconds(20)); + } + + Volatile.Read(ref signals).ShouldBeGreaterThan(beforeCommit); + + // And live notifications flow again on the new connection. + signalled = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously); + await RealClock.WaitAsync(TimeSpan.FromMilliseconds(300)); + signalled = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously); + await AppendAsync(writer, new StreamId("pg-b-2"), ExpectedVersion.NoStream); + await signalled.Task.WaitAsync(TimeSpan.FromSeconds(10), Ct); + } + + [Fact] + [Trait("Id", "SCK-26")] + [Trait("Covers", "ADR-010")] + public async Task InProgressWritingTransaction_HoldsTheHorizon_UntilItEnds() + { + await using PostgreSqlStore store = await Server.CreateStoreAsync(); + await using NpgsqlConnection other = await Server.DataSource.OpenConnectionAsync(Ct); + await using NpgsqlTransaction open = await other.BeginTransactionAsync(Ct); + await using (var write = new NpgsqlCommand($"INSERT INTO \"{store.Options.Schema}\".nodes (node_id, roles, heartbeat_at) VALUES ('x', 0, now())", other, open)) + { + await write.ExecuteNonQueryAsync(Ct); // takes a transaction id + } + + CommitResult committed = await AppendAsync(store, Stream, ExpectedVersion.NoStream); + LogBatch held = await store.ReadAsync(GlobalPosition.Start, BucketRange.All, 10, Ct); + await RealClock.WaitAsync(TimeSpan.FromMilliseconds(100)); + TimeSpan age = await store.GetHorizonAgeAsync(Ct); + await open.CommitAsync(Ct); + LogBatch released = await store.ReadAsync(GlobalPosition.Start, BucketRange.All, 10, Ct); + + held.Events.ShouldBeEmpty(); + held.Horizon.ShouldBeLessThan(committed.LastPosition!.Value); + age.ShouldBeGreaterThan(TimeSpan.Zero); + released.Events.Single().Position.ShouldBe(committed.LastPosition!.Value); + released.Horizon.ShouldBeGreaterThanOrEqualTo(committed.LastPosition!.Value); + } + + [Fact] + [Trait("Id", "SCK-18")] + [Trait("Covers", "ADR-028")] + public async Task Payloads_RoundTripByteForByte_IncludingWhitespaceKeyOrderAndNulEscapes() + { + await using PostgreSqlStore store = await Server.CreateStoreAsync(); + const string data = "{ \"b\" : 1,\n \"a\": [ 1, 2 ], \"b\": \"dup\", \"z\": \"\\u0000\" }"; + + await AppendAsync(store, Stream, ExpectedVersion.NoStream, data); + await using (IStorageSession session = await store.BeginAsync(Tenant, Ct)) + { + session.Documents.Upsert("docs", "1", 1, Encoding.UTF8.GetBytes(data)); + session.SaveProcessState("pm", "1", 0, Encoding.UTF8.GetBytes(data), completed: false); + await session.CommitAsync(Ct); + } + + Encoding.UTF8.GetString((await store.ReadStreamAsync(Tenant, Stream, new StreamVersion(1), 1, Ct)).Events[0].Data.Span).ShouldBe(data); + Encoding.UTF8.GetString((await ((IDocumentReader)store).GetAsync(Tenant, "docs", "1", Ct))!.Data.Span).ShouldBe(data); + await using IStorageSession read = await store.BeginAsync(Tenant, Ct); + Encoding.UTF8.GetString((await read.LoadProcessStateAsync("pm", "1", Ct))!.State.Span).ShouldBe(data); + } + + [Fact] + [Trait("Id", "SCK-63")] + [Trait("Covers", "doc 05 8.1")] + public async Task SessionConnection_RunsCustomSqlInTheSameTransaction() + { + await using PostgreSqlStore store = await Server.CreateStoreAsync(); + string table = $"\"{store.Options.Schema}\".custom_view"; + await Server.ExecuteAsync($"CREATE TABLE {table} (id int PRIMARY KEY)"); + await AppendAsync(store, Stream, ExpectedVersion.NoStream); + + // Custom SQL follows the append (ES-R1): flush it first, so a conflict surfaces before any custom write. + await using (IStorageSession conflicting = await store.BeginAsync(Tenant, Ct)) + { + conflicting.Append(Stream, "pg", ExpectedVersion.NoStream, [StorageConformance.Event()]); + Should.Throw(() => conflicting.Connection, "the append is queued and not yet sent"); + await Should.ThrowAsync(() => conflicting.FlushAsync(Ct).AsTask()); + } + + await using (IStorageSession rolledBack = await store.BeginAsync(Tenant, Ct)) + { + rolledBack.Append(Stream, "pg", ExpectedVersion.Exact(new StreamVersion(1)), [StorageConformance.Event()]); + await rolledBack.FlushAsync(Ct); + await InsertAsync(rolledBack, table, 1); // disposed without a commit: rolled back with the append + } + + await using (IStorageSession committed = await store.BeginAsync(Tenant, Ct)) + { + committed.Append(Stream, "pg", ExpectedVersion.Exact(new StreamVersion(1)), [StorageConformance.Event()]); + await committed.FlushAsync(Ct); + await InsertAsync(committed, table, 2); + await committed.CommitAsync(Ct); + } + + await using NpgsqlCommand count = Server.DataSource.CreateCommand($"SELECT array_agg(id ORDER BY id) FROM {table}"); + ((int[])(await count.ExecuteScalarAsync(Ct))!).ShouldBe([2]); + } + + [Fact] + [Trait("Id", "SCK-20")] + public async Task Commit_WithoutWrites_IsANoOp_AndDisposeRollsBack() + { + await using PostgreSqlStore store = await Server.CreateStoreAsync(); + await using (IStorageSession empty = await store.BeginAsync(Tenant, Ct)) + { + (await empty.CommitAsync(Ct)).ShouldBe(default); + } + + await using (IStorageSession abandoned = await store.BeginAsync(Tenant, Ct)) + { + abandoned.Append(Stream, "pg", ExpectedVersion.NoStream, [StorageConformance.Event()]); + } + + (await store.GetStreamInfoAsync(Tenant, Stream, Ct)).ShouldBeNull(); + await using IStorageSession done = await store.BeginAsync(Tenant, Ct); + await done.CommitAsync(Ct); + Should.Throw(() => done.EnqueueOutbox(Row("k", DateTimeOffset.UnixEpoch))); + } + + private static async Task InsertAsync(IStorageSession session, string table, int id) + { + await using var command = new NpgsqlCommand($"INSERT INTO {table} (id) VALUES ({id})", (NpgsqlConnection)session.Connection!, (NpgsqlTransaction)session.Transaction!); + await command.ExecuteNonQueryAsync(Ct); + } + + private static async Task AppendAsync(PostgreSqlStore store, StreamId stream, ExpectedVersion expected, string data = "{\"n\":1}") + { + await using IStorageSession session = await store.BeginAsync(Tenant, Ct); + session.Append(stream, "pg", expected, [StorageConformance.Event(data: data)]); + return await session.CommitAsync(Ct); + } + + private static async Task EnqueueAsync(PostgreSqlStore store, OutboxMessage message) + { + await using IStorageSession session = await store.BeginAsync(Tenant, Ct); + session.EnqueueOutbox(message); + await session.CommitAsync(Ct); + } + + private static OutboxMessage Row(string key, DateTimeOffset deliverAt) + { + var envelope = new MessageEnvelope + { + MessageId = new MessageId(Guid.CreateVersion7()), + Type = "pg.sent", + TypeVersion = 1, + Source = "pg", + Time = DateTimeOffset.UnixEpoch, + PartitionKey = key, + Body = Encoding.UTF8.GetBytes("{}"), + }; + return new OutboxMessage(envelope, "dest", OutboxKind.Scheduled, deliverAt, 0); + } +} diff --git a/tests/Storage/SourceFlow.Storage.Tests/PostgreSql/PostgreSqlTenancyTests.cs b/tests/Storage/SourceFlow.Storage.Tests/PostgreSql/PostgreSqlTenancyTests.cs new file mode 100644 index 00000000..07346d8b --- /dev/null +++ b/tests/Storage/SourceFlow.Storage.Tests/PostgreSql/PostgreSqlTenancyTests.cs @@ -0,0 +1,149 @@ +using System.Text; +using Npgsql; +using SourceFlow.Storage.PostgreSQL; +using SourceFlow.Testing.Conformance; + +namespace SourceFlow.Storage.Tests.PostgreSql; + +/// The whole storage conformance kit with row-level security on, through the DML-only application role (WP-2.6). +[Collection(PostgreSqlCollection.Name)] +[Trait("Category", "Integration")] +[Trait("Provider", "PostgreSQL")] +[Trait("Requires", "Docker")] +public sealed class PostgreSqlRowLevelSecurityConformanceTests(PostgreSqlServer server) : PostgreSqlTest(server) +{ + public static TheoryData CaseIds => new(StorageConformance.Cases.Where(c => !c.RequiresClockControl).Select(c => c.Id)); + + [Theory] + [MemberData(nameof(CaseIds))] + [Trait("Covers", "ADR-022")] + public async Task Sck(string id) + { + ConformanceCase @case = StorageConformance.Cases.Single(c => c.Id == id); + await using var fixture = new PostgreSqlStorageFixture(await Server.CreateRowLevelSecurityStoreAsync()); + + await @case.Run(fixture, TestContext.Current.CancellationToken); + } +} + +/// SCK-56..60: tenant isolation enforced by the database (ADR-022, WP-2.6). +[Collection(PostgreSqlCollection.Name)] +[Trait("Category", "Integration")] +[Trait("Provider", "PostgreSQL")] +[Trait("Requires", "Docker")] +public sealed class PostgreSqlTenancyTests(PostgreSqlServer server) : PostgreSqlTest(server) +{ + private static readonly StreamId Stream = new("acct-1"); + + private static CancellationToken Ct => TestContext.Current.CancellationToken; + + [Fact] + [Trait("Id", "SCK-59")] + [Trait("Covers", "ADR-022")] + public async Task ForgedQueries_SeeOnlyTheSessionTenant_AndCannotWriteAnotherTenant() + { + await using PostgreSqlStore store = await Server.CreateRowLevelSecurityStoreAsync(); + await SeedAsync(store, "eu", 2); + await SeedAsync(store, "us", 3); + string events = $"\"{store.Options.Schema}\".events"; + string documents = $"\"{store.Options.Schema}\".documents"; + + // User SQL inside a session (an EF Core projection, a custom projection) with no tenant predicate at all. + await using (IStorageSession eu = await store.BeginAsync("eu", Ct)) + { + eu.Documents.Upsert("docs", "probe", 1, "{}"u8.ToArray()); // queues nothing on the wire yet + (await ScalarAsync(eu, $"SELECT count(*) FROM {events}")).ShouldBe(2); + (await ScalarAsync(eu, $"SELECT count(*) FROM {events} WHERE tenant_id = 'us'")).ShouldBe(0); + (await ScalarAsync(eu, $"SELECT count(*) FROM {documents}")).ShouldBe(1); + + PostgresException forged = await Should.ThrowAsync(() => + ScalarAsync(eu, $"WITH i AS (INSERT INTO {documents} (tenant_id, collection, id, version, data) VALUES ('us', 'docs', 'x', 1, '{{}}') RETURNING 1) SELECT count(*) FROM i")); + forged.SqlState.ShouldBe(PostgresErrorCodes.InsufficientPrivilege); + } + + // Without a tenant setting the application role sees nothing. + await using NpgsqlDataSource app = NpgsqlDataSource.Create(Server.ConnectionStringFor(Server.AppRole)); + await using NpgsqlCommand bare = app.CreateCommand($"SELECT count(*) FROM {events}"); + ((long)(await bare.ExecuteScalarAsync(Ct))!).ShouldBe(0); + } + + [Fact] + [Trait("Id", "SCK-60")] + [Trait("Covers", "ADR-022")] + public async Task TheGlobalLog_UsesTheSystemRole_AndSeesEveryTenant() + { + await using PostgreSqlStore store = await Server.CreateRowLevelSecurityStoreAsync(); + await SeedAsync(store, "eu", 1); + CommitResult last = await SeedAsync(store, "us", 1); + + LogBatch log = await ReadFinalAsync(store, last.LastPosition!.Value); + + log.Events.Select(e => e.TenantId).ShouldBe(["eu", "us"]); + log.Events.ShouldAllBe(e => e.Bucket == Buckets.Of(e.TenantId, e.StreamId)); + Buckets.Of("eu", Stream).ShouldNotBe(Buckets.Of("us", Stream)); + } + + [Fact] + [Trait("Id", "SCK-60")] + [Trait("Covers", "ADR-022")] + public async Task TenantScopedReads_OutsideSessions_AreIsolatedByTheDatabase() + { + await using PostgreSqlStore store = await Server.CreateRowLevelSecurityStoreAsync(); + await SeedAsync(store, "eu", 2); + await store.SaveAsync("eu", new Snapshot(Stream, new StreamVersion(2), "Account", "h", "{}"u8.ToArray()), Ct); + await store.ArchiveStreamAsync("us", Stream, Ct); // another tenant's archive touches nothing + + (await store.ReadStreamAsync("eu", Stream, new StreamVersion(1), 10, Ct)).Events.Count.ShouldBe(2); + (await store.ReadStreamAsync("us", Stream, new StreamVersion(1), 10, Ct)).Events.ShouldBeEmpty(); + (await store.GetStreamInfoAsync("eu", Stream, Ct))!.IsArchived.ShouldBeFalse(); + (await ((ISnapshotStore)store).GetAsync("us", Stream, Ct)).ShouldBeNull(); + (await ((IDocumentReader)store).ListAsync("us", "docs", 10, Ct)).ShouldBeEmpty(); + (await ((IDocumentReader)store).ListAsync("eu", "docs", 10, Ct)).Count.ShouldBe(1); + } + + [Fact] + [Trait("Id", "SCK-M07")] + [Trait("Covers", "ADR-022")] + public async Task Verify_RejectsAnIsolationMismatch_AndMigrateFixesIt() + { + string schema = PostgreSqlServer.NewSchema(); + await new PostgreSqlSchemaMigrator(Server.DataSource, schema).MigrateAsync(Ct); + var rls = new PostgreSqlSchemaMigrator(Server.DataSource, schema, TenantIsolation.RowLevelSecurity); + var runtime = new PostgreSqlSchemaMigrator(Server.DataSource, schema, TenantIsolation.Runtime); + + await runtime.VerifyAsync(Ct); + (await Should.ThrowAsync(() => rls.VerifyAsync(Ct))).Message.ShouldContain("events"); + (await rls.MigrateAsync(Ct)).ShouldBeEmpty(); + await rls.VerifyAsync(Ct); + await Should.ThrowAsync(() => runtime.VerifyAsync(Ct)); + rls.Script().ShouldContain($"ALTER TABLE \"{schema}\".events ENABLE ROW LEVEL SECURITY, FORCE ROW LEVEL SECURITY;"); + } + + private static async Task SeedAsync(PostgreSqlStore store, string tenant, int events) + { + await using IStorageSession session = await store.BeginAsync(tenant, Ct); + session.Append(Stream, "acct", ExpectedVersion.NoStream, [.. Enumerable.Range(0, events).Select(_ => StorageConformance.Event())]); + session.Documents.Upsert("docs", Stream.Value, events, Encoding.UTF8.GetBytes($"{{\"tenant\":\"{tenant}\"}}")); + return await session.CommitAsync(Ct); + } + + private static async Task ScalarAsync(IStorageSession session, string sql) + { + await using var command = new NpgsqlCommand(sql, (NpgsqlConnection)session.Connection!, (NpgsqlTransaction)session.Transaction!); + return (T)(await command.ExecuteScalarAsync(Ct))!; + } + + private static async Task ReadFinalAsync(PostgreSqlStore store, GlobalPosition through) + { + while (true) + { + LogBatch batch = await store.ReadAsync(GlobalPosition.Start, BucketRange.All, 100, Ct); + if (batch.Horizon >= through) + { + return batch; + } + + await RealClock.WaitAsync(TimeSpan.FromMilliseconds(10)); + } + } +} diff --git a/tests/Storage/SourceFlow.Storage.Tests/PostgreSql/RealClock.cs b/tests/Storage/SourceFlow.Storage.Tests/PostgreSql/RealClock.cs new file mode 100644 index 00000000..932174c1 --- /dev/null +++ b/tests/Storage/SourceFlow.Storage.Tests/PostgreSql/RealClock.cs @@ -0,0 +1,13 @@ +namespace SourceFlow.Storage.Tests.PostgreSql; + +/// +/// Waits on the system clock. Only for integration tests against an external clock that cannot be faked (database +/// lease expiry, LISTEN latency, eventual consistency of a real host); everything else uses FakeTimeProvider (plan 04 §8). +/// +internal static class RealClock +{ + public static Task WaitAsync(TimeSpan delay) + { + return Task.Delay(delay, TimeProvider.System, TestContext.Current.CancellationToken); + } +} diff --git a/tests/Storage/SourceFlow.Storage.Tests/SourceFlow.Storage.Tests.csproj b/tests/Storage/SourceFlow.Storage.Tests/SourceFlow.Storage.Tests.csproj new file mode 100644 index 00000000..1dcdea1f --- /dev/null +++ b/tests/Storage/SourceFlow.Storage.Tests/SourceFlow.Storage.Tests.csproj @@ -0,0 +1,27 @@ + + + + + true + + + + + + + + + + + + + + + + + + + + diff --git a/tests/Storage/SourceFlow.Storage.Tests/SqlServer/SqlServerBankTests.cs b/tests/Storage/SourceFlow.Storage.Tests/SqlServer/SqlServerBankTests.cs new file mode 100644 index 00000000..0cb9576b --- /dev/null +++ b/tests/Storage/SourceFlow.Storage.Tests/SqlServer/SqlServerBankTests.cs @@ -0,0 +1,179 @@ +using System.Text.Json; +using Bank.Accounts; +using Bank.Contracts; +using Bank.Transfers; +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.Hosting; +using SourceFlow.Hosting; +using SourceFlow.Messaging; +using SourceFlow.Runtime; +using SourceFlow.Storage.SqlServer; + +namespace SourceFlow.Storage.Tests.SqlServer; + +/// +/// The Bank sample on SQL Server with the real clock (plan 06 §4, SQL Server leg; WP-4.4): commands, inline and async +/// projections, the outbox relay, the transfer process manager, fenced checkpoints, and re-decide on real conflicts. +/// +[Collection(SqlServerCollection.Name)] +[Trait("Category", "EndToEnd")] +[Trait("Provider", "SqlServer")] +[Trait("Requires", "Docker")] +public sealed class SqlServerBankTests(SqlServerServer server) : SqlServerTest(server) +{ + private static readonly TimeSpan Patience = TimeSpan.FromSeconds(30); + + private static CancellationToken Ct => TestContext.Current.CancellationToken; + + [Fact] + [Trait("Id", "E2E-01")] + [Trait("Covers", "ADR-002;ADR-009")] + public async Task AccountLifecycle_InlineSummary() + { + using IHost host = await StartAsync(inlineSummary: true); + ICommandSender commands = host.Services.GetRequiredService(); + AccountId id = AccountId.New(); + + (await commands.SendAsync(new OpenAccount(id, "Ada", 100m), null, Ct)).Status.ShouldBe(CommandStatus.Accepted); + (await commands.SendAsync(new Deposit(id, 50m), null, Ct)).Version.ShouldBe(new StreamVersion(2)); + (await commands.SendAsync(new Withdraw(id, 30m), null, Ct)).Version.ShouldBe(new StreamVersion(3)); + CommandResult rejected = await commands.SendAsync(new Withdraw(id, 1000m), null, Ct); + + rejected.Status.ShouldBe(CommandStatus.Rejected); + (await SummaryAsync(host, id))!.ShouldBe(new AccountSummary(id, "Ada", 120m, AccountStatus.Open, 3)); + } + + [Fact] + [Trait("Id", "E2E-03")] + [Trait("Covers", "ADR-006")] + public async Task IdempotencyKey_IsDeduplicatedByTheInbox() + { + using IHost host = await StartAsync(inlineSummary: true); + ICommandSender commands = host.Services.GetRequiredService(); + AccountId id = AccountId.New(); + await commands.SendAsync(new OpenAccount(id, "Ada", 1m), null, Ct); + var options = new SendOptions { IdempotencyKey = "mssql-deposit-1" }; + + CommandResult first = await commands.SendAsync(new Deposit(id, 5m), options, Ct); + CommandResult second = await commands.SendAsync(new Deposit(id, 5m), options, Ct); + + second.Status.ShouldBe(CommandStatus.Duplicate); + second.Version.ShouldBe(first.Version); + (await SummaryAsync(host, id))!.Balance.ShouldBe(6m); + } + + [Fact] + [Trait("Id", "E2E-04")] + [Trait("Covers", "ADR-008;GAP-05")] + public async Task ParallelDeposits_ReDecideOnRealConflicts() + { + using IHost host = await StartAsync(inlineSummary: true, configure: sf => sf.Configure(o => o.MaxConcurrencyRetries = 50)); + ICommandSender commands = host.Services.GetRequiredService(); + AccountId id = AccountId.New(); + await commands.SendAsync(new OpenAccount(id, "Ada", 0.01m), null, Ct); + + CommandResult[] results = await Task.WhenAll(Enumerable.Range(0, 20) + .Select(_ => Task.Run(async () => await commands.SendAsync(new Deposit(id, 1m), null, Ct)))); + + results.ShouldAllBe(r => r.Status == CommandStatus.Accepted); + results.Select(r => r.Version.Value).Distinct().Count().ShouldBe(20); + (await SummaryAsync(host, id))!.Balance.ShouldBe(20.01m); + } + + [Fact] + [Trait("Id", "E2E-06")] + [Trait("Covers", "ADR-010;ADR-016")] + public async Task AsyncProjection_CatchesUpThroughFencedCheckpoints() + { + using IHost host = await StartAsync(inlineSummary: false, configure: sf => sf.Configure(o => o.SubscriptionPartitions = 4)); + ICommandSender commands = host.Services.GetRequiredService(); + AccountId[] ids = [.. Enumerable.Range(0, 8).Select(_ => AccountId.New())]; + foreach (AccountId id in ids) + { + await commands.SendAsync(new OpenAccount(id, "Ada", 10m), null, Ct); + await commands.SendAsync(new Deposit(id, 5m), null, Ct); + } + + foreach (AccountId id in ids) + { + await EventuallyAsync(async () => (await SummaryAsync(host, id))?.Balance == 15m, $"summary of {id}"); + } + } + + [Fact] + [Trait("Id", "E2E-13")] + [Trait("Covers", "ADR-006;ADR-020")] + public async Task MoneyTransfer_ProcessManagerCompletesThroughTheOutbox() + { + using IHost host = await StartAsync(inlineSummary: true); + ICommandSender commands = host.Services.GetRequiredService(); + AccountId from = AccountId.New(); + AccountId to = AccountId.New(); + await commands.SendAsync(new OpenAccount(from, "Ada", 100m), null, Ct); + await commands.SendAsync(new OpenAccount(to, "Grace", 0.5m), null, Ct); + + var transfer = TransferId.New(); + (await commands.SendAsync(new RequestTransfer(transfer, from, to, 40m), null, Ct)).Status.ShouldBe(CommandStatus.Accepted); + + await EventuallyAsync(async () => (await SummaryAsync(host, from))?.Balance == 60m && (await SummaryAsync(host, to))?.Balance == 40.5m, "transfer applied"); + SqlServerStore store = host.Services.GetRequiredService(); + await EventuallyAsync(async () => (await store.ReadStreamAsync(MessageEnvelope.DefaultTenant, StreamId.For(Transfer.AggregateName, transfer), new StreamVersion(1), 10, Ct)) + .Events.Any(e => e.Type == "bank.transfer.completed"), "transfer completed"); + await EventuallyAsync(async () => await store.DueOutboxCountAsync(Ct) == 0, "due outbox drained"); + (await store.CountAsync(Ct)).ShouldBe(1, "only the process manager's timeout stays scheduled"); + } + + private async Task StartAsync(bool inlineSummary, Action? configure = null) + { + string schema = SqlServerServer.NewSchema(); + HostApplicationBuilder builder = Host.CreateApplicationBuilder(new HostApplicationBuilderSettings { EnvironmentName = Environments.Development, DisableDefaults = true }); + builder.Services.AddSourceFlow(sf => + { + sf.ServiceName = "accounts"; + sf.AddModule(); + sf.AddModule(); + sf.AddModule(); + sf.Projections(p => + { + ProjectionModeBuilder summary = p.Add(); + if (inlineSummary) + { + summary.Inline(); + } + else + { + summary.Async(); + } + }); + sf.UseSqlServer(Server.ConnectionString, o => o.Schema = schema); + sf.UseInMemoryTransport(); + configure?.Invoke(sf); + }); + IHost host = builder.Build(); + await host.StartAsync(Ct); + return host; + } + + private static async Task SummaryAsync(IHost host, AccountId id) + { + RuntimeModel model = host.Services.GetRequiredService(); + ProjectionDescriptor projection = model.Projections.Single(p => p.ProjectionType == typeof(AccountSummaryProjection)); + StoredDocument? stored = await host.Services.GetRequiredService() + .ToPorts().Documents.GetAsync(MessageEnvelope.DefaultTenant, projection.Collection, id.ToStreamSegment(), Ct); + return stored is null ? null : (AccountSummary?)JsonSerializer.Deserialize(stored.Data.Span, model.JsonTypeInfoFor(typeof(AccountSummary))); + } + + private static async Task EventuallyAsync(Func> condition, string what) + { + DateTimeOffset deadline = TimeProvider.System.GetUtcNow() + Patience; + while (!await condition()) + { + if (TimeProvider.System.GetUtcNow() > deadline) + { + throw new TimeoutException($"Timed out waiting for: {what}."); + } + + await Task.Delay(TimeSpan.FromMilliseconds(50), TimeProvider.System, Ct); + } + } +} diff --git a/tests/Storage/SourceFlow.Storage.Tests/SqlServer/SqlServerQueryTests.cs b/tests/Storage/SourceFlow.Storage.Tests/SqlServer/SqlServerQueryTests.cs new file mode 100644 index 00000000..d496b0a0 --- /dev/null +++ b/tests/Storage/SourceFlow.Storage.Tests/SqlServer/SqlServerQueryTests.cs @@ -0,0 +1,463 @@ +using System.Globalization; +using System.Text.Json; +using Bank.Accounts; +using CsCheck; +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.DependencyInjection.Extensions; +using Microsoft.Extensions.Hosting; +using SourceFlow.Hosting; +using SourceFlow.Messaging; +using SourceFlow.Query; +using SourceFlow.Runtime; +using SourceFlow.Storage.SqlServer; +using SourceFlow.Storage.SqlServer.Query; + +namespace SourceFlow.Storage.Tests.SqlServer; + +/// +/// QRY-01..20, 40..44, 60 on SQL Server: the SFQL T-SQL compiler (doc 14 §7, §10, §12; WP-4.4). Every query runs twice +/// over the same SQL Server data, compiled to T-SQL and in the in-memory interpreter, and the rows must be identical +/// (cross-provider equivalence). Golden SQL, the injection corpus and the no-literal property cover ADR-026. +/// +[Collection(SqlServerCollection.Name)] +[Trait("Category", "Integration")] +[Trait("Provider", "SqlServer")] +[Trait("Requires", "Docker")] +public sealed class SqlServerQueryTests(SqlServerServer server) : SqlServerTest(server) +{ + private static readonly RuntimeModel Model = new SourceFlowModelBuilder().AddModule().Build(); + private static readonly QueryCatalog Catalog = QueryCatalog.Build(Model); + + private IHost _host = null!; + private ServiceProvider _reference = null!; + private readonly List _accounts = []; + private readonly List _results = []; + + private static CancellationToken Ct => TestContext.Current.CancellationToken; + + private IQueryService Compiled => _host.Services.GetRequiredService(); + + private IQueryService Interpreted => _reference.GetRequiredService(); + + public override async ValueTask InitializeAsync() + { + await base.InitializeAsync(); + string schema = SqlServerServer.NewSchema("q"); + HostApplicationBuilder builder = Host.CreateApplicationBuilder(new HostApplicationBuilderSettings { EnvironmentName = Environments.Development, DisableDefaults = true }); + builder.Services.AddSourceFlow(sf => Configure(sf, schema)); + _host = builder.Build(); + await _host.StartAsync(Ct); + + // The reference: the same schema through the interpreter (no provider engine). + var services = new ServiceCollection(); + services.AddSourceFlow(sf => Configure(sf, schema)); + services.RemoveAll(); + _reference = services.BuildServiceProvider(); + + ICommandSender commands = _host.Services.GetRequiredService(); + string[] holders = ["Ada", "Grace", "Linus", "Barbara", "Edsger", "adam", "Zed"]; + for (int i = 0; i < holders.Length; i++) + { + var id = AccountId.New(); + _accounts.Add(id); + _results.Add(await commands.SendAsync(new OpenAccount(id, holders[i], 100m + i), null, Ct)); + if (i is > 0 and < 5) + { + _results.Add(await commands.SendAsync(new Deposit(id, 150m * i + 0.25m), null, Ct)); + } + } + + _results.Add(await commands.SendAsync(new Withdraw(_accounts[1], 50m), null, Ct)); + _results.Add(await commands.SendAsync(new Deposit(_accounts[1], 50m), null, Ct)); + _results.Add(await commands.SendAsync(new CloseAccount(_accounts[4], "moved"), null, Ct)); + _results.ShouldAllBe(r => r.Status == CommandStatus.Accepted); + } + + public override async ValueTask DisposeAsync() + { + await _reference.DisposeAsync(); + await _host.StopAsync(CancellationToken.None); + _host.Dispose(); + await base.DisposeAsync(); + } + + public static TheoryData EquivalentQueries => new() + { + { "QRY-01", "from readmodel \"account-summary\" | where balance >= 250 | project holder, balance | order by balance desc" }, + { "QRY-02", "from readmodel \"account-summary\" | summarize n = count(), total = sum(balance), smallest = min(balance), biggest = max(balance)" }, + { "QRY-03", "from readmodel \"account-summary\" | project holder | order by holder" }, + { "QRY-04", "from readmodel \"account-summary\" | where holder like 'A%' or holder in ('Grace', 'Zed') | project holder | order by holder desc" }, + { "QRY-05", "from readmodel \"account-summary\" | where balance between 200 and 600 and not (holder = 'Linus') | project holder, status, version" }, + { "QRY-06", "from readmodel \"account-summary\" | project holder, doubled = balance * 2, third = round(balance / 3, 4), up = upper(holder), n = length(holder), tag = concat(holder, '-', status)" }, + { "QRY-07", "from readmodel \"account-summary\" | summarize n = count(), total = sum(balance) by status | order by status" }, + { "QRY-08", "from readmodel \"account-summary\" | summarize n = count() by status | where n > 1" }, + { "QRY-09", "from events of \"bank.account.deposited\", \"bank.account.withdrawn\" | where time >= ago(1d) | summarize n = count(), total = sum(data.amount), biggest = max(data.amount) by type | order by type" }, + { "QRY-10", "from events of \"bank.account.opened\" | where time >= ago(1d) | project stream, version, typeversion, holder = data.holder, deposit = data.initialDeposit" }, + { "QRY-11", "from events of \"bank.account.deposited\" | where time >= ago(1d) | project position, aggregatekey, amount = data.amount, after = data.balanceAfter | order by amount desc" }, + { "QRY-12", "from events of \"bank.account.opened\", \"bank.account.deposited\" | where time >= ago(1d) | summarize n = count(), missing = count(data.initialDeposit) by type" }, + { "QRY-13", "from events of \"bank.account.opened\" | where time >= ago(1d) | summarize n = count() by day = bin(time, 1d)" }, + { "QRY-14", "from readmodel \"account-summary\" as a | join events of \"bank.account.withdrawn\" as e on e.aggregatekey = a.id | project a.holder, e.data.amount" }, + { "QRY-15", "from readmodel \"account-summary\" as a | join kind=left events of \"bank.account.closed\" as e on e.aggregatekey = a.id | project a.holder, reason = e.data.reason | order by a.holder" }, + { "QRY-16", "from readmodel \"account-summary\" | where coalesce(null, balance) > 300 and holder is not null | project holder, b = coalesce(balance, 0)" }, + { "QRY-17", "from events of \"bank.account.deposited\" | where time >= ago(1d) and data.amount > 300 | project amount = data.amount, big = case when data.amount > 500 then 'big' else 'small' end" }, + { "QRY-18", "from events of \"bank.account.opened\" | where time >= ago(1d) and has_tag('vip') | project stream" }, + }; + + [Theory] + [Trait("Covers", "doc 14 12")] + [MemberData(nameof(EquivalentQueries))] + public async Task CompiledAndInterpreted_GiveTheSameRows(string id, string query) + { + IReadOnlyList compiled = await RowsAsync(Compiled, query); + IReadOnlyList interpreted = await RowsAsync(Interpreted, query); + + compiled.ShouldBe(interpreted, $"{id}: {query}"); + } + + [Fact] + [Trait("Id", "QRY-19")] + [Trait("Covers", "doc 14 12")] + public async Task SqlSyntax_Subqueries_AreEquivalent() + { + var sql = new QueryOptions { Language = QueryLanguage.Sql }; + string[] queries = + [ + "SELECT holder FROM readmodel.\"account-summary\" WHERE id IN (SELECT aggregatekey FROM events.\"bank.account.withdrawn\" WHERE time >= ago(7d)) ORDER BY holder", + "SELECT a.holder FROM readmodel.\"account-summary\" a WHERE NOT EXISTS (SELECT 1 FROM events.\"bank.account.deposited\" e WHERE e.aggregatekey = a.id) ORDER BY a.holder", + "SELECT DISTINCT status FROM readmodel.\"account-summary\" ORDER BY status", + "SELECT status, COUNT(*) AS n, SUM(balance) AS total FROM readmodel.\"account-summary\" GROUP BY status HAVING SUM(balance) > 100 ORDER BY total DESC", + ]; + + foreach (string query in queries) + { + IReadOnlyList compiled = await RowsAsync(Compiled, query, options: sql); + compiled.ShouldBe(await RowsAsync(Interpreted, query, options: sql), query); + compiled.ShouldNotBeEmpty(query); + } + + (await RowsAsync(Compiled, queries[0], options: sql)).ShouldBe(["Grace"]); + (await RowsAsync(Compiled, queries[1], options: sql)).ShouldBe(["Ada", "Zed", "adam"]); // ordinal (BIN2): upper case first + } + + [Fact] + [Trait("Id", "QRY-20")] + [Trait("Covers", "doc 14 7.4")] + public async Task KeysetPages_AreInterchangeableBetweenEngines() + { + const string query = "from events of \"bank.account.opened\", \"bank.account.deposited\" | where time >= ago(1d) | project stream, type, version"; + var options = new QueryOptions { PageSize = 3 }; + var mixed = new List(); + string? continuation = null; + int page = 0; + do + { + // Alternate engines page by page: the continuation token is engine-neutral. + QueryPage result = await (page++ % 2 == 0 ? Compiled : Interpreted).QueryPageAsync(query, continuation: continuation, options: options, cancellationToken: Ct); + mixed.AddRange(result.Rows.Select(Render)); + continuation = result.Continuation; + } + while (continuation is not null); + + mixed.Count.ShouldBe(12); // 7 opened + 5 deposited + mixed.ShouldBe(await RowsAsync(Compiled, query, options: new QueryOptions { PageSize = 100 })); + } + + [Fact] + [Trait("Id", "QRY-40")] + [Trait("Covers", "doc 14 12")] + public async Task PositionAndStream_Predicates() + { + GlobalPosition middle = _results[5].Token.Position; + IReadOnlyDictionary parameters = new Dictionary { ["p"] = middle.ToString() }; + const string query = "from events of \"bank.account.deposited\" | where position > @p and time >= ago(1d) | project position, amount = data.amount"; + + IReadOnlyList compiled = await RowsAsync(Compiled, query, parameters); + compiled.ShouldBe(await RowsAsync(Interpreted, query, parameters)); + compiled.ShouldNotBeEmpty(); + + IReadOnlyDictionary stream = new Dictionary { ["s"] = StreamId.For(BankAccount.AggregateName, _accounts[1]).Value }; + const string streamQuery = "from stream @s | project version, type"; + (await RowsAsync(Compiled, streamQuery, stream)).ShouldBe(await RowsAsync(Interpreted, streamQuery, stream)); + (await RowsAsync(Compiled, streamQuery, stream)).Count.ShouldBe(4); + } + + [Fact] + [Trait("Id", "SCK-69")] + [Trait("Covers", "doc 05 9;doc 14 12")] + public async Task ArchivedStreams_AreLeftOut_UnlessIncludeArchived_InBothEngines() + { + await _host.Services.GetRequiredService().ArchiveStreamAsync(MessageEnvelope.DefaultTenant, StreamId.For(BankAccount.AggregateName, _accounts[2]), Ct); + string[] queries = + [ + "from events of \"bank.account.opened\", \"bank.account.deposited\" | where time >= ago(1d) | summarize n = count() by type | order by type", + "from events of \"bank.account.opened\", \"bank.account.deposited\" | where time >= ago(1d) | summarize n = count() by type | order by type options (include_archived = true)", + "from readmodel \"account-summary\" as a | join events of \"bank.account.deposited\" as e on e.aggregatekey = a.id | project a.holder, e.data.amount | order by holder", + ]; + + foreach (string query in queries) + { + (await RowsAsync(Compiled, query)).ShouldBe(await RowsAsync(Interpreted, query), query); + } + + (await RowsAsync(Compiled, queries[0])).ShouldBe(["bank.account.deposited | 4", "bank.account.opened | 6"]); + (await RowsAsync(Compiled, queries[1])).ShouldBe(["bank.account.deposited | 5", "bank.account.opened | 7"]); + (await RowsAsync(Compiled, queries[2])).ShouldNotContain(r => r.StartsWith("Linus", StringComparison.Ordinal)); + } + + [Fact] + [Trait("Id", "QRY-41")] + [Trait("Covers", "doc 14 8")] + public async Task Tenancy() + { + var other = new QueryOptions { Tenant = "someone-else" }; + (await RowsAsync(Compiled, "from readmodel \"account-summary\"", options: other)).ShouldBeEmpty(); + (await RowsAsync(Compiled, "from events of \"bank.account.opened\" | where time >= ago(1d)", options: other)).ShouldBeEmpty(); + (await RowsAsync(Compiled, "from events of \"bank.account.opened\" | where time >= ago(1d) | summarize n = count() options (tenants = 'all')")).ShouldBe(["7"]); + } + + [Fact] + [Trait("Id", "QRY-42")] + [Trait("Covers", "ADR-026")] + public void GoldenSql_ReadModel() + { + CompiledQuery compiled = Compile( + "from readmodel \"account-summary\" | where status = 1 and balance < @below | project id, balance | order by balance | take 50", + new Dictionary { ["below"] = 0m }); + + compiled.Sql.ShouldBe( + "SELECT * FROM (SELECT t0.id COLLATE Latin1_General_100_BIN2 AS o0, CAST(JSON_VALUE(t0.data, N'$.\"balance\"') AS decimal(38, 10)) AS o1, " + + "CAST(JSON_VALUE(t0.data, N'$.\"balance\"') AS decimal(38, 10)) AS k0, t0.id COLLATE Latin1_General_100_BIN2 AS k1 " + + "FROM [sf].documents t0 WHERE t0.tenant_id = @p1 AND t0.collection = @p2 " + + "AND (((CAST(JSON_VALUE(t0.data, N'$.\"status\"') AS bigint)) = (@p3)) AND ((CAST(JSON_VALUE(t0.data, N'$.\"balance\"') AS decimal(38, 10))) < (@p4)))) q " + + "ORDER BY CASE WHEN q.k0 IS NULL THEN 1 ELSE 0 END, q.k0 ASC, CASE WHEN q.k1 IS NULL THEN 1 ELSE 0 END, q.k1 ASC " + + "OFFSET @p5 ROWS FETCH NEXT @p6 ROWS ONLY"); + compiled.Parameters.Select(p => p.Value).ShouldBe(["-", "account-summary@1", 1L, 0m, 0L, 51L]); + } + + [Fact] + [Trait("Id", "QRY-43")] + [Trait("Covers", "ADR-026")] + public void GoldenSql_EventsWithHorizonAndTieBreak() + { + CompiledQuery compiled = Compile("from events of \"bank.account.deposited\" | where data.amount >= @min and time >= ago(7d) | project stream, amount = data.amount | order by time desc", + new Dictionary { ["min"] = 10m }); + + compiled.Sql.ShouldContain("t0.event_type IN (@p2)"); + compiled.Sql.ShouldContain("t0.rv < MIN_ACTIVE_ROWVERSION()"); + compiled.Sql.ShouldContain("(t0.created_at) >= (DATEADD(second, CAST(@p5 AS int), @p4))"); + compiled.Sql.ShouldContain("ORDER BY CASE WHEN q.k0 IS NULL THEN 0 ELSE 1 END, q.k0 DESC, CASE WHEN q.k1_c IS NULL THEN 1 ELSE 0 END, q.k1_c ASC, q.k1_s ASC"); + compiled.Parameters.ShouldContain(p => Equals(p.Value, -604800L)); + } + + [Fact] + [Trait("Id", "QRY-44")] + [Trait("Covers", "ADR-026")] + public async Task InjectionCorpus_IsRejectedOrHarmless() + { + string[] rejected = + [ + "SELECT * FROM readmodel.\"account-summary\"; DROP TABLE x", + "SELECT * FROM readmodel.\"account-summary\" WHERE holder = 'a' -- ' OR 1=1", + "SELECT * FROM readmodel.\"account-summary\" /* x */", + "SELECT name FROM sys.tables", + "SELECT * FROM INFORMATION_SCHEMA.TABLES", + "UPDATE readmodel.\"account-summary\" SET balance = 0", + "SELECT * FROM readmodel.\"account-summary\" UNION SELECT * FROM readmodel.\"account-summary\"", + "SELECT * FROM readmodel.\"account-summary\" WAITFOR DELAY '00:00:10'", + "EXEC xp_cmdshell 'dir'", + "SELECT * FROM readmodel.\"account-summary\" WHERE holder = 'a‮'", + "SELECT * FROM readmodel.\"account-summary\" WHERE holder = 'a\0'", + "SELECT * FROM [dbo].outbox", + ]; + foreach (string text in rejected) + { + QueryException e = await Should.ThrowAsync(async () => + await Compiled.QueryPageAsync(text, options: new QueryOptions { Language = QueryLanguage.Sql }, cancellationToken: Ct)); + e.Code.ShouldStartWith("SFQ0", customMessage: text); + int stage = int.Parse(e.Code.AsSpan(3, 2), CultureInfo.InvariantCulture); // SFQ01xx syntax, SFQ02xx bind + stage.ShouldBeInRange(1, 2, text); + } + + string[] payloads = + [ + "Open' OR '1'='1", + "'; DROP TABLE documents; --", + "'; WAITFOR DELAY '00:00:05'; --", + "", + "%' OR 1=1 OR holder LIKE '%", + "[A-Z]%", + "Ad[a]", + "Ada' UNION SELECT name FROM sys.tables --", + "Аda", + "ADA", + ]; + foreach (string payload in payloads) + { + var parameters = new Dictionary { ["h"] = payload }; + (await RowsAsync(Compiled, "from readmodel \"account-summary\" | where holder = @h or holder like @h", parameters)).ShouldBeEmpty(payload); + (await RowsAsync(Compiled, "from readmodel \"account-summary\" | where holder = @h", parameters)).ShouldBeEmpty(payload); + } + + (await RowsAsync(Compiled, "from readmodel \"account-summary\" | where holder = 'Ada' | project holder")).ShouldBe(["Ada"]); + } + + [Fact] + [Trait("Id", "QRY-36")] + [Trait("Covers", "doc 14 7.1")] + public async Task UnsupportedConstructs_AreRefused_NotRunInTheInterpreter() + { + QueryExplainer explain = new(_host.Services); + const string compiled = "from readmodel \"account-summary\" | project holder"; + const string folded = "from readmodel \"account-summary\" | project tag = concat(holder, ':', balance) | order by tag"; + + explain.Engine(compiled).ShouldBe("sqlserver"); + explain.Engine(folded).ShouldBe("interpreter", "decimal text differs between engines: T-SQL can't run it"); + + // CR-21: the interpreter would read the whole collection with no statement timeout; SQL Server refuses instead. + QueryException refused = await Should.ThrowAsync(() => RowsAsync(Compiled, folded)); + refused.Code.ShouldBe(QueryCodes.NotCompilable); + (await RowsAsync(Interpreted, folded)).ShouldNotBeEmpty("a store without an engine still runs it"); + } + + [Fact] + [Trait("Id", "QRY-63")] + [Trait("Covers", "ADR-023 4;doc 14 12")] + public async Task EscapedLikePatterns_AndTrailingSpaces_GiveTheSameRows() + { + // CR-22: T-SQL pads trailing spaces in comparisons and has no default LIKE escape; SFQL compares ordinally and + // escapes with a backslash, like the interpreter and PostgreSQL. + ICommandSender commands = _host.Services.GetRequiredService(); + foreach (string holder in new[] { "Ada ", "a%b", "axb", "x[y]z", @"back\slash" }) + { + (await commands.SendAsync(new OpenAccount(AccountId.New(), holder, 7m), null, Ct)).Status.ShouldBe(CommandStatus.Accepted); + } + + (string Query, object? Parameter, string[] Expected)[] cases = + [ + ("from readmodel \"account-summary\" | where holder = @p | project holder", "Ada", ["Ada"]), + ("from readmodel \"account-summary\" | where holder = @p | project holder", "Ada ", ["Ada "]), + ("from readmodel \"account-summary\" | where holder <> @p and holder like 'Ad%' | project holder", "Ada", ["Ada "]), + ("from readmodel \"account-summary\" | where holder in ('Ada', 'Zed') | project holder | order by holder", null, ["Ada", "Zed"]), + ("from readmodel \"account-summary\" | where holder not in ('Ada') and holder like 'Ad%' | project holder", null, ["Ada "]), + ("from readmodel \"account-summary\" | where holder like @p | project holder", @"a\%b", ["a%b"]), + ("from readmodel \"account-summary\" | where holder like @p | project holder | order by holder", "a%b", ["a%b", "axb"]), + ("from readmodel \"account-summary\" | where holder like @p | project holder", "x[y]%", ["x[y]z"]), + ("from readmodel \"account-summary\" | where holder like @p | project holder", @"back\\slash", [@"back\slash"]), + ("from readmodel \"account-summary\" | where holder like 'Ad%' | summarize n = count() by holder", null, ["Ada | 1", "Ada | 1"]), + ]; + + foreach ((string query, object? parameter, string[] expected) in cases) + { + Dictionary? parameters = parameter is null ? null : new() { ["p"] = parameter }; + // Ordered ordinally here: T-SQL sorts 'Ada' and 'Ada ' as equal, so their order is not part of the contract. + string[] compiled = [.. (await RowsAsync(Compiled, query, parameters)).Order(StringComparer.Ordinal)]; + compiled.ShouldBe([.. (await RowsAsync(Interpreted, query, parameters)).Order(StringComparer.Ordinal)], $"{query} with {parameter}"); + compiled.ShouldBe(expected, $"{query} with {parameter}"); + } + + var sql = new QueryOptions { Language = QueryLanguage.Sql }; + const string distinct = "SELECT DISTINCT holder FROM readmodel.\"account-summary\" WHERE holder LIKE 'Ad%'"; + (await RowsAsync(Compiled, distinct, options: sql)).Order(StringComparer.Ordinal).ShouldBe(["Ada", "Ada "]); + (await RowsAsync(Interpreted, distinct, options: sql)).Order(StringComparer.Ordinal).ShouldBe(["Ada", "Ada "]); + } + + [Fact] + [Trait("Id", "QRY-60")] + [Trait("Category", "Property")] + [Trait("Covers", "ADR-026")] + public void NoLiteral_EverRequestValueIsAParameter() + { + string[] templates = + [ + "from readmodel \"account-summary\" | where holder = {0} | project holder", + "from readmodel \"account-summary\" | where holder like {0} or holder in ({0}, 'x') | project holder", + "from readmodel \"account-summary\" | project holder, tag = concat(holder, {0}) | order by tag", + "from events of \"bank.account.closed\" | where time >= ago(1d) and data.reason = {0}", + "from readmodel \"account-summary\" | where coalesce(holder, {0}) = {0} | summarize n = count() by status", + ]; + Gen.String[Gen.Char.AlphaNumeric, 6, 24] + .Select(Gen.Int[0, templates.Length - 1]) + .Sample((literal, template) => + { + string marker = "zq" + literal; + string text = string.Format(CultureInfo.InvariantCulture, templates[template], "'" + marker + "'"); + CompiledQuery compiled = Compile(text, new Dictionary()); + compiled.Sql.ShouldNotContain(marker); + compiled.Parameters.ShouldContain(p => Equals(p.Value, marker)); + }, iter: 200); + + // Opaque paths on untyped events come from the request too: the path is bound, never inlined (CR-37). + Gen.String[Gen.Char.AlphaNumeric, 6, 24].Sample(literal => + { + string marker = "zq" + literal; + foreach (string text in new[] { $"from events | where sfcorrelationid = @c and exists data.{marker}.inner" }) + { + CompiledQuery compiled = Compile(text, new Dictionary { ["c"] = "x" }); + compiled.Sql.ShouldNotContain(marker, customMessage: text); + } + }, iter: 100); + } + + // ================================================================ helpers + + private void Configure(SourceFlowBuilder sf, string schema) + { + sf.ServiceName = "accounts"; + sf.AddModule(); + sf.Projections(p => p.Add().Inline()); + sf.UseSqlServer(Server.ConnectionString, o => o.Schema = schema); + sf.UseInMemoryTransport(); + } + + private static CompiledQuery Compile(string text, IReadOnlyDictionary parameters, string schema = "sf") + { + ParseResult parsed = SfqlParser.Parse(text, QueryLanguage.Sfql, QueryLimits.Default); + parsed.Diagnostics.ShouldBeEmpty(); + BindResult bound = SfqlBinder.Bind(parsed.Query!, text, Catalog); + bound.Diagnostics.ShouldBeEmpty(); + var execution = new QueryExecution(bound.Query!, parameters, "-", new DateTimeOffset(2026, 11, 11, 0, 0, 0, TimeSpan.Zero), null, 0, 51, QueryPolicySettings.Default); + return SqlServerQueryCompiler.Compile(execution, schema); + } + + private static async Task> RowsAsync(IQueryService service, string query, IReadOnlyDictionary? parameters = null, QueryOptions? options = null) + { + var rows = new List(); + await foreach (QueryRow row in service.QueryAsync(query, parameters, options, Ct)) + { + rows.Add(Render(row)); + } + + return rows; + } + + private static string Render(QueryRow row) + { + return string.Join(" | ", row.Values.Select(Render)); + } + + private static string Render(object? value) + { + return value switch + { + null => "null", + decimal d => (d / 1.0000000000000000000000000000m).ToString(CultureInfo.InvariantCulture), + DateTimeOffset t => t.UtcDateTime.ToString("O", CultureInfo.InvariantCulture), + JsonElement e => e.GetRawText(), + string[] tags => "[" + string.Join(",", tags) + "]", + IFormattable f => f.ToString(null, CultureInfo.InvariantCulture), + _ => value.ToString() ?? string.Empty, + }; + } + + // Which engine a query runs in: the provider engine when it can compile the bound query, else the interpreter. + private sealed class QueryExplainer(IServiceProvider services) + { + public string Engine(string text) + { + ParseResult parsed = SfqlParser.Parse(text, QueryLanguage.Sfql, QueryLimits.Default); + BindResult bound = SfqlBinder.Bind(parsed.Query!, text, QueryCatalog.Build(services.GetRequiredService())); + IQueryEngine engine = services.GetServices().OfType().Single(); + return engine.CanExecute(bound.Query!) ? ((SqlServerQueryEngine)engine).EngineName : "interpreter"; + } + } +} diff --git a/tests/Storage/SourceFlow.Storage.Tests/SqlServer/SqlServerSchemaTests.cs b/tests/Storage/SourceFlow.Storage.Tests/SqlServer/SqlServerSchemaTests.cs new file mode 100644 index 00000000..026e088c --- /dev/null +++ b/tests/Storage/SourceFlow.Storage.Tests/SqlServer/SqlServerSchemaTests.cs @@ -0,0 +1,144 @@ +using Bank.Accounts; +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.Diagnostics.HealthChecks; +using Microsoft.Extensions.Hosting; +using SourceFlow.Hosting; +using SourceFlow.Storage.SqlServer; + +namespace SourceFlow.Storage.Tests.SqlServer; + +/// The SQL Server migrator (SCK-M01..06, doc 05 §11) and monitor readings (UT-HC, doc 08 §5) on SQL Server (WP-4.4). +[Collection(SqlServerCollection.Name)] +[Trait("Category", "Integration")] +[Trait("Provider", "SqlServer")] +[Trait("Requires", "Docker")] +public sealed class SqlServerSchemaTests(SqlServerServer server) : SqlServerTest(server) +{ + private static CancellationToken Ct => TestContext.Current.CancellationToken; + + [Fact] + [Trait("Id", "SCK-M01")] + [Trait("Covers", "doc 05 11")] + public async Task Migrate_IsIdempotent_AndRecordsHistory() + { + var migrator = new SqlServerSchemaMigrator(Server.ConnectionString, SqlServerServer.NewSchema("m")); + + IReadOnlyList first = await migrator.MigrateAsync(Ct); + IReadOnlyList second = await migrator.MigrateAsync(Ct); + + first.ShouldBe([1, 2, 3, 4]); + second.ShouldBeEmpty(); + (await migrator.GetAppliedVersionsAsync(Ct)).ShouldBe([1, 2, 3, 4]); + await migrator.VerifyAsync(Ct); + } + + [Fact] + [Trait("Id", "SCK-M02")] + public async Task ConcurrentMigrators_ApplyOnce() + { + string schema = SqlServerServer.NewSchema("m"); + + IReadOnlyList[] results = await Task.WhenAll(Enumerable.Range(0, 4) + .Select(_ => Task.Run(() => new SqlServerSchemaMigrator(Server.ConnectionString, schema).MigrateAsync(Ct)))); + + results.Count(r => r.Count == 4).ShouldBe(1, "the application lock serialises migrators: one applies, the others find nothing to do"); + results.Count(r => r.Count == 0).ShouldBe(3); + } + + [Fact] + [Trait("Id", "SCK-M03")] + public async Task Verify_FailsOnAMissingSchema_AndOnAModifiedScript() + { + string schema = SqlServerServer.NewSchema("m"); + var migrator = new SqlServerSchemaMigrator(Server.ConnectionString, schema); + + (await Should.ThrowAsync(() => migrator.VerifyAsync(Ct))).Message.ShouldContain("not installed"); + await migrator.MigrateAsync(Ct); + await Server.ExecuteAsync($"UPDATE [{schema}].schema_history SET checksum = N'tampered' WHERE version = 1"); + + (await Should.ThrowAsync(() => migrator.VerifyAsync(Ct))).Message.ShouldContain("was modified"); + (await Should.ThrowAsync(() => migrator.MigrateAsync(Ct))).Message.ShouldContain("was modified"); + } + + [Fact] + [Trait("Id", "SCK-M04")] + public void Script_HasTheLockTheTablesAndTheHistory() + { + string script = new SqlServerSchemaMigrator(Server.ConnectionString, "sales").Script(); + + script.ShouldStartWith(":on error exit\nSET XACT_ABORT ON;\nBEGIN TRANSACTION;\nEXEC sp_getapplock"); + script.ShouldContain("CREATE TABLE [sales].events"); + script.ShouldContain("CREATE UNIQUE INDEX ix_events_commit_order ON [sales].events (rv) INCLUDE (bucket);"); + script.ShouldContain("INSERT INTO [sales].schema_history (version, name, checksum) VALUES (1, N'initial', N'" + SqlServerSchemaMigrator.EmbeddedScripts[0].Checksum + "');"); + script.ShouldEndWith("COMMIT TRANSACTION;\nGO\nSET NOEXEC OFF;\n"); + + // CR-60: after a failed batch (rolled back by XACT_ABORT), no later batch runs outside the transaction. + string[] batches = script.Split("\nGO\n"); + batches.Skip(1).ShouldAllBe(b => b.StartsWith("IF @@TRANCOUNT = 0 SET NOEXEC ON;", StringComparison.Ordinal) || b.StartsWith("SET NOEXEC OFF;", StringComparison.Ordinal)); + } + + [Theory] + [Trait("Id", "SCK-M05")] + [InlineData("Sales")] + [InlineData("sales; DROP TABLE x")] + [InlineData("")] + public void InvalidSchemaNames_AreRejected(string schema) + { + Should.Throw(() => new SqlServerStore(new SqlServerStorageOptions { ConnectionString = "Server=x", Schema = schema })); + } + + [Fact] + [Trait("Id", "QRY-65")] + [Trait("Covers", "doc 14 7.1;Q-R3")] + public void TheQueryConnection_IsReadIntent_AndNeverTheWriteConnection() + { + // CR-23: a query connection without ApplicationIntent=ReadOnly is refused; without one, queries use the read-intent + // form of the write connection, never the write connection as it is. + Should.Throw(() => new SqlServerStore(new SqlServerStorageOptions { ConnectionString = "Server=x", QueryConnectionString = "Server=y" })) + .Message.ShouldContain("ApplicationIntent=ReadOnly"); + var options = new SqlServerStorageOptions { ConnectionString = "Server=x;Database=d" }; + new Microsoft.Data.SqlClient.SqlConnectionStringBuilder(options.QueryConnection).ApplicationIntent.ShouldBe(Microsoft.Data.SqlClient.ApplicationIntent.ReadOnly); + new SqlServerSchemaMigrator(Server.ConnectionString, "sales").QueryGrantsScript("reader").ShouldContain("DENY INSERT, UPDATE, DELETE, EXECUTE, ALTER ON SCHEMA::[sales] TO [reader]"); + } + + [Fact] + [Trait("Id", "UT-HC-10")] + [Trait("Covers", "doc 08 3.2")] + public async Task MonitorReadings_AndTheStoreHealthCheck() + { + string schema = SqlServerServer.NewSchema(); + HostApplicationBuilder builder = Host.CreateApplicationBuilder(new HostApplicationBuilderSettings { EnvironmentName = Environments.Development, DisableDefaults = true }); + builder.Services.AddHealthChecks().AddSourceFlow(); + builder.Services.AddSourceFlow(sf => + { + sf.ServiceName = "accounts"; + sf.AddModule(); + sf.Roles = SourceFlowRoles.Api; // nothing relays: the outbox backlog stays + sf.Routing(r => r.Publish().AsIs().To("accounts.events")); + sf.UseSqlServer(Server.ConnectionString, o => o.Schema = schema); + }); + using IHost host = builder.Build(); + await host.StartAsync(Ct); + SqlServerStore store = host.Services.GetRequiredService(); + ICommandSender commands = host.Services.GetRequiredService(); + await commands.SendAsync(new OpenAccount(AccountId.New(), "Ada", 1m), null, Ct); + await commands.SendAsync(new OpenAccount(AccountId.New(), "Bob", 2m), null, Ct); + StoredEvent first = (await store.ReadAsync(GlobalPosition.Start, BucketRange.All, 1, Ct)).Events.ShouldHaveSingleItem(); + + StoreProbe probe = await store.ProbeAsync(Ct); + IReadOnlyList outbox = await store.GetOutboxBacklogAsync(Ct); + long all = await store.CountEventsAfterAsync(GlobalPosition.Start, BucketRange.All, 1000, Ct); + long afterFirst = await store.CountEventsAfterAsync(first.Position, BucketRange.All, 1000, Ct); + HealthReport health = await host.Services.GetRequiredService().CheckHealthAsync(c => c.Name == "sourceflow.store", Ct); + + probe.SchemaCurrent.ShouldBeTrue(probe.Detail); + outbox.Sum(o => o.Pending).ShouldBe(2); + outbox.ShouldAllBe(o => o.OldestDueAt != null); + all.ShouldBe(2); + afterFirst.ShouldBe(1); + (await store.CountParkedDeadLettersAsync(Ct)).ShouldBeEmpty(); + (await store.CountActiveProcessesAsync(Ct)).ShouldBeEmpty(); + (await store.GetHorizonAgeAsync(Ct)).ShouldBeGreaterThanOrEqualTo(TimeSpan.Zero); + health.Entries["sourceflow.store"].Status.ShouldNotBe(HealthStatus.Unhealthy, health.Entries["sourceflow.store"].Description); + } +} diff --git a/tests/Storage/SourceFlow.Storage.Tests/SqlServer/SqlServerServer.cs b/tests/Storage/SourceFlow.Storage.Tests/SqlServer/SqlServerServer.cs new file mode 100644 index 00000000..f7dc6317 --- /dev/null +++ b/tests/Storage/SourceFlow.Storage.Tests/SqlServer/SqlServerServer.cs @@ -0,0 +1,127 @@ +using Microsoft.Data.SqlClient; +using SourceFlow.Storage.SqlServer; +using SourceFlow.Storage.Tests.SqlServer; +using Testcontainers.MsSql; + +[assembly: AssemblyFixture(typeof(SqlServerServer))] + +namespace SourceFlow.Storage.Tests.SqlServer; + +/// +/// One SQL Server per test run: a Testcontainers container (SQL Server 2022), or the server in +/// SOURCEFLOW_TEST_SQLSERVER. Tests isolate themselves with a fresh schema each, so they never share state. It +/// starts on first use, so runs that select no SQL Server test never need Docker. +/// +public sealed class SqlServerServer : IAsyncLifetime +{ + /// The default image; the nightly matrix overrides it with SOURCEFLOW_TEST_SQLSERVER_IMAGE (2022, 2025). + public const string DefaultImage = "mcr.microsoft.com/mssql/server:2022-CU14-ubuntu-22.04"; + + private readonly Lazy _started; + private MsSqlContainer? _container; + + public SqlServerServer() + { + _started = new Lazy(StartAsync); + } + + public string ConnectionString { get; private set; } = string.Empty; + + public ValueTask InitializeAsync() + { + return ValueTask.CompletedTask; + } + + public Task EnsureStartedAsync() + { + return _started.Value; + } + + public async ValueTask DisposeAsync() + { + if (_container is not null) + { + await _container.DisposeAsync(); + } + } + + /// A unique, valid schema name. + public static string NewSchema(string prefix = "t") + { + return prefix + "_" + Guid.CreateVersion7().ToString("N"); + } + + /// A store on a fresh, migrated schema. + public async Task CreateStoreAsync(TimeProvider? time = null, string? schema = null) + { + var store = new SqlServerStore(new SqlServerStorageOptions { ConnectionString = ConnectionString, Schema = schema ?? NewSchema() }, time); + await store.CreateMigrator().MigrateAsync(TestContext.Current.CancellationToken); + return store; + } + + /// Runs one statement. + public async Task ExecuteAsync(string sql) + { + await using var connection = new SqlConnection(ConnectionString); + await connection.OpenAsync(TestContext.Current.CancellationToken); + await using var command = new SqlCommand(sql, connection); + await command.ExecuteNonQueryAsync(TestContext.Current.CancellationToken); + } + + private async Task StartAsync() + { + string? external = Environment.GetEnvironmentVariable("SOURCEFLOW_TEST_SQLSERVER"); + string server; + if (!string.IsNullOrWhiteSpace(external)) + { + server = external; + } + else + { + string image = Environment.GetEnvironmentVariable("SOURCEFLOW_TEST_SQLSERVER_IMAGE") is { Length: > 0 } custom ? custom : DefaultImage; + _container = new MsSqlBuilder(image).Build(); + await _container.StartAsync(); + server = _container.GetConnectionString(); + } + + // A database of our own with snapshot reads (doc 05 §5.5 recommends READ_COMMITTED_SNAPSHOT). + var builder = new SqlConnectionStringBuilder(server) { TrustServerCertificate = true }; + string database = string.IsNullOrEmpty(builder.InitialCatalog) || builder.InitialCatalog == "master" ? "sourceflow" : builder.InitialCatalog; + builder.InitialCatalog = "master"; + await using (var connection = new SqlConnection(builder.ConnectionString)) + { + await connection.OpenAsync(); + await using var command = new SqlCommand( + $"IF DB_ID(N'{database}') IS NULL BEGIN CREATE DATABASE [{database}]; ALTER DATABASE [{database}] SET READ_COMMITTED_SNAPSHOT ON; END", + connection); + await command.ExecuteNonQueryAsync(); + } + + builder.InitialCatalog = database; + builder.MaxPoolSize = 300; + ConnectionString = builder.ConnectionString; + } +} + +/// Base of SQL Server tests: starts the shared server before each test. +public abstract class SqlServerTest(SqlServerServer server) : IAsyncLifetime +{ + protected SqlServerServer Server { get; } = server; + + public virtual async ValueTask InitializeAsync() + { + await Server.EnsureStartedAsync(); + } + + public virtual ValueTask DisposeAsync() + { + return ValueTask.CompletedTask; + } +} + +/// SQL Server tests that assert on the global log run one at a time: the horizon is database-wide. +[CollectionDefinition(Name, DisableParallelization = true)] +public sealed class SqlServerCollection +{ + public const string Name = "SqlServer"; +} diff --git a/tests/Storage/SourceFlow.Storage.Tests/SqlServer/SqlServerStorageConformanceTests.cs b/tests/Storage/SourceFlow.Storage.Tests/SqlServer/SqlServerStorageConformanceTests.cs new file mode 100644 index 00000000..925e23ca --- /dev/null +++ b/tests/Storage/SourceFlow.Storage.Tests/SqlServer/SqlServerStorageConformanceTests.cs @@ -0,0 +1,81 @@ +using SourceFlow.Storage.SqlServer; +using SourceFlow.Testing.Conformance; + +namespace SourceFlow.Storage.Tests.SqlServer; + +/// An over a SQL Server store on its own schema. +internal sealed class SqlServerStorageFixture(SqlServerStore store) : IStorageFixture +{ + public SqlServerStore Store { get; } = store; + + public IEventStore Events => Store; + + public IEventLogReader Log => Store; + + public IStorageSessionFactory Sessions => Store; + + public ICheckpointStore Checkpoints => Store; + + public ILeaseManager Leases => Store; + + public IOutboxStore Outbox => Store; + + public IDeadLetterStore DeadLetters => Store; + + public ISnapshotStore Snapshots => Store; + + public IDocumentReader Documents => Store; + + public IStoreNotifications Notifications => Store; + + // Leases use the database clock by design (doc 05 §7.4). + public bool SupportsClockControl => false; + + public DateTimeOffset Now => TimeProvider.System.GetUtcNow(); + + public ValueTask AdvanceClockAsync(TimeSpan by) + { + throw new NotSupportedException("The SQL Server store uses the database clock for leases."); + } + + public ValueTask DisposeAsync() + { + return Store.DisposeAsync(); + } +} + +/// The storage conformance kit against SQL Server (SCK-01..58, plan 06 §2; WP-4.4). +[Collection(SqlServerCollection.Name)] +[Trait("Category", "Integration")] +[Trait("Provider", "SqlServer")] +[Trait("Requires", "Docker")] +public sealed class SqlServerStorageConformanceTests(SqlServerServer server) : SqlServerTest(server) +{ + public static TheoryData CaseIds => new(StorageConformance.Cases.Select(c => c.Id)); + + [Theory] + [MemberData(nameof(CaseIds))] + [Trait("Covers", "ADR-008;ADR-009;ADR-010;ES-R1;ES-R2;GAP-15")] + public async Task Sck(string id) + { + ConformanceCase @case = StorageConformance.Cases.Single(c => c.Id == id); + if (@case.RequiresClockControl) + { + Assert.Skip("Needs a controllable store clock; SQL Server leases use the database clock."); + } + + await using var fixture = new SqlServerStorageFixture(await Server.CreateStoreAsync()); + + await @case.Run(fixture, TestContext.Current.CancellationToken); + } + + [Fact] + [Trait("Id", "SCK-L01")] + [Trait("Category", "Property")] + [Trait("Covers", "ADR-006;ADR-008")] + public void AppendsAndOutbox_AreLinearizable() + { + SourceFlow.Tests.Shared.StorageLinearizability.AppendsAndOutbox( + () => new SqlServerStorageFixture(Server.CreateStoreAsync().GetAwaiter().GetResult()), iterations: 40, threads: 4); + } +} diff --git a/tests/Tooling/SourceFlow.Tooling.Tests/CliTests.cs b/tests/Tooling/SourceFlow.Tooling.Tests/CliTests.cs new file mode 100644 index 00000000..6ee1b6c6 --- /dev/null +++ b/tests/Tooling/SourceFlow.Tooling.Tests/CliTests.cs @@ -0,0 +1,632 @@ +using System.Text.Json; +using System.Text.Json.Nodes; +using Bank.Accounts; +using Microsoft.Extensions.DependencyInjection; +using SourceFlow.Hosting; +using SourceFlow.Messaging; +using SourceFlow.Runtime; +using SourceFlow.Storage; +using SourceFlow.Testing; +using SourceFlow.Tool; +using SourceFlow.Transport; + +namespace SourceFlow.Tooling.Tests; + +/// UT-CLI-01..34 (plan 05, WP-4.1, WP-2.7): dotnet sourceflow parsing and handlers, run inside an in-memory service. +[Trait("Category", "Unit")] +public sealed class CliTests +{ + private static CancellationToken Ct => TestContext.Current.CancellationToken; + + // ================================================================ parsing and modes + + [Fact] + [Trait("Id", "UT-CLI-01")] + public async Task Help_ListsTheCommandGroups() + { + (int code, string output, _) = await RunAsync(null, "--help"); + + code.ShouldBe(0); + foreach (string group in new[] { "db", "dlq", "projection", "topology", "query", "schema" }) + { + output.ShouldContain(group); + } + } + + [Fact] + [Trait("Id", "UT-CLI-02")] + public async Task UnknownCommands_AndMissingRequiredOptions_AreUsageErrors() + { + (int unknown, _, _) = await RunAsync(null, "frobnicate"); + (int missing, _, string error) = await RunAsync(null, "dlq", "discard", Guid.Empty.ToString()); + + unknown.ShouldNotBe(0); + missing.ShouldNotBe(0); + error.ShouldContain("--reason"); + } + + [Fact] + [Trait("Id", "UT-CLI-03")] + public async Task DbScript_PrintsTheMigrationsForTheSchema() + { + (int code, string output, _) = await RunAsync(null, "db", "script", "--schema", "billing"); + + code.ShouldBe(0); + output.ShouldContain("CREATE TABLE \"billing\".events"); + output.ShouldContain("CREATE TABLE \"billing\".schemas"); + } + + [Fact] + [Trait("Id", "UT-CLI-27")] + public async Task ModelCommands_OutsideAService_ExplainHowToRunThem() + { + (int code, _, string error) = await RunAsync(null, "schema", "export"); + + code.ShouldBe(1); + error.ShouldContain("dotnet run --project -- sourceflow schema export"); + } + + [Fact] + [Trait("Id", "UT-CLI-28")] + public async Task StoreCommands_WithoutAConnection_Fail() + { + string? previous = Environment.GetEnvironmentVariable("SOURCEFLOW_CONNECTION"); + Environment.SetEnvironmentVariable("SOURCEFLOW_CONNECTION", null); + try + { + (int code, _, string error) = await RunAsync(null, "dlq", "list"); + + code.ShouldBe(1); + error.ShouldContain("--connection"); + } + finally + { + Environment.SetEnvironmentVariable("SOURCEFLOW_CONNECTION", previous); + } + } + + [Fact] + [Trait("Id", "UT-CLI-29")] + public async Task IndexSync_NeedsPostgreSql() + { + await using SourceFlowTestHost host = await BankAsync(); + + (int code, _, string error) = await RunAsync(host, "db", "index", "sync"); + + code.ShouldBe(1); + error.ShouldContain("PostgreSQL"); + } + + [Fact] + [Trait("Id", "UT-CLI-30")] + public async Task TryRun_OnlyHandlesSourceFlowArguments() + { + await using SourceFlowTestHost host = await BankAsync(); + + (await SourceFlowCli.TryRunAsync(["--urls", "http://*:80"], host.Services, Ct)).ShouldBeNull(); + (await SourceFlowCli.TryRunAsync(["sourceflow", "topology", "export"], host.Services, Ct)).ShouldBe(0); + } + + // ================================================================ dlq + + [Fact] + [Trait("Id", "UT-CLI-04")] + [Trait("Id", "UT-CLI-05")] + public async Task DlqListAndShow() + { + await using SourceFlowTestHost host = await BankAsync(); + Guid id = await ParkAsync(host); + + (int listed, string list, _) = await RunAsync(host, "dlq", "list", "--consumer", "accounts"); + (int shown, string show, _) = await RunAsync(host, "dlq", "show", id.ToString(), "--payload"); + + listed.ShouldBe(0); + list.ShouldContain(id.ToString()); + list.ShouldContain("1 dead letter(s)"); + shown.ShouldBe(0); + show.ShouldContain("reason: PermanentFailure"); + show.ShouldContain("bank.account.open v1"); + show.ShouldContain("payload: {"); + } + + [Fact] + [Trait("Id", "UT-CLI-06")] + public async Task DlqReplay_ProcessesTheMessage() + { + await using SourceFlowTestHost host = await BankAsync(); + var account = AccountId.New(); + Guid id = await ParkAsync(host, new OpenAccount(account, "Ada", 5m)); + + (int code, _, _) = await RunAsync(host, "dlq", "replay", id.ToString(), "--note", "fixed"); + await host.WaitForIdleAsync(); + + code.ShouldBe(0); + (await host.EventsAsync(StreamId.For(BankAccount.AggregateName, account))).ShouldHaveSingleItem(); + (await host.Store.GetAsync(id, Ct))!.Status.ShouldBe(DeadLetterStatus.Replayed); + } + + [Fact] + [Trait("Id", "UT-CLI-37")] + [Trait("Covers", "doc 04 7")] + public async Task OutboxWrites_UseThePartitionCountTheServiceRecorded() + { + var store = new SourceFlow.Storage.InMemory.InMemoryStore(); + await using SourceFlowTestHost host = await SourceFlowTestHost.StartAsync(sf => + { + sf.ServiceName = "accounts"; + sf.AddModule(); + sf.Configure(o => o.OutboxPartitions = 5); + }, store: store, cancellationToken: Ct); + StoragePorts storage = host.Services.GetRequiredService().Storage; + + (await Cli.OutboxPartitionsAsync(storage, null, Ct)).ShouldBe(5); // CR-60: not the default 16 + (await Cli.OutboxPartitionsAsync(storage, 7, Ct)).ShouldBe(7); // --outbox-partitions still wins + } + + [Fact] + [Trait("Id", "UT-CLI-07")] + [Trait("Id", "UT-CLI-08")] + public async Task DlqDiscard_ThenPurge() + { + await using SourceFlowTestHost host = await BankAsync(); + Guid id = await ParkAsync(host); + + (int discarded, _, _) = await RunAsync(host, "dlq", "discard", id.ToString(), "--reason", "obsolete"); + (await host.Store.GetAsync(id, Ct))!.StatusNote.ShouldBe($"by {Environment.UserName}@{Environment.MachineName}: obsolete"); + (int purged, string output, _) = await RunAsync(host, "dlq", "purge", "--before", host.Time.GetUtcNow().AddMinutes(1).ToString("O")); + + discarded.ShouldBe(0); + purged.ShouldBe(0); + output.ShouldContain("Purged 1 dead letter(s)"); + (await host.Store.GetAsync(id, Ct)).ShouldBeNull(); + } + + // ================================================================ projection + + [Fact] + [Trait("Id", "UT-CLI-09")] + public async Task ProjectionSkip_MovesPastTheNextEvent_AndAudits() + { + await using SourceFlowTestHost host = await BankAsync(loops: false); + await host.SendAsync(new OpenAccount(AccountId.New(), "Ada", 1m), cancellationToken: Ct); + + (int code, string output, _) = await RunAsync(host, "projection", "skip", Summary, "--reason", "bad data"); + + code.ShouldBe(0); + output.ShouldContain("Skipped the event at"); + (await host.Store.GetAsync(Summary, 0, Ct)).ShouldNotBe(GlobalPosition.Start); + (await host.Store.QueryAsync(new DeadLetterQuery(Status: DeadLetterStatus.Discarded), Ct)).ShouldHaveSingleItem().StatusNote + .ShouldBe($"skipped: by {Environment.UserName}@{Environment.MachineName}: bad data"); // the operator is recorded (doc 10 §1) + } + + [Fact] + [Trait("Id", "UT-CLI-10")] + [Trait("Id", "UT-CLI-11")] + [Trait("Covers", "doc 06 3")] + public async Task ProjectionRepartition_StartsNewPartitionsAtTheMinimum_AndRefusesBadCounts() + { + await using SourceFlowTestHost host = await BankAsync(loops: false, partitions: 2); + LeaseToken lease = (await host.Store.TryAcquireAsync($"sub:{Summary}:1", "seed", TimeSpan.FromSeconds(1), Ct))!; + await using (IStorageSession session = await host.Store.BeginAsync(MessageEnvelope.DefaultTenant, Ct)) + { + session.SaveCheckpoint(Summary, 1, new GlobalPosition(9, 1), lease); + await session.CommitAsync(Ct); + } + + await host.Store.ReleaseAsync(lease, Ct); + + (int code, string output, _) = await RunAsync(host, "projection", "repartition", Summary, "--from", "2", "--to", "4"); + (int bad, _, string error) = await RunAsync(host, "projection", "repartition", Summary, "--from", "2", "--to", "3"); + + code.ShouldBe(0); + output.ShouldContain("4 partitions from 0:0"); // partition 0 had no checkpoint: the minimum is the start + for (int p = 0; p < 4; p++) + { + (await host.Store.GetAsync(Summary, p, Ct)).ShouldBe(GlobalPosition.Start); + } + + bad.ShouldBe(1); + error.ShouldContain("powers of two"); + } + + [Fact] + [Trait("Id", "UT-CLI-12")] + [Trait("Id", "UT-CLI-13")] + [Trait("Covers", "doc 06 6")] + public async Task ProjectionRebuildInPlace_RefusesWhileRunning_ThenDropsTheDocumentsAndReplays_DropRefusesTheServingGeneration() + { + var store = new SourceFlow.Storage.InMemory.InMemoryStore(); + var id = AccountId.New(); + await using (SourceFlowTestHost running = await BankAsync(store: store)) + { + await running.SendAsync(new OpenAccount(id, "Ada", 1m), cancellationToken: Ct); + await running.WaitForIdleAsync(); + (int refused, _, string error) = await RunAsync(running, "projection", "rebuild", "account-summary@1", "--in-place"); + refused.ShouldBe(1); + error.ShouldContain("stop the subscription first"); + } + + await using (SourceFlowTestHost stopped = await BankAsync(loops: false, store: store)) + { + (int rebuilt, string output, _) = await RunAsync(stopped, "projection", "rebuild", "account-summary@1", "--in-place"); + rebuilt.ShouldBe(0); + output.ShouldContain("dropped 1 document(s)"); + (await stopped.DocumentAsync(id.ToStreamSegment())).ShouldBeNull(); + } + + await using SourceFlowTestHost restarted = await BankAsync(store: store); + await restarted.WaitForIdleAsync(); + (await restarted.DocumentAsync(id.ToStreamSegment())).ShouldNotBeNull(); // replayed + + (int dropped, _, string refusal) = await RunAsync(restarted, "projection", "drop", "account-summary@1"); + dropped.ShouldBe(1); + refusal.ShouldContain("serves reads"); + } + + [Fact] + [Trait("Id", "UT-CLI-31")] + [Trait("Id", "UT-CLI-32")] + [Trait("Covers", "doc 06 6;ADR-032")] + public async Task ProjectionRebuild_BuildsANewGenerationBesideTheServingOne_ThenTheRetiredOneCanBeDropped() + { + var store = new SourceFlow.Storage.InMemory.InMemoryStore(); + var id = AccountId.New(); + await using SourceFlowTestHost host = await BankAsync(store: store); + await host.SendAsync(new OpenAccount(id, "Ada", 7m), cancellationToken: Ct); + await host.WaitForIdleAsync(); + await AliasAsync(store, host, a => a.Target == "account-summary@1"); + + (int rebuilt, string output, _) = await RunAsync(host, "projection", "rebuild", "account-summary@1"); + rebuilt.ShouldBe(0); + output.ShouldContain("building account-summary@1.2 beside account-summary@1"); + await AliasAsync(store, host, a => a.Target == "account-summary@1.2"); + + (int listed, string list, _) = await RunAsync(host, "projection", "generations", "--format", "json"); + listed.ShouldBe(0); + JsonNode row = JsonNode.Parse(list)!.AsArray().ShouldHaveSingleItem()!; + row["serving"]!.GetValue().ShouldBe("account-summary@1.2"); + row["previous"]!.GetValue().ShouldBe("account-summary@1"); + (await host.DocumentAsync(id.ToStreamSegment()))!.Balance.ShouldBe(7m); + + (int dropped, string drop, _) = await RunAsync(host, "projection", "drop", "account-summary@1"); + dropped.ShouldBe(0); + drop.ShouldContain("Dropped 1 document(s)"); + (await store.ListAliasesAsync(Ct))[0].Previous.ShouldBeNull(); + } + + [Fact] + [Trait("Id", "UT-CLI-33")] + [Trait("Id", "UT-CLI-34")] + [Trait("Covers", "doc 06 6")] + public async Task ProjectionSwitch_RollsReadsBack_AndRebuildValidatesTheGeneration() + { + var store = new SourceFlow.Storage.InMemory.InMemoryStore(); + await using SourceFlowTestHost host = await BankAsync(store: store); + await host.SendAsync(new OpenAccount(AccountId.New(), "Ada", 1m), cancellationToken: Ct); + await host.WaitForIdleAsync(); + await AliasAsync(store, host, a => a.Target == "account-summary@1"); + await RunAsync(host, "projection", "rebuild", "account-summary@1"); + await AliasAsync(store, host, a => a.Target == "account-summary@1.2"); + + (int switched, string output, _) = await RunAsync(host, "projection", "switch", "account-summary", "account-summary@1", "--reason", "bad build"); + (int same, _, string already) = await RunAsync(host, "projection", "switch", "account-summary", "account-summary@1", "--reason", "again"); + (int foreign, _, string mismatch) = await RunAsync(host, "projection", "switch", "account-summary", "other@1", "--reason", "typo"); + (int version, _, string wrongVersion) = await RunAsync(host, "projection", "rebuild", "account-summary@3"); + (int malformed, _, string bad) = await RunAsync(host, "projection", "rebuild", "account-summary"); + + switched.ShouldBe(0); + output.ShouldContain("from account-summary@1.2 to account-summary@1"); + CollectionAlias alias = (await store.ListAliasesAsync(Ct)).ShouldHaveSingleItem(); + alias.Target.ShouldBe("account-summary@1"); + alias.Previous.ShouldBe("account-summary@1.2"); + same.ShouldBe(1); + already.ShouldContain("already serves reads"); + foreign.ShouldBe(1); + mismatch.ShouldContain("not a generation of account-summary"); + version.ShouldBe(1); + wrongVersion.ShouldContain("not version 3"); + malformed.ShouldBe(1); + bad.ShouldContain("not a read-model generation"); + } + + private static async Task AliasAsync(SourceFlow.Storage.InMemory.InMemoryStore store, SourceFlowTestHost host, Func condition) + { + for (int i = 0; i < 300; i++) + { + if ((await store.ListAliasesAsync(Ct)).FirstOrDefault() is { } alias && condition(alias)) + { + return; + } + + await host.WaitForIdleAsync(); + await Task.Delay(TimeSpan.FromMilliseconds(10), TimeProvider.System, Ct); + } + + throw new TimeoutException("The alias did not reach the expected state: " + string.Join(", ", await store.ListAliasesAsync(Ct))); + } + + // ================================================================ topology + + [Fact] + [Trait("Id", "UT-CLI-14")] + [Trait("Id", "UT-CLI-15")] + [Trait("Id", "UT-CLI-16")] + [Trait("Id", "UT-TOP-15")] + [Trait("Covers", "doc 07 5")] + public async Task Topology_ExportsJsonAndText_AndValidates() + { + await using SourceFlowTestHost host = await BankAsync(routing: r => r.Publish().As(AccountContracts.ToV1).To("accounts.events")); + + (int json, string exported, _) = await RunAsync(host, "topology", "export"); + (int text, string lines, _) = await RunAsync(host, "topology", "export", "--format", "text"); + (int valid, string validated, _) = await RunAsync(host, "topology", "validate"); + + json.ShouldBe(0); + JsonNode topology = JsonNode.Parse(exported)!; + topology["schemaVersion"]!.GetValue().ShouldBe(TopologyExport.SchemaVersion); + topology["transport"]!.GetValue().ShouldBe("sourceflow.inmemory"); + topology["endpoint"]!["name"]!.GetValue().ShouldBe("accounts"); + topology["publishes"]![0]!["topic"]!.GetValue().ShouldBe("accounts.events"); + topology["publishes"]![0]!["messages"]![0]!.GetValue().ShouldBe("accounts.account-opened.v1"); + topology["endpoint"]!["commands"]!.AsArray().Select(c => c!.GetValue()).ShouldContain("bank.account.open.v1"); + topology["resources"]!.AsArray().Select(r => r!["name"]!.GetValue()).ShouldBe(["accounts", "accounts.events"]); + text.ShouldBe(0); + lines.ShouldContain("publish accounts.events"); + valid.ShouldBe(0); + validated.ShouldContain("in place"); + exported.ShouldBe(TopologyExport.ToJson(host.Runtime.TopologyDocument()), "the CLI writes the library export"); + lines.ShouldContain("resources (sourceflow.inmemory)"); + } + + [Fact] + [Trait("Id", "UT-TOP-15")] + public async Task TopologyExport_WritesToAFile() + { + await using SourceFlowTestHost host = await BankAsync(routing: r => r.Publish().As(AccountContracts.ToV1).To("accounts.events")); + string file = Path.Combine(Path.GetTempPath(), $"topology-{Guid.CreateVersion7():N}.json"); + try + { + (int code, string output, _) = await RunAsync(host, "topology", "export", "--output", file); + (int bad, _, string error) = await RunAsync(host, "topology", "export", "--format", "yaml"); + + code.ShouldBe(0); + output.ShouldContain(file); + (await File.ReadAllTextAsync(file, TestContext.Current.CancellationToken)).ShouldBe(TopologyExport.ToJson(host.Runtime.TopologyDocument())); + bad.ShouldNotBe(0); + error.ShouldContain("yaml"); + } + finally + { + File.Delete(file); + } + } + + // ================================================================ query + + [Fact] + [Trait("Id", "UT-CLI-17")] + [Trait("Id", "UT-CLI-22")] + public async Task Query_Table_WithParameters() + { + await using SourceFlowTestHost host = await SeededAsync(); + + (int code, string output, _) = await RunAsync(host, "query", "from readmodel \"account-summary\" | where balance > @min | project holder, balance | order by holder", "--param", "min=15"); + + code.ShouldBe(0); + output.ShouldContain("holder"); + output.ShouldContain("=cmd"); + output.ShouldNotContain("Ada"); + output.ShouldContain("(2 rows)"); + } + + [Fact] + [Trait("Id", "UT-CLI-18")] + [Trait("Id", "UT-CLI-19")] + public async Task Query_JsonAndCsv_WithFormulaNeutralisation() + { + await using SourceFlowTestHost host = await SeededAsync(); + const string Query = "from readmodel \"account-summary\" | project holder, balance | order by holder"; + + (_, string json, _) = await RunAsync(host, "query", Query, "--format", "json"); + (_, string csv, _) = await RunAsync(host, "query", Query, "--format", "csv"); + + string[] rows = json.Split('\n', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries); + rows.Length.ShouldBe(3); + JsonDocument.Parse(rows[1]).RootElement.GetProperty("holder").GetString().ShouldBe("Ada"); + string[] lines = csv.Split('\n', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries); + lines[0].ShouldBe("holder,balance"); + lines[1].ShouldBe("'=cmd,20"); + } + + [Fact] + [Trait("Id", "UT-CLI-20")] + [Trait("Id", "UT-CLI-21")] + public async Task Query_ExplainAndValidate() + { + await using SourceFlowTestHost host = await SeededAsync(); + + (int explained, string plan, _) = await RunAsync(host, "query", "from readmodel \"account-summary\" | where balance > @min", "--param", "min=1", "--explain"); + (int invalid, _, string diagnostics) = await RunAsync(host, "query", "DELETE FROM x", "--sql", "--validate"); + + explained.ShouldBe(0); + plan.ShouldContain("engine: in-memory"); + plan.ShouldContain("parameters: 1"); + invalid.ShouldBe(1); + diagnostics.ShouldContain("SFQ0102"); + } + + // ================================================================ schema + + [Fact] + [Trait("Id", "UT-CLI-23")] + [Trait("Id", "UT-CLI-24")] + [Trait("Id", "UT-CLI-25")] + [Trait("Covers", "doc 14 2.2")] + public async Task SchemaExport_AndCheckAgainstItself() + { + await using SourceFlowTestHost host = await BankAsync(); + string directory = Directory.CreateTempSubdirectory("sourceflow-cli-").FullName; + string lockFile = Path.Combine(directory, "schemas.lock.json"); + string asyncApi = Path.Combine(directory, "asyncapi.json"); + + (int exported, _, _) = await RunAsync(host, "schema", "export", "--out", lockFile); + (int api, _, _) = await RunAsync(host, "schema", "export", "--format", "asyncapi", "--out", asyncApi); + (int checkedCode, string output, _) = await RunAsync(host, "schema", "check", "--baseline", lockFile); + + exported.ShouldBe(0); + JsonNode.Parse(await File.ReadAllTextAsync(lockFile, Ct))!["schemas"]!.AsArray().Count.ShouldBeGreaterThan(5); + api.ShouldBe(0); + JsonNode.Parse(await File.ReadAllTextAsync(asyncApi, Ct))!["asyncapi"]!.GetValue().ShouldBe("3.0.0"); + checkedCode.ShouldBe(0); + output.ShouldContain("Compatible"); + Directory.Delete(directory, recursive: true); + } + + [Fact] + [Trait("Id", "UT-CLI-26")] + [Trait("Covers", "doc 14 2.2")] + public async Task SchemaCheck_ABreakingChange_ExitsOne() + { + await using SourceFlowTestHost host = await BankAsync(); + string directory = Directory.CreateTempSubdirectory("sourceflow-cli-").FullName; + string lockFile = Path.Combine(directory, "schemas.lock.json"); + await RunAsync(host, "schema", "export", "--out", lockFile); + + // The published bank.account.opened v1 had a field this build no longer has. + JsonNode baseline = JsonNode.Parse(await File.ReadAllTextAsync(lockFile, Ct))!; + JsonNode opened = baseline["schemas"]!.AsArray().First(s => s!["type"]!.GetValue() == "bank.account.opened")!; + opened["schema"]!["properties"]!["branch"] = new JsonObject { ["type"] = "string" }; + await File.WriteAllTextAsync(lockFile, baseline.ToJsonString(), Ct); + + (int code, _, string error) = await RunAsync(host, "schema", "check", "--baseline", lockFile); + + code.ShouldBe(1); + error.ShouldContain("SFC03"); + error.ShouldContain("bank.account.opened v1.branch"); + Directory.Delete(directory, recursive: true); + } + + // ================================================================ refusals and empty results + + [Fact] + [Trait("Id", "UT-CLI-35")] + public async Task Refusals_SayWhatToDoInstead() + { + await using SourceFlowTestHost host = await BankAsync(loops: false); + string missingBaseline = Path.Combine(Path.GetTempPath(), $"no-such-lock-{Guid.CreateVersion7():N}.json"); + + // The global tool can't see the projection: repartitioning re-applies events, so it asks for --idempotent first. + (int unconfirmed, _, string confirm) = await RunAsync(null, "projection", "repartition", Summary, "--from", "1", "--to", "2", "--connection", "Host=localhost;Port=1"); + (int foreign, _, string guard) = await RunAsync(host, "projection", "repartition", "projection:other@1", "--from", "1", "--to", "2"); + (int status, _, string unknownStatus) = await RunAsync(host, "dlq", "list", "--status", "lost"); + (int parameter, _, string badParameter) = await RunAsync(host, "query", "from readmodel \"account-summary\" | where balance > @min", "--param", "min"); + (int format, _, string badFormat) = await RunAsync(host, "schema", "export", "--format", "xml"); + (int baseline, _, string noBaseline) = await RunAsync(host, "schema", "check", "--baseline", missingBaseline); + + unconfirmed.ShouldBe(1); + confirm.ShouldContain("--idempotent"); + foreign.ShouldBe(1); + guard.ShouldContain("isn't a document projection"); + status.ShouldBe(1); + unknownStatus.ShouldContain("Unknown status 'lost'"); + parameter.ShouldBe(1); + badParameter.ShouldContain("must be name=value"); + format.ShouldBe(1); + badFormat.ShouldContain("Unknown format 'xml'"); + baseline.ShouldBe(1); + noBaseline.ShouldContain("doesn't exist"); + } + + [Fact] + [Trait("Id", "UT-CLI-36")] + public async Task EmptyResults_StatusFilters_AndJsonSchemas() + { + await using SourceFlowTestHost host = await BankAsync(loops: false); + Guid parked = await ParkAsync(host); + Guid discarded = await ParkAsync(host); + await RunAsync(host, "dlq", "discard", discarded.ToString(), "--reason", "obsolete"); + + (int generations, string noAliases, _) = await RunAsync(host, "projection", "generations"); + (int queried, string noRows, _) = await RunAsync(host, "query", "from readmodel \"account-summary\" | project holder"); + (_, string all, _) = await RunAsync(host, "dlq", "list", "--status", "all"); + (_, string onlyDiscarded, _) = await RunAsync(host, "dlq", "list", "--status", "discarded"); + (_, string replayed, _) = await RunAsync(host, "dlq", "list", "--status", "replayed"); + (int exported, string schemas, _) = await RunAsync(host, "schema", "export", "--format", "jsonschema"); + + generations.ShouldBe(0); + noAliases.ShouldContain("No read-model aliases yet."); + queried.ShouldBe(0); + noRows.ShouldContain("(no rows)"); + all.ShouldContain(parked.ToString()); + all.ShouldContain("2 dead letter(s)"); + onlyDiscarded.ShouldContain(discarded.ToString()); + onlyDiscarded.ShouldNotContain(parked.ToString()); + replayed.ShouldContain("0 dead letter(s)"); + exported.ShouldBe(0); + JsonNode.Parse(schemas)!.AsArray().Count.ShouldBeGreaterThan(5); + } + + // ================================================================ helpers + + private const string Summary = "projection:account-summary@1"; + + private static async Task<(int Code, string Output, string Error)> RunAsync(SourceFlowTestHost? host, params string[] args) + { + using var output = new StringWriter(); + using var error = new StringWriter(); + int code = await SourceFlowCli.RunAsync(args, host?.Services, output, error, Ct); + return (code, output.ToString(), error.ToString()); + } + + private static Task BankAsync(bool loops = true, int partitions = 1, Action? routing = null, SourceFlow.Storage.InMemory.InMemoryStore? store = null) + { + return SourceFlowTestHost.StartAsync(sf => + { + sf.ServiceName = "accounts"; + sf.AddModule(); + sf.AddModule(); + sf.Projections(p => p.Add().Async()); + sf.Configure(o => o.SubscriptionPartitions = partitions); + if (!loops) + { + sf.Roles = SourceFlowRoles.Api; + } + + if (routing is not null) + { + sf.Routing(routing); + } + }, store: store); + } + + private static async Task SeededAsync() + { + SourceFlowTestHost host = await BankAsync(); + await host.SendAsync(new OpenAccount(AccountId.New(), "Ada", 10m), cancellationToken: Ct); + await host.SendAsync(new OpenAccount(AccountId.New(), "=cmd", 20m), cancellationToken: Ct); + await host.SendAsync(new OpenAccount(AccountId.New(), "Grace", 30m), cancellationToken: Ct); + await host.WaitForIdleAsync(); + return host; + } + + private static async Task ParkAsync(SourceFlowTestHost host, OpenAccount? command = null) + { + DateTimeOffset now = host.Time.GetUtcNow(); + var id = Guid.CreateVersion7(now); + await host.Store.ParkAsync(new DeadLetter + { + Id = id, + Consumer = "accounts", + Source = "receive", + Envelope = host.Runtime.CreateEnvelope(command ?? new OpenAccount(AccountId.New(), "Ada", 1m)), + Destination = "accounts", + Reason = "PermanentFailure", + ErrorType = "System.InvalidOperationException", + ErrorMessage = "boom", + Attempts = 1, + FirstFailedAt = now, + ParkedAt = now, + }, Ct); + return id; + } +} diff --git a/tests/Tooling/SourceFlow.Tooling.Tests/ManifestCliTests.cs b/tests/Tooling/SourceFlow.Tooling.Tests/ManifestCliTests.cs new file mode 100644 index 00000000..23e326a8 --- /dev/null +++ b/tests/Tooling/SourceFlow.Tooling.Tests/ManifestCliTests.cs @@ -0,0 +1,128 @@ +using System.Text.Json.Nodes; +using Bank.Accounts; +using SourceFlow.Testing; +using SourceFlow.Tool; + +namespace SourceFlow.Tooling.Tests; + +/// dotnet sourceflow manifest export and the manifest drift check (doc 15 §3.2, WP-S.2). +public sealed class ManifestCliTests +{ + private static CancellationToken Ct => TestContext.Current.CancellationToken; + + [Fact] + [Trait("Category", "Unit")] + [Trait("Id", "UT-MAN-15")] + [Trait("Covers", "WFD-11")] + public async Task Export_InsideAService_WritesTheManifest_AndCheckDetectsDrift() + { + await using SourceFlowTestHost host = await SourceFlowTestHost.StartAsync(sf => + { + sf.ServiceName = "accounts"; + sf.AddModule(); + sf.AddModule(); + sf.Routing(r => r.Publish().As(AccountContracts.ToV1).To("accounts.events")); + }, cancellationToken: Ct); + string folder = Path.Combine(Path.GetTempPath(), "sourceflow-manifest-" + Path.GetRandomFileName()); + string file = Path.Combine(folder, "artifacts", "sourceflow.manifest.json"); + try + { + (int code, string output, _) = await RunAsync(host, "manifest", "export", "--output", file); + code.ShouldBe(0); + output.ShouldContain("Wrote " + file); + JsonObject manifest = JsonNode.Parse(await File.ReadAllTextAsync(file, Ct))!.AsObject(); + manifest["service"]!.GetValue().ShouldBe("accounts"); + manifest["publishes"]![0]!["as"]!.GetValue().ShouldBe("accounts.account-opened.v1"); + + (code, output, _) = await RunAsync(host, "manifest", "export", "--check", "--output", file); + code.ShouldBe(0); + output.ShouldContain("up to date"); + + // Windows line endings in a checked-out file are not drift. + await File.WriteAllTextAsync(file, (await File.ReadAllTextAsync(file, Ct)).Replace("\n", "\r\n", StringComparison.Ordinal), Ct); + (code, _, _) = await RunAsync(host, "manifest", "export", "--check", "--output", file); + code.ShouldBe(0); + + await File.WriteAllTextAsync(file, (await File.ReadAllTextAsync(file, Ct)).Replace("\"accounts.events\"", "\"old.events\"", StringComparison.Ordinal), Ct); + (code, _, string error) = await RunAsync(host, "manifest", "export", "--check", "--output", file); + code.ShouldBe(1); + error.ShouldContain("Manifest drift"); + error.ShouldContain("committed: \"topic\": \"old.events\""); + error.ShouldContain("regenerated: \"topic\": \"accounts.events\""); + + (code, _, error) = await RunAsync(host, "manifest", "export", "--check", "--output", Path.Combine(folder, "none.json")); + code.ShouldBe(1); + error.ShouldContain("doesn't exist"); + + (code, output, _) = await RunAsync(host, "manifest", "export"); + code.ShouldBe(0); + output.ShouldStartWith("{\n \"manifestVersion\": 1,"); + + (code, _, error) = await RunAsync(host, "manifest", "export", "--check"); + code.ShouldBe(1); + error.ShouldContain("--check needs --output"); + } + finally + { + if (Directory.Exists(folder)) + { + Directory.Delete(folder, recursive: true); + } + } + } + + [Fact] + [Trait("Category", "Unit")] + [Trait("Id", "UT-MAN-15")] + public async Task Export_FromTheGlobalTool_NeedsAProject() + { + (int code, _, string error) = await RunAsync(null, "manifest", "export"); + code.ShouldBe(1); + error.ShouldContain("needs the service's model"); + + (code, _, error) = await RunAsync(null, "manifest", "export", "--project", Path.Combine(Path.GetTempPath(), "no-such-project-" + Path.GetRandomFileName())); + code.ShouldBe(1); + error.ShouldContain("is not a project file"); + } + + [Fact] + [Trait("Category", "Integration")] + [Trait("Id", "UT-MAN-15")] + [Trait("Covers", "WFD-11;WFD-NFR-3")] + public async Task Export_DesignTimeRunOfASampleHost_MatchesTheCommittedManifest_WithoutADatabase() + { + string root = RepositoryRoot(); + string project = Path.Combine(root, "samples", "TravelBooking", "Bookings.Api", "Bookings.Api.csproj"); + string configuration = AppContext.BaseDirectory.Contains($"{Path.DirectorySeparatorChar}Release{Path.DirectorySeparatorChar}", StringComparison.Ordinal) ? "Release" : "Debug"; + bool built = File.Exists(Path.Combine(root, "samples", "TravelBooking", "Bookings.Api", "bin", configuration, "net10.0", "Bookings.Api.dll")); + + // Port 1 refuses connections: a design-time run that touched the database would fail. + (int code, string output, string error) = await RunAsync( + null, + ["manifest", "export", "--project", project, "-c", configuration, .. built ? new[] { "--no-build" } : [], "--check", + "--output", Path.Combine(root, "samples", "TravelBooking", "Bookings", "sourceflow.manifest.json"), + "--", "--ConnectionStrings:SourceFlow=Host=localhost;Port=1;Timeout=1"]); + + code.ShouldBe(0, error); + output.ShouldContain("up to date"); + } + + private static async Task<(int Code, string Output, string Error)> RunAsync(SourceFlowTestHost? host, params string[] args) + { + using var output = new StringWriter(); + using var error = new StringWriter(); + int code = await SourceFlowCli.RunAsync(args, host?.Services, output, error, Ct); + return (code, output.ToString(), error.ToString()); + } + + private static string RepositoryRoot() + { + string? directory = AppContext.BaseDirectory; + while (directory is not null && !File.Exists(Path.Combine(directory, "SourceFlow.slnx"))) + { + directory = Path.GetDirectoryName(directory); + } + + return directory ?? throw new InvalidOperationException("Repository root not found."); + } +} diff --git a/tests/Tooling/SourceFlow.Tooling.Tests/ObservabilityTests.cs b/tests/Tooling/SourceFlow.Tooling.Tests/ObservabilityTests.cs new file mode 100644 index 00000000..3b4984dc --- /dev/null +++ b/tests/Tooling/SourceFlow.Tooling.Tests/ObservabilityTests.cs @@ -0,0 +1,135 @@ +using System.Text; +using System.Text.Json.Nodes; +using SourceFlow.Diagnostics; +using SourceFlow.Testing; +using SourceFlow.Tool; + +namespace SourceFlow.Tooling.Tests; + +/// +/// The dashboard and alert generator (WP-4.3, doc 08 §3, §6), and the CI drift check: deploy/observability must be +/// what the generator writes today. Set SOURCEFLOW_APPROVE=1 to rewrite the committed files. +/// +[Trait("Category", "Unit")] +public sealed class ObservabilityTests +{ + private static readonly string Directory = Path.Combine(FindRoot(), "deploy", "observability"); + + [Theory] + [InlineData(Observability.DashboardFile)] + [InlineData(Observability.AlertsFile)] + [Trait("Id", "UT-HC-15")] + [Trait("Covers", "doc 08 6")] + public void TheCommittedFiles_AreWhatTheGeneratorWrites(string file) + { + string generated = file == Observability.DashboardFile ? Observability.Dashboard() : Observability.AlertRules(); + string path = Path.Combine(Directory, file); + string? committed = File.Exists(path) ? File.ReadAllText(path).ReplaceLineEndings("\n") : null; + if (committed != generated && string.Equals(Environment.GetEnvironmentVariable(Approvals.ApproveVariable), "1", StringComparison.Ordinal)) + { + System.IO.Directory.CreateDirectory(Directory); + File.WriteAllText(path, generated, new UTF8Encoding(encoderShouldEmitUTF8Identifier: false)); + return; + } + + committed.ShouldBe(generated, $"{path} is out of date: run `dotnet sourceflow observability export --output deploy/observability` or the tests with {Approvals.ApproveVariable}=1."); + } + + [Fact] + [Trait("Id", "UT-HC-15")] + public void TheDashboard_HasAPanelPerInstrument_AndTheSloRow() + { + JsonObject dashboard = JsonNode.Parse(Observability.Dashboard())!.AsObject(); + JsonObject[] panels = [.. dashboard["panels"]!.AsArray().Select(p => p!.AsObject())]; + + foreach (InstrumentInfo instrument in SourceFlowTelemetry.Catalogue) + { + JsonObject panel = panels.Single(p => p["title"]!.GetValue() == instrument.Name); + panel["targets"]!.AsArray().ShouldAllBe(t => t!["expr"]!.GetValue().Contains(Observability.Prom(instrument.Name), StringComparison.Ordinal)); + } + + panels.Where(p => p["type"]!.GetValue() == "stat").Select(p => p["title"]!.GetValue()) + .ShouldBe(["Write availability", "Write latency p99", "Read-model freshness", "Delivery durability", "Parked messages (1 h)"]); + panels.Select(p => p["id"]!.GetValue()).ShouldBeUnique(); + foreach (JsonObject panel in panels.Where(p => p["type"]!.GetValue() != "row")) + { + JsonObject grid = panel["gridPos"]!.AsObject(); + (grid["x"]!.GetValue() + grid["w"]!.GetValue()).ShouldBeLessThanOrEqualTo(24, panel["title"]!.GetValue()); + } + } + + [Fact] + [Trait("Id", "UT-HC-15")] + public void PrometheusNames_FollowTheOpenTelemetryConversion() + { + Observability.Prom(SourceFlowTelemetry.Instruments.CommandDuration).ShouldBe("sourceflow_command_duration_seconds"); + Observability.Prom(SourceFlowTelemetry.Instruments.DeadLetterParked).ShouldBe("sourceflow_deadletter_parked_total"); + Observability.Prom(SourceFlowTelemetry.Instruments.OutboxAge).ShouldBe("sourceflow_outbox_age_seconds"); + Observability.Prom(SourceFlowTelemetry.Instruments.SubscriptionLag).ShouldBe("sourceflow_subscription_lag"); + Observability.Prom(SourceFlowTelemetry.Instruments.SentMessages).ShouldBe("messaging_client_sent_messages_total"); + Observability.Label(SourceFlowTelemetry.Tags.Outcome).ShouldBe("sourceflow_outcome"); + Should.Throw(() => Observability.Prom("sourceflow.not.an.instrument")); + } + + [Fact] + [Trait("Id", "UT-HC-15")] + [Trait("Covers", "doc 08 6")] + public void TheAlerts_CoverEverySlo_AndUseOnlyCatalogueMetrics() + { + string[] metrics = [.. SourceFlowTelemetry.Catalogue.Select(i => Observability.Prom(i.Name))]; + HashSet labels = [.. SourceFlowTelemetry.Catalogue.SelectMany(i => i.Tags).Select(Observability.Label)]; + string rules = Observability.AlertRules(); + + Observability.Alerts.Select(a => a.Name).ShouldBe( + ["SourceFlowDeadLetterParked", "SourceFlowSubscriptionStalled", "SourceFlowOutboxDelayed", "SourceFlowReadModelsStale", "SourceFlowWriteLatency", "SourceFlowWriteErrors", "SourceFlowHorizonHeld", "SourceFlowWorkflowManualIntervention"]); + foreach (AlertRule alert in Observability.Alerts) + { + System.Text.RegularExpressions.Regex.Matches(alert.Expression, "(sourceflow|messaging)_[a-z_]+") + .Select(m => m.Value.Replace("_bucket", string.Empty, StringComparison.Ordinal).Replace("_count", string.Empty, StringComparison.Ordinal)) + .Where(m => !labels.Contains(m)) + .ShouldAllBe(m => metrics.Contains(m), alert.Name); + alert.Severity.ShouldBeOneOf("page", "warning"); + } + + rules.ShouldStartWith("# Generated"); + rules.ShouldContain("groups:\n - name: sourceflow\n rules:\n - alert: SourceFlowDeadLetterParked\n"); + rules.ShouldNotContain("\r"); + } + + [Fact] + [Trait("Id", "UT-HC-15")] + public async Task TheCli_WritesBothFiles() + { + string directory = Path.Combine(Path.GetTempPath(), "sourceflow-observability-" + Guid.CreateVersion7().ToString("N")[^12..]); + try + { + using var output = new StringWriter(); + using var error = new StringWriter(); + int code = await SourceFlowCli.RunAsync(["observability", "export", "--output", directory], output: output, error: error, cancellationToken: TestContext.Current.CancellationToken); + + code.ShouldBe(0, error.ToString()); + (await File.ReadAllTextAsync(Path.Combine(directory, Observability.DashboardFile), TestContext.Current.CancellationToken)).ShouldBe(Observability.Dashboard()); + (await File.ReadAllTextAsync(Path.Combine(directory, Observability.AlertsFile), TestContext.Current.CancellationToken)).ShouldBe(Observability.AlertRules()); + } + finally + { + if (System.IO.Directory.Exists(directory)) + { + System.IO.Directory.Delete(directory, recursive: true); + } + } + } + + private static string FindRoot() + { + for (DirectoryInfo? directory = new(AppContext.BaseDirectory); directory is not null; directory = directory.Parent) + { + if (File.Exists(Path.Combine(directory.FullName, "SourceFlow.slnx"))) + { + return directory.FullName; + } + } + + throw new InvalidOperationException("The repository root was not found."); + } +} diff --git a/tests/Tooling/SourceFlow.Tooling.Tests/SourceFlow.Tooling.Tests.csproj b/tests/Tooling/SourceFlow.Tooling.Tests/SourceFlow.Tooling.Tests.csproj new file mode 100644 index 00000000..b33253ff --- /dev/null +++ b/tests/Tooling/SourceFlow.Tooling.Tests/SourceFlow.Tooling.Tests.csproj @@ -0,0 +1,9 @@ + + + + + + + + + diff --git a/tests/Tooling/SourceFlow.Tooling.Tests/SpecTests.cs b/tests/Tooling/SourceFlow.Tooling.Tests/SpecTests.cs new file mode 100644 index 00000000..675aa86b --- /dev/null +++ b/tests/Tooling/SourceFlow.Tooling.Tests/SpecTests.cs @@ -0,0 +1,158 @@ +using Bank.Accounts; +using Bank.Transfers; +using SourceFlow.Testing; + +namespace SourceFlow.Tooling.Tests; + +/// UT-TST (plan 05): the spec library, tested with the Bank domain. +[Trait("Category", "Unit")] +public sealed class SpecTests +{ + private static readonly AccountId Account = AccountId.Parse("0193a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b"); + private static readonly AccountId Other = AccountId.Parse("0193a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5c"); + private static readonly DateTimeOffset Now = new(2026, 2, 1, 0, 0, 0, TimeSpan.Zero); + + [Fact] + [Trait("Id", "UT-TST-01")] + public void AggregateSpec_Then_PassesForTheProducedEvents() + { + new AggregateSpec() + .At(Now) + .When(new OpenAccount(Account, "Ada", 10m)) + .Then(new AccountOpened(Account, "Ada", 10m, Now)) + .ThenState(s => s.Balance == 10m && s.Status == AccountStatus.Open); + } + + [Fact] + [Trait("Id", "UT-TST-02")] + public void AggregateSpec_ThenRejected_AndThenNoOp() + { + new AggregateSpec() + .Given(new AccountOpened(Account, "Ada", 10m, Now)) + .When(new Withdraw(Account, 11m)) + .ThenRejected(AccountErrors.InsufficientFunds.Code); + + new AggregateSpec() + .Given(new AccountOpened(Account, "Ada", 10m, Now), new AccountClosed(Account, "x", Now)) + .When(new CloseAccount(Account, "again")) + .ThenNoOp(); + } + + [Fact] + [Trait("Id", "UT-TST-03")] + public void AggregateSpec_Mismatch_FailsWithAReadableMessage() + { + AggregateSpec spec = new AggregateSpec().When(new Deposit(Account, 1m)); + + Should.Throw(() => spec.Then(new MoneyDeposited(Account, 1m, 1m))).Message.ShouldContain("account.not_open"); + Should.Throw(() => spec.ThenNoOp()); + Should.Throw(() => new AggregateSpec().ThenNoOp()).Message.ShouldContain("When"); + } + + [Fact] + [Trait("Id", "UT-TST-04")] + [Trait("Covers", "ADR-020")] + public void ProcessManagerSpec_HappyPath_SendsAndCompletes() + { + var transfer = TransferId.Parse("0193a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5d"); + var spec = ProcessManagerSpec.For().WithModule(); + + spec.When(new TransferRequested(transfer, Account, Other, 5m)) + .ThenSends(new Withdraw(Account, 5m)) + .ThenSchedules(new TransferTimedOut(transfer), new DateTimeOffset(2026, 1, 1, 0, 5, 0, TimeSpan.Zero)); + spec.When(new MoneyWithdrawn(Account, 5m, 5m)).ThenSends(new Deposit(Other, 5m)); + spec.When(new MoneyDeposited(Other, 5m, 5m)).ThenSends(new CompleteTransfer(transfer)).ThenCompleted(); + spec.When(new TransferTimedOut(transfer)).ThenIgnored(); + } + + [Fact] + [Trait("Id", "UT-TST-05")] + [Trait("Covers", "ADR-020")] + public void ProcessManagerSpec_TimeoutWhileDepositing_Compensates() + { + var transfer = TransferId.Parse("0193a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5d"); + + ProcessManagerSpec.For().WithModule() + .Given(new TransferRequested(transfer, Account, Other, 5m), new MoneyWithdrawn(Account, 5m, 5m)) + .WhenTimeAdvances(MoneyTransfer.Timeout) + .When(new TransferTimedOut(transfer)) + .ThenSends(new Deposit(Account, 5m), new FailTransfer(transfer, "timeout")) + .ThenCompleted(); + } + + [Fact] + [Trait("Id", "UT-TST-06")] + public void ProjectionSpec_BuildsTheDocument() + { + StreamId stream = StreamId.For(BankAccount.AggregateName, Account); + + new ProjectionSpec() + .Given(stream, new AccountOpened(Account, "Ada", 10m, Now), new MoneyDeposited(Account, 5m, 15m)) + .Then(Account, new AccountSummary(Account, "Ada", 15m, AccountStatus.Open, 2)) + .Then(Other, null); + } + + [Fact] + [Trait("Id", "UT-TST-07")] + public void Approvals_MismatchWritesReceivedFile() + { + string name = "approval-selftest-" + Environment.ProcessId; + + ApprovalMismatchException mismatch = Should.Throw(() => Approvals.AssertMatches("content", name)); + + // Next to this test file, wherever the build put the compiler-supplied path (CI maps it to /_/…). + mismatch.ReceivedPath.ShouldEndWith(Path.Combine("SourceFlow.Tooling.Tests", "Approved", name + ".received.txt")); + File.ReadAllText(mismatch.ReceivedPath).ShouldBe("content\n"); + File.Delete(mismatch.ReceivedPath); + } + + [Fact] + [Trait("Id", "UT-TST-08")] + public void Approvals_ResolveDeterministicSourcePaths_ToTheFileInTheRepository() + { + // ContinuousIntegrationBuild maps source paths to /_/…; the approved folder is still found in the checkout. + string name = "approval-mapped-" + Environment.ProcessId; + const string Mapped = "/_/tests/Tooling/SourceFlow.Tooling.Tests/SpecTests.cs"; + + ApprovalMismatchException mismatch = Should.Throw(() => Approvals.AssertMatches("content", name, Mapped)); + + mismatch.ReceivedPath.ShouldNotStartWith("/_/"); + File.Exists(mismatch.ReceivedPath).ShouldBeTrue(); + Path.GetDirectoryName(Path.GetDirectoryName(mismatch.ReceivedPath)).ShouldBe(Path.GetDirectoryName(ThisFile())); + File.Delete(mismatch.ReceivedPath); + } + + private static string ThisFile([System.Runtime.CompilerServices.CallerFilePath] string path = "") + { + return Approvals.ResolveSourcePath(path); + } + [Fact] + [Trait("Id", "UT-TST-21")] + [Trait("Covers", "doc 11 2")] + public void ProcessManagerSpec_FailsWhereAServiceWould() + { + var transfer = TransferId.Parse("0193a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5d"); + var other = TransferId.Parse("0193a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5e"); + + // A first message that can't start an instance: MoneyWithdrawn has no CorrelateBy, and nothing caused it. + Should.Throw(() => ProcessManagerSpec.For().WithModule() + .When(new MoneyWithdrawn(Account, 5m, 5m))).Message.ShouldContain("doesn't correlate"); + + // A message that correlates to another instance: a service would apply it there, not here. + ProcessManagerSpec started = ProcessManagerSpec.For().WithModule() + .Given(new TransferRequested(transfer, Account, Other, 5m)); + started.Id.ShouldBe(transfer); + Should.Throw(() => started.When(new TransferRequested(other, Account, Other, 5m))).Message.ShouldContain("not to this spec's"); + + // A message the process manager doesn't handle is never delivered to it. + Should.Throw(() => started.When(new OpenAccount(Account, "Ada", 1m))).Message.ShouldContain("doesn't handle"); + + // Sending a command whose contract the service doesn't register fails, as at runtime. + Should.Throw(() => ProcessManagerSpec.For() + .When(new TransferRequested(transfer, Account, Other, 5m))); + + // The state is what was stored: written as JSON and read back. + started.State.Stage.ShouldBe(TransferStage.Withdrawing); + started.State.Amount.ShouldBe(5m); + } +} diff --git a/tests/Tooling/SourceFlow.Tooling.Tests/StudioHostTests.cs b/tests/Tooling/SourceFlow.Tooling.Tests/StudioHostTests.cs new file mode 100644 index 00000000..09b90845 --- /dev/null +++ b/tests/Tooling/SourceFlow.Tooling.Tests/StudioHostTests.cs @@ -0,0 +1,453 @@ +using System.Net; +using System.Net.Http.Json; +using System.Text; +using System.Text.Json.Nodes; +using SourceFlow.Tool; +using SourceFlow.Tool.Studio; + +namespace SourceFlow.Tooling.Tests; + +/// +/// dotnet sourceflow studio, the Studio local host (WP-S.8, doc 15 §6.3, §6.4): loopback only, a Host-header +/// guard, writes limited to the workspace's workflow and layout files, a read-only mode, and the manifest export trigger. +/// +[Trait("Category", "Unit")] +public sealed class StudioHostTests : IAsyncLifetime +{ + private readonly string _root = Path.Combine(Path.GetTempPath(), "sourceflow-studio-" + Guid.CreateVersion7().ToString("N")[^12..]); + private readonly List _exported = []; + + private static CancellationToken Ct => TestContext.Current.CancellationToken; + + public ValueTask InitializeAsync() + { + string golden = Path.Combine(Repository(), "tests", "Golden"); + Directory.CreateDirectory(Path.Combine(_root, "manifests")); + foreach (string manifest in Directory.GetFiles(Path.Combine(golden, "domain"), "*.json")) + { + File.Copy(manifest, Path.Combine(_root, "manifests", Path.GetFileName(manifest))); + } + + Directory.CreateDirectory(Path.Combine(_root, "orders", "workflows")); + Directory.CreateDirectory(Path.Combine(_root, "orders", "src")); + Directory.CreateDirectory(Path.Combine(_root, "orders", "tests")); + File.WriteAllText(Path.Combine(_root, "orders", "tests", "Orders.Tests.csproj"), ""); + Directory.CreateDirectory(Path.Combine(_root, "docs")); + File.Copy(Path.Combine(golden, "cases", "01-order-fulfilment", "workflow.sfflow.yaml"), Path.Combine(_root, "orders", "workflows", "order-fulfilment.sfflow.yaml")); + File.WriteAllText(Path.Combine(_root, "orders", "src", "Orders.csproj"), ""); + File.WriteAllText(Path.Combine(_root, "docs", "example.sfflow.yaml"), "name: example\n"); + File.WriteAllText(Path.Combine(_root, "secret.txt"), "secret"); + File.WriteAllText(Path.Combine(_root, "sourceflow.domain.yaml"), """ + domain: commerce + description: Order to delivery + services: + - name: orders + manifest: manifests/orders.manifest.json + workflows: orders/workflows + project: orders/src + tests: orders/tests + module: Orders.OrdersModule + - name: inventory + manifest: manifests/inventory.manifest.json + - name: payments + manifest: manifests/payments.manifest.json + - name: shipping + manifest: manifests/shipping.manifest.json + """); + return ValueTask.CompletedTask; + } + + public ValueTask DisposeAsync() + { + Directory.Delete(_root, recursive: true); + return ValueTask.CompletedTask; + } + + [Fact] + [Trait("Id", "UT-STU-HOST-01")] + [Trait("Covers", "WFD-NFR-5")] + public async Task BindsToLoopbackOnly() + { + await using StudioHost host = await Start(); + + host.Url.Host.ShouldBe("127.0.0.1"); + host.Url.Port.ShouldBeGreaterThan(0); + using HttpClient client = Client(host); + (await client.GetAsync("api/workspace", Ct)).StatusCode.ShouldBe(HttpStatusCode.OK); + (await client.GetAsync("api/nothing", Ct)).StatusCode.ShouldBe(HttpStatusCode.NotFound); + } + + [Theory] + [Trait("Id", "UT-STU-HOST-02")] + [Trait("Covers", "WFD-NFR-5")] + [InlineData("evil.example", HttpStatusCode.Forbidden)] + [InlineData("192.168.1.10", HttpStatusCode.Forbidden)] + [InlineData("localhost.evil.example", HttpStatusCode.Forbidden)] + [InlineData("localhost", HttpStatusCode.OK)] + [InlineData("127.0.0.1", HttpStatusCode.OK)] + public async Task NonLoopbackHostHeaders_AreRefused(string name, HttpStatusCode expected) + { + await using StudioHost host = await Start(); + using HttpClient client = Client(host); + using var request = new HttpRequestMessage(HttpMethod.Get, "api/workspace"); + request.Headers.Host = name + ":" + host.Url.Port; + + HttpResponseMessage response = await client.SendAsync(request, Ct); + + response.StatusCode.ShouldBe(expected, "DNS rebinding: a page on another name must not reach the workspace"); + response.Headers.GetValues("Content-Security-Policy").Single().ShouldContain("default-src 'self'"); + response.Headers.GetValues("Content-Security-Policy").Single().ShouldContain("base-uri 'self'", Case.Sensitive, "the app's (its relative URLs, WP-S.12); no other origin"); + response.Headers.GetValues("X-Frame-Options").Single().ShouldBe("DENY"); + } + + [Fact] + [Trait("Id", "UT-STU-HOST-03")] + [Trait("Covers", "WFD-NFR-5")] + public async Task Writes_ComeFromTheStudioPageOnly_AsJson() + { + await using StudioHost host = await Start(); + using HttpClient client = Client(host); + + using var foreign = Put("orders/workflows/x.sfflow.yaml", "a: 1"); + foreign.Headers.Add("Origin", "https://evil.example"); + (await client.SendAsync(foreign, Ct)).StatusCode.ShouldBe(HttpStatusCode.Forbidden); + + using var plain = new HttpRequestMessage(HttpMethod.Put, "api/files?path=orders/workflows/x.sfflow.yaml") { Content = new StringContent("{\"content\":\"a\"}", Encoding.UTF8, "text/plain") }; + (await client.SendAsync(plain, Ct)).StatusCode.ShouldBe(HttpStatusCode.UnsupportedMediaType, "a simple cross-site form post can't send JSON"); + + using var own = Put("orders/workflows/x.sfflow.yaml", "a: 1"); + own.Headers.Add("Origin", host.Url.GetLeftPart(UriPartial.Authority)); + (await client.SendAsync(own, Ct)).StatusCode.ShouldBe(HttpStatusCode.OK); + } + + [Fact] + [Trait("Id", "UT-STU-HOST-04")] + [Trait("Covers", "WFD-10")] + public async Task Workspace_ListsServicesManifestsAndWorkflows() + { + await using StudioHost host = await Start(); + using HttpClient client = Client(host); + + JsonNode workspace = (await client.GetFromJsonAsync("api/workspace", Ct))!; + + workspace["domain"]!.GetValue().ShouldBe("commerce"); + workspace["readOnly"]!.GetValue().ShouldBeFalse(); + JsonArray services = workspace["services"]!.AsArray(); + services.Select(s => s!["name"]!.GetValue()).ShouldBe(["orders", "inventory", "payments", "shipping"]); + JsonNode orders = services[0]!; + orders["workflowFiles"]!.AsArray().Select(f => f!.GetValue()).ShouldBe(["orders/workflows/order-fulfilment.sfflow.yaml"]); + orders["project"]!.GetValue().ShouldBe("orders/src"); + orders["tests"]!.GetValue().ShouldBe("orders/tests"); + orders["module"]!.GetValue().ShouldBe("Orders.OrdersModule"); + services[1]!["tests"].ShouldBeNull(); + JsonNode.Parse(orders["manifestJson"]!.GetValue())!["service"]!.GetValue().ShouldBe("orders"); + services[1]!["workflows"].ShouldBeNull(); + } + + [Theory] + [Trait("Id", "UT-STU-HOST-05")] + [Trait("Covers", "WFD-NFR-5")] + [InlineData("orders/workflows/order-fulfilment.sfflow.yaml", HttpStatusCode.OK)] + [InlineData("docs/example.sfflow.yaml", HttpStatusCode.OK)] + [InlineData("orders/workflows/missing.sfflow.yaml", HttpStatusCode.NotFound)] + [InlineData("secret.txt", HttpStatusCode.Forbidden)] + [InlineData("sourceflow.domain.yaml", HttpStatusCode.Forbidden)] + [InlineData("../outside.sfflow.yaml", HttpStatusCode.Forbidden)] + [InlineData("orders/../../outside.sfflow.yaml", HttpStatusCode.Forbidden)] + [InlineData("C:/Windows/win.sfflow.yaml", HttpStatusCode.Forbidden)] + [InlineData("/etc/passwd.sfflow.yaml", HttpStatusCode.Forbidden)] + public async Task Reads_AreLimitedToWorkflowAndLayoutFilesInTheWorkspace(string path, HttpStatusCode expected) + { + await using StudioHost host = await Start(); + using HttpClient client = Client(host); + + HttpResponseMessage response = await client.GetAsync("api/files?path=" + Uri.EscapeDataString(path), Ct); + + response.StatusCode.ShouldBe(expected); + if (expected == HttpStatusCode.OK) + { + (await response.Content.ReadAsStringAsync(Ct)).ShouldContain("name:"); + } + } + + [Fact] + [Trait("Id", "UT-STU-HOST-06")] + [Trait("Covers", "WFD-NFR-5")] + public async Task Writes_AreLimitedToTheServicesWorkflowFolders() + { + await using StudioHost host = await Start(); + using HttpClient client = Client(host); + const string Text = "# edited in Studio\nname: order-fulfilment\n"; + + HttpResponseMessage written = await client.SendAsync(Put("orders/workflows/order-fulfilment.sfflow.yaml", Text), Ct); + written.StatusCode.ShouldBe(HttpStatusCode.OK); + File.ReadAllText(Path.Combine(_root, "orders", "workflows", "order-fulfilment.sfflow.yaml")).ShouldBe(Text, "byte for byte"); + Directory.GetFiles(Path.Combine(_root, "orders", "workflows"), "*.tmp-*").ShouldBeEmpty("written through a temporary file and a move"); + + (await client.SendAsync(Put("orders/workflows/nested/order-fulfilment.sfflow.layout.json", "{}"), Ct)).StatusCode.ShouldBe(HttpStatusCode.OK); + (await client.SendAsync(Put("docs/example.sfflow.yaml", Text), Ct)).StatusCode.ShouldBe(HttpStatusCode.Forbidden, "not a service's workflows folder"); + (await client.SendAsync(Put("orders/workflows/notes.txt", Text), Ct)).StatusCode.ShouldBe(HttpStatusCode.Forbidden); + (await client.SendAsync(Put("orders/workflows/../../x.sfflow.yaml", Text), Ct)).StatusCode.ShouldBe(HttpStatusCode.Forbidden); + using var empty = new HttpRequestMessage(HttpMethod.Put, "api/files?path=orders/workflows/y.sfflow.yaml") { Content = JsonContent.Create(new JsonObject()) }; + (await client.SendAsync(empty, Ct)).StatusCode.ShouldBe(HttpStatusCode.BadRequest); + File.Exists(Path.Combine(_root, "x.sfflow.yaml")).ShouldBeFalse(); + } + + [Fact] + [Trait("Id", "UT-STU-HOST-07")] + [Trait("Covers", "WFD-NFR-5")] + public async Task ReadOnlyMode_RefusesEveryWrite() + { + await using StudioHost host = await Start(readOnly: true); + using HttpClient client = Client(host); + + (await client.GetFromJsonAsync("api/workspace", Ct))!["readOnly"]!.GetValue().ShouldBeTrue(); + (await client.GetAsync("api/files?path=orders/workflows/order-fulfilment.sfflow.yaml", Ct)).StatusCode.ShouldBe(HttpStatusCode.OK); + HttpResponseMessage write = await client.SendAsync(Put("orders/workflows/order-fulfilment.sfflow.yaml", "x"), Ct); + write.StatusCode.ShouldBe(HttpStatusCode.Forbidden); + (await write.Content.ReadAsStringAsync(Ct)).ShouldContain("--read-only"); + (await client.PostAsync("api/services/orders/manifest/export", null, Ct)).StatusCode.ShouldBe(HttpStatusCode.Forbidden); + _exported.ShouldBeEmpty(); + } + + [Fact] + [Trait("Id", "UT-STU-HOST-08")] + [Trait("Covers", "WFD-12")] + public async Task ManifestExport_RunsForTheServicesProject_AndRewritesItsManifest() + { + await using StudioHost host = await Start(); + using HttpClient client = Client(host); + + HttpResponseMessage exported = await client.PostAsync("api/services/orders/manifest/export", null, Ct); + + exported.StatusCode.ShouldBe(HttpStatusCode.OK); + _exported.ShouldBe([Path.Combine(_root, "orders", "src")]); + File.ReadAllText(Path.Combine(_root, "manifests", "orders.manifest.json")).ShouldContain("\"exported\": true"); + (await client.PostAsync("api/services/inventory/manifest/export", null, Ct)).StatusCode.ShouldBe(HttpStatusCode.BadRequest, "no project in the workspace"); + (await client.PostAsync("api/services/nobody/manifest/export", null, Ct)).StatusCode.ShouldBe(HttpStatusCode.NotFound); + } + + [Fact] + [Trait("Id", "UT-STU-HOST-09")] + [Trait("Covers", "WFD-NFR-5")] + public async Task ServesTheApp_WithClientRoutes_AndTheCompressedCore() + { + string app = Path.Combine(_root, "app"); + string framework = Path.Combine(_root, "framework"); + Directory.CreateDirectory(Path.Combine(app, "assets")); + Directory.CreateDirectory(framework); + File.WriteAllText(Path.Combine(app, "index.html"), "Studio"); + File.WriteAllText(Path.Combine(app, "assets", "app.js"), "console.log(1)"); + File.WriteAllText(Path.Combine(framework, "dotnet.js"), "plain"); + File.WriteAllBytes(Path.Combine(framework, "dotnet.js.br"), [1, 2, 3]); + await using StudioHost host = await Start(assets: app, framework: framework); + using HttpClient client = Client(host); + + (await client.GetStringAsync("", Ct)).ShouldContain("Studio"); + (await client.GetStringAsync("workflows/orders/order-fulfilment", Ct)).ShouldContain("Studio", Case.Sensitive, "client-side routes get the SPA"); + using var navigation = new HttpRequestMessage(HttpMethod.Get, "workflows/orders/workflows/order-fulfilment.sfflow.yaml"); + navigation.Headers.Accept.ParseAdd("text/html"); + (await (await client.SendAsync(navigation, Ct)).Content.ReadAsStringAsync(Ct)).ShouldContain("Studio", Case.Sensitive, "a workflow route ends in .sfflow.yaml"); + (await client.GetAsync("workflows/orders/workflows/order-fulfilment.sfflow.yaml", Ct)).StatusCode.ShouldBe(HttpStatusCode.NotFound, "not a page navigation"); + HttpResponseMessage script = await client.GetAsync("assets/app.js", Ct); + script.Content.Headers.ContentType!.MediaType.ShouldBe("text/javascript"); + (await client.GetAsync("assets/missing.js", Ct)).StatusCode.ShouldBe(HttpStatusCode.NotFound); + + using var compressed = new HttpRequestMessage(HttpMethod.Get, "_framework/dotnet.js"); + compressed.Headers.AcceptEncoding.ParseAdd("br"); + HttpResponseMessage brotli = await client.SendAsync(compressed, Ct); + brotli.Content.Headers.ContentEncoding.ShouldBe(["br"]); + (await brotli.Content.ReadAsByteArrayAsync(Ct)).ShouldBe([1, 2, 3]); + (await client.GetStringAsync("_framework/dotnet.js", Ct)).ShouldBe("plain"); + (await client.PostAsync("index.html", null, Ct)).StatusCode.ShouldBe(HttpStatusCode.MethodNotAllowed); + } + + [Fact] + [Trait("Id", "UT-STU-HOST-10")] + [Trait("Covers", "WFD-10")] + public async Task TheCli_StartsAndStopsTheHost_AndReportsABadWorkspace() + { + var output = new StringWriter(); + var error = new StringWriter(); + (await SourceFlowCli.RunAsync(["studio", "--workspace", Path.Combine(_root, "missing")], null, output, error, Ct)).ShouldBe(1); + error.ToString().ShouldContain("not found"); + + using var stop = CancellationTokenSource.CreateLinkedTokenSource(Ct); + var started = new StringWriter(); + Task run = SourceFlowCli.RunAsync(["studio", "--workspace", _root, "--port", "0", "--read-only"], null, started, error, stop.Token); + for (int i = 0; i < 200 && !started.ToString().Contains("SourceFlow Studio:", StringComparison.Ordinal); i++) + { + await Task.Delay(TimeSpan.FromMilliseconds(50), TimeProvider.System, Ct); + } + + started.ToString().ShouldMatch(@"SourceFlow Studio: http://127\.0\.0\.1:\d+/ \(read-only\)"); + await stop.CancelAsync(); + (await run).ShouldBe(0); + } + + [Fact] + [Trait("Id", "UT-STU-HOST-11")] + [Trait("Covers", "WFD-34")] + public async Task Specs_AreGeneratedIntoTheOwnersTestProject() + { + await using StudioHost host = await Start(); + using HttpClient client = Client(host); + string file = Path.Combine(_root, "orders", "tests", "Workflows", "OrderFulfilmentV1PathTests.cs"); + + // A dry run is the preview: the same text, nothing written. + JsonNode preview = (await (await client.PostAsJsonAsync("api/services/orders/specs", new { workflow = "orders/workflows/order-fulfilment.sfflow.yaml", dryRun = true }, Ct)).Content.ReadFromJsonAsync(Ct))!; + preview["written"]!.GetValue().ShouldBeFalse(); + preview["path"]!.GetValue().ShouldBe("orders/tests/Workflows/OrderFulfilmentV1PathTests.cs"); + File.Exists(file).ShouldBeFalse(); + + HttpResponseMessage cover = await client.PostAsJsonAsync("api/services/orders/specs", new { workflow = "orders/workflows/order-fulfilment.sfflow.yaml" }, Ct); + + cover.StatusCode.ShouldBe(HttpStatusCode.OK, await cover.Content.ReadAsStringAsync(Ct)); + JsonNode written = (await cover.Content.ReadFromJsonAsync(Ct))!; + written["path"]!.GetValue().ShouldBe("orders/tests/Workflows/OrderFulfilmentV1PathTests.cs"); + written["tests"]!.GetValue().ShouldBe(6, "the minimal cover by default (doc 15 §5.3)"); + string text = File.ReadAllText(file); + written["written"]!.GetValue().ShouldBeTrue(); + text.ShouldBe(preview["text"]!.GetValue()); + text.ShouldStartWith("// "); + text.ShouldContain("namespace Orders.Tests.Workflows;"); + text.ShouldContain("WorkflowSpec.For()"); + Directory.GetFiles(Path.GetDirectoryName(file)!, "*.tmp-*").ShouldBeEmpty(); + + // Selected paths regenerate the generated file. + HttpResponseMessage two = await client.PostAsJsonAsync("api/services/orders/specs", new { workflow = "orders/workflows/order-fulfilment.sfflow.yaml", paths = new[] { "P01", "P02" } }, Ct); + two.StatusCode.ShouldBe(HttpStatusCode.OK, await two.Content.ReadAsStringAsync(Ct)); + (await two.Content.ReadFromJsonAsync(Ct))!["tests"]!.GetValue().ShouldBe(2); + File.ReadAllText(file).Length.ShouldBeLessThan(text.Length); + } + + [Fact] + [Trait("Id", "UT-STU-HOST-12")] + [Trait("Covers", "WFD-NFR-5")] + public async Task Specs_AreRefused_OutsideATestProject_OrOverAHandWrittenFile() + { + await using StudioHost host = await Start(); + using HttpClient client = Client(host); + Task Specs(string service, string workflow) => client.PostAsJsonAsync("api/services/" + service + "/specs", new { workflow }, Ct); + const string Workflow = "orders/workflows/order-fulfilment.sfflow.yaml"; + + (await Specs("nobody", Workflow)).StatusCode.ShouldBe(HttpStatusCode.NotFound); + (await Specs("inventory", Workflow)).StatusCode.ShouldBe(HttpStatusCode.BadRequest, "not inventory's workflow"); + (await Specs("orders", "docs/example.sfflow.yaml")).StatusCode.ShouldBe(HttpStatusCode.BadRequest, "not a workflow file of the service"); + + string hand = Path.Combine(_root, "orders", "tests", "Workflows", "OrderFulfilmentV1PathTests.cs"); + Directory.CreateDirectory(Path.GetDirectoryName(hand)!); + File.WriteAllText(hand, "// written by a person\n"); + HttpResponseMessage conflict = await Specs("orders", Workflow); + conflict.StatusCode.ShouldBe(HttpStatusCode.Conflict); + (await Error(conflict)).ShouldContain("isn't a file Studio generated"); + File.ReadAllText(hand).ShouldBe("// written by a person\n"); + File.Delete(hand); + + string domain = Path.Combine(_root, "sourceflow.domain.yaml"); + string original = File.ReadAllText(domain); + File.WriteAllText(domain, original.Replace(" tests: orders/tests\n", "", StringComparison.Ordinal).Replace(" tests: orders/tests\r\n", "", StringComparison.Ordinal)); + (await Error(await Specs("orders", Workflow))).ShouldContain("has no 'tests'"); + File.WriteAllText(domain, original.Replace("orders/tests", "../elsewhere", StringComparison.Ordinal)); + (await Specs("orders", Workflow)).StatusCode.ShouldBe(HttpStatusCode.Forbidden, "only inside the workspace"); + File.WriteAllText(domain, original.Replace("orders/tests", "docs", StringComparison.Ordinal)); + (await Error(await Specs("orders", Workflow))).ShouldContain("not a project folder"); + File.WriteAllText(domain, original.Replace(" module: Orders.OrdersModule\n", "", StringComparison.Ordinal).Replace(" module: Orders.OrdersModule\r\n", "", StringComparison.Ordinal)); + (await Error(await Specs("orders", Workflow))).ShouldContain("has no 'module'"); + File.WriteAllText(domain, original); + + File.WriteAllText(Path.Combine(_root, "orders", "workflows", "order-fulfilment.sfflow.yaml"), "sourceflow.workflow: 1\nname: broken\n"); + (await Error(await Specs("orders", Workflow))).ShouldContain("has errors"); + File.Exists(hand).ShouldBeFalse(); + + await using StudioHost readOnly = await Start(readOnly: true); + using HttpClient reader = Client(readOnly); + (await reader.PostAsJsonAsync("api/services/orders/specs", new { workflow = Workflow }, Ct)).StatusCode.ShouldBe(HttpStatusCode.Forbidden); + File.WriteAllText(Path.Combine(_root, "orders", "workflows", "order-fulfilment.sfflow.yaml"), File.ReadAllText(Path.Combine(Repository(), "tests", "Golden", "cases", "01-order-fulfilment", "workflow.sfflow.yaml"))); + (await reader.PostAsJsonAsync("api/services/orders/specs", new { workflow = Workflow, dryRun = true }, Ct)).StatusCode.ShouldBe(HttpStatusCode.OK, "a preview writes nothing"); + File.Exists(hand).ShouldBeFalse(); + } + + [Fact] + [Trait("Id", "UT-STU-HOST-13")] + [Trait("Covers", "WFD-NFR-5")] + public void Containment_NeedsASeparator_ASiblingNamedLikeTheFolderIsOutside() + { + string dist = Path.Combine(_root, "dist"); + + StudioHost.Inside(dist, Path.Combine(_root, "dist", "app.js")).ShouldBeTrue(); + StudioHost.Inside(dist, Path.Combine(_root, "dist-other", "secret.js")).ShouldBeFalse("'dist' must not admit 'dist-other' (CR-48)"); + StudioHost.Inside(dist, dist).ShouldBeFalse("the folder itself is not a file inside it"); + } + + [Fact] + [Trait("Id", "UT-STU-HOST-14")] + [Trait("Covers", "WFD-NFR-5")] + public async Task ManifestExport_NeverWritesThroughALink() + { + string outside = Path.Combine(Path.GetTempPath(), "sourceflow-outside-" + Guid.CreateVersion7().ToString("N") + ".json"); + string manifest = Path.Combine(_root, "manifests", "orders.manifest.json"); + string original = File.ReadAllText(manifest); // the workspace reads it at start: the link must lead to a valid manifest + File.WriteAllText(outside, original); + File.Delete(manifest); + try + { + File.CreateSymbolicLink(manifest, outside); + } + catch (Exception e) when (e is IOException or UnauthorizedAccessException) + { + File.Delete(outside); + Assert.Skip("Creating a symbolic link needs Developer Mode or administrator rights here: " + e.Message); + } + + try + { + await using StudioHost host = await Start(); + using HttpClient client = Client(host); + + (await client.PostAsync("api/services/orders/manifest/export", null, Ct)).StatusCode.ShouldBe(HttpStatusCode.Forbidden); + File.ReadAllText(outside).ShouldBe(original, "nothing was written through the link"); + } + finally + { + File.Delete(outside); + } + } + + // ================================================================ helpers + + private Task Start(bool readOnly = false, string? assets = null, string? framework = null) + { + return StudioHost.StartAsync(new StudioHostOptions(_root, Port: 0, readOnly, assets, framework, (project, _) => + { + _exported.Add(project); + return Task.FromResult("{\n \"manifestVersion\": 1,\n \"service\": \"orders\",\n \"exported\": true\n}\n"); + }), Ct); + } + + private static async Task Error(HttpResponseMessage response) + { + return (await response.Content.ReadFromJsonAsync(Ct))!["error"]!.GetValue(); + } + + private static HttpClient Client(StudioHost host) + { + return new HttpClient { BaseAddress = host.Url }; + } + + private static HttpRequestMessage Put(string path, string content) + { + return new HttpRequestMessage(HttpMethod.Put, "api/files?path=" + Uri.EscapeDataString(path)) { Content = JsonContent.Create(new JsonObject { ["content"] = content }) }; + } + + private static string Repository() + { + string? directory = AppContext.BaseDirectory; + while (directory is not null && !File.Exists(Path.Combine(directory, "SourceFlow.slnx"))) + { + directory = Path.GetDirectoryName(directory); + } + + return directory ?? throw new InvalidOperationException("Repository root not found."); + } +} diff --git a/tests/Workflows/SourceFlow.Studio.Tests/Fixture/OrderFulfilment.cs b/tests/Workflows/SourceFlow.Studio.Tests/Fixture/OrderFulfilment.cs new file mode 100644 index 00000000..ca1c04dd --- /dev/null +++ b/tests/Workflows/SourceFlow.Studio.Tests/Fixture/OrderFulfilment.cs @@ -0,0 +1,262 @@ +using System.Text.Json.Serialization; + +namespace SourceFlow.Studio.Tests.Fixture; + +// The doc 15 §5.1 domain, so the generator compiles order-fulfilment.sfflow.yaml (next to this file) into +// OrderFulfilmentWorkflowV1 in this assembly (WP-S.5), and order-fulfilment-v2.sfflow.yaml into OrderFulfilmentWorkflowV2 +// (WP-S.6: versions side by side). Field names match the golden manifests. Local aggregates own the +// commands of the happy path, so one SourceFlowTestHost can run the workflow end to end; the compensation commands have +// no owner here (their steps are exercised through WorkflowSpec). + +[StronglyTypedId] public readonly partial record struct OrderId(Guid Value); + +[MessageType("orders.place-order", 1)] +public sealed record PlaceOrder(OrderId OrderId, decimal Total, IReadOnlyList Lines, string CustomerEmail, bool Priority) : ICommand; + +[MessageType("orders.order-placed", 1)] +public sealed record OrderPlaced(OrderId OrderId, decimal Total, IReadOnlyList Lines, string CustomerEmail, bool Priority) : IEvent; + +[MessageType("orders.order-approved", 1)] +public sealed record OrderApproved(OrderId OrderId) : IEvent; + +[MessageType("orders.order-rejected-by-review", 1)] +public sealed record OrderRejectedByReview(OrderId OrderId, string Reason) : IEvent; + +[MessageType("orders.address-corrected", 1)] +public sealed record AddressCorrected(OrderId OrderId) : IEvent; + +[MessageType("orders.correct-address", 1)] +public sealed record CorrectAddress(OrderId OrderId) : ICommand; + +[MessageType("orders.approve-order", 1)] +public sealed record ApproveOrder(OrderId OrderId) : ICommand; + +[MessageType("orders.mark-fulfilled", 1)] +public sealed record MarkFulfilled(OrderId OrderId) : ICommand; + +[MessageType("orders.order-fulfilled", 1)] +public sealed record OrderFulfilled(OrderId OrderId) : IEvent; + +[MessageType("orders.cancel-order", 1)] +public sealed record CancelOrder(OrderId OrderId, string Reason) : ICommand; + +[MessageType("orders.order-cancelled", 1)] +public sealed record OrderCancelled(OrderId OrderId, string Reason) : IEvent; + +[MessageType("inventory.reserve-stock", 1)] +public sealed record ReserveStock(OrderId OrderId, IReadOnlyList Lines) : ICommand; + +[MessageType("inventory.release-stock", 1)] +public sealed record ReleaseStock(OrderId OrderId) : ICommand; + +[MessageType("inventory.stock-reserved", 1)] +public sealed record StockReserved(OrderId OrderId) : IEvent; + +[MessageType("inventory.stock-released", 1)] +public sealed record StockReleased(OrderId OrderId) : IEvent; + +[MessageType("payments.charge", 1)] +public sealed record Charge(OrderId OrderId, decimal Amount) : ICommand; + +[MessageType("payments.refund", 1)] +public sealed record Refund(Guid PaymentId, decimal Amount) : ICommand; + +[MessageType("payments.payment-captured", 1)] +public sealed record PaymentCaptured(Guid PaymentId, OrderId OrderId, decimal Amount, string CardHolder) : IEvent; + +[MessageType("payments.refunded", 1)] +public sealed record Refunded(Guid PaymentId, OrderId OrderId) : IEvent; + +[MessageType("shipping.create-shipment", 1)] +public sealed record CreateShipment(OrderId OrderId, IReadOnlyList Lines, string? Note) : ICommand; + +[MessageType("shipping.shipment-created", 1)] +public sealed record ShipmentCreated(OrderId OrderId, Guid ShipmentId) : IEvent; + +[MessageType("shipping.fix-address", 1)] +public sealed record FixAddress(OrderId OrderId) : ICommand; + +[MessageType("shipping.shipment-address-fixed", 1)] +public sealed record ShipmentAddressFixed(OrderId OrderId) : IEvent; + +/// Orders: places and fulfils orders. +[Aggregate("fixture-order")] +public sealed partial record Order : IAggregate +{ + public static Order Initial { get; } = new(); + + public bool Placed { get; init; } + + public Decision Decide(PlaceOrder c, DecisionContext ctx) => + Placed ? Decision.NoOp : Decision.Accept(new OrderPlaced(c.OrderId, c.Total, c.Lines, c.CustomerEmail, c.Priority)); + + public Decision Decide(MarkFulfilled c, DecisionContext ctx) => Decision.Accept(new OrderFulfilled(c.OrderId)); + + public Decision Decide(CancelOrder c, DecisionContext ctx) => Decision.Accept(new OrderCancelled(c.OrderId, c.Reason)); + + public Decision Decide(CorrectAddress c, DecisionContext ctx) => Decision.Accept(new AddressCorrected(c.OrderId)); + + public Decision Decide(ApproveOrder c, DecisionContext ctx) => Decision.Accept(new OrderApproved(c.OrderId)); + + private Order When(OrderPlaced e) => this with { Placed = true }; + + private Order When(OrderCancelled e) => this; + + private Order When(OrderFulfilled e) => this; + + private Order When(AddressCorrected e) => this; + + private Order When(OrderApproved e) => this; +} + +/// Inventory: reserves stock unless an order asks for the line "none". +[Aggregate("fixture-stock")] +public sealed partial record Stock : IAggregate +{ + public static Stock Initial { get; } = new(); + + public Decision Decide(ReserveStock c, DecisionContext ctx) => + c.Lines.Contains("none") ? Decision.Reject(new Error("inventory.out_of_stock", "Out of stock.")) : Decision.Accept(new StockReserved(c.OrderId)); + + private Stock When(StockReserved e) => this; +} + +/// Payments: declines charges over 100,000 and suspects fraud on exactly 13. +[Aggregate("fixture-payment")] +public sealed partial record Payment : IAggregate +{ + public static Payment Initial { get; } = new(); + + public Decision Decide(Charge c, DecisionContext ctx) => c.Amount switch + { + > 100_000 => Decision.Reject(new Error("payments.declined", "Declined.")), + 13 => Decision.Reject(new Error("payments.fraud_suspected", "Fraud suspected.")), + _ => Decision.Accept(new PaymentCaptured(c.OrderId.Value, c.OrderId, c.Amount, "card-holder")), + }; + + private Payment When(PaymentCaptured e) => this; +} + +/// Shipping: creates shipments unless a line is "bad-address" and the address was not fixed. +[Aggregate("fixture-shipment")] +public sealed partial record Shipment : IAggregate +{ + public static Shipment Initial { get; } = new(); + + public bool AddressFixed { get; init; } + + public Decision Decide(CreateShipment c, DecisionContext ctx) => + c.Lines.Contains("bad-address") && !AddressFixed ? Decision.Reject(new Error("shipping.address_invalid", "Invalid address.")) : Decision.Accept(new ShipmentCreated(c.OrderId, c.OrderId.Value)); + + public Decision Decide(FixAddress c, DecisionContext ctx) => Decision.Accept(new ShipmentAddressFixed(c.OrderId)); + + private Shipment When(ShipmentCreated e) => this; + + private Shipment When(ShipmentAddressFixed e) => this with { AddressFixed = true }; +} + +/// The fixture module: registers the messages, the aggregates and, generated, the workflow. +[SourceFlowModule(typeof(FixtureJsonContext))] +public sealed partial class FixtureModule; + +/// +/// The fixture module without one workflow version: a deployment that never had it, or removed it (doc 15 §5.6). The +/// generated module registers every version in this assembly; this leaves out. +/// +public sealed class FixtureWithout : ISourceFlowModule + where TWorkflow : class +{ + public static string ModuleName => "FixtureModule"; + + public static void Register(ISourceFlowModuleBuilder builder) + { + FixtureModule.Register(new Without(builder)); + } + + private sealed class Without(ISourceFlowModuleBuilder inner) : ISourceFlowModuleBuilder + { + public void AddJsonTypeInfoResolver(System.Text.Json.Serialization.Metadata.IJsonTypeInfoResolver resolver) => inner.AddJsonTypeInfoResolver(resolver); + + public void AddJsonConverter(JsonConverter converter) => inner.AddJsonConverter(converter); + + public void AddMessage(string name, int version) + where TMessage : class, IMessage => inner.AddMessage(name, version); + + public void AddUpcaster() + where TFrom : class, IMessage + where TTo : class, IMessage + where TUpcaster : class, IUpcaster, new() => inner.AddUpcaster(); + + public void AddAggregate() + where TAggregate : class, IAggregateRuntime + where TId : struct, IStronglyTypedId => inner.AddAggregate(); + + public void AddCommandHandler<[System.Diagnostics.CodeAnalysis.DynamicallyAccessedMembers(System.Diagnostics.CodeAnalysis.DynamicallyAccessedMemberTypes.PublicConstructors)] THandler, TCommand, TAggregate>() + where THandler : class, ICommandHandler + where TCommand : class, ICommand + where TAggregate : class => inner.AddCommandHandler(); + + public void AddProcessManager() + where TProcess : class, IProcessManagerRuntime + where TId : struct, IStronglyTypedId + { + if (typeof(TProcess) != typeof(TWorkflow)) + { + inner.AddProcessManager(); + } + } + + public void AddProjection() + where TProjection : class, IDocumentProjectionRuntime, new() + where TDocument : class + where TKey : notnull => inner.AddProjection(); + + public void AddSessionProjection() + where TProjection : class, ISessionProjectionRuntime, new() + where TUnitOfWork : class => inner.AddSessionProjection(); + + public void AddEventHandler<[System.Diagnostics.CodeAnalysis.DynamicallyAccessedMembers(System.Diagnostics.CodeAnalysis.DynamicallyAccessedMemberTypes.PublicConstructors)] THandler, TEvent>() + where THandler : class, IEventHandler + where TEvent : class, IMessage => inner.AddEventHandler(); + + public void AddDomainQuery() + where TQuery : class, IDomainQueryRuntime + where TResult : class => inner.AddDomainQuery(); + } +} + +/// JSON metadata (DC-1), with the rejection replies the workflow handles. +[JsonSerializable(typeof(PlaceOrder))] +[JsonSerializable(typeof(OrderPlaced))] +[JsonSerializable(typeof(OrderApproved))] +[JsonSerializable(typeof(OrderRejectedByReview))] +[JsonSerializable(typeof(AddressCorrected))] +[JsonSerializable(typeof(CorrectAddress))] +[JsonSerializable(typeof(ApproveOrder))] +[JsonSerializable(typeof(FixAddress))] +[JsonSerializable(typeof(ShipmentAddressFixed))] +[JsonSerializable(typeof(MarkFulfilled))] +[JsonSerializable(typeof(OrderFulfilled))] +[JsonSerializable(typeof(CancelOrder))] +[JsonSerializable(typeof(OrderCancelled))] +[JsonSerializable(typeof(ReserveStock))] +[JsonSerializable(typeof(ReleaseStock))] +[JsonSerializable(typeof(StockReserved))] +[JsonSerializable(typeof(StockReleased))] +[JsonSerializable(typeof(Charge))] +[JsonSerializable(typeof(Refund))] +[JsonSerializable(typeof(PaymentCaptured))] +[JsonSerializable(typeof(Refunded))] +[JsonSerializable(typeof(CreateShipment))] +[JsonSerializable(typeof(ShipmentCreated))] +[JsonSerializable(typeof(CommandRejected))] +[JsonSerializable(typeof(CommandRejected))] +[JsonSerializable(typeof(CommandRejected))] +[JsonSerializable(typeof(CommandRejected))] +[JsonSerializable(typeof(CommandRejected))] +[JsonSerializable(typeof(Order))] +[JsonSerializable(typeof(Stock))] +[JsonSerializable(typeof(Payment))] +[JsonSerializable(typeof(Shipment))] +[JsonSourceGenerationOptions(PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase)] +public sealed partial class FixtureJsonContext : JsonSerializerContext; diff --git a/tests/Workflows/SourceFlow.Studio.Tests/Fixture/order-fulfilment-v2.sfflow.yaml b/tests/Workflows/SourceFlow.Studio.Tests/Fixture/order-fulfilment-v2.sfflow.yaml new file mode 100644 index 00000000..19ed5f62 --- /dev/null +++ b/tests/Workflows/SourceFlow.Studio.Tests/Fixture/order-fulfilment-v2.sfflow.yaml @@ -0,0 +1,68 @@ +sourceflow.workflow: 1 +name: order-fulfilment +version: 2 # WP-S.6: v2 drops the large-order review (doc 15 §5.6) +owner: orders # generated into the orders service +description: Reserve stock, take payment, ship. + +start: + on: orders.order-placed.v1 # local domain event of the owner + correlate: data.orderId # instance id +data: # instance data, typed from schemas + orderId: { from: start.data.orderId } + amount: { from: start.data.total } + lines: { from: start.data.lines } + +steps: + - id: reserve-stock + send: { command: inventory.reserve-stock.v1, map: { orderId: $data.orderId, lines: $data.lines } } + await: + success: inventory.stock-reserved.v1 + failure: + - rejected: inventory.out_of_stock + then: fail # compensate completed steps (none yet), then Compensated + timeout: { after: PT5M, retry: { max: 2 }, then: fail } + compensate: + send: { command: inventory.release-stock.v1, map: { orderId: $data.orderId } } + await: { success: inventory.stock-released.v1 } + retry: { max: 5, backoff: exponential, initial: PT30S, cap: PT10M } + timeout: { after: PT15M } + + - id: charge-payment + send: { command: payments.charge.v1, map: { orderId: $data.orderId, amount: $data.amount } } + await: + success: + on: payments.payment-captured.v1 + capture: { paymentId: event.data.paymentId } + failure: + - rejected: payments.declined + retry: { max: 3, backoff: fixed, initial: PT10M } # business retry + then: fail + - rejected: payments.fraud_suspected + then: fail + timeout: { after: PT2M, retry: { max: 2 }, then: fail } + compensate: + send: { command: payments.refund.v1, map: { paymentId: $data.paymentId, amount: $data.amount } } + await: { success: payments.refunded.v1 } + retry: { max: 5, backoff: exponential, initial: PT1M } + timeout: { after: PT30M } + + - id: create-shipment + pivot: true # point of no return + send: { command: shipping.create-shipment.v1, map: { orderId: $data.orderId, lines: $data.lines } } + await: + success: shipping.shipment-created.v1 + failure: + - rejected: shipping.address_invalid + then: { goto: await-address-fix } # forward recovery after pivot + timeout: { after: PT1H, retry: { max: 3, backoff: exponential, initial: PT5M }, then: manual } + next: complete + + - id: await-address-fix + await: { success: orders.address-corrected.v1 } + timeout: { after: P2D, then: manual } + next: create-shipment + +on: + completed: { send: { command: orders.mark-fulfilled.v1, map: { orderId: $data.orderId } } } + compensated: { send: { command: orders.cancel-order.v1, map: { orderId: $data.orderId, reason: $failure.code } } } + manual: { alert: true } # metric + structured log + dead-letter-style record diff --git a/tests/Workflows/SourceFlow.Studio.Tests/Fixture/order-fulfilment.sfflow.yaml b/tests/Workflows/SourceFlow.Studio.Tests/Fixture/order-fulfilment.sfflow.yaml new file mode 100644 index 00000000..7fd7d7b9 --- /dev/null +++ b/tests/Workflows/SourceFlow.Studio.Tests/Fixture/order-fulfilment.sfflow.yaml @@ -0,0 +1,77 @@ +sourceflow.workflow: 1 +name: order-fulfilment +version: 1 +owner: orders # generated into the orders service +description: Reserve stock, take payment, ship. + +start: + on: orders.order-placed.v1 # local domain event of the owner + correlate: data.orderId # instance id +data: # instance data, typed from schemas + orderId: { from: start.data.orderId } + amount: { from: start.data.total } + lines: { from: start.data.lines } + +steps: + - id: reserve-stock + send: { command: inventory.reserve-stock.v1, map: { orderId: $data.orderId, lines: $data.lines } } + await: + success: inventory.stock-reserved.v1 + failure: + - rejected: inventory.out_of_stock + then: fail # compensate completed steps (none yet), then Compensated + timeout: { after: PT5M, retry: { max: 2 }, then: fail } + compensate: + send: { command: inventory.release-stock.v1, map: { orderId: $data.orderId } } + await: { success: inventory.stock-released.v1 } + retry: { max: 5, backoff: exponential, initial: PT30S, cap: PT10M } + timeout: { after: PT15M } + + - id: charge-payment + send: { command: payments.charge.v1, map: { orderId: $data.orderId, amount: $data.amount } } + await: + success: + on: payments.payment-captured.v1 + capture: { paymentId: event.data.paymentId } + failure: + - rejected: payments.declined + retry: { max: 3, backoff: fixed, initial: PT10M } # business retry + then: fail + - rejected: payments.fraud_suspected + then: fail + timeout: { after: PT2M, retry: { max: 2 }, then: fail } + compensate: + send: { command: payments.refund.v1, map: { paymentId: $data.paymentId, amount: $data.amount } } + await: { success: payments.refunded.v1 } + retry: { max: 5, backoff: exponential, initial: PT1M } + timeout: { after: PT30M } + + - id: review-large-order + when: "$data.amount > 5000" # CESQL guard; skipped when false + await: + success: orders.order-approved.v1 + failure: + - on: orders.order-rejected-by-review.v1 + then: fail + timeout: { after: P1D, then: manual } + + - id: create-shipment + pivot: true # point of no return + send: { command: shipping.create-shipment.v1, map: { orderId: $data.orderId, lines: $data.lines } } + await: + success: shipping.shipment-created.v1 + failure: + - rejected: shipping.address_invalid + then: { goto: await-address-fix } # forward recovery after pivot + timeout: { after: PT1H, retry: { max: 3, backoff: exponential, initial: PT5M }, then: manual } + next: complete + + - id: await-address-fix + await: { success: orders.address-corrected.v1 } + timeout: { after: P2D, then: manual } + next: create-shipment + +on: + completed: { send: { command: orders.mark-fulfilled.v1, map: { orderId: $data.orderId } } } + compensated: { send: { command: orders.cancel-order.v1, map: { orderId: $data.orderId, reason: $failure.code } } } + manual: { alert: true } # metric + structured log + dead-letter-style record diff --git a/tests/Workflows/SourceFlow.Studio.Tests/Golden.cs b/tests/Workflows/SourceFlow.Studio.Tests/Golden.cs new file mode 100644 index 00000000..81f2081c --- /dev/null +++ b/tests/Workflows/SourceFlow.Studio.Tests/Golden.cs @@ -0,0 +1,90 @@ +using System.Text; +using System.Text.Encodings.Web; +using System.Text.Json; +using System.Text.Json.Nodes; +using SourceFlow.Studio.Dsl.Diagnostics; +using SourceFlow.Studio.Dsl.Validation; +using SourceFlow.Studio.Workspace; + +namespace SourceFlow.Studio.Tests; + +/// +/// The WF-GOLD fixtures in tests/Golden: a commerce domain's manifests and one folder per case with +/// workflow.sfflow.yaml and the expected outputs. The .NET and WASM runs read the same files (plan 10 §3). +/// +internal static class Golden +{ + public const string ApproveVariable = "SOURCEFLOW_APPROVE"; + + public static readonly string Root = Path.Combine(RepositoryRoot(), "tests", "Golden"); + + private static readonly Lazy Domain = new(() => + DomainWorkspace.LoadAsync(Path.Combine(Root, "domain")).GetAwaiter().GetResult()); + + private static readonly JsonSerializerOptions Indented = new() + { + WriteIndented = true, + NewLine = "\n", + Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping, + }; + + public static WorkflowEnvironment Environment => new(Domain.Value.Manifests); + + public static TheoryData Cases() + { + return new TheoryData(Directory.GetDirectories(Path.Combine(Root, "cases")).Select(Path.GetFileName).Order(StringComparer.Ordinal)!); + } + + public static string Workflow(string @case) + { + return File.ReadAllText(Path.Combine(Root, "cases", @case, "workflow.sfflow.yaml")); + } + + public static string Json(IEnumerable diagnostics) + { + var array = new JsonArray(); + foreach (WorkflowDiagnostic d in diagnostics) + { + array.Add((JsonNode)new JsonObject + { + ["id"] = d.Id, + ["severity"] = d.IsError ? "error" : "warning", + ["line"] = d.Location.Line, + ["column"] = d.Location.Column, + ["message"] = d.Message, + }); + } + + return array.ToJsonString(Indented) + "\n"; + } + + /// Compares with the case's expected file; with SOURCEFLOW_APPROVE=1 it writes it. + public static void AssertMatches(string @case, string file, string actual) + { + string path = Path.Combine(Root, "cases", @case, file); + string? expected = File.Exists(path) ? File.ReadAllText(path).Replace("\r\n", "\n", StringComparison.Ordinal) : null; + if (expected == actual) + { + return; + } + + if (System.Environment.GetEnvironmentVariable(ApproveVariable) is "1" or "true") + { + File.WriteAllText(path, actual, new UTF8Encoding(encoderShouldEmitUTF8Identifier: false)); + return; + } + + actual.ShouldBe(expected, $"{@case}/{file} differs; review the change and run with {ApproveVariable}=1 to approve it."); + } + + private static string RepositoryRoot() + { + string? directory = AppContext.BaseDirectory; + while (directory is not null && !File.Exists(Path.Combine(directory, "SourceFlow.slnx"))) + { + directory = Path.GetDirectoryName(directory); + } + + return directory ?? throw new InvalidOperationException("Repository root not found."); + } +} diff --git a/tests/Workflows/SourceFlow.Studio.Tests/GoldenTests.cs b/tests/Workflows/SourceFlow.Studio.Tests/GoldenTests.cs new file mode 100644 index 00000000..bcfd26c0 --- /dev/null +++ b/tests/Workflows/SourceFlow.Studio.Tests/GoldenTests.cs @@ -0,0 +1,44 @@ +using SourceFlow.Studio.Dsl; +using SourceFlow.Studio.Dsl.Simulation; + +namespace SourceFlow.Studio.Tests; + +/// WF-GOLD-01..31: each case's diagnostics (plan 10 §3.1). +[Trait("Category", "Unit")] +public sealed class GoldenTests +{ + [Theory] + [Trait("Id", "WF-GOLD-01..31")] + [Trait("Covers", "WFD-28;WFD-NFR-2")] + [MemberData(nameof(Cases))] + public void Diagnostics_MatchTheGoldenFile(string @case) + { + WorkflowAnalysisResult result = WorkflowAnalysis.Analyze(Golden.Workflow(@case), Golden.Environment); + + Golden.AssertMatches(@case, "expected.diagnostics.json", Golden.Json(result.Diagnostics)); + } + + [Theory] + [Trait("Id", "WF-GOLD-01..31")] + [Trait("Covers", "WFD-34")] + [MemberData(nameof(Cases))] + public void Paths_MatchTheGoldenFile(string @case) + { + WorkflowAnalysisResult result = WorkflowAnalysis.Analyze(Golden.Workflow(@case), Golden.Environment); + if (result.HasErrors) + { + return; // paths and diagrams are for valid workflows + } + + PathSet paths = PathEnumerator.Enumerate(result.Workflow!); + string text = string.Join("\n", paths.Paths.Select(p => p.ToString())) + + "\n\nedges: " + paths.Edges.Count + ", uncovered: " + (paths.Uncovered.Count == 0 ? "none" : string.Join(", ", paths.Uncovered)) + + (paths.Truncated ? "\ntruncated" : string.Empty) + "\n"; + Golden.AssertMatches(@case, "expected.paths.txt", text); + } + + public static TheoryData Cases() + { + return Golden.Cases(); + } +} diff --git a/tests/Workflows/SourceFlow.Studio.Tests/NestedCorrelationTests.cs b/tests/Workflows/SourceFlow.Studio.Tests/NestedCorrelationTests.cs new file mode 100644 index 00000000..355f6ae6 --- /dev/null +++ b/tests/Workflows/SourceFlow.Studio.Tests/NestedCorrelationTests.cs @@ -0,0 +1,82 @@ +using System.Text.Json.Nodes; +using SourceFlow.Studio.Dsl; +using SourceFlow.Studio.Dsl.Diagnostics; +using SourceFlow.Studio.Dsl.Manifests; +using SourceFlow.Studio.Dsl.Model; +using SourceFlow.Studio.Dsl.Reading; +using SourceFlow.Studio.Dsl.Simulation; +using SourceFlow.Studio.Dsl.Specs; +using SourceFlow.Studio.Dsl.Validation; + +namespace SourceFlow.Studio.Tests; + +/// UT-WF-80 (WP-C.11, CR-35): one reading of a nested start.correlate path, everywhere. +[Trait("Category", "Unit")] +public sealed class NestedCorrelationTests +{ + private static readonly DateTimeOffset T0 = new(2026, 1, 1, 0, 0, 0, TimeSpan.Zero); + + // doc 15 §5.1's workflow, correlated by the customer's copy of the order id, nested in the start message. + private static string Nested(string path = "data.customer.orderId") => + Golden.Workflow("01-order-fulfilment").Replace("correlate: data.orderId", "correlate: " + path, StringComparison.Ordinal); + + // The golden domain, with orders.order-placed.v1 carrying { customer: { orderId, email } } as well. + private static WorkflowEnvironment Environment() + { + string path = Path.Combine(Golden.Root, "domain", "orders.manifest.json"); + JsonObject manifest = JsonNode.Parse(File.ReadAllText(path))!.AsObject(); + JsonObject placed = manifest["messages"]!.AsArray().Select(m => m!.AsObject()).Single(m => (string?)m["type"] == "orders.order-placed"); + placed["fields"]!.AsArray().Add(new JsonObject + { + ["name"] = "customer", + ["type"] = "object", + ["fields"] = new JsonArray(new JsonObject { ["name"] = "orderId", ["type"] = "uuid" }, new JsonObject { ["name"] = "email", ["type"] = "string", ["personalData"] = true }), + }); + ServiceManifest orders = ServiceManifest.Parse(manifest.ToJsonString()); + return new WorkflowEnvironment(Golden.Environment.Manifests.Where(m => m.Service != "orders").Append(orders)); + } + + [Fact] + [Trait("Id", "UT-WF-80")] + [Trait("Covers", "doc 15 5.4")] + public void ANestedCorrelatePath_IsReadTheSameWayEverywhere_AndKeepsItsTimers() + { + // The helper: the start message is read along the path; awaited events carry the last segment. + CorrelationPath.IsValid("data.customer.orderId").ShouldBeTrue(); + CorrelationPath.IsValid("customer.orderId").ShouldBeFalse("a path starts with data."); + CorrelationPath.IsValid("data.customer..orderId").ShouldBeFalse(); + CorrelationPath.InstanceKey("data.customer.orderId").ShouldBe("orderId"); + + // The reader and the validator: the nested field exists in the manifest; a missing one is WF-V04. + WorkflowEnvironment environment = Environment(); + WorkflowAnalysis.Analyze(Nested(), environment).Diagnostics.ShouldBeEmpty(); + WorkflowAnalysis.Analyze(Nested("data.customer.missing"), environment).Diagnostics + .ShouldContain(d => d.Id == WorkflowRules.Correlation && d.Message.Contains("'customer.missing'", StringComparison.Ordinal)); + + // The simulator: the instance is the nested value, and the timers it schedules carry that instance. + WorkflowDefinition workflow = WorkflowReader.Read(Nested()).Workflow!; + var start = new Dictionary + { + ["orderId"] = "order-7", ["total"] = 100m, ["lines"] = new List { "sku-1" }, ["customerEmail"] = "a@b.c", ["priority"] = false, + ["customer"] = new Dictionary { ["orderId"] = "customer-copy-7", ["email"] = "a@b.c" }, + }; + SimulationResult started = WorkflowSimulator.Start(workflow, start, T0); + started.State.Instance.ShouldBe("customer-copy-7"); + started.State.Timer.ShouldNotBeNull("reserve-stock's timeout"); + SimulationResult timedOut = WorkflowSimulator.Step(started.State, SimulationInput.FireTimer()); + timedOut.State.Instance.ShouldBe("customer-copy-7"); + timedOut.State.Attempt.ShouldBe(2, "the timer reached its instance: the step is sent again"); + + // The path explorer: its placeholder start data puts the instance at the nested path. + PathSet paths = PathEnumerator.Enumerate(workflow); + paths.Paths.ShouldNotBeEmpty(); + foreach (WorkflowPath path in paths.Paths) + { + PathEnumerator.Replay(workflow, path)[0].State.Instance.ShouldBe("instance-1", path.ToString()); + } + + // The spec generator: the start message's sample carries the instance under customer.orderId. + string specs = SpecGenerator.Generate(workflow, environment); + specs.ShouldContain("\"customer\":{\"orderId\":"); + } +} diff --git a/tests/Workflows/SourceFlow.Studio.Tests/OrderFulfilmentSampleTests.cs b/tests/Workflows/SourceFlow.Studio.Tests/OrderFulfilmentSampleTests.cs new file mode 100644 index 00000000..33e35643 --- /dev/null +++ b/tests/Workflows/SourceFlow.Studio.Tests/OrderFulfilmentSampleTests.cs @@ -0,0 +1,111 @@ +using SourceFlow.Studio.Dsl; +using SourceFlow.Studio.Dsl.Manifests; +using SourceFlow.Studio.Dsl.Model; +using SourceFlow.Studio.Dsl.Simulation; +using SourceFlow.Studio.Dsl.Specs; +using SourceFlow.Studio.Dsl.Validation; +using SourceFlow.Studio.Workspace; + +namespace SourceFlow.Studio.Tests; + +/// +/// The OrderFulfilment sample (samples/OrderFulfilment, WP-S.13) as a workspace: its exported manifests are exact (the +/// WP-S.1 acceptance), its workflow validates against all four services with no diagnostic, enumerates the §5.1 path set, +/// and the specs Studio generated for it are current. +/// +[Trait("Category", "Unit")] +public sealed class OrderFulfilmentSampleTests +{ + private static readonly string Sample = Path.GetFullPath(Path.Combine(AppContext.BaseDirectory, "..", "..", "..", "..", "..", "..", "samples", "OrderFulfilment")); + + private static CancellationToken Ct => TestContext.Current.CancellationToken; + + [Fact] + [Trait("Id", "UT-MAN-16")] + [Trait("Covers", "WFD-11;WFD-12")] + public async Task Manifests_HaveExactEmitsAndRejects_ForEveryService() + { + DomainWorkspace workspace = await DomainWorkspace.LoadAsync(Sample, cancellationToken: Ct); + + workspace.Services.Select(s => s.Name).ShouldBe(["orders", "inventory", "payments", "shipping"]); + Commands(workspace, "inventory").ShouldBe( + [ + "inventory.release-stock: emits inventory.stock-released.v1; rejects none", + "inventory.reserve-stock: emits inventory.stock-reserved.v1; rejects inventory.nothing_to_reserve, inventory.out_of_stock", + ]); + Commands(workspace, "payments").ShouldBe( + [ + "payments.charge: emits payments.payment-captured.v1; rejects payments.declined, payments.fraud_suspected, payments.invalid_amount", + "payments.refund: emits payments.refunded.v1; rejects none", + ]); + Commands(workspace, "shipping").ShouldBe(["shipping.create-shipment: emits shipping.shipment-created.v1; rejects shipping.address_invalid"]); + Commands(workspace, "orders").ShouldContain("orders.place-order: emits orders.order-placed.v1; rejects orders.empty, orders.invalid_total"); + + ServiceManifest orders = workspace.Services.Single(s => s.Name == "orders").Manifest; + orders.CommandRoutes.Where(r => r.ReplyOnReject).Select(r => r.Command).ShouldBe(["inventory.reserve-stock.v1", "payments.charge.v1", "shipping.create-shipment.v1"]); + orders.Workflows.ShouldHaveSingleItem().Name.ShouldBe("order-fulfilment"); + } + + [Fact] + [Trait("Id", "UT-WF-71")] + [Trait("Covers", "WFD-28")] + public async Task Workflow_ValidatesAgainstTheWholeDomain_WithNoDiagnostic() + { + (DomainWorkspace workspace, WorkflowAnalysisResult analysis) = await AnalyzeAsync(); + + workspace.Services.Single(s => s.Name == "orders").WorkflowFiles.ShouldHaveSingleItem().ShouldEndWith("order-fulfilment.sfflow.yaml"); + analysis.Diagnostics.ShouldBeEmpty(); + analysis.Workflow.ShouldNotBeNull().ProcessName.ShouldBe("order-fulfilment@1"); + } + + [Fact] + [Trait("Id", "UT-WF-72")] + [Trait("Covers", "WFD-33")] + public async Task Workflow_HasTheDocExamplesPathSet() + { + (_, WorkflowAnalysisResult analysis) = await AnalyzeAsync(); + + // The sample adds data (the address) and map fields to the doc 15 §5.1 example, not states or outcomes. + PathSet paths = PathEnumerator.Enumerate(analysis.Workflow!); + paths.Paths.Count.ShouldBe(437); + paths.MinimalCover().Count.ShouldBe(6); + paths.Paths.Select(p => p.End).Distinct().Order().ShouldBe([WorkflowStatus.Completed, WorkflowStatus.Compensated, WorkflowStatus.ManualIntervention]); + } + + [Fact] + [Trait("Id", "UT-WF-73")] + [Trait("Covers", "WFD-34")] + public async Task GeneratedSpecs_AreCurrent() + { + (DomainWorkspace workspace, WorkflowAnalysisResult analysis) = await AnalyzeAsync(); + WorkspaceService orders = workspace.Services.Single(s => s.Name == "orders"); + + // The options the local host uses for the service's tests and module (sourceflow.domain.yaml). + string expected = SpecGenerator.Generate(analysis.Workflow!, new WorkflowEnvironment(workspace.Manifests), new SpecOptions + { + Namespace = "Orders.Tests.Workflows", + ModuleType = orders.ModuleType!, + WorkflowType = "Orders.OrderFulfilmentWorkflowV1", + }); + string file = Path.Combine(Sample, orders.TestsLocation!, "Workflows", "OrderFulfilmentV1PathTests.cs"); + + File.ReadAllText(file).ReplaceLineEndings("\n").ShouldBe(expected, "regenerate the specs in Studio (Paths → Generate specs) after changing the workflow"); + } + + private static async Task<(DomainWorkspace Workspace, WorkflowAnalysisResult Analysis)> AnalyzeAsync() + { + DomainWorkspace workspace = await DomainWorkspace.LoadAsync(Sample, cancellationToken: Ct); + string file = Path.Combine(workspace.Root, "Orders", "Workflows", "order-fulfilment.sfflow.yaml"); + return (workspace, WorkflowAnalysis.Analyze(await File.ReadAllTextAsync(file, Ct), new WorkflowEnvironment(workspace.Manifests))); + } + + private static string[] Commands(DomainWorkspace workspace, string service) + { + return [.. workspace.Services.Single(s => s.Name == service).Manifest.Aggregates + .SelectMany(a => a.Commands) + .Select(c => $"{c.Type}: emits {Join(c.Emits)}; rejects {Join(c.Rejects)}") + .Order(StringComparer.Ordinal)]; + + static string Join(IReadOnlyList values) => values.Count == 0 ? "none" : string.Join(", ", values.Order(StringComparer.Ordinal)); + } +} diff --git a/tests/Workflows/SourceFlow.Studio.Tests/SchemaTests.cs b/tests/Workflows/SourceFlow.Studio.Tests/SchemaTests.cs new file mode 100644 index 00000000..9a2e05ba --- /dev/null +++ b/tests/Workflows/SourceFlow.Studio.Tests/SchemaTests.cs @@ -0,0 +1,128 @@ +using System.Globalization; +using System.Text.Json.Nodes; +using System.Text.RegularExpressions; +using Json.Schema; +using SourceFlow.Studio.Dsl; +using SourceFlow.Studio.Dsl.Diagnostics; +using YamlDotNet.Core; +using YamlDotNet.RepresentationModel; + +namespace SourceFlow.Studio.Tests; + +/// The normative schema schemas/workflow-1.json agrees with the reader on every golden file (plan 10 WP-S.3). +[Trait("Category", "Unit")] +public sealed partial class SchemaTests +{ + private static readonly Lazy Schema = new(() => + JsonSchema.FromText(File.ReadAllText(Path.Combine(Golden.Root, "..", "..", "schemas", "workflow-1.json")))); + + [Theory] + [Trait("Id", "UT-WF-12")] + [Trait("Covers", "WFD-20")] + [MemberData(nameof(Cases))] + public void Schema_AndReader_AgreeOnEveryGoldenFile(string @case) + { + string yaml = Golden.Workflow(@case); + WorkflowAnalysisResult analysis = WorkflowAnalysis.Analyze(yaml, Golden.Environment); + if (analysis.Diagnostics.Any(d => d.Id == WorkflowRules.Syntax)) + { + return; // not YAML, or anchors and aliases: a YAML-level rule the JSON form can't express + } + + bool structural = analysis.Diagnostics.Any(d => d.Id.StartsWith("WF-S", StringComparison.Ordinal) || d.Id == WorkflowRules.NestedCompensation); + EvaluationResults results = Schema.Value.Evaluate(ToJson(yaml), new EvaluationOptions { OutputFormat = OutputFormat.List }); + + results.IsValid.ShouldBe(!structural, string.Join("; ", analysis.Diagnostics.Select(d => d.ToString()))); + } + + [Theory] + [Trait("Id", "UT-WF-12")] + [InlineData("PT30S", true)] + [InlineData("PT1.5S", true)] + [InlineData("P1DT12H", true)] + [InlineData("P2W", true)] + [InlineData("PT0S", true)] + [InlineData("P1M", false)] + [InlineData("PT", false)] + [InlineData("P", false)] + [InlineData("5m", false)] + [InlineData("PT1.5M", false)] + public void Durations_SchemaAndReaderAgree(string duration, bool valid) + { + Dsl.Model.IsoDuration.TryParse(duration, out _).ShouldBe(valid); + Regex pattern = new(((JsonObject)JsonNode.Parse(File.ReadAllText(Path.Combine(Golden.Root, "..", "..", "schemas", "workflow-1.json")))!["$defs"]!["duration"]!)["pattern"]!.GetValue()); + pattern.IsMatch(duration).ShouldBe(valid); + } + + public static TheoryData Cases() + { + return Golden.Cases(); + } + + // YAML to JSON with the reader's scalar rules (YAML 1.2 core schema; quoted scalars are strings). + internal static JsonNode? ToJson(string yaml) + { + var stream = new YamlStream(); + stream.Load(new StringReader(yaml)); + return Convert(stream.Documents[0].RootNode); + } + + private static JsonNode? Convert(YamlNode node) + { + switch (node) + { + case YamlMappingNode mapping: + var obj = new JsonObject(); + foreach (KeyValuePair pair in mapping.Children) + { + obj[((YamlScalarNode)pair.Key).Value!] = Convert(pair.Value); + } + + return obj; + case YamlSequenceNode sequence: + var array = new JsonArray(); + foreach (YamlNode child in sequence.Children) + { + array.Add(Convert(child)); + } + + return array; + case YamlScalarNode scalar: + string text = scalar.Value ?? string.Empty; + if (scalar.Style is ScalarStyle.SingleQuoted or ScalarStyle.DoubleQuoted or ScalarStyle.Literal or ScalarStyle.Folded) + { + return JsonValue.Create(text); + } + + if (text is "" or "~" or "null") + { + return null; + } + + if (text is "true" or "false") + { + return JsonValue.Create(text == "true"); + } + + if (IntegerPattern().IsMatch(text)) + { + return JsonValue.Create(long.Parse(text, CultureInfo.InvariantCulture)); + } + + if (FloatPattern().IsMatch(text)) + { + return JsonValue.Create(decimal.Parse(text, NumberStyles.Float, CultureInfo.InvariantCulture)); + } + + return JsonValue.Create(text); + default: + throw new NotSupportedException(node.GetType().Name); + } + } + + [GeneratedRegex("^[-+]?[0-9]+$")] + private static partial Regex IntegerPattern(); + + [GeneratedRegex("^[-+]?(\\.[0-9]+|[0-9]+(\\.[0-9]*)?)([eE][-+]?[0-9]+)?$")] + private static partial Regex FloatPattern(); +} diff --git a/tests/Workflows/SourceFlow.Studio.Tests/SimulationTests.cs b/tests/Workflows/SourceFlow.Studio.Tests/SimulationTests.cs new file mode 100644 index 00000000..da564941 --- /dev/null +++ b/tests/Workflows/SourceFlow.Studio.Tests/SimulationTests.cs @@ -0,0 +1,417 @@ +using System.Xml.Linq; +using Microsoft.CodeAnalysis; +using Microsoft.CodeAnalysis.CSharp; +using SourceFlow.Messaging; +using SourceFlow.Studio.Dsl; +using SourceFlow.Studio.Dsl.Export; +using SourceFlow.Studio.Dsl.Model; +using SourceFlow.Studio.Dsl.Reading; +using SourceFlow.Studio.Dsl.Simulation; +using SourceFlow.Studio.Dsl.Specs; + +namespace SourceFlow.Studio.Tests; + +/// UT-WF-41..60 (plan 10 §3.1): the simulator (doc 15 §5.3), the path enumerator, the exporters and the spec generator. +[Trait("Category", "Unit")] +public sealed class SimulationTests +{ + private static readonly DateTimeOffset T0 = new(2026, 1, 1, 0, 0, 0, TimeSpan.Zero); + + private static readonly Dictionary Order = new() + { + ["orderId"] = "order-7", ["total"] = 6000m, ["lines"] = new List { "sku-1" }, ["customerEmail"] = "a@b.c", ["priority"] = false, + }; + + private static WorkflowDefinition Example => WorkflowReader.Read(Golden.Workflow("01-order-fulfilment")).Workflow!; + + private static SimulationResult Started(IReadOnlyDictionary? data = null) => WorkflowSimulator.Start(Example, data ?? Order, T0); + + private static SimulationResult Run(SimulationResult result, params SimulationInput[] inputs) + { + foreach (SimulationInput input in inputs) + { + result = WorkflowSimulator.Step(result.State, input); + } + + return result; + } + + private static Dictionary Captured(string paymentId) => new() { ["paymentId"] = paymentId }; + + // ================================================================ the transition table (UT-WF-41..52) + + [Fact] + [Trait("Id", "UT-WF-41")] + [Trait("Covers", "WFD-33")] + public void Start_BindsData_AndEntersTheFirstStep() + { + SimulationResult result = Started(); + + result.State.Status.ShouldBe(WorkflowStatus.Running); + result.State.Instance.ShouldBe("order-7"); + result.State.Data["amount"].ShouldBe(6000m); + result.State.Step.ShouldBe("reserve-stock"); + result.State.Attempt.ShouldBe(1); + SentCommand sent = result.Sent.Single(); + sent.Command.ShouldBe("inventory.reserve-stock.v1"); + sent.Fields.Select(f => f.Key).ShouldBe(["orderId", "lines"]); + sent.MessageId.ShouldBe(WorkflowIds.Send("order-fulfilment@1", "order-7", "reserve-stock", 1)); + result.State.Timer.ShouldBe(new SimulationTimer(SimulationTimer.Timeout, "reserve-stock", 1, T0.AddMinutes(5))); + result.Effects.Select(e => e.Kind).ShouldBe([SimulationEffect.Status, SimulationEffect.Send, SimulationEffect.Schedule]); + Should.Throw(() => WorkflowSimulator.Start(null!, Order, T0)); + Should.Throw(() => WorkflowSimulator.Step(null!, SimulationInput.Succeed())); + } + + [Fact] + [Trait("Id", "UT-WF-42")] + public void Success_Captures_CancelsTheTimer_PushesTheCompensation_AndMovesOn() + { + SimulationResult result = Run(Started(), SimulationInput.Succeed(), SimulationInput.Succeed(Captured("pay-1"))); + + result.State.Data["paymentId"].ShouldBe("pay-1"); + result.State.CompensationStack.ShouldBe(["reserve-stock", "charge-payment"]); + result.State.Step.ShouldBe("review-large-order"); + result.Effects.Select(e => e.Kind).ShouldBe([SimulationEffect.Capture, SimulationEffect.Cancel, SimulationEffect.Schedule]); + result.Sent.ShouldBeEmpty("an await-only step sends nothing"); + } + + [Fact] + [Trait("Id", "UT-WF-43")] + public void Rejection_WithRetry_WaitsTheBackoff_ThenResendsWithTheNextAttemptId() + { + SimulationResult declined = Run(Started(), SimulationInput.Succeed(), SimulationInput.Reject("payments.declined")); + + declined.State.Phase.ShouldBe(WorkflowPhase.Retrying); + declined.State.Attempt.ShouldBe(2); + declined.State.Timer.ShouldBe(new SimulationTimer(SimulationTimer.Retry, "charge-payment", 2, T0.AddMinutes(10))); + declined.State.Retries["failure:0"].ShouldBe(1); + + SimulationResult resent = Run(declined, SimulationInput.FireTimer()); + resent.State.Now.ShouldBe(T0.AddMinutes(10)); + resent.Sent.Single().MessageId.ShouldBe(WorkflowIds.Send("order-fulfilment@1", "order-7", "charge-payment", 2)); + resent.State.Phase.ShouldBe(WorkflowPhase.Awaiting); + Run(declined, SimulationInput.Succeed()).Effects.Single().Kind.ShouldBe(SimulationEffect.Ignored, "an outcome while waiting to retry is ignored"); + } + + [Fact] + [Trait("Id", "UT-WF-44")] + [Trait("Covers", "WFD-24")] + public void RetriesExhausted_Fail_CompensatesInReverseOrder() + { + SimulationResult result = Run(Started(), SimulationInput.Succeed(), SimulationInput.Succeed(Captured("pay-1")), + SimulationInput.FailWith("orders.order-rejected-by-review.v1")); + + result.State.Status.ShouldBe(WorkflowStatus.Compensating); + result.State.Step.ShouldBe("charge-payment", "the most recent first"); + result.Sent.Single().ShouldSatisfyAllConditions( + c => c.Command.ShouldBe("payments.refund.v1"), + c => c.Fields.First().Value.ShouldBe("pay-1"), + c => c.MessageId.ShouldBe(WorkflowIds.Compensation("order-fulfilment@1", "order-7", "charge-payment", 1))); + result.State.Failure!.Code.ShouldBe("orders.order-rejected-by-review.v1"); + + result = Run(result, SimulationInput.Succeed()); + result.State.Step.ShouldBe("reserve-stock"); + result.Sent.Single().Command.ShouldBe("inventory.release-stock.v1"); + + result = Run(result, SimulationInput.Succeed()); + result.State.Status.ShouldBe(WorkflowStatus.Compensated); + result.State.CompensationStack.ShouldBeEmpty(); + result.Sent.Single().ShouldSatisfyAllConditions( + c => c.Command.ShouldBe("orders.cancel-order.v1"), + c => c.Fields.Single(f => f.Key == "reason").Value.ShouldBe("orders.order-rejected-by-review.v1")); + + // Exhausting a business retry: declined three times, then a fourth → fail. + SimulationResult declined = Run(Started(), SimulationInput.Succeed(), + SimulationInput.Reject("payments.declined"), SimulationInput.FireTimer(), + SimulationInput.Reject("payments.declined"), SimulationInput.FireTimer(), + SimulationInput.Reject("payments.declined"), SimulationInput.FireTimer(), + SimulationInput.Reject("payments.declined")); + declined.State.Status.ShouldBe(WorkflowStatus.Compensating); + declined.State.Step.ShouldBe("reserve-stock", "charge-payment never succeeded, so only reserve-stock is undone"); + } + + [Fact] + [Trait("Id", "UT-WF-45")] + public void CompensationRetry_TimesOut_RetriesWithBackoff_ThenSucceeds() + { + SimulationResult result = Run(Started(), SimulationInput.Succeed(), SimulationInput.Reject("payments.fraud_suspected")); + result.State.Step.ShouldBe("reserve-stock"); + result.State.Timer!.Due.ShouldBe(T0.AddMinutes(15)); + + result = Run(result, SimulationInput.FireTimer()); + result.State.Phase.ShouldBe(WorkflowPhase.Retrying); + result.State.Timer!.ShouldSatisfyAllConditions(t => t.Kind.ShouldBe(SimulationTimer.Retry), t => t.Due.ShouldBe(T0.AddMinutes(15).AddSeconds(30))); + + result = Run(result, SimulationInput.FireTimer()); + result.Sent.Single().MessageId.ShouldBe(WorkflowIds.Compensation("order-fulfilment@1", "order-7", "reserve-stock", 2)); + Run(result, SimulationInput.Succeed()).State.Status.ShouldBe(WorkflowStatus.Compensated); + } + + [Fact] + [Trait("Id", "UT-WF-46")] + public void CompensationExhausted_GoesToManualIntervention_KeepingTheStack() + { + SimulationResult result = Run(Started(), SimulationInput.Succeed(), SimulationInput.Reject("payments.fraud_suspected")); + for (int i = 0; i < 5; i++) + { + result = Run(result, SimulationInput.FireTimer(), SimulationInput.FireTimer()); // timeout, then the retry delay + } + + result = Run(result, SimulationInput.FireTimer()); // the sixth attempt times out: no retries left + + result.State.Status.ShouldBe(WorkflowStatus.ManualIntervention); + result.State.CompensationStack.ShouldBe(["reserve-stock"]); + result.State.CompensationPending.ShouldBeTrue(); + result.Effects.ShouldContain(e => e.Kind == SimulationEffect.Alert); + } + + [Fact] + [Trait("Id", "UT-WF-47")] + public void ThenManual_StopsInManualIntervention_KeepingThePosition() + { + SimulationResult result = Run(Started(), SimulationInput.Succeed(), SimulationInput.Succeed(Captured("p")), SimulationInput.FireTimer()); + + result.State.Status.ShouldBe(WorkflowStatus.ManualIntervention); + result.State.Step.ShouldBe("review-large-order"); + result.State.Failure!.Code.ShouldBe("timeout"); + result.State.CompensationPending.ShouldBeFalse(); + } + + [Fact] + [Trait("Id", "UT-WF-48")] + public void StaleTimeouts_AreIgnored() + { + SimulationResult result = Run(Started(), SimulationInput.FireTimer()); // reserve-stock timed out: immediate re-send (no delay) + result.State.Attempt.ShouldBe(2); + result.Sent.Single().MessageId.ShouldBe(WorkflowIds.Send("order-fulfilment@1", "order-7", "reserve-stock", 2)); + + SimulationResult stale = Run(result, SimulationInput.Timer(SimulationTimer.Timeout, "reserve-stock", 1)); + stale.Effects.Single().ShouldSatisfyAllConditions(e => e.Kind.ShouldBe(SimulationEffect.Ignored), e => e.Text.ShouldContain("stale")); + stale.State.Attempt.ShouldBe(2); + Run(result, SimulationInput.Timer(SimulationTimer.Timeout, "reserve-stock", 2)).State.Attempt.ShouldBe(3, "the current attempt's timeout counts"); + } + + [Fact] + [Trait("Id", "UT-WF-49")] + public void GotoAfterThePivot_RecoversForward_WithoutCompensation() + { + SimulationResult result = Run(Started(), SimulationInput.Succeed(), SimulationInput.Succeed(Captured("p")), SimulationInput.Succeed(), + SimulationInput.Reject("shipping.address_invalid")); + + result.State.Step.ShouldBe("await-address-fix"); + result.State.Status.ShouldBe(WorkflowStatus.Running); + + result = Run(result, SimulationInput.Succeed()); + result.State.Step.ShouldBe("create-shipment"); + result.Sent.Single().MessageId.ShouldBe(WorkflowIds.Send("order-fulfilment@1", "order-7", "create-shipment", 2), + "a re-entered step continues its attempt numbering: a new id, so the owner's inbox runs the re-send"); + result.State.Attempt.ShouldBe(2); + + result = Run(result, SimulationInput.Succeed()); + result.State.Status.ShouldBe(WorkflowStatus.Completed); + result.Sent.Single().ShouldSatisfyAllConditions(c => c.Command.ShouldBe("orders.mark-fulfilled.v1"), c => c.MessageId.ShouldBe(WorkflowIds.Terminal("order-fulfilment@1", "order-7", "completed"))); + } + + [Fact] + [Trait("Id", "UT-WF-50")] + public void GuardedStep_IsSkippedWhenFalse() + { + var small = new Dictionary(Order) { ["total"] = 100m }; + + SimulationResult result = Run(WorkflowSimulator.Start(Example, small, T0), SimulationInput.Succeed(), SimulationInput.Succeed(Captured("p"))); + + result.Effects.ShouldContain(e => e.Kind == SimulationEffect.Skip && e.Text == "review-large-order"); + result.State.Step.ShouldBe("create-shipment"); + WorkflowSimulator.Start(Example, small, T0, new SimulationOptions { Guard = _ => true }).State.Data["amount"].ShouldBe(100m); + } + + [Fact] + [Trait("Id", "UT-WF-51")] + public void Resume_AndRetryStep_ContinueFromManualIntervention() + { + SimulationResult manual = Run(Started(), SimulationInput.Succeed(), SimulationInput.Succeed(Captured("p")), SimulationInput.FireTimer()); + + SimulationResult resumed = Run(manual, SimulationInput.Resume()); + resumed.State.ShouldSatisfyAllConditions(s => s.Status.ShouldBe(WorkflowStatus.Running), s => s.Step.ShouldBe("review-large-order"), + s => s.Attempt.ShouldBe(2, "a resumed step is a new attempt (new send id, new timer)")); + Run(manual, SimulationInput.Resume("create-shipment")).Sent.Single().Command.ShouldBe("shipping.create-shipment.v1"); + Run(manual, SimulationInput.Resume("nowhere")).State.Status.ShouldBe(WorkflowStatus.ManualIntervention); + Run(manual, SimulationInput.RetryStep()).State.Attempt.ShouldBe(2); + Run(Started(), SimulationInput.Resume()).Effects.Single().Kind.ShouldBe(SimulationEffect.Ignored, "resume needs ManualIntervention"); + + // A failed compensation resumes compensating. + SimulationResult stuck = Run(Started(), SimulationInput.Succeed(), SimulationInput.Reject("payments.fraud_suspected")); + for (int i = 0; i < 5; i++) + { + stuck = Run(stuck, SimulationInput.FireTimer(), SimulationInput.FireTimer()); + } + + stuck = Run(stuck, SimulationInput.FireTimer()); + SimulationResult again = Run(stuck, SimulationInput.Resume()); + again.State.Status.ShouldBe(WorkflowStatus.Compensating); + again.Sent.Single().Command.ShouldBe("inventory.release-stock.v1"); + Run(again, SimulationInput.Succeed()).State.Status.ShouldBe(WorkflowStatus.Compensated); + Run(stuck, SimulationInput.RetryStep()).State.Attempt.ShouldBe(7); + } + + [Fact] + [Trait("Id", "UT-WF-52")] + public void Abort_UnhandledOutcomes_AndTerminalInstances() + { + SimulationResult running = Run(Started(), SimulationInput.Succeed(), SimulationInput.Succeed(Captured("p"))); + + SimulationResult aborted = Run(running, SimulationInput.Abort("customer asked")); + aborted.State.Status.ShouldBe(WorkflowStatus.Aborted); + aborted.Sent.ShouldBeEmpty("no compensation unless asked"); + Run(aborted, SimulationInput.Succeed()).Effects.Single().Kind.ShouldBe(SimulationEffect.Ignored, "terminal instances ignore everything"); + + SimulationResult undone = Run(running, SimulationInput.Abort("fraud", compensate: true), SimulationInput.Succeed(), SimulationInput.Succeed()); + undone.State.Status.ShouldBe(WorkflowStatus.Aborted, "an abort with compensation ends Aborted, not Compensated"); + undone.Sent.ShouldBeEmpty("on.compensated is not sent for an abort"); + + SimulationResult unexpected = Run(Started(), SimulationInput.Reject("inventory.warehouse_closed")); + unexpected.State.Status.ShouldBe(WorkflowStatus.ManualIntervention, "an undeclared rejection needs an operator"); + unexpected.State.Failure!.Code.ShouldBe("inventory.warehouse_closed"); + + WorkflowDefinition guarded = WorkflowReader.Read(Golden.Workflow("27-local-steps")).Workflow!; + SimulationResult ignored = WorkflowSimulator.Start(guarded, new Dictionary { ["orderId"] = "o", ["total"] = 0m }, T0); + ignored.Effects.Single().Text.ShouldContain("start.when is false"); + } + + // ================================================================ paths (UT-WF-53..56) + + [Fact] + [Trait("Id", "UT-WF-53")] + [Trait("Covers", "WFD-34")] + public void Paths_BoundLoopsAndRetries() + { + PathSet paths = PathEnumerator.Enumerate(Example); + + paths.Paths.Count.ShouldBe(437); + paths.Truncated.ShouldBeFalse(); + paths.Paths.ShouldAllBe(p => p.Moves.Count(m => m.Step == "create-shipment" && m.Outcome == "success") <= 1); + paths.Paths.Max(p => p.Moves.Select((m, i) => (m, i)).Count(x => x.m.Step == "create-shipment" && (x.i == 0 || p.Moves[x.i - 1].Step != "create-shipment"))).ShouldBe(2, "a step is entered at most twice"); + int declined = paths.Paths.Select(p => p.Moves.Count(m => m.Edge == "charge-payment:rejected:payments.declined")).Max(); + declined.ShouldBe(4, "retry loops at 0, 1 and max (3 retries: 4 rejections)"); + paths.Paths.ShouldContain(p => p.Moves.Count(m => m.Edge == "charge-payment:rejected:payments.declined") == 1); + PathEnumerator.Enumerate(Example, new PathOptions { MaxPaths = 10 }).ShouldSatisfyAllConditions(s => s.Paths.Count.ShouldBe(10), s => s.Truncated.ShouldBeTrue()); + } + + [Fact] + [Trait("Id", "UT-WF-54")] + public void Paths_EndInEveryReachableStatus_AndReplayFaithfully() + { + PathSet paths = PathEnumerator.Enumerate(Example); + + paths.Paths.Select(p => p.End).Distinct().Order().ShouldBe([WorkflowStatus.Completed, WorkflowStatus.Compensated, WorkflowStatus.ManualIntervention]); + foreach (WorkflowPath path in paths.Paths.Take(50).Concat(paths.Paths.TakeLast(50))) + { + PathEnumerator.Replay(Example, path).Last().State.Status.ShouldBe(path.End, path.ToString()); + } + + paths.Paths[0].Id.ShouldBe("P01"); + paths.Paths[0].ToString().ShouldStartWith("P01 reserve-stock: success → "); + } + + [Fact] + [Trait("Id", "UT-WF-55")] + public void Coverage_MarksEveryEdge_AndTheMinimalCoverKeepsIt() + { + PathSet paths = PathEnumerator.Enumerate(Example); + + paths.Uncovered.ShouldBeEmpty(); + paths.Edges.ShouldContain("review-large-order:skip"); + paths.Edges.ShouldContain("compensate:charge-payment:retry"); + paths.Covering("create-shipment:rejected:shipping.address_invalid").ShouldNotBeEmpty(); + IReadOnlyList cover = paths.MinimalCover(); + cover.Count.ShouldBeLessThan(20); + paths.Edges.ShouldAllBe(e => cover.Any(p => p.Moves.Any(m => m.Covers(e)))); + cover.Select(p => p.End).Distinct().Count().ShouldBe(3); + } + + [Fact] + [Trait("Id", "UT-WF-56")] + public void Paths_OfSmallWorkflows() + { + PathSet minimal = PathEnumerator.Enumerate(WorkflowReader.Read(Golden.Workflow("02-minimal")).Workflow!); + minimal.Paths.Select(p => p.ToString()).ShouldBe(["P01 approve: success ⇒ Completed", "P02 approve: timeout ⇒ ManualIntervention"]); + PathEnumerator.Enumerate(WorkflowReader.Read(Golden.Workflow("27-local-steps")).Workflow!).Paths.Count.ShouldBe(3, "start.when is assumed to hold"); + Should.Throw(() => PathEnumerator.Enumerate(null!)); + } + + // ================================================================ exporters and specs (UT-WF-57..60) + + [Theory] + [Trait("Id", "UT-WF-57")] + [Trait("Covers", "WFD-30;WFD-NFR-4")] + [MemberData(nameof(ValidCases))] + public void Mermaid_MatchesTheGoldenFile(string @case) + { + string mermaid = MermaidExporter.Export(WorkflowReader.Read(Golden.Workflow(@case)).Workflow!); + + mermaid.ShouldStartWith("---\ntitle: "); + mermaid.ShouldContain("stateDiagram-v2\n"); + Golden.AssertMatches(@case, "expected.mmd", mermaid); + } + + [Theory] + [Trait("Id", "UT-WF-58")] + [Trait("Covers", "WFD-36")] + [MemberData(nameof(ValidCases))] + public void Bpmn_IsAConsistentBpmn20Model(string @case) + { + string bpmn = BpmnExporter.Export(WorkflowReader.Read(Golden.Workflow(@case)).Workflow!); + + XDocument document = XDocument.Parse(bpmn); + XNamespace ns = BpmnExporter.Namespace; + document.Root!.Name.ShouldBe(ns + "definitions"); + string[] ids = [.. document.Descendants().Select(e => (string?)e.Attribute("id")).OfType()]; + ids.Distinct().Count().ShouldBe(ids.Length, "ids are unique"); + string[] references = [.. document.Descendants().SelectMany(e => e.Attributes().Where(a => a.Name.LocalName is "sourceRef" or "targetRef" or "attachedToRef" or "messageRef" or "default")).Select(a => a.Value)]; + references.ShouldAllBe(r => ids.Contains(r)); + XElement process = document.Root.Element(ns + "process")!; + process.Elements(ns + "startEvent").Count().ShouldBe(1); + process.Elements(ns + "sequenceFlow").ShouldAllBe(f => process.Elements().Any(e => (string?)e.Attribute("id") == (string)f.Attribute("targetRef")!)); + Golden.AssertMatches(@case, "expected.bpmn", bpmn); + } + + [Fact] + [Trait("Id", "UT-WF-59")] + [Trait("Covers", "WFD-34")] + public void Specs_AreGeneratedPerPath_AndParseAsCSharp() + { + WorkflowDefinition workflow = Example; + string specs = SpecGenerator.Generate(workflow, Golden.Environment, new SpecOptions { Namespace = "Orders.Tests", ModuleType = "Orders.OrdersModule", WorkflowType = "Orders.OrderFulfilmentWorkflowV1" }); + + SyntaxTree tree = CSharpSyntaxTree.ParseText(specs, new CSharpParseOptions(LanguageVersion.Preview), cancellationToken: TestContext.Current.CancellationToken); + tree.GetDiagnostics(TestContext.Current.CancellationToken).ShouldBeEmpty(); + specs.ShouldContain("WorkflowSpec.For()"); + int tests = specs.Split("[Fact").Length - 1; + tests.ShouldBe(PathEnumerator.Enumerate(workflow).MinimalCover().Count); + specs.ShouldNotContain("Skip =", Case.Sensitive, "the solver finds data for every guard decision"); + Golden.AssertMatches("01-order-fulfilment", "expected.specs.cs", specs); + + SpecGenerator.WorkflowTypeName(workflow).ShouldBe("OrderFulfilmentWorkflowV1"); + SpecGenerator.Pascal("await-address-fix").ShouldBe("AwaitAddressFix"); + string selected = SpecGenerator.Generate(workflow, Golden.Environment, new SpecOptions { PathIds = ["P01", "P02"] }); + (selected.Split("[Fact").Length - 1).ShouldBe(2); + (SpecGenerator.Generate(WorkflowReader.Read(Golden.Workflow("02-minimal")).Workflow!, Golden.Environment, new SpecOptions { AllPaths = true }).Split("[Fact").Length - 1).ShouldBe(2); + } + + [Fact] + [Trait("Id", "UT-WF-60")] + [Trait("Covers", "WFD-29")] + public void WorkflowIds_MatchTheRuntimesUuidV5() + { + WorkflowIds.Namespace.ShouldBe(MessageIds.SourceFlowNamespace); + string name = WorkflowIds.Name("order-fulfilment@1", "order-7", "reserve-stock", 2); + WorkflowIds.Send("order-fulfilment@1", "order-7", "reserve-stock", 2).ShouldBe(MessageIds.CreateVersion5(MessageIds.SourceFlowNamespace, name)); + WorkflowIds.Version5(new Guid("6ba7b810-9dad-11d1-80b4-00c04fd430c8"), "python.org").ShouldBe(new Guid("886313e1-3b8a-5372-9b90-0c9aee199e5d"), "RFC 9562 test vector"); + WorkflowIds.Compensation("w@1", "i", "s", 1).ShouldNotBe(WorkflowIds.Send("w@1", "i", "s", 1)); + } + + public static TheoryData ValidCases() + { + return new TheoryData(Golden.Cases().Select(row => (string)row.Data).Where(c => !WorkflowAnalysis.Analyze(Golden.Workflow(c), Golden.Environment).HasErrors)); + } +} diff --git a/tests/Workflows/SourceFlow.Studio.Tests/SourceFlow.Studio.Tests.csproj b/tests/Workflows/SourceFlow.Studio.Tests/SourceFlow.Studio.Tests.csproj new file mode 100644 index 00000000..bfc6ceab --- /dev/null +++ b/tests/Workflows/SourceFlow.Studio.Tests/SourceFlow.Studio.Tests.csproj @@ -0,0 +1,21 @@ + + + + true + + + + + + + + + + + + + diff --git a/tests/Workflows/SourceFlow.Studio.Tests/StudioApiTests.cs b/tests/Workflows/SourceFlow.Studio.Tests/StudioApiTests.cs new file mode 100644 index 00000000..21d4171f --- /dev/null +++ b/tests/Workflows/SourceFlow.Studio.Tests/StudioApiTests.cs @@ -0,0 +1,393 @@ +using System.Reflection; +using System.Text; +using System.Text.Json; +using System.Text.Json.Nodes; +using Microsoft.CodeAnalysis; +using Microsoft.CodeAnalysis.CSharp; +using Microsoft.CodeAnalysis.CSharp.Syntax; +using SourceFlow.Studio.Dsl; +using SourceFlow.Studio.Dsl.Api; +using SourceFlow.Studio.Dsl.Export; +using SourceFlow.Studio.Dsl.Model; +using SourceFlow.Studio.Dsl.Reading; +using SourceFlow.Studio.Dsl.Simulation; +using SourceFlow.Studio.Dsl.Specs; + +namespace SourceFlow.Studio.Tests; + +/// +/// The Studio core's JSON API (WP-S.7, ADR-025): what SourceFlow.Studio.Wasm exports. These run it in .NET; the Vitest +/// suite (web/core-client, WASM-01..08) runs the same API compiled to WebAssembly against the same golden files. +/// +[Trait("Category", "Unit")] +public sealed class StudioApiTests +{ + private static readonly string Repository = Path.GetFullPath(Path.Combine(Golden.Root, "..", "..")); + private static readonly string ExportsSource = Path.Combine(Repository, "src", "Workflows", "SourceFlow.Studio.Wasm", "Exports.cs"); + private static readonly string Declaration = Path.Combine(Repository, "web", "core-client", "src", "generated", "exports.d.ts"); + + [Fact] + [Trait("Id", "UT-WASM-01")] + [Trait("Covers", "WFD-NFR-2")] + public void EveryApiMethod_IsExported_AndTheTypeScriptDeclarationIsGeneratedFromTheExports() + { + string[] api = [.. typeof(StudioApi).GetMethods(BindingFlags.Public | BindingFlags.Static) + .Where(m => m.ReturnType == typeof(string) && m.GetParameters() is [{ ParameterType: var p }] && p == typeof(string)) + .OrderBy(m => m.MetadataToken) + .Select(m => m.Name)]; + IReadOnlyList exports = Exports(); + + exports.Select(e => e.Name).ShouldBe(api, "one [JSExport] per StudioApi method, in the same order"); + exports.ShouldAllBe(e => e.Delegates, "each export only calls StudioApi's method of the same name"); + api.ShouldBe(["Version", "Parse", "Validate", "SimulateStep", "EnumeratePaths", "ToMermaid", "ToBpmn", "GenerateSpecs", "Graph", "Sequence"]); + + string generated = TypeScript(exports); + string? committed = File.Exists(Declaration) ? File.ReadAllText(Declaration).Replace("\r\n", "\n", StringComparison.Ordinal) : null; + if (committed != generated && Environment.GetEnvironmentVariable(Golden.ApproveVariable) is "1" or "true") + { + Directory.CreateDirectory(Path.GetDirectoryName(Declaration)!); + File.WriteAllText(Declaration, generated, new UTF8Encoding(encoderShouldEmitUTF8Identifier: false)); + return; + } + + committed.ShouldBe(generated, $"web/core-client/src/generated/exports.d.ts is out of date: run the tests with {Golden.ApproveVariable}=1."); + } + + [Theory] + [Trait("Id", "UT-WASM-02")] + [Trait("Covers", "WFD-28;WFD-NFR-2")] + [MemberData(nameof(Cases))] + public void Validate_GivesTheGoldenDiagnostics(string @case) + { + JsonNode result = Ok(StudioApi.Validate(Request(new JsonObject { ["yaml"] = Golden.Workflow(@case), ["manifests"] = Manifests() }))); + + result["diagnostics"]!.ToJsonString(new JsonSerializerOptions { WriteIndented = true, NewLine = "\n", Encoder = System.Text.Encodings.Web.JavaScriptEncoder.UnsafeRelaxedJsonEscaping }).ShouldBe( + File.ReadAllText(Path.Combine(Golden.Root, "cases", @case, "expected.diagnostics.json")).Replace("\r\n", "\n", StringComparison.Ordinal).TrimEnd('\n')); + WorkflowAnalysisResult analysis = WorkflowAnalysis.Analyze(Golden.Workflow(@case), Golden.Environment); + result["valid"]!.GetValue().ShouldBe(analysis.Workflow is not null && !analysis.HasErrors); + } + + [Fact] + [Trait("Id", "UT-WASM-03")] + [Trait("Covers", "WFD-33")] + public void SimulateStep_DrivesTheSimulator_ThroughTheOpaqueState() + { + string yaml = Golden.Workflow("01-order-fulfilment"); + var data = new JsonObject { ["orderId"] = "o-1", ["total"] = 100, ["lines"] = new JsonArray("sku"), ["customerEmail"] = "a@b.c", ["priority"] = false }; + + JsonNode started = Ok(StudioApi.SimulateStep(Request(new JsonObject { ["yaml"] = yaml, ["input"] = new JsonObject { ["kind"] = "start", ["data"] = data }, ["now"] = "2026-01-01T00:00:00Z" }))); + started["status"]!.GetValue().ShouldBe("Running"); + started["step"]!.GetValue().ShouldBe("reserve-stock"); + JsonNode send = started["effects"]!.AsArray().Single(e => e!["kind"]!.GetValue() == "send")!; + send["command"]!["type"]!.GetValue().ShouldBe("inventory.reserve-stock.v1"); + send["command"]!["messageId"]!.GetValue().ShouldBe(WorkflowIds.Send("order-fulfilment@1", "o-1", "reserve-stock", 1).ToString("D")); + send["command"]!["fields"]!["orderId"]!.GetValue().ShouldBe("o-1"); + started["timer"]!["kind"]!.GetValue().ShouldBe("timeout"); + + JsonNode next = Step(yaml, started, new JsonObject { ["kind"] = "succeed" }); + next["step"]!.GetValue().ShouldBe("charge-payment"); + next["transitions"]!.AsArray().Single()!["kind"]!.GetValue().ShouldBe("success"); + JsonNode retried = Step(yaml, next, new JsonObject { ["kind"] = "reject", ["code"] = "payments.declined" }); + retried["phase"]!.GetValue().ShouldBe("Retrying"); + JsonNode fired = Step(yaml, retried, new JsonObject { ["kind"] = "timer" }); + fired["attempt"]!.GetValue().ShouldBe(2); + JsonNode fraud = Step(yaml, fired, new JsonObject { ["kind"] = "rejected", ["command"] = "payments.charge.v1", ["code"] = "payments.fraud_suspected" }); + fraud["status"]!.GetValue().ShouldBe("Compensating"); + fraud["compensationStack"]!.AsArray().Select(s => s!.GetValue()).ShouldBe(["reserve-stock"]); + fraud["failure"]!["code"]!.GetValue().ShouldBe("payments.fraud_suspected"); + JsonNode undone = Step(yaml, fraud, new JsonObject { ["kind"] = "receive", ["type"] = "inventory.stock-released.v1" }); + undone["status"]!.GetValue().ShouldBe("Compensated"); + undone["terminal"]!.GetValue().ShouldBeTrue(); + Step(yaml, undone, new JsonObject { ["kind"] = "resume" })["effects"]![0]!["kind"]!.GetValue().ShouldBe("ignored"); + + // Operators, guards and failure events. + JsonNode large = Ok(StudioApi.SimulateStep(Request(new JsonObject + { + ["yaml"] = yaml, + ["input"] = new JsonObject { ["kind"] = "start", ["data"] = data.DeepClone() }, + ["guards"] = new JsonObject { ["review-large-order"] = true }, + }))); + large = Step(yaml, Step(yaml, large, new JsonObject { ["kind"] = "succeed" }), new JsonObject { ["kind"] = "succeed", ["data"] = new JsonObject { ["paymentId"] = "p" } }, guards: true); + large["step"]!.GetValue().ShouldBe("review-large-order", "the forced guard ran the review"); + JsonNode manual = Step(yaml, large, new JsonObject { ["kind"] = "timer", ["timer"] = "timeout", ["step"] = "review-large-order", ["attempt"] = 1 }); + manual["status"]!.GetValue().ShouldBe("ManualIntervention"); + Step(yaml, manual, new JsonObject { ["kind"] = "retry-step" })["attempt"]!.GetValue().ShouldBe(2); + Step(yaml, manual, new JsonObject { ["kind"] = "resume", ["step"] = "create-shipment" })["step"]!.GetValue().ShouldBe("create-shipment"); + Step(yaml, manual, new JsonObject { ["kind"] = "abort", ["reason"] = "x", ["compensate"] = true })["status"]!.GetValue().ShouldBe("Compensating"); + Step(yaml, Step(yaml, manual, new JsonObject { ["kind"] = "resume" }), new JsonObject { ["kind"] = "fail", ["event"] = "orders.order-rejected-by-review.v1" })["status"]!.GetValue().ShouldBe("Compensating"); + } + + [Fact] + [Trait("Id", "UT-WASM-04")] + [Trait("Covers", "WFD-34;WFD-30;WFD-36")] + public void PathsExportsAndSpecs_EqualTheLibrary() + { + string yaml = Golden.Workflow("01-order-fulfilment"); + var workflow = WorkflowReader.Read(yaml).Workflow!; + PathSet expected = PathEnumerator.Enumerate(workflow); + + JsonNode paths = Ok(StudioApi.EnumeratePaths(Request(new JsonObject { ["yaml"] = yaml }))); + paths["paths"]!.AsArray().Select(p => p!["text"]!.GetValue()).ShouldBe(expected.Paths.Select(p => p.ToString())); + paths["edges"]!.AsArray().Count.ShouldBe(expected.Edges.Count); + paths["minimalCover"]!.AsArray().Select(p => p!.GetValue()).ShouldBe(expected.MinimalCover().Select(p => p.Id)); + paths["truncated"]!.GetValue().ShouldBeFalse(); + Ok(StudioApi.EnumeratePaths(Request(new JsonObject { ["yaml"] = yaml, ["maxPaths"] = 3, ["maxStepEntries"] = 1, ["maxMoves"] = 50 })))["truncated"]!.GetValue().ShouldBeTrue(); + + // Each move carries the input that takes it, so a client replays a path one SimulateStep at a time (WP-S.11). + foreach (JsonNode path in paths["paths"]!.AsArray().Select(p => p!)) + { + var guards = new JsonObject { ["$start"] = true }; + foreach (var step in workflow.Steps) + { + guards["$success:" + step.Id] = true; + } + + foreach ((string step, JsonNode? decision) in path["guards"]!.AsObject()) + { + guards[step] = decision!.GetValue(); + } + + JsonNode state = Ok(StudioApi.SimulateStep(Request(new JsonObject + { + ["yaml"] = yaml, + ["input"] = new JsonObject { ["kind"] = "start", ["data"] = new JsonObject { ["orderId"] = "instance-1" } }, + ["guards"] = guards.DeepClone(), + }))); + foreach (JsonNode move in path["moves"]!.AsArray().Select(m => m!).Where(m => m["input"] is not null)) + { + state = Ok(StudioApi.SimulateStep(Request(new JsonObject + { + ["yaml"] = yaml, + ["state"] = state["state"]!.GetValue(), + ["input"] = move["input"]!.DeepClone(), + ["guards"] = guards.DeepClone(), + }))); + } + + state["status"]!.GetValue().ShouldBe(path["end"]!.GetValue(), path["text"]!.GetValue()); + } + + JsonNode first = paths["paths"]![0]!["moves"]![0]!; + first["input"]!.ToJsonString().ShouldBe("""{"kind":"succeed"}"""); + paths["paths"]!.AsArray().SelectMany(p => p!["moves"]!.AsArray()).Select(m => m!["input"]?["kind"]?.GetValue()) + .Where(k => k is not null).Distinct().Order(StringComparer.Ordinal).ShouldBe(["fail", "reject", "succeed", "timer"]); + + Ok(StudioApi.ToMermaid(Request(new JsonObject { ["yaml"] = yaml })))["text"]!.GetValue().ShouldBe(MermaidExporter.Export(workflow)); + Ok(StudioApi.ToBpmn(Request(new JsonObject { ["yaml"] = yaml })))["text"]!.GetValue().ShouldBe(BpmnExporter.Export(workflow)); + string specs = Ok(StudioApi.GenerateSpecs(Request(new JsonObject + { + ["yaml"] = yaml, + ["manifests"] = Manifests(), + ["namespace"] = "Orders.Tests", + ["moduleType"] = "Orders.OrdersModule", + ["workflowType"] = "Orders.OrderFulfilmentWorkflowV1", + })))["text"]!.GetValue(); + specs.ShouldBe(File.ReadAllText(Path.Combine(Golden.Root, "cases", "01-order-fulfilment", "expected.specs.cs")).Replace("\r\n", "\n", StringComparison.Ordinal)); + Ok(StudioApi.GenerateSpecs(Request(new JsonObject { ["yaml"] = yaml, ["manifests"] = Manifests(), ["pathIds"] = new JsonArray("P01") })))["text"]!.GetValue() + .Split("[Fact").Length.ShouldBe(2, "only the selected path"); + Ok(StudioApi.GenerateSpecs(Request(new JsonObject { ["yaml"] = yaml, ["manifests"] = Manifests(), ["allPaths"] = true })))["text"]!.GetValue() + .Split("[Fact").Length.ShouldBe(expected.Paths.Count + 1); + } + + [Fact] + [Trait("Id", "UT-WASM-05")] + [Trait("Covers", "WFD-NFR-2")] + public void Failures_AreEnvelopes_NeverExceptions() + { + Error(StudioApi.Parse("[]")).ShouldBe("The request must be a JSON object."); + Error(StudioApi.Parse("{")).ShouldNotBeNullOrEmpty(); + Error(StudioApi.Validate("{}")).ShouldBe("'yaml' is required."); + Error(StudioApi.Validate(Request(new JsonObject { ["yaml"] = "x: 1", ["manifests"] = new JsonArray(1) }))).ShouldContain("manifest JSON strings"); + Error(StudioApi.SimulateStep(Request(new JsonObject { ["yaml"] = Golden.Workflow("02-minimal") }))).ShouldBe("'input' is required."); + Error(StudioApi.SimulateStep(Request(new JsonObject { ["yaml"] = Golden.Workflow("02-minimal"), ["input"] = new JsonObject { ["kind"] = "succeed" } }))).ShouldBe("'state' is required after the start."); + Error(StudioApi.SimulateStep(Request(new JsonObject { ["yaml"] = Golden.Workflow("02-minimal"), ["input"] = new JsonObject() }))).ShouldBe("'input.kind' is required."); + Error(StudioApi.SimulateStep(Request(new JsonObject { ["yaml"] = Golden.Workflow("02-minimal"), ["input"] = new JsonObject { ["kind"] = "start", ["data"] = new JsonObject() }, ["now"] = "soon" }))) + .ShouldContain("ISO-8601"); + + JsonNode started = Ok(StudioApi.SimulateStep(Request(new JsonObject { ["yaml"] = Golden.Workflow("02-minimal"), ["input"] = new JsonObject { ["kind"] = "start", ["data"] = new JsonObject() } }))); + Error(StudioApi.SimulateStep(Request(new JsonObject { ["yaml"] = Golden.Workflow("02-minimal"), ["state"] = started["state"]!.GetValue(), ["input"] = new JsonObject { ["kind"] = "jump" } }))) + .ShouldBe("Unknown input kind 'jump'."); + Error(StudioApi.SimulateStep(Request(new JsonObject { ["yaml"] = Golden.Workflow("02-minimal"), ["state"] = started["state"]!.GetValue(), ["input"] = new JsonObject { ["kind"] = "fail" } }))) + .ShouldBe("'input.event' is required for fail."); + + JsonNode broken = JsonNode.Parse(StudioApi.ToMermaid(Request(new JsonObject { ["yaml"] = Golden.Workflow("03-s01-invalid-yaml") })))!; + broken["ok"]!.GetValue().ShouldBeFalse(); + broken["diagnostics"]!.AsArray().ShouldNotBeEmpty("the reader's diagnostics explain why"); + Ok(StudioApi.Version(string.Empty))["api"]!.GetValue().ShouldBe(StudioApi.ApiVersion); + Ok(StudioApi.Parse(Request(new JsonObject { ["yaml"] = "- not a mapping" })))["workflow"].ShouldBeNull(); + Ok(StudioApi.Parse(Request(new JsonObject { ["yaml"] = Golden.Workflow("02-minimal") })))["workflow"]!["name"]!.GetValue().ShouldNotBeNullOrEmpty(); + } + + [Theory] + [Trait("Id", "UT-WASM-06")] + [Trait("Covers", "WFD-30;WFD-NFR-4")] + [MemberData(nameof(Cases))] + public void Graph_MatchesTheGoldenFile(string @case) + { + WorkflowAnalysisResult analysis = WorkflowAnalysis.Analyze(Golden.Workflow(@case), Golden.Environment); + if (analysis.HasErrors) + { + return; // diagrams are for valid workflows + } + + JsonNode graph = Ok(StudioApi.Graph(Request(new JsonObject { ["yaml"] = Golden.Workflow(@case) }))); + string[] nodes = [.. graph["nodes"]!.AsArray().Select(n => n!["id"]!.GetValue())]; + graph["edges"]!.AsArray().ShouldAllBe(e => nodes.Contains(e!["source"]!.GetValue()) && nodes.Contains(e["target"]!.GetValue()), "edges join nodes"); + graph["edges"]!.AsArray().Select(e => e!["id"]!.GetValue()).ShouldBeUnique(); + Golden.AssertMatches(@case, "expected.graph.json", graph.ToJsonString(new JsonSerializerOptions { WriteIndented = true, NewLine = "\n", Encoder = System.Text.Encodings.Web.JavaScriptEncoder.UnsafeRelaxedJsonEscaping }) + "\n"); + } + + [Fact] + [Trait("Id", "UT-WASM-07")] + [Trait("Covers", "WFD-30;WFD-NFR-4")] + public void Graph_EncodesEveryPathKind() + { + JsonNode graph = Ok(StudioApi.Graph(Request(new JsonObject { ["yaml"] = Golden.Workflow("01-order-fulfilment") }))); + JsonNode Node(string id) => graph["nodes"]!.AsArray().Single(n => n!["id"]!.GetValue() == id)!; + JsonNode[] Edges(string kind) => [.. graph["edges"]!.AsArray().Where(e => e!["kind"]!.GetValue() == kind).Select(e => e!)]; + + Node("create-shipment")["kind"]!.GetValue().ShouldBe("pivot"); + Node("review-large-order")["when"]!.GetValue().ShouldBe("$data.amount > 5000"); + Node("reserve-stock")["compensable"]!.GetValue().ShouldBeTrue(); + Node("undo:charge-payment")["order"]!.GetValue().ShouldBe(1, "the most recent completed step is undone first"); + Node("undo:reserve-stock")["parent"]!.GetValue().ShouldBe("Compensating"); + foreach (string kind in new[] { "start", "success", "failure", "retry", "timeout", "compensation", "manual", "skip" }) + { + JsonNode[] edges = Edges(kind); + edges.ShouldNotBeEmpty(kind); + edges.ShouldAllBe(e => e["label"]!.GetValue().StartsWith(Symbol(kind), StringComparison.Ordinal), kind + " edges carry their symbol"); + } + + Edges("retry").ShouldContain(e => e["source"]!.GetValue() == "charge-payment" && e["label"]!.GetValue() == "↻ 3× every PT10M on payments.declined"); + Edges("failure").ShouldContain(e => e["source"]!.GetValue() == "create-shipment" && e["target"]!.GetValue() == "await-address-fix"); + Edges("timeout").ShouldContain(e => e["source"]!.GetValue() == "review-large-order" && e["target"]!.GetValue() == "ManualIntervention"); + Edges("success").ShouldContain(e => e["description"]!.GetValue() == "Success: shipping.shipment-created.v1 moves from create-shipment to Completed"); + Error(StudioApi.Graph(Request(new JsonObject { ["yaml"] = Golden.Workflow("03-s01-invalid-yaml") }))).ShouldContain("errors"); + } + + [Fact] + [Trait("Id", "UT-WASM-08")] + [Trait("Covers", "WFD-31")] + public void Sequence_PlacesEachMessageBetweenItsServices() + { + string yaml = Golden.Workflow("01-order-fulfilment"); + WorkflowDefinition workflow = WorkflowReader.Read(yaml).Workflow!; + PathSet paths = PathEnumerator.Enumerate(workflow); + string happy = paths.Paths.First(p => p.End == WorkflowStatus.Completed && p.Moves.All(m => m.Outcome == "success")).Id; + string compensated = paths.Paths.First(p => p.End == WorkflowStatus.Compensated && p.Moves.Any(m => m.Outcome == "compensated")).Id; + + JsonNode sequence = Ok(StudioApi.Sequence(Request(new JsonObject { ["yaml"] = yaml, ["manifests"] = Manifests(), ["path"] = happy }))); + sequence["lanes"]![0]!["id"]!.GetValue().ShouldBe("workflow"); + string[] lanes = [.. sequence["lanes"]!.AsArray().Select(l => l!["id"]!.GetValue())]; + lanes.ShouldContain("inventory"); + lanes.ShouldContain("payments"); + lanes.ShouldContain("shipping"); + JsonArray messages = sequence["messages"]!.AsArray(); + messages[0]!["kind"]!.GetValue().ShouldBe("start"); + messages.ShouldContain(m => m!["kind"]!.GetValue() == "command" && m["to"]!.GetValue() == "inventory" && m["type"]!.GetValue() == "inventory.reserve-stock.v1"); + messages.ShouldContain(m => m!["kind"]!.GetValue() == "event" && m["from"]!.GetValue() == "payments" && m["to"]!.GetValue() == "workflow"); + messages.ShouldAllBe(m => lanes.Contains(m!["from"]!.GetValue()) && lanes.Contains(m["to"]!.GetValue())); + messages[^1]!["label"]!.GetValue().ShouldBe("→ orders.mark-fulfilled.v1", "on.completed"); + + JsonArray undo = Ok(StudioApi.Sequence(Request(new JsonObject { ["yaml"] = yaml, ["manifests"] = Manifests(), ["path"] = compensated })))["messages"]!.AsArray(); + undo.ShouldContain(m => m!["kind"]!.GetValue() == "compensation" && m["label"]!.GetValue().StartsWith("⟲ ", StringComparison.Ordinal)); + undo.ShouldContain(m => m!["kind"]!.GetValue() == "status" && m["label"]!.GetValue().StartsWith("Compensating", StringComparison.Ordinal)); + Error(StudioApi.Sequence(Request(new JsonObject { ["yaml"] = yaml, ["manifests"] = Manifests(), ["path"] = "P999" }))).ShouldStartWith("No path 'P999'"); + } + + private static string Symbol(string kind) + { + return kind switch + { + "success" => "✓", "failure" => "✕", "retry" => "↻", "timeout" => "⏱", "compensation" => "⟲", "manual" => "✋", "skip" => "⤼", _ => "▶", + }; + } + + // ================================================================ helpers + + public static TheoryData Cases() + { + return Golden.Cases(); + } + + private static string Request(JsonObject request) + { + return request.ToJsonString(); + } + + private static JsonNode Ok(string response) + { + JsonNode envelope = JsonNode.Parse(response)!; + envelope["ok"]!.GetValue().ShouldBeTrue(response); + return envelope["result"]!; + } + + private static string Error(string response) + { + JsonNode envelope = JsonNode.Parse(response)!; + envelope["ok"]!.GetValue().ShouldBeFalse(response); + return envelope["error"]!.GetValue(); + } + + private static JsonNode Step(string yaml, JsonNode previous, JsonObject input, bool guards = false) + { + var request = new JsonObject { ["yaml"] = yaml, ["state"] = previous["state"]!.GetValue(), ["input"] = input }; + if (guards) + { + request["guards"] = new JsonObject { ["review-large-order"] = true }; + } + + return Ok(StudioApi.SimulateStep(Request(request))); + } + + // The golden domain's manifests, in sourceflow.domain.yaml order (as DomainWorkspace loads them). + private static JsonArray Manifests() + { + string domain = Path.Combine(Golden.Root, "domain"); + return new JsonArray([.. File.ReadAllLines(Path.Combine(domain, "sourceflow.domain.yaml")) + .Select(l => l.Trim()) + .Where(l => l.StartsWith("manifest:", StringComparison.Ordinal)) + .Select(l => (JsonNode)JsonValue.Create(File.ReadAllText(Path.Combine(domain, l["manifest:".Length..].Trim())))!)]); + } + + private sealed record Export(string Name, string Summary, bool Delegates); + + private static List Exports() + { + CompilationUnitSyntax root = CSharpSyntaxTree.ParseText(File.ReadAllText(ExportsSource), cancellationToken: TestContext.Current.CancellationToken).GetCompilationUnitRoot(TestContext.Current.CancellationToken); + var exports = new List(); + foreach (MethodDeclarationSyntax method in root.DescendantNodes().OfType() + .Where(m => m.AttributeLists.SelectMany(a => a.Attributes).Any(a => a.Name.ToString() == "JSExport"))) + { + method.ReturnType.ToString().ShouldBe("string", method.Identifier.Text); + method.ParameterList.Parameters.Select(p => p.Type!.ToString() + " " + p.Identifier.Text).ShouldBe(["string request"], method.Identifier.Text); + string summary = string.Join(" ", method.GetLeadingTrivia().ToFullString().Split('\n') + .Select(l => l.Trim().TrimStart('/').Trim()) + .Where(l => l.Length > 0) + .Select(l => l.Replace("", string.Empty, StringComparison.Ordinal).Replace("", string.Empty, StringComparison.Ordinal).Trim()) + .Where(l => l.Length > 0 && !l.StartsWith('['))); + bool delegates = method.ExpressionBody?.Expression.ToString() == $"StudioApi.{method.Identifier.Text}(request)"; + exports.Add(new Export(method.Identifier.Text, summary, delegates)); + } + + return exports; + } + + private static string TypeScript(IEnumerable exports) + { + var text = new StringBuilder() + .Append("// \n") + .Append("// Generated from the [JSExport] signatures in src/Workflows/SourceFlow.Studio.Wasm/Exports.cs by StudioApiTests\n") + .Append("// (tests/Workflows/SourceFlow.Studio.Tests, UT-WASM-01). Do not edit: run the tests with SOURCEFLOW_APPROVE=1.\n") + .Append('\n') + .Append("/** The exports of SourceFlow.Studio.Wasm.dll (`SourceFlow.Studio.Wasm.Exports`): one JSON request in, one JSON envelope out. */\n") + .Append("export interface StudioExports {\n"); + foreach (Export export in exports) + { + text.Append(" /** ").Append(export.Summary).Append(" */\n") + .Append(" ").Append(export.Name).Append("(request: string): string;\n"); + } + + return text.Append("}\n\n/** The name of an export. */\nexport type ExportName = keyof StudioExports;\n").ToString(); + } +} diff --git a/tests/Workflows/SourceFlow.Studio.Tests/TimerAndPivotTests.cs b/tests/Workflows/SourceFlow.Studio.Tests/TimerAndPivotTests.cs new file mode 100644 index 00000000..cc4f0cb2 --- /dev/null +++ b/tests/Workflows/SourceFlow.Studio.Tests/TimerAndPivotTests.cs @@ -0,0 +1,123 @@ +using SourceFlow.Studio.Dsl.Model; +using SourceFlow.Studio.Dsl.Reading; +using SourceFlow.Studio.Dsl.Simulation; + +namespace SourceFlow.Studio.Tests; + +/// UT-WF-77..79 (WP-C.10, CR-19, CR-20): timer identity and due time, and the pivot as a point of no return. +[Trait("Category", "Unit")] +public sealed class TimerAndPivotTests +{ + private static readonly DateTimeOffset T0 = new(2026, 1, 1, 0, 0, 0, TimeSpan.Zero); + + private static readonly Dictionary Order = new() + { + ["orderId"] = "order-7", ["total"] = 6000m, ["lines"] = new List { "sku-1" }, ["customerEmail"] = "a@b.c", ["priority"] = false, + }; + + // A post-pivot step whose timeout says 'fail' (WF-V07 refuses it; the engine must too, for definitions validated before). + private const string PastThePivot = """ + sourceflow.workflow: 1 + name: ship-order + version: 1 + owner: orders + start: { on: orders.order-placed.v1, correlate: data.orderId } + data: + orderId: { from: start.data.orderId } + steps: + - id: reserve + send: { command: inventory.reserve-stock.v1, map: { orderId: $data.orderId } } + await: { success: inventory.stock-reserved.v1 } + timeout: { after: PT5M, then: fail } + compensate: + send: { command: inventory.release-stock.v1, map: { orderId: $data.orderId } } + await: { success: inventory.stock-released.v1 } + timeout: { after: PT15M } + - id: ship + pivot: true + send: { command: shipping.create-shipment.v1, map: { orderId: $data.orderId } } + await: { success: shipping.shipment-created.v1 } + timeout: { after: PT1H, then: manual } + - id: confirm + send: { command: orders.approve-order.v1, map: { orderId: $data.orderId } } + await: { success: orders.order-approved.v1 } + timeout: { after: PT1H, then: fail } + """; + + private static WorkflowDefinition Example => WorkflowReader.Read(Golden.Workflow("01-order-fulfilment")).Workflow!; + + private static SimulationResult Run(SimulationResult result, params SimulationInput[] inputs) + { + foreach (SimulationInput input in inputs) + { + result = WorkflowSimulator.Step(result.State, input); + } + + return result; + } + + [Fact] + [Trait("Id", "UT-WF-77")] + [Trait("Covers", "doc 15 5.1;doc 15 5.3")] + public void APaymentRejectedWithinFiveMinutes_GivesReleaseStockItsOwnFifteenMinuteTimeout() + { + SimulationResult started = WorkflowSimulator.Start(Example, Order, T0); + SimulationTimer reserveTimeout = started.State.Timer!; // reserve-stock's 5-minute timeout, cancelled on success + SimulationResult compensating = Run(started, + SimulationInput.Receive("inventory.stock-reserved.v1", new Dictionary { ["orderId"] = "order-7" }), + SimulationInput.RejectedFor("payments.charge.v1", "payments.fraud_suspected", "fraud")); + + compensating.State.Status.ShouldBe(WorkflowStatus.Compensating); + SimulationTimer compensation = compensating.State.Timer.ShouldNotBeNull(); + compensation.Kind.ShouldBe(SimulationTimer.CompensateTimeout); + compensation.Step.ShouldBe("compensate:reserve-stock"); + compensation.Due.ShouldBe(compensating.State.Now.AddMinutes(15), "release-stock's own timeout"); + + // The cancelled step timeout is still delivered at T0 + 5 min: it is not the compensation's. + SimulationResult late = Run(compensating, SimulationInput.Timer(reserveTimeout.Kind, reserveTimeout.Step, reserveTimeout.Attempt, reserveTimeout.Due)); + late.Effects.Single().Kind.ShouldBe(SimulationEffect.Ignored); + late.State.Status.ShouldBe(WorkflowStatus.Compensating); + late.State.Timer.ShouldBe(compensation); + } + + [Fact] + [Trait("Id", "UT-WF-78")] + [Trait("Covers", "doc 15 5.3")] + public void ACancelledStepTimer_DeliveredLate_IsIgnored_AndSoIsOneWithTheWrongDueTime() + { + SimulationResult started = WorkflowSimulator.Start(Example, Order, T0); + SimulationTimer reserveTimeout = started.State.Timer!; + SimulationResult charging = Run(started, SimulationInput.Receive("inventory.stock-reserved.v1", new Dictionary { ["orderId"] = "order-7" })); + SimulationTimer pending = charging.State.Timer.ShouldNotBeNull(); + + Run(charging, SimulationInput.Timer(reserveTimeout.Kind, reserveTimeout.Step, reserveTimeout.Attempt, reserveTimeout.Due)) + .Effects.Single().Kind.ShouldBe(SimulationEffect.Ignored, "the step it belonged to is done"); + Run(charging, SimulationInput.Timer(pending.Kind, pending.Step, pending.Attempt, pending.Due.AddMinutes(-1))) + .Effects.Single().Kind.ShouldBe(SimulationEffect.Ignored, "same identity, but not the timer that is pending"); + Run(charging, SimulationInput.Timer(pending.Kind, pending.Step, pending.Attempt, pending.Due)) + .State.Attempt.ShouldBe(2, "the pending timer counts"); + } + + [Fact] + [Trait("Id", "UT-WF-79")] + [Trait("Covers", "doc 15 2;WF-V07")] + public void AfterThePivot_CompensationIsRefused_ExceptForAnAuditedOperatorAbort() + { + WorkflowDefinition workflow = WorkflowReader.Read(PastThePivot).Workflow!; + SimulationResult shipped = Run(WorkflowSimulator.Start(workflow, new Dictionary { ["orderId"] = "o-1" }, T0), + SimulationInput.Receive("inventory.stock-reserved.v1", new Dictionary { ["orderId"] = "o-1" }), + SimulationInput.Receive("shipping.shipment-created.v1", new Dictionary { ["orderId"] = "o-1" })); + shipped.State.PivotPassed.ShouldBeTrue(); + + SimulationResult failed = Run(shipped, SimulationInput.FireTimer()); // confirm times out: 'then: fail' + failed.State.Status.ShouldBe(WorkflowStatus.ManualIntervention, "no compensation after the point of no return"); + failed.Sent.ShouldBeEmpty("release-stock is not sent"); + + Run(failed, SimulationInput.Resume("reserve")).Effects.ShouldContain(e => e.Kind == SimulationEffect.Ignored && e.Text.Contains("before the pivot")); + + SimulationResult aborted = Run(failed, SimulationInput.Abort("customer cancelled after shipping", compensate: true)); + aborted.Effects.ShouldContain(e => e.Kind == SimulationEffect.Audit); + aborted.State.Status.ShouldBe(WorkflowStatus.Compensating); + aborted.Sent.Single().Command.ShouldBe("inventory.release-stock.v1"); + } +} diff --git a/tests/Workflows/SourceFlow.Studio.Tests/TravelBookingSampleTests.cs b/tests/Workflows/SourceFlow.Studio.Tests/TravelBookingSampleTests.cs new file mode 100644 index 00000000..ef94312d --- /dev/null +++ b/tests/Workflows/SourceFlow.Studio.Tests/TravelBookingSampleTests.cs @@ -0,0 +1,117 @@ +using SourceFlow.Studio.Dsl; +using SourceFlow.Studio.Dsl.Manifests; +using SourceFlow.Studio.Dsl.Model; +using SourceFlow.Studio.Dsl.Simulation; +using SourceFlow.Studio.Dsl.Specs; +using SourceFlow.Studio.Dsl.Validation; +using SourceFlow.Studio.Workspace; + +namespace SourceFlow.Studio.Tests; + +/// +/// The TravelBooking sample (samples/TravelBooking) as a workspace: its exported manifests are exact, its trip-booking +/// workflow validates against both services with no diagnostic and has the expected path set, and the specs Studio +/// generated for it are current. +/// +[Trait("Category", "Unit")] +public sealed class TravelBookingSampleTests +{ + private static readonly string Sample = Path.GetFullPath(Path.Combine(AppContext.BaseDirectory, "..", "..", "..", "..", "..", "..", "samples", "TravelBooking")); + + private static CancellationToken Ct => TestContext.Current.CancellationToken; + + [Fact] + [Trait("Id", "UT-MAN-17")] + [Trait("Covers", "WFD-11;WFD-12")] + public async Task Manifests_HaveExactEmitsAndRejects_ForBothServices() + { + DomainWorkspace workspace = await DomainWorkspace.LoadAsync(Sample, cancellationToken: Ct); + + workspace.Services.Select(s => s.Name).ShouldBe(["bookings", "hotels"]); + Commands(workspace, "hotels").ShouldBe( + [ + "hotels.confirm-reservation: emits hotels.reservation-confirmed.v1; rejects hotels.hold_lost", + "hotels.register-hotel: emits hotels.hotel-registered.v1; rejects hotels.invalid_rooms", + "hotels.release-room: emits hotels.room-released.v1; rejects none", + "hotels.reserve-room: emits hotels.room-reserved.v1; rejects hotels.sold_out, hotels.unknown_hotel", + ]); + Commands(workspace, "bookings").ShouldContain("bookings.request-booking: emits bookings.booking-requested.v1; rejects bookings.guest_required, bookings.invalid_stay"); + + ServiceManifest bookings = workspace.Services.Single(s => s.Name == "bookings").Manifest; + bookings.CommandRoutes.Where(r => r.ReplyOnReject).Select(r => r.Command).ShouldBe(["hotels.confirm-reservation.v1", "hotels.reserve-room.v1"]); + bookings.Workflows.ShouldHaveSingleItem().Name.ShouldBe("trip-booking"); + ServiceManifest hotels = workspace.Services.Single(s => s.Name == "hotels").Manifest; + hotels.Publishes.Select(p => p.Topic).Distinct().ShouldBe(["hotels.events"]); + } + + [Fact] + [Trait("Id", "UT-WF-74")] + [Trait("Covers", "WFD-28")] + public async Task Workflow_ValidatesAgainstBothServices_WithNoDiagnostic() + { + (DomainWorkspace workspace, WorkflowAnalysisResult analysis) = await AnalyzeAsync(); + + workspace.Services.Single(s => s.Name == "bookings").WorkflowFiles.ShouldHaveSingleItem().ShouldEndWith("trip-booking.sfflow.yaml"); + analysis.Diagnostics.ShouldBeEmpty(); + analysis.Workflow.ShouldNotBeNull().ProcessName.ShouldBe("trip-booking@1"); + } + + [Fact] + [Trait("Id", "UT-WF-75")] + [Trait("Covers", "WFD-33")] + public async Task Workflow_ReachesEveryEnd() + { + (_, WorkflowAnalysisResult analysis) = await AnalyzeAsync(); + + PathSet paths = PathEnumerator.Enumerate(analysis.Workflow!); + paths.Paths.Count.ShouldBe(ExpectedPaths); + paths.MinimalCover().Count.ShouldBe(ExpectedCover); + paths.Paths.Select(p => p.End).Distinct().Order().ShouldBe([WorkflowStatus.Completed, WorkflowStatus.Compensated, WorkflowStatus.ManualIntervention]); + } + + [Fact] + [Trait("Id", "UT-WF-76")] + [Trait("Covers", "WFD-34")] + public async Task GeneratedSpecs_AreCurrent() + { + (DomainWorkspace workspace, WorkflowAnalysisResult analysis) = await AnalyzeAsync(); + WorkspaceService bookings = workspace.Services.Single(s => s.Name == "bookings"); + + // The options the local host uses for the service's tests and module (sourceflow.domain.yaml). + string expected = SpecGenerator.Generate(analysis.Workflow!, new WorkflowEnvironment(workspace.Manifests), new SpecOptions + { + Namespace = "TravelBooking.Tests.Workflows", + ModuleType = bookings.ModuleType!, + WorkflowType = "Bookings.TripBookingWorkflowV1", + }); + string file = Path.Combine(Sample, bookings.TestsLocation!, "Workflows", "TripBookingV1PathTests.cs"); + if (string.Equals(Environment.GetEnvironmentVariable(SourceFlow.Testing.Approvals.ApproveVariable), "1", StringComparison.Ordinal)) + { + Directory.CreateDirectory(Path.GetDirectoryName(file)!); + await File.WriteAllTextAsync(file, expected, Ct); + } + + File.ReadAllText(file).ReplaceLineEndings("\n").ShouldBe(expected, "regenerate the specs in Studio (Paths → Generate specs) after changing the workflow"); + } + + // The trip-booking workflow's paths (retry loops at 0, 1 and the maximum) and the minimal cover Studio generates specs for. + private const int ExpectedPaths = 27; + private const int ExpectedCover = 6; + + private static async Task<(DomainWorkspace Workspace, WorkflowAnalysisResult Analysis)> AnalyzeAsync() + { + DomainWorkspace workspace = await DomainWorkspace.LoadAsync(Sample, cancellationToken: Ct); + string file = Path.Combine(workspace.Root, "Bookings", "Workflows", "trip-booking.sfflow.yaml"); + return (workspace, WorkflowAnalysis.Analyze(await File.ReadAllTextAsync(file, Ct), new WorkflowEnvironment(workspace.Manifests))); + } + + private static string[] Commands(DomainWorkspace workspace, string service) + { + return [.. workspace.Services.Single(s => s.Name == service).Manifest.Aggregates + .SelectMany(a => a.Commands) + .Select(c => $"{c.Type}: emits {Join(c.Emits)}; rejects {Join(c.Rejects)}") + .Order(StringComparer.Ordinal)]; + + static string Join(IReadOnlyList values) => values.Count == 0 ? "none" : string.Join(", ", values.Order(StringComparer.Ordinal)); + } +} diff --git a/tests/Workflows/SourceFlow.Studio.Tests/WorkflowDslTests.cs b/tests/Workflows/SourceFlow.Studio.Tests/WorkflowDslTests.cs new file mode 100644 index 00000000..52e2d96f --- /dev/null +++ b/tests/Workflows/SourceFlow.Studio.Tests/WorkflowDslTests.cs @@ -0,0 +1,562 @@ +using SourceFlow.Studio.Dsl; +using SourceFlow.Studio.Dsl.Diagnostics; +using SourceFlow.Studio.Dsl.Expressions; +using SourceFlow.Studio.Dsl.Manifests; +using SourceFlow.Studio.Dsl.Model; +using SourceFlow.Studio.Dsl.Reading; +using SourceFlow.Studio.Dsl.Validation; + +namespace SourceFlow.Studio.Tests; + +/// UT-WF-01..40 (plan 10 §3.1): the DSL reader, guards and the validation rules WF-V01…V16. +[Trait("Category", "Unit")] +public sealed class WorkflowDslTests +{ + private static WorkflowDefinition Example => WorkflowReader.Read(Golden.Workflow("01-order-fulfilment")).Workflow!; + + // ================================================================ reader (UT-WF-01..11) + + [Fact] + [Trait("Id", "UT-WF-01")] + [Trait("Covers", "WFD-20")] + public void Reader_ReadsEveryElementOfTheDocExample() + { + ReadResult read = WorkflowReader.Read(Golden.Workflow("01-order-fulfilment")); + read.Diagnostics.ShouldBeEmpty(); + WorkflowDefinition w = read.Workflow!; + + (w.SchemaVersion, w.Name, w.Version, w.Owner, w.ProcessName).ShouldBe((1, "order-fulfilment", 1, "orders", "order-fulfilment@1")); + w.Description.ShouldBe("Reserve stock, take payment, ship."); + (w.Start.On, w.Start.Correlate, w.Start.When).ShouldBe(("orders.order-placed.v1", "data.orderId", null)); + w.Data.Select(d => (d.Name, d.From)).ShouldBe([("orderId", "start.data.orderId"), ("amount", "start.data.total"), ("lines", "start.data.lines")]); + w.Steps.Select(s => s.Id).ShouldBe(["reserve-stock", "charge-payment", "review-large-order", "create-shipment", "await-address-fix"]); + w.PivotIndex.ShouldBe(3); + + WorkflowStep reserve = w.Steps[0]; + reserve.Send!.Command.ShouldBe("inventory.reserve-stock.v1"); + reserve.Send.Map.Select(m => (m.Field, m.Value.Kind, m.Value.Text)).ShouldBe([("orderId", MapValueKind.Path, "$data.orderId"), ("lines", MapValueKind.Path, "$data.lines")]); + reserve.Await!.Success.On.ShouldBe("inventory.stock-reserved.v1"); + reserve.Await.Failures.Single().Rejected.ShouldBe("inventory.out_of_stock"); + reserve.Await.Failures.Single().Then.Kind.ShouldBe(ThenKind.Fail); + reserve.Timeout!.After.ShouldBe(TimeSpan.FromMinutes(5)); + reserve.Timeout.Retry!.Max.ShouldBe(2); + reserve.Compensate!.Send!.Command.ShouldBe("inventory.release-stock.v1"); + reserve.Compensate.Retry!.Backoff.ShouldBe(Backoff.Exponential); + reserve.Compensate.Retry.Cap.ShouldBe(TimeSpan.FromMinutes(10)); + reserve.Compensate.Timeout!.After.ShouldBe(TimeSpan.FromMinutes(15)); + + WorkflowStep charge = w.Steps[1]; + charge.Await!.Success.Capture.Single().ShouldSatisfyAllConditions(c => c.Field.ShouldBe("paymentId"), c => c.Path.ShouldBe("event.data.paymentId")); + charge.Await.Failures[0].Retry!.Initial.ShouldBe(TimeSpan.FromMinutes(10)); + charge.Await.Failures[1].Rejected.ShouldBe("payments.fraud_suspected"); + + w.Steps[2].When.ShouldBe("$data.amount > 5000"); + w.Steps[2].Await!.Failures.Single().On.ShouldBe("orders.order-rejected-by-review.v1"); + w.Steps[2].Timeout!.Then.Kind.ShouldBe(ThenKind.Manual); + w.Steps[3].Pivot.ShouldBeTrue(); + w.Steps[3].Await!.Failures.Single().Then.ShouldSatisfyAllConditions(t => t.Kind.ShouldBe(ThenKind.Goto), t => t.Target.ShouldBe("await-address-fix")); + w.Steps[3].Next.ShouldBe(WorkflowStep.CompleteKeyword); + w.Steps[4].Next.ShouldBe("create-shipment"); + w.On.Completed!.Command.ShouldBe("orders.mark-fulfilled.v1"); + w.On.Compensated!.Map.Single(m => m.Field == "reason").Value.Text.ShouldBe("$failure.code"); + w.On.ManualAlert.ShouldBeTrue(); + } + + [Theory] + [Trait("Id", "UT-WF-02")] + [InlineData("PT30S", 30)] + [InlineData("PT5M", 300)] + [InlineData("PT1H", 3600)] + [InlineData("P1D", 86400)] + [InlineData("P1DT2H3M4S", 93784)] + [InlineData("P2W", 1209600)] + [InlineData("PT0.5S", 0.5)] + public void Durations_AreIso8601_AndRoundTrip(string text, double seconds) + { + IsoDuration.TryParse(text, out TimeSpan duration).ShouldBeTrue(); + duration.ShouldBe(TimeSpan.FromSeconds(seconds)); + IsoDuration.TryParse(IsoDuration.Format(duration), out TimeSpan again).ShouldBeTrue(); + again.ShouldBe(duration); + IsoDuration.Format(TimeSpan.Zero).ShouldBe("PT0S"); + Should.Throw(() => IsoDuration.Format(TimeSpan.FromSeconds(-1))); + } + + [Theory] + [Trait("Id", "UT-WF-02")] + [InlineData("P1Y")] + [InlineData("P1M")] + [InlineData("PT")] + [InlineData("PT1M2H")] + [InlineData("P1.5D")] + [InlineData("PTT1M")] + [InlineData("1H")] + [InlineData("")] + [InlineData(null)] + public void Durations_RejectUnsupportedForms(string? text) + { + IsoDuration.TryParse(text, out _).ShouldBeFalse(); + } + + [Fact] + [Trait("Id", "UT-WF-03")] + [Trait("Covers", "WFD-28")] + public void Reader_KeepsSourcePositions() + { + WorkflowDefinition w = Example; + + w.At("owner").ShouldBe(new SourceLocation(4, 8)); + w.Start.At("on").ShouldBe(new SourceLocation(8, 7)); + w.Steps[1].Location.Line.ShouldBe(30); + w.Steps[1].Send!.At("command").ShouldBe(new SourceLocation(31, 23)); + w.Steps[1].Send!.Map[1].At("value").Line.ShouldBe(31); + w.Steps[3].At("pivot").ShouldBe(new SourceLocation(59, 12)); + w.Steps[3].At("missing").ShouldBe(w.Steps[3].Location); + SourceLocation.None.Line.ShouldBe(0); + new SourceLocation(2, 3).ToString().ShouldBe("(2,3)"); + } + + [Fact] + [Trait("Id", "UT-WF-04")] + [Trait("Covers", "WFD-20")] + public void Reader_ReportsEveryUnknownKey_AndKeepsReading() + { + ReadResult read = WorkflowReader.Read(Golden.Workflow("04-s02-unknown-keys")); + + read.Diagnostics.Select(d => (d.Id, d.Location.Line)).ShouldBe([(WorkflowRules.UnknownKey, 5), (WorkflowRules.UnknownKey, 14)]); + read.Diagnostics[1].Message.ShouldContain("'retries'"); + read.Workflow!.Steps.Single().Id.ShouldBe("approve"); + read.HasErrors.ShouldBeTrue(); + } + + [Theory] + [Trait("Id", "UT-WF-05")] + [InlineData(2, "Update SourceFlow Studio")] + [InlineData(0, "version 1 is the first DSL version")] + public void Reader_SchemaVersionMismatch_GivesAMigrationHint(int version, string hint) + { + ReadResult read = WorkflowReader.Read(Golden.Workflow("02-minimal").Replace("sourceflow.workflow: 1", "sourceflow.workflow: " + version, StringComparison.Ordinal)); + + read.Diagnostics.Single().ShouldSatisfyAllConditions(d => d.Id.ShouldBe(WorkflowRules.SchemaVersion), d => d.Message.ShouldContain(hint)); + } + + [Fact] + [Trait("Id", "UT-WF-06")] + public void Reader_TypesScalars_AndMapValues() + { + const string Yaml = """ + sourceflow.workflow: 1 + name: typed + version: 1 + owner: orders + start: { on: orders.order-placed.v1, correlate: data.orderId } + data: + count: { type: integer, default: 3 } + ratio: { type: number, default: 1.5 } + flag: { type: boolean, default: true } + label: { type: string, default: '42' } + none: { type: string, default: ~ } + steps: + - id: one + send: + command: orders.note-audit.v1 + map: { note: "text", n: 7, d: -2.25, b: false, z: null, q: '$data.count', p: $data.count, h: { $hook: Compute } } + await: { success: orders.audit-noted.v1 } + timeout: { after: PT1M, then: manual } + """; + + WorkflowDefinition w = WorkflowReader.Read(Yaml).Workflow!; + + w.Data.Select(d => d.Default!.Kind).ShouldBe([ScalarKind.Integer, ScalarKind.Number, ScalarKind.Boolean, ScalarKind.String, ScalarKind.Null]); + w.Data[3].Default!.ToString().ShouldBe("'42'"); + w.Data[4].Default!.ToString().ShouldBe("null"); + IReadOnlyList map = w.Steps[0].Send!.Map; + map.Select(m => m.Value.Kind).ShouldBe([MapValueKind.Literal, MapValueKind.Literal, MapValueKind.Literal, MapValueKind.Literal, MapValueKind.Literal, MapValueKind.Literal, MapValueKind.Path, MapValueKind.Hook]); + map.Take(6).Select(m => m.Value.Literal!.Kind).ShouldBe([ScalarKind.String, ScalarKind.Integer, ScalarKind.Number, ScalarKind.Boolean, ScalarKind.Null, ScalarKind.String]); + map[2].Value.Literal!.Text.ShouldBe("-2.25"); + map[5].Value.Literal!.Text.ShouldBe("$data.count", "quoted: a literal, not a path"); + map[7].Value.Text.ShouldBe("Compute"); + map[5].Value.Literal!.ShouldBe(WorkflowReader.Read(Yaml).Workflow!.Steps[0].Send!.Map[5].Value.Literal, "values compare by kind and text"); + map[5].Value.Literal!.ShouldNotBe(map[0].Value.Literal); + } + + [Fact] + [Trait("Id", "UT-WF-07")] + public void Reader_ReadsThenTimeoutAndCompensateForms() + { + WorkflowDefinition local = WorkflowReader.Read(Golden.Workflow("27-local-steps")).Workflow!; + local.Steps[0].Timeout!.ShouldSatisfyAllConditions(t => t.None.ShouldBeTrue(), t => t.Reason.ShouldBe("the order service always answers"), t => t.After.ShouldBeNull()); + local.Steps[0].Compensate!.ShouldSatisfyAllConditions(c => c.None.ShouldBeTrue(), c => c.Reason.ShouldBe("a rejection is final")); + local.Steps[1].Await!.Failures.Single().Then.Kind.ShouldBe(ThenKind.Complete); + + WorkflowDefinition retries = WorkflowReader.Read(Golden.Workflow("28-retries-and-backoff")).Workflow!; + RetrySpec retry = retries.Steps[0].Timeout!.Retry!; + (retry.Max, retry.Backoff, retry.Initial, retry.Cap, retry.Jitter).ShouldBe((20, Backoff.Exponential, TimeSpan.FromSeconds(1), (TimeSpan?)TimeSpan.FromHours(1), false)); + retry.Delay(1).ShouldBe(TimeSpan.FromSeconds(1)); + retry.Delay(4).ShouldBe(TimeSpan.FromSeconds(8)); + retry.Delay(20).ShouldBe(TimeSpan.FromHours(1), "capped"); + retries.Steps[0].Timeout!.Then.ShouldSatisfyAllConditions(t => t.Kind.ShouldBe(ThenKind.Goto), t => t.ToString().ShouldBe("goto approve")); + + ReadResult scalars = WorkflowReader.Read(Golden.Workflow("02-minimal").Replace("timeout: { after: PT1H, then: manual }", "timeout: none\n compensate: none", StringComparison.Ordinal)); + scalars.Workflow!.Steps[0].Timeout!.None.ShouldBeTrue(); + scalars.Workflow.Steps[0].Compensate!.None.ShouldBeTrue(); + } + + [Theory] + [Trait("Id", "UT-WF-08")] + [InlineData("a: [1", 2)] + [InlineData("- just\n- a list\n", 1)] + [InlineData("sourceflow.workflow: 1\n---\nsourceflow.workflow: 1\n", 1)] + [InlineData("sourceflow.workflow: 1\nname: x\nname: y\n", 3)] + public void Reader_InvalidYaml_IsReportedWithAPosition(string yaml, int line) + { + ReadResult read = WorkflowReader.Read(yaml); + + read.Workflow.ShouldBeNull(); + read.Diagnostics.Single().ShouldSatisfyAllConditions(d => d.Id.ShouldBe(WorkflowRules.Syntax), d => d.Location.Line.ShouldBe(line)); + Should.Throw(() => WorkflowReader.Read(null!)); + } + + [Fact] + [Trait("Id", "UT-WF-09")] + public void Reader_RejectsAnchorsAndAliases() + { + ReadResult read = WorkflowReader.Read(Golden.Workflow("29-s01-anchors")); + + read.Diagnostics.Single().ShouldSatisfyAllConditions(d => d.Id.ShouldBe(WorkflowRules.Syntax), d => d.Message.ShouldContain("Anchors and aliases")); + read.Workflow.ShouldNotBeNull(); + } + + [Theory] + [Trait("Id", "UT-WF-10")] + [InlineData(" await: { success: orders.order-approved.v1 }", " await: { success: orders.order-approved.v1, failure: [ { rejected: x.y, on: orders.order-approved.v1 } ] }", "either 'rejected")] + [InlineData(" orderId: { from: start.data.orderId }", " orderId: { from: start.data.orderId, type: uuid }", "'type' and 'default' are for fields without one")] + [InlineData(" orderId: { from: start.data.orderId }", " orderId: { personal: true }", "needs 'from' or 'type'")] + [InlineData(" orderId: { from: start.data.orderId }", " orderId: { type: money }", "Unknown data type 'money'")] + [InlineData(" timeout: { after: PT1H, then: manual }", " timeout: { after: PT1H, none: true, then: manual }", "'after' or 'none: true', not both")] + [InlineData(" timeout: { after: PT1H, then: manual }", " timeout: { then: manual }", "needs 'after'")] + [InlineData(" timeout: { after: PT1H, then: manual }", " timeout: { after: PT1H, retry: { backoff: linear }, then: manual }", "needs 'max'")] + [InlineData(" timeout: { after: PT1H, then: manual }", " timeout: { after: PT1H, retry: { max: 1, backoff: linear }, then: manual }", "'fixed' or 'exponential'")] + [InlineData("steps:\n", "steps: []\nignored:\n", "lists no step")] + [InlineData(" send: { command: orders.approve-order.v1, map: { orderId: $data.orderId } }", " send: { command: orders.approve-order.v1, map: { orderId: [1, 2] } }", "a path ($data.x")] + public void Reader_ReportsShapeErrors(string find, string replace, string expected) + { + string yaml = Golden.Workflow("02-minimal").Replace(find, replace, StringComparison.Ordinal); + if (find == "steps:\n") + { + yaml = yaml[..yaml.IndexOf("steps:", StringComparison.Ordinal)] + "steps: []\n"; + } + + WorkflowReader.Read(yaml).Diagnostics.ShouldContain(d => (d.Id == WorkflowRules.Shape || d.Id == WorkflowRules.UnknownKey) && d.Message.Contains(expected), string.Join("; ", WorkflowReader.Read(yaml).Diagnostics)); + } + + [Theory] + [Trait("Id", "UT-WF-11")] + [InlineData(" - id: approve", " - id: complete", "'complete' is reserved")] + [InlineData("correlate: data.orderId", "correlate: orderId", "path into the start message")] + [InlineData(" orderId: { from: start.data.orderId }", " orderId: { from: data.orderId }", "path into the start message")] + [InlineData(" orderId: { from: start.data.orderId }", " order-id: { from: start.data.orderId }", "is not an identifier")] + [InlineData("orderId: $data.orderId", "orderId: $data.order-id", "is not a valid path")] + [InlineData("orderId: $data.orderId", "orderId: { $hook: compute }", "PascalCase")] + [InlineData("owner: orders", "owner: Orders", "is not a service name")] + public void Reader_ReportsFormatErrors(string find, string replace, string expected) + { + WorkflowReader.Read(Golden.Workflow("02-minimal").Replace(find, replace, StringComparison.Ordinal)).Diagnostics + .ShouldContain(d => d.Id == WorkflowRules.Format && d.Message.Contains(expected)); + } + + // ================================================================ guards (UT-WF-13..15) + + [Theory] + [Trait("Id", "UT-WF-13")] + [Trait("Covers", "WFD-26")] + [InlineData("$data.amount > 5000")] + [InlineData("(event.data.total >= 1.5 OR NOT $data.flag) and $data.name like 'a%'")] + [InlineData("$data.code NOT IN ('x', 'y') AND EXISTS $data.reviewer")] + [InlineData("-$data.amount + 2 * 3 / 4 % 5 < 0 or $data.name <> \"it's\"")] + [InlineData("$data.name = 'it''s' AND $data.x != null AND TRUE")] + public void Guards_Parse(string text) + { + GuardParseResult parsed = GuardParser.Parse(text); + + parsed.Error.ShouldBeNull(); + parsed.Expression.ShouldNotBeNull(); + } + + [Theory] + [Trait("Id", "UT-WF-13")] + [InlineData("$data.amount >", "ends early", 14)] + [InlineData("$data.amount > 1)", "unexpected ')'", 16)] + [InlineData("amount > 1", "unknown name 'amount'", 0)] + [InlineData("$data > 1", "is not a path", 0)] + [InlineData("$data.a = 'open", "unterminated string", 10)] + [InlineData("$data.a NOT 1", "expected LIKE or IN", 12)] + [InlineData("$data.a IN 1", "expected '('", 11)] + [InlineData("$data.a # 1", "unexpected character '#'", 8)] + [InlineData("EXISTS 1", "EXISTS needs a path", 7)] + [InlineData("1.2.3 = 1", "is not a number", 0)] + public void Guards_ReportParseErrors(string text, string expected, int position) + { + GuardParseResult parsed = GuardParser.Parse(text); + + parsed.Expression.ShouldBeNull(); + parsed.Error!.ShouldContain(expected); + parsed.ErrorPosition.ShouldBe(position); + } + + [Theory] + [Trait("Id", "UT-WF-14")] + [InlineData("$data.amount > 5000", null)] + [InlineData("$data.id = 'abc' AND $data.at < '2026-01-01'", null)] + [InlineData("$data.flag", null)] + [InlineData("$data.amount", "not true or false")] + [InlineData("$data.amount > 'big'", "compares a number with text")] + [InlineData("$data.flag AND $data.amount", "'AND' needs true/false")] + [InlineData("$data.name LIKE 1", "'LIKE' needs text")] + [InlineData("$data.name + 1 > 2", "'+' needs a number")] + [InlineData("$data.flag < true", "doesn't order true and false")] + [InlineData("$data.items = $data.items", "can't compare array values")] + [InlineData("$data.amount IN (1, 'x')", "compares a number with text")] + [InlineData("NOT $data.amount", "'NOT' needs true/false")] + [InlineData("-$data.name > 1", "'-' needs a number")] + [InlineData("$data.missing = 1", "'$data.missing' is not in scope here ($data.*)")] + public void Guards_BindAgainstTypes(string text, string? error) + { + var types = new Dictionary + { + ["$data.amount"] = "number", ["$data.id"] = "uuid", ["$data.at"] = "date-time", ["$data.flag"] = "boolean", + ["$data.name"] = "string", ["$data.items"] = "array", + }; + + string? result = GuardBinder.Bind(GuardParser.Parse(text).Expression!, p => types.GetValueOrDefault(p), "$data.*"); + + if (error is null) + { + result.ShouldBeNull(); + } + else + { + result.ShouldNotBeNull().ShouldContain(error); + } + } + + [Theory] + [Trait("Id", "UT-WF-15")] + [InlineData("$data.amount > 5000", true)] + [InlineData("$data.amount > 9000", false)] + [InlineData("$data.amount / 0 > 1", false)] + [InlineData("$data.amount % 7 = 0 AND -$data.amount < 0", true)] + [InlineData("$data.missing > 1", false)] + [InlineData("$data.missing = null", true)] + [InlineData("$data.missing != 1", false)] + [InlineData("NOT ($data.missing > 1)", false)] + [InlineData("NOT ($data.name = null) AND $data.missing = null AND ($data.missing != null) = false", true)] + [InlineData("$data.missing > 1 OR $data.amount > 1", true)] + [InlineData("$data.missing > 1 AND $data.amount > 1", false)] + [InlineData("NOT ($data.missing > 1 OR $data.amount < 1)", false)] + [InlineData("$data.missing IN (1)", false)] + [InlineData("EXISTS $data.missing", false)] + [InlineData("EXISTS $data.name", true)] + [InlineData("$data.name LIKE 'Ad_%' AND $data.name NOT LIKE '%z'", true)] + [InlineData("$data.name LIKE 'Ada' AND 'a%b' LIKE 'a\\%b'", true)] + [InlineData("$data.code IN ('x', 'y') AND $data.code NOT IN ('z')", true)] + [InlineData("$data.flag = true OR $data.flag = false", true)] + [InlineData("$data.flag > false", true)] + [InlineData("$data.count = 7 AND $data.ratio < 0.6 AND $data.id = '7d6f0f8a-1b2c-4d3e-8f9a-0b1c2d3e4f5a'", true)] + [InlineData("$data.amount - 1 * 2 + 1 = 7000 - 1", true)] + [InlineData("$data.name < $data.code", true)] + [InlineData("$data.amount = 'x'", false)] + public void Guards_Evaluate_WithCesqlNullSemantics(string text, bool expected) + { + var values = new Dictionary + { + ["$data.amount"] = 7000m, ["$data.name"] = "Ada", ["$data.code"] = "x", ["$data.flag"] = true, ["$data.count"] = 7, + ["$data.ratio"] = 0.5, ["$data.id"] = Guid.Parse("7d6f0f8a-1b2c-4d3e-8f9a-0b1c2d3e4f5a"), + }; + + GuardEvaluator.Evaluate(GuardParser.Parse(text).Expression!, p => values.GetValueOrDefault(p)).ShouldBe(expected); + } + + // ================================================================ rules (UT-WF-16..31: one negative and the positive per rule) + + [Theory] + [Trait("Id", "UT-WF-16..31")] + [Trait("Covers", "WFD-28")] + [InlineData("WF-V01", "09-v01-unknown-type", 2)] + [InlineData("WF-V02", "10-v02-command-owner", 3)] + [InlineData("WF-V03", "11-v03-unreachable-event", 2)] + [InlineData("WF-V04", "12-v04-correlation", 2)] + [InlineData("WF-V05", "13-v05-unreachable-step", 1)] + [InlineData("WF-V06", "15-v06-timeouts", 3)] + [InlineData("WF-V07", "16-v07-pivot", 4)] + [InlineData("WF-V08", "17-v08-rejections", 4)] + [InlineData("WF-V09", "18-v09-compensation", 2)] + [InlineData("WF-V10", "19-v10-retries", 4)] + [InlineData("WF-V11", "20-v11-goto", 2)] + [InlineData("WF-V12", "21-v12-map", 6)] + [InlineData("WF-V13", "22-v13-guards", 3)] + [InlineData("WF-V14", "23-v14-personal-data", 2)] + [InlineData("WF-V15", "24-v15-published-version", 1)] + [InlineData("WF-V16", "25-v16-nested-compensation", 2)] + public void EveryRule_HasAPositiveAndANegativeCase(string rule, string negative, int count) + { + foreach (string positive in new[] { "01-order-fulfilment", "02-minimal", "26-guards-and-hooks", "27-local-steps", "28-retries-and-backoff" }) + { + WorkflowAnalysis.Analyze(Golden.Workflow(positive), Golden.Environment).Diagnostics.ShouldNotContain(d => d.Id == rule, positive); + } + + WorkflowAnalysisResult result = WorkflowAnalysis.Analyze(Golden.Workflow(negative), Golden.Environment); + result.Diagnostics.Count(d => d.Id == rule).ShouldBe(count, string.Join("\n", result.Diagnostics)); + result.Diagnostics.Where(d => d.Id == rule).ShouldAllBe(d => d.Severity == WorkflowRules.SeverityOf(rule) && d.Location.Line > 0); + } + + [Fact] + [Trait("Id", "UT-WF-32")] + public void PivotAndCompensation_Combined() + { + WorkflowAnalysisResult result = WorkflowAnalysis.Analyze(Golden.Workflow("16-v07-pivot"), Golden.Environment); + + result.Diagnostics.Where(d => d.Id == WorkflowRules.Pivot).Select(d => d.Message).ShouldBe( + [ + "Step 'create-shipment' is at or after the pivot, so a failure can't 'fail' (no compensation after the point of no return); use manual, complete or goto.", + "Step 'create-shipment' is at or after the pivot, so it can't be compensated; recover forward instead.", + "Step 'await-address-fix' is at or after the pivot, so its timeout can't 'fail' (no compensation after the point of no return); use manual or goto.", + "A workflow has one pivot; 'create-shipment' is already the pivot.", + ]); + result.Diagnostics.ShouldNotContain(d => d.Id == WorkflowRules.MissingCompensation, "steps after the pivot need no compensation"); + } + + [Fact] + [Trait("Id", "UT-WF-33")] + public void NestedGotoLoops_WithWaits_AreValid() + { + string yaml = Golden.Workflow("02-minimal").Replace(" timeout: { after: PT1H, then: manual }\n", """ + timeout: { after: PT1H, then: { goto: second } } + - id: second + send: { command: orders.approve-order.v1, map: { orderId: $data.orderId } } + await: + success: orders.order-approved.v1 + failure: + - on: orders.order-rejected-by-review.v1 + then: { goto: approve } + timeout: { after: PT1H, then: { goto: second } } + next: complete + + """, StringComparison.Ordinal); + + WorkflowAnalysis.Analyze(yaml, Golden.Environment).Diagnostics.ShouldBeEmpty(); + } + + [Fact] + [Trait("Id", "UT-WF-34")] + public void GuardBindingErrors_InEveryScope() + { + WorkflowAnalysisResult result = WorkflowAnalysis.Analyze(Golden.Workflow("22-v13-guards"), Golden.Environment); + + string[] messages = [.. result.Diagnostics.Where(d => d.Id == WorkflowRules.Guard).Select(d => d.Message)]; + messages[0].ShouldContain("doesn't parse"); // start.when + messages[1].ShouldContain("'event.data.sku' is not in scope"); // await.success.when + messages[2].ShouldContain("compares a number with text"); // step.when + } + + [Fact] + [Trait("Id", "UT-WF-35")] + [Trait("Covers", "WFD-29")] + public void PartialMode_SkipsRulesNeedingUnknownServices() + { + // Compile time: only the owner's static manifest (no service name, no routes). + ServiceManifest owner = ServiceManifest.Parse(File.ReadAllText(Path.Combine(Golden.Root, "domain", "orders.manifest.json")) + .Replace("\"service\": \"orders\"", "\"assembly\": \"Orders\"", StringComparison.Ordinal) + .Replace("\"endpoint\": \"orders\",", string.Empty, StringComparison.Ordinal)); + var environment = new WorkflowEnvironment([owner], compilingService: "orders", partial: true); + + WorkflowAnalysisResult result = WorkflowAnalysis.Analyze(Golden.Workflow("01-order-fulfilment"), environment); + + result.Diagnostics.ShouldBeEmpty(string.Join("\n", result.Diagnostics)); + WorkflowAnalysis.Analyze(Golden.Workflow("09-v01-unknown-type"), environment).Diagnostics.Count(d => d.Id == WorkflowRules.UnknownType).ShouldBe(2, "unknown types are still errors"); + WorkflowAnalysis.Analyze(Golden.Workflow("09-v01-unknown-type"), environment).Diagnostics.First(d => d.Id == WorkflowRules.UnknownType).Message.ShouldContain("contract package"); + } + + [Fact] + [Trait("Id", "UT-WF-36")] + public void Owner_MustBeTheCompilingService_AndAWorkspaceService() + { + var compiled = new WorkflowEnvironment(Golden.Environment.Manifests, compilingService: "payments"); + WorkflowAnalysis.Analyze(Golden.Workflow("02-minimal"), compiled).Diagnostics + .ShouldContain(d => d.Id == WorkflowRules.CommandOwner && d.Message.Contains("compiled by 'payments'")); + + WorkflowAnalysis.Analyze(Golden.Workflow("02-minimal").Replace("owner: orders", "owner: billing", StringComparison.Ordinal), Golden.Environment).Diagnostics + .ShouldContain(d => d.Id == WorkflowRules.CommandOwner && d.Message.Contains("'billing' is not a service of the workspace")); + } + + [Fact] + [Trait("Id", "UT-WF-37")] + public void DuplicateNameAndVersion_InTheOwner_IsAnError() + { + WorkflowDefinition first = WorkflowReader.Read(Golden.Workflow("02-minimal")).Workflow!; + WorkflowDefinition second = WorkflowReader.Read(Golden.Workflow("02-minimal").Replace("id: approve", "id: approve-again", StringComparison.Ordinal)).Workflow!; + WorkflowDefinition other = WorkflowReader.Read(Golden.Workflow("02-minimal").Replace("version: 1", "version: 2", StringComparison.Ordinal)).Workflow!; + var environment = new WorkflowEnvironment(Golden.Environment.Manifests, siblings: [first, second, other]); + + WorkflowValidator.Validate(first, environment).ShouldContain(d => d.Id == WorkflowRules.Version && d.Message == "approve-order@1 is declared twice in orders."); + WorkflowValidator.Validate(other, environment).ShouldNotContain(d => d.Id == WorkflowRules.Version); + Should.Throw(() => WorkflowValidator.Validate(null!, environment)); + Should.Throw(() => WorkflowValidator.Validate(first, null!)); + } + + [Fact] + [Trait("Id", "UT-WF-38")] + [Trait("Covers", "WFD-35")] + public void Fingerprint_IgnoresLayoutAndComments_ButNotStructure() + { + string text = Golden.Workflow("01-order-fulfilment"); + string fingerprint = WorkflowFingerprint.Compute(WorkflowReader.Read(text).Workflow!); + + fingerprint.ShouldStartWith("sha256:"); + fingerprint.Length.ShouldBe(23); + string relaid = text.Replace("# point of no return", "# the point of no return", StringComparison.Ordinal) + .Replace("description: Reserve stock, take payment, ship.", "description: Something else.", StringComparison.Ordinal) + .Replace("map: { orderId: $data.orderId, amount: $data.amount }", "map: { amount: $data.amount, orderId: $data.orderId }", StringComparison.Ordinal); + WorkflowFingerprint.Compute(WorkflowReader.Read(relaid).Workflow!).ShouldBe(fingerprint); + WorkflowFingerprint.Compute(WorkflowReader.Read(text.Replace("after: PT2M", "after: PT3M", StringComparison.Ordinal)).Workflow!).ShouldNotBe(fingerprint); + WorkflowFingerprint.Compute(WorkflowReader.Read(text.Replace("max: 3, backoff: fixed", "max: 4, backoff: fixed", StringComparison.Ordinal)).Workflow!).ShouldNotBe(fingerprint); + + // Published with this fingerprint: no WF-V15. + WorkflowDefinition w = WorkflowReader.Read(Golden.Workflow("24-v15-published-version")).Workflow!; + ServiceManifest orders = ServiceManifest.Parse(File.ReadAllText(Path.Combine(Golden.Root, "domain", "orders.manifest.json")) + .Replace("sha256:0000000000000000", WorkflowFingerprint.Compute(w), StringComparison.Ordinal)); + var environment = new WorkflowEnvironment(Golden.Environment.Manifests.Where(m => m.Service != "orders").Append(orders)); + WorkflowValidator.Validate(w, environment).ShouldNotContain(d => d.Id == WorkflowRules.Version); + } + + [Fact] + [Trait("Id", "UT-WF-39")] + public void RuleIds_AreStable_AndSeveritiesMatchTheDoc() + { + WorkflowRules.All.Count.ShouldBe(24); + WorkflowRules.All.Distinct().Count().ShouldBe(24); + WorkflowRules.All.Where(id => WorkflowRules.SeverityOf(id) == WorkflowSeverity.Warning).ShouldBe(["WF-V09", "WF-V14", "WF-V18"]); + Enumerable.Range(1, 18).Select(i => $"WF-V{i:00}").ShouldAllBe(id => WorkflowRules.All.Contains(id)); + + var diagnostic = new WorkflowDiagnostic("WF-V06", WorkflowSeverity.Error, "message", new SourceLocation(3, 4)); + diagnostic.ToString().ShouldBe("(3,4): error WF-V06: message"); + diagnostic.ShouldBe(new WorkflowDiagnostic("WF-V06", WorkflowSeverity.Error, "message", new SourceLocation(3, 4))); + new WorkflowDiagnostic("WF-V09", WorkflowSeverity.Warning, "m", SourceLocation.None).ToString().ShouldContain("warning"); + } + + [Fact] + [Trait("Id", "UT-WF-40")] + public void Analysis_SortsAndDeduplicates_AndStopsAtUnreadableYaml() + { + WorkflowAnalysisResult result = WorkflowAnalysis.Analyze(Golden.Workflow("21-v12-map"), Golden.Environment); + + result.Diagnostics.Select(d => (d.Location.Line, d.Location.Column)).ShouldBeInOrder(); + result.Diagnostics.Distinct().Count().ShouldBe(result.Diagnostics.Count); + result.HasErrors.ShouldBeTrue(); + + WorkflowAnalysisResult broken = WorkflowAnalysis.Analyze("a: [", Golden.Environment); + broken.Workflow.ShouldBeNull(); + broken.Diagnostics.Single().Id.ShouldBe(WorkflowRules.Syntax); + WorkflowAnalysis.Analyze(Golden.Workflow("01-order-fulfilment"), Golden.Environment).HasErrors.ShouldBeFalse(); + Should.Throw(() => WorkflowAnalysis.Analyze("x: 1", null!)); + } +} diff --git a/tests/Workflows/SourceFlow.Studio.Tests/WorkflowOperationsTests.cs b/tests/Workflows/SourceFlow.Studio.Tests/WorkflowOperationsTests.cs new file mode 100644 index 00000000..ec668adf --- /dev/null +++ b/tests/Workflows/SourceFlow.Studio.Tests/WorkflowOperationsTests.cs @@ -0,0 +1,522 @@ +using System.Collections.Concurrent; +using System.Diagnostics; +using System.Diagnostics.Metrics; +using System.Text.Json.Nodes; +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.Time.Testing; +using SourceFlow.Diagnostics; +using SourceFlow.Messaging; +using SourceFlow.Query; +using SourceFlow.Storage; +using SourceFlow.Storage.InMemory; +using SourceFlow.Studio.Dsl.Json; +using SourceFlow.Studio.Dsl.Model; +using SourceFlow.Studio.Dsl.Reading; +using SourceFlow.Studio.Dsl.Simulation; +using SourceFlow.Studio.Tests.Fixture; +using SourceFlow.Testing; +using SourceFlow.Tool; +using SourceFlow.Workflows; +using SimStatus = SourceFlow.Studio.Dsl.Simulation.WorkflowStatus; + +namespace SourceFlow.Studio.Tests; + +/// +/// Runtime support for DSL workflows (WP-S.6, doc 15 §5.6, §7): transition metrics and spans, the workflow-instances read +/// model with its gauge and domain query, the version-removal guard, the operator CLI, and the order-fulfilment paths +/// WF-E2E-09 (forward recovery after the pivot) and WF-E2E-10 (versions side by side) in an in-memory host. +/// +[Trait("Category", "Unit")] +public sealed class WorkflowOperationsTests +{ + private const string Workflow = "order-fulfilment"; + private static readonly DateTimeOffset T0 = new(2026, 3, 1, 9, 0, 0, TimeSpan.Zero); + + private static readonly WorkflowDefinition Definition = WorkflowReader.Read(File.ReadAllText(Path.Combine(AppContext.BaseDirectory, "..", "..", "..", "Fixture", "order-fulfilment.sfflow.yaml"))).Workflow!; + + private static CancellationToken Ct => TestContext.Current.CancellationToken; + + // ================================================================ transitions (engine) + + [Fact] + [Trait("Id", "UT-WF-61")] + [Trait("Covers", "WFD-37")] + public void Engine_RecordsEachTransitionOnce_WithItsKind() + { + Kinds(Start(100m), Ok(), Ok(Captured()), Ok()).ShouldBe(["success", "success", "success", "complete"], "the review is skipped: no transition"); + Kinds(Start(100m), SimulationInput.Reject("inventory.out_of_stock")).ShouldBe(["failure"], "nothing to compensate"); + Kinds(Start(100m), SimulationInput.FireTimer()).ShouldBe(["timeout", "retry"]); + Kinds(Start(100m), Ok(), SimulationInput.Reject("payments.declined")).ShouldBe(["success", "retry"], "a business retry is not a failure"); + Kinds(Start(100m), Ok(), SimulationInput.Reject("payments.fraud_suspected"), Ok()).ShouldBe(["success", "failure", "compensate"]); + Kinds(Start(6000m), Ok(), Ok(Captured()), SimulationInput.FireTimer()).ShouldBe(["success", "success", "timeout", "failure", "manual"]); + + SimulationTransition.Kinds.ShouldBe(WorkflowTransition.Kinds, "the engine and the runtime agree on the kind tag values"); + } + + // ================================================================ metrics and spans (host) + + [Fact] + [Trait("Id", "UT-WF-62")] + [Trait("Covers", "WFD-37")] + public async Task Host_CountsTransitions_OncePerCommittedTransition_WithLowCardinalityTags() + { + await using SourceFlowTestHost host = await Host>(); + using var metrics = new Metrics(host); + var order = OrderId.New(); + + await host.SendAsync(new PlaceOrder(order, 120m, ["sku-1"], "a@b.c", Priority: false), cancellationToken: Ct); + await host.WaitForIdleAsync(); + + metrics.Counts(SourceFlowTelemetry.Instruments.WorkflowTransitions, SourceFlowTelemetry.Tags.TransitionKind) + .ShouldBe(new Dictionary { ["success"] = 3, ["complete"] = 1 }); + metrics.Measurements(SourceFlowTelemetry.Instruments.WorkflowTransitions).ShouldAllBe(m => + m.Tags.Count == 3 && (string)m.Tags["workflow"]! == Workflow && (string)m.Tags["version"]! == "1"); + metrics.Measurements(SourceFlowTelemetry.Instruments.WorkflowManualIntervention).ShouldBeEmpty(); + } + + [Fact] + [Trait("Id", "UT-WF-63")] + [Trait("Covers", "WFD-37")] + public async Task ManualIntervention_IsCountedOnce_AndAlertedOn() + { + var time = new FakeTimeProvider(T0); + await using SourceFlowTestHost host = await Host>(time); + using var metrics = new Metrics(host); + + OrderId order = await ToManualAsync(host, time); + + metrics.Measurements(SourceFlowTelemetry.Instruments.WorkflowManualIntervention).ShouldHaveSingleItem().Tags + .ShouldBe(new Dictionary { ["workflow"] = Workflow, ["version"] = "1" }, ignoreOrder: true); + (await Summary(host, order)).Status.ShouldBe("ManualIntervention"); + Observability.Alerts.ShouldContain(a => a.Name == "SourceFlowWorkflowManualIntervention" + && a.Expression.Contains("sourceflow_workflow_manual_intervention_total", StringComparison.Ordinal) && a.Severity == "page"); + } + + [Fact] + [Trait("Id", "UT-WF-70")] + [Trait("Covers", "WFD-37")] + public async Task Transitions_AreSpans_UnderTheReactSpan() + { + var spans = new ConcurrentQueue(); + using var listener = new ActivityListener + { + ShouldListenTo = s => s.Name == SourceFlowTelemetry.ActivitySourceName, + Sample = (ref ActivityCreationOptions _) => ActivitySamplingResult.AllDataAndRecorded, + ActivityStopped = spans.Enqueue, + }; + ActivitySource.AddActivityListener(listener); + await using SourceFlowTestHost host = await Host>(); + var order = OrderId.New(); + string instance = WorkflowInstanceId.From(order.ToString()).ToStreamSegment(); + + await host.SendAsync(new PlaceOrder(order, 120m, ["sku-1"], "a@b.c", Priority: false), cancellationToken: Ct); + await host.WaitForIdleAsync(); + + Activity[] mine = [.. spans.Where(s => s.DisplayName.StartsWith("workflow ", StringComparison.Ordinal) && (string?)s.Parent?.GetTagItem(SourceFlowTelemetry.Tags.ProcessId) == instance)]; + mine.Select(s => s.DisplayName).ShouldBe( + ["workflow order-fulfilment reserve-stock", "workflow order-fulfilment charge-payment", "workflow order-fulfilment create-shipment", "workflow order-fulfilment create-shipment"], + ignoreOrder: true); + Activity shipped = mine.First(s => (string?)s.GetTagItem(SourceFlowTelemetry.Tags.WorkflowTransition) == "complete"); + shipped.Parent!.DisplayName.ShouldBe("react order-fulfilment@1"); + shipped.GetTagItem(SourceFlowTelemetry.Tags.WorkflowStep).ShouldBe("create-shipment"); + shipped.GetTagItem(SourceFlowTelemetry.Tags.WorkflowAttempt).ShouldBe(1); + } + + // ================================================================ read model, gauge and domain query + + [Fact] + [Trait("Id", "UT-WF-64")] + [Trait("Covers", "WFD-37")] + public async Task InstanceDocument_FollowsTheInstance_AndFeedsTheActiveGauge() + { + var time = new FakeTimeProvider(T0); + await using SourceFlowTestHost host = await Host>(time, monitor: true); + using var metrics = new Metrics(host); + var done = OrderId.New(); + await host.SendAsync(new PlaceOrder(done, 120m, ["sku-1"], "a@b.c", Priority: false), cancellationToken: Ct); + OrderId stuck = await ToManualAsync(host, time); + + WorkflowInstanceSummary completed = await Summary(host, done); + completed.ShouldSatisfyAllConditions( + s => s.Status.ShouldBe("Completed"), + s => s.Step.ShouldBeNull(), + s => s.StartedAt.ShouldBe(T0), + s => s.IsActive.ShouldBeFalse()); + WorkflowInstanceSummary manual = await Summary(host, stuck); + manual.ShouldSatisfyAllConditions( + s => s.Step.ShouldBe("review-large-order"), + s => s.FailureCode.ShouldBe("timeout"), + s => s.PendingCompensations.ShouldBe(2, "reserve-stock and charge-payment would be undone"), + s => s.UpdatedAt.ShouldBeGreaterThan(s.StartedAt)); + + (await host.Store.CountActiveWorkflowsAsync(Ct)).ShouldBe([new WorkflowStatusCount(Workflow, 1, "ManualIntervention", 1)]); + (await metrics.GaugeAsync(SourceFlowTelemetry.Instruments.WorkflowActive, m => (string?)m.Tags.GetValueOrDefault("status") == "ManualIntervention")).ShouldHaveSingleItem().ShouldSatisfyAllConditions( + m => m.Value.ShouldBe(1), + m => m.Tags.ShouldBe(new Dictionary { ["workflow"] = Workflow, ["version"] = "1", ["status"] = "ManualIntervention" }, ignoreOrder: true)); + } + + [Fact] + [Trait("Id", "UT-WF-65")] + [Trait("Covers", "WFD-37")] + public async Task WorkflowInstancesQuery_BindsAtStartup_AndReturnsTheInstances() + { + await using SourceFlowTestHost host = await Host>(); + var order = OrderId.New(); + await host.SendAsync(new PlaceOrder(order, 120m, ["sku-1"], "a@b.c", Priority: false), cancellationToken: Ct); + await host.WaitForIdleAsync(); + + host.Runtime.Model.DomainQueries.ShouldContain(q => q.Name == "orders.workflow-instances" && q.Version == 1, "SF0018: checked against the catalog at startup"); + WorkflowInstancesQuery.QueryName.ShouldBe("orders.workflow-instances", "the workflows' owner names the service"); + IReadOnlyList rows = await host.Services.GetRequiredService().ExecuteAsync(new WorkflowInstancesQuery(Workflow), cancellationToken: Ct); + + rows.ShouldHaveSingleItem().ShouldSatisfyAllConditions( + r => r.Instance.ShouldBe(order.ToString()), + r => r.WorkflowVersion.ShouldBe(1), + r => r.Status.ShouldBe("Completed"), + r => r.ProcessName.ShouldBe("order-fulfilment@1")); + (await host.Services.GetRequiredService().ExecuteAsync(new WorkflowInstancesQuery("other"), cancellationToken: Ct)).ShouldBeEmpty(); + } + + // ================================================================ version guard + + [Fact] + [Trait("Id", "UT-WF-66")] + [Trait("Covers", "WFD-35")] + public async Task Startup_IsBlocked_WhileARemovedVersionHasActiveInstances() + { + var store = new InMemoryStore(TimeProvider.System); + await Seed(store, "order-fulfilment@2", "wf_01", completed: false); + await Seed(store, "order-fulfilment@2", "wf_02", completed: true); + await Seed(store, "other-flow@1", "wf_03", completed: false); + + WorkflowVersionRemovedException blocked = await Should.ThrowAsync(() => Host>(store: store)); + blocked.Message.ShouldContain("order-fulfilment@2 has 1 active instance(s)"); + blocked.Message.ShouldNotContain("other-flow", Case.Sensitive, "another workflow's instances are not this service's concern"); + + await using (await Host(store: store)) + { + // version 2 registered again: it starts + } + + await Seed(store, "order-fulfilment@2", "wf_01", completed: true, version: 1); + await using SourceFlowTestHost removed = await Host>(store: store); + removed.Runtime.Model.ProcessManagers.ShouldNotContain(p => p.Name == "order-fulfilment@2", "removable once every instance finished"); + } + + // ================================================================ CLI + + [Fact] + [Trait("Id", "UT-WF-67")] + [Trait("Covers", "WFD-35;WFD-37")] + public async Task Cli_ListsAndShowsInstances_AndSaysWhetherAVersionCanBeRemoved() + { + var time = new FakeTimeProvider(T0); + await using SourceFlowTestHost host = await Host>(time); + var done = OrderId.New(); + await host.SendAsync(new PlaceOrder(done, 120m, ["sku-1"], "a@b.c", Priority: false), cancellationToken: Ct); + OrderId stuck = await ToManualAsync(host, time); + + (int code, string output, _) = await Cli(host, "workflow", "list", "--active"); + code.ShouldBe(0); + output.ShouldContain(stuck.ToString()); + output.ShouldNotContain(done.ToString()); + output.ShouldContain("ManualIntervention"); + output.ShouldContain("1 instance(s)"); + + (_, string all, _) = await Cli(host, "workflow", "list", "--name", Workflow, "--version", "1"); + all.ShouldContain("2 instance(s)"); + all.ShouldContain("order-fulfilment@1: 1 active instance(s) across tenants; keep it until they finish"); + (await Cli(host, "workflow", "list", "--name", Workflow, "--version", "2")).Output.ShouldContain("order-fulfilment@2: no active instances in any tenant; it can be removed."); + + (int shown, string show, _) = await Cli(host, "workflow", "show", "order-fulfilment@1", stuck.ToString()); + shown.ShouldBe(0); + show.ShouldContain("status: ManualIntervention"); + show.ShouldContain("step: review-large-order (attempt 1)"); + show.ShouldContain("failure: timeout at review-large-order"); + (await Cli(host, "workflow", "show", "order-fulfilment@1", "nope")).ShouldSatisfyAllConditions(r => r.Code.ShouldBe(1), r => r.Error.ShouldContain("No instance 'nope'")); + (await Cli(host, "workflow", "show", "order-fulfilment", stuck.ToString())).Error.ShouldContain("name@version"); + } + + [Fact] + [Trait("Id", "UT-WF-68")] + [Trait("Covers", "WFD-35")] + public async Task Cli_Resume_SendsWorkflowControl_ThroughTheScheduler() + { + var time = new FakeTimeProvider(T0); + await using SourceFlowTestHost host = await Host>(time); + OrderId order = await ToManualAsync(host, time); + + (int code, string output, _) = await Cli(host, "workflow", "resume", "order-fulfilment@1", order.ToString(), "--step", "create-shipment", "--note", "approved by phone"); + code.ShouldBe(0); + output.ShouldBe("Sent resume to order-fulfilment@1 " + order + Environment.NewLine); + await host.WaitForIdleAsync(); + + (await Summary(host, order)).Status.ShouldBe("Completed"); + (await host.EventsAsync(StreamId.For("fixture-shipment", order.ToStreamSegment()))).ShouldHaveSingleItem().ShouldBeOfType(); + (await Cli(host, "workflow", "resume", "order-fulfilment@1", order.ToString())).ShouldSatisfyAllConditions( + r => r.Code.ShouldBe(1), + r => r.Error.ShouldContain("is Completed: 'resume' needs ManualIntervention")); + } + + [Fact] + [Trait("Id", "UT-WF-69")] + [Trait("Covers", "WFD-35")] + public async Task Cli_RetryStep_AndAbort_ActOnTheInstance() + { + var time = new FakeTimeProvider(T0); + await using SourceFlowTestHost host = await Host>(time); + OrderId retried = await ToManualAsync(host, time); + OrderId aborted = await ToManualAsync(host, time); + + (await Cli(host, "workflow", "retry-step", "order-fulfilment@1", retried.ToString())).Code.ShouldBe(0); + (await Cli(host, "workflow", "abort", "order-fulfilment@1", aborted.ToString(), "--reason", "customer cancelled")).Code.ShouldBe(0); + await host.WaitForIdleAsync(); + + (await Summary(host, retried)).ShouldSatisfyAllConditions(s => s.Status.ShouldBe("Running"), s => s.Step.ShouldBe("review-large-order"), s => s.Attempt.ShouldBe(2)); + (await Summary(host, aborted)).Status.ShouldBe("Aborted"); + (await Cli(host, "workflow", "abort", "order-fulfilment@1", aborted.ToString(), "--reason", "again")).Error.ShouldContain("only an unfinished instance can be aborted"); + (await Cli(host, "workflow", "abort", "order-fulfilment@1", retried.ToString())).Code.ShouldNotBe(0, "--reason is required (audited)"); + } + + // ================================================================ end to end (in-memory) + + [Fact] + [Trait("Id", "WF-E2E-09")] + [Trait("Category", "Workflow")] + [Trait("Covers", "WFD-22;WFD-25")] + public async Task AfterThePivot_AnInvalidAddress_RecoversForward_WithoutCompensation() + { + await using SourceFlowTestHost host = await Host>(); + using var metrics = new Metrics(host); + var order = OrderId.New(); + + await host.SendAsync(new PlaceOrder(order, 120m, ["sku-1", "bad-address"], "a@b.c", Priority: false), cancellationToken: Ct); + await host.WaitForIdleAsync(); + (await Summary(host, order)).ShouldSatisfyAllConditions(s => s.Status.ShouldBe("Running"), s => s.Step.ShouldBe("await-address-fix")); + + await host.SendAsync(new FixAddress(order), cancellationToken: Ct); + await host.SendAsync(new CorrectAddress(order), cancellationToken: Ct); + await host.WaitForIdleAsync(); + + (await Summary(host, order)).Status.ShouldBe("Completed"); + (await host.EventsAsync(StreamId.For("fixture-shipment", order.ToStreamSegment()))).Select(e => e.GetType().Name) + .ShouldBe(["ShipmentAddressFixed", "ShipmentCreated"], "the re-entered step was sent again with a new id, so the owner's inbox ran it"); + (await host.EventsAsync(StreamId.For("fixture-order", order.ToStreamSegment()))).Select(e => e.GetType().Name) + .ShouldBe(["OrderPlaced", "AddressCorrected", "OrderFulfilled"], "forward recovery: nothing cancelled"); + metrics.Counts(SourceFlowTelemetry.Instruments.WorkflowTransitions, SourceFlowTelemetry.Tags.TransitionKind).ShouldNotContainKey("compensate"); + } + + [Fact] + [Trait("Id", "WF-E2E-10")] + [Trait("Category", "Workflow")] + [Trait("Covers", "WFD-35")] + public async Task Version2_StartsNewOrders_WhileVersion1Finishes_AndVersion1CantBeRemovedUntilThen() + { + var store = new InMemoryStore(TimeProvider.System); + var inFlight = OrderId.New(); + await using (SourceFlowTestHost before = await Host>(store: store)) + { + await before.SendAsync(new PlaceOrder(inFlight, 6000m, ["sku-1"], "a@b.c", Priority: false), cancellationToken: Ct); + await before.WaitForIdleAsync(); + (await Summary(before, inFlight)).Step.ShouldBe("review-large-order", "version 1 waits for the review"); + } + + (await Should.ThrowAsync(() => Host>(store: store))) + .Message.ShouldContain("order-fulfilment@1 has 1 active instance(s)"); + + await using (SourceFlowTestHost both = await Host(store: store)) + { + var fresh = OrderId.New(); + await both.SendAsync(new PlaceOrder(fresh, 6000m, ["sku-1"], "a@b.c", Priority: false), cancellationToken: Ct); + await both.SendAsync(new ApproveOrder(inFlight), cancellationToken: Ct); + await both.WaitForIdleAsync(); + + (await Summary(both, fresh, version: 2)).Status.ShouldBe("Completed", "version 2 has no review step"); + (await both.Runtime.Storage.Documents.GetAsync(MessageEnvelope.DefaultTenant, WorkflowInstanceSummary.Collection, WorkflowInstanceSummary.DocumentId("order-fulfilment@1", fresh.ToString()), Ct)) + .ShouldBeNull("new instances start on the latest version only"); + (await Summary(both, inFlight)).Status.ShouldBe("Completed", "the in-flight instance finished on version 1"); + (await both.Runtime.Storage.Documents.GetAsync(MessageEnvelope.DefaultTenant, WorkflowInstanceSummary.Collection, WorkflowInstanceSummary.DocumentId("order-fulfilment@2", inFlight.ToString()), Ct)) + .ShouldBeNull(); + } + + await using SourceFlowTestHost after = await Host>(store: store); + after.Runtime.Model.ProcessManagers.Select(p => p.Name).ShouldContain("order-fulfilment@2"); + } + + [Fact] + [Trait("Id", "UT-PM-21")] + [Trait("Covers", "doc 15 5.6")] + public async Task ANodeThatDoesntKnowVersion1_StillLeavesItsInstancesAlone() + { + // A rolling deploy: a node still on version 1 starts an order; a node already on version 2 (which doesn't register + // version 1, so can't see its state) reads the same start event. The shared claim keeps it to one instance. + var store = new InMemoryStore(TimeProvider.System); + var order = OrderId.New(); + await using (SourceFlowTestHost v1 = await Host>(store: store)) + { + await v1.SendAsync(new PlaceOrder(order, 120m, ["sku-1"], "a@b.c", Priority: false), cancellationToken: Ct); + await v1.WaitForIdleAsync(); + (await Summary(v1, order)).Status.ShouldBe("Completed"); + } + + await using SourceFlowTestHost v2 = await SourceFlowTestHost.StartAsync(sf => + { + sf.ServiceName = "orders"; + sf.AddModule>(); + sf.ProcessManager(p => p.StartFrom(SourceFlow.Hosting.SubscriptionStart.Beginning)); // it reads the past start event + }, store: store, cancellationToken: Ct); + var fresh = OrderId.New(); + await v2.SendAsync(new PlaceOrder(fresh, 120m, ["sku-1"], "a@b.c", Priority: false), cancellationToken: Ct); + await v2.WaitForIdleAsync(); + + (await Summary(v2, fresh, version: 2)).Status.ShouldBe("Completed", "a new order starts on version 2"); + await using IStorageSession session = await store.BeginAsync(MessageEnvelope.DefaultTenant, Ct); + string segment = WorkflowInstanceId.From(order.ToString()).ToStreamSegment(); + (await session.LoadProcessStateAsync("order-fulfilment@2", segment, Ct)).ShouldBeNull("version 1 claimed that order"); + System.Text.Encoding.UTF8.GetString((await session.LoadProcessStateAsync("workflow-claim:order-fulfilment", segment, Ct)).ShouldNotBeNull().State.Span) + .ShouldContain("order-fulfilment@1"); + System.Text.Encoding.UTF8.GetString((await session.LoadProcessStateAsync("workflow-claim:order-fulfilment", WorkflowInstanceId.From(fresh.ToString()).ToStreamSegment(), Ct)).ShouldNotBeNull().State.Span) + .ShouldContain("order-fulfilment@2"); + } + + // ================================================================ helpers + + private static Task Host(TimeProvider? time = null, InMemoryStore? store = null, bool monitor = false) + where TModule : ISourceFlowModule + { + return SourceFlowTestHost.StartAsync(sf => + { + sf.ServiceName = "orders"; + sf.AddModule(); + if (monitor) + { + sf.Configure(o => o.MonitorInterval = TimeSpan.FromMilliseconds(100)); + } + }, time, store: store, cancellationToken: Ct); + } + + // A large order waits for its review; the review times out after a day: manual intervention. + private static async Task ToManualAsync(SourceFlowTestHost host, FakeTimeProvider time) + { + var order = OrderId.New(); + await host.SendAsync(new PlaceOrder(order, 6000m, ["sku-1"], "a@b.c", Priority: false), cancellationToken: Ct); + await host.WaitForIdleAsync(); + time.Advance(TimeSpan.FromDays(1) + TimeSpan.FromSeconds(1)); + await host.WaitForIdleAsync(); + (await Summary(host, order)).Status.ShouldBe("ManualIntervention"); + return order; + } + + private static async Task Summary(SourceFlowTestHost host, OrderId order, int version = 1) + { + StoredDocument document = (await host.Runtime.Storage.Documents.GetAsync(MessageEnvelope.DefaultTenant, WorkflowInstanceSummary.Collection, + WorkflowInstanceSummary.DocumentId($"{Workflow}@{version}", order.ToString()), Ct)).ShouldNotBeNull(); + return WorkflowRuntime.DeserializeSummary(document.Data.Span); + } + + private static async Task Seed(InMemoryStore store, string process, string instance, bool completed, long version = 0) + { + await using IStorageSession session = await store.BeginAsync(MessageEnvelope.DefaultTenant, Ct); + session.SaveProcessState(process, instance, version, "{\"state\":null}"u8.ToArray(), completed); + await session.CommitAsync(Ct); + } + + private static async Task<(int Code, string Output, string Error)> Cli(SourceFlowTestHost host, params string[] args) + { + var output = new StringWriter(); + var error = new StringWriter(); + int code = await SourceFlowCli.RunAsync(args, host.Services, output, error, Ct); + return (code, output.ToString(), error.ToString()); + } + + private static SimulationResult Start(decimal total) + { + var data = new JsonObject { ["orderId"] = "order-7", ["total"] = total, ["lines"] = new JsonArray("sku-1"), ["customerEmail"] = "a@b.c", ["priority"] = false }; + return WorkflowSimulator.Start(Definition, (Dictionary)SimulationStateJson.FromJson(JsonLite.Parse(data.ToJsonString()))!, T0); + } + + private static SimulationInput Ok(IReadOnlyDictionary? data = null) => SimulationInput.Succeed(data); + + private static Dictionary Captured() => new() { ["paymentId"] = "p-1" }; + + private static string[] Kinds(SimulationResult start, params SimulationInput[] inputs) + { + var kinds = new List(start.Transitions.Select(t => t.Kind)); + SimulationResult current = start; + foreach (SimulationInput input in inputs) + { + current = WorkflowSimulator.Step(current.State, input); + kinds.AddRange(current.Transitions.Select(t => t.Kind)); + } + + current.State.Status.ShouldNotBe(SimStatus.Aborted); + return [.. kinds]; + } + + /// Listens to one host's workflow instruments. + private sealed class Metrics : IDisposable + { + private readonly MeterListener _listener = new(); + private readonly ConcurrentQueue<(string Name, long Value, Dictionary Tags)> _measurements = new(); + + public Metrics(SourceFlowTestHost host) + { + Meter meter = host.Runtime.Metrics.Meter; + _listener.InstrumentPublished = (instrument, listener) => + { + if (instrument.Meter == meter && instrument.Name.StartsWith("sourceflow.workflow.", StringComparison.Ordinal)) + { + listener.EnableMeasurementEvents(instrument); + } + }; + _listener.SetMeasurementEventCallback((i, value, tags, _) => Add(i, value, tags)); + _listener.SetMeasurementEventCallback((i, value, tags, _) => Add(i, value, tags)); + _listener.Start(); + } + + public IReadOnlyList<(string Name, long Value, Dictionary Tags)> Measurements(string instrument) + { + return [.. _measurements.Where(m => m.Name == instrument)]; + } + + public Dictionary Counts(string instrument, string tag) + { + return Measurements(instrument).GroupBy(m => (string)m.Tags[tag]!).ToDictionary(g => g.Key, g => g.Sum(m => m.Value)); + } + + // Samples the observable gauges until the monitor's latest reading has a measurement that satisfies until. + public async Task Tags)>> GaugeAsync( + string instrument, Func<(string Name, long Value, Dictionary Tags), bool> until) + { + for (int i = 0; i < 500; i++) + { + _measurements.Clear(); + _listener.RecordObservableInstruments(); + if (Measurements(instrument) is { Count: > 0 } found && found.Any(until)) + { + return found; + } + + await Task.Delay(TimeSpan.FromMilliseconds(10), TimeProvider.System, Ct); + } + + return []; + } + + public void Dispose() + { + _listener.Dispose(); + } + + private void Add(Instrument instrument, long value, ReadOnlySpan> tags) + { + var map = new Dictionary(StringComparer.Ordinal); + foreach (KeyValuePair tag in tags) + { + map[tag.Key] = tag.Value; + } + + _measurements.Enqueue((instrument.Name, value, map)); + } + } +} diff --git a/tests/Workflows/SourceFlow.Studio.Tests/WorkflowReplyTests.cs b/tests/Workflows/SourceFlow.Studio.Tests/WorkflowReplyTests.cs new file mode 100644 index 00000000..b10f89f5 --- /dev/null +++ b/tests/Workflows/SourceFlow.Studio.Tests/WorkflowReplyTests.cs @@ -0,0 +1,55 @@ +using System.Text.Json.Nodes; +using SourceFlow.Studio.Tests.Fixture; +using SourceFlow.Testing; +using SourceFlow.Workflows; + +namespace SourceFlow.Studio.Tests; + +/// UT-PM-19..20 (WP-C.11, CR-32, CR-33): rejection replies reach the generated workflow, and only for the attempt that sent them. +[Trait("Category", "Unit")] +public sealed class WorkflowReplyTests +{ + private const string Order = "12345678-1234-5678-9abc-def012345678"; + + private static WorkflowSpec Started() + { + var data = new JsonObject { ["orderId"] = Order, ["total"] = 100m, ["lines"] = new JsonArray("sku-1"), ["customerEmail"] = "a@b.c", ["priority"] = false }; + return WorkflowSpec.For().Start("orders.order-placed.v1", data.ToJsonString()); + } + + [Fact] + [Trait("Id", "UT-PM-19")] + [Trait("Covers", "doc 15 5.3")] + public void ARejectedCompensation_IsAFailedAttempt_RetriedOnItsSchedule() + { + WorkflowSpec spec = Started() + .Succeed("inventory.stock-reserved.v1", new JsonObject { ["orderId"] = Order }.ToJsonString()) + .Reject("payments.fraud_suspected") // charge-payment fails: compensate reserve-stock + .ThenSends("inventory.release-stock.v1") + .Reject("inventory.not_reserved") // the compensation itself is rejected + .ThenStatus(WorkflowStatus.Compensating); + + WorkflowTimer retry = spec.Timers[^1]; + retry.Kind.ShouldBe("retry", "release-stock's retry: 5, from 30 s"); + retry.Step.ShouldBe("compensate:reserve-stock"); + spec.FireTimer().ThenSends("inventory.release-stock.v1"); + } + + [Fact] + [Trait("Id", "UT-PM-20")] + [Trait("Covers", "doc 15 5.5")] + public void ALateRejectionOfAnEarlierAttempt_IsIgnored() + { + WorkflowSpec spec = Started() + .FireTimer() // reserve-stock times out: attempt 2 is sent + .ThenSends("inventory.reserve-stock.v1"); + spec.Sent.Count.ShouldBe(2); + + spec.RejectAt(0, "inventory.out_of_stock"); // attempt 1's rejection arrives late + spec.LastReaction.ShouldBeNull("it is not the current attempt's reply"); + spec.ThenStatus(WorkflowStatus.Running); + + spec.Reject("inventory.out_of_stock") // attempt 2's own rejection counts + .ThenStatus(WorkflowStatus.Compensated); + } +} diff --git a/tests/Workflows/SourceFlow.Studio.Tests/WorkflowRuntimeTests.cs b/tests/Workflows/SourceFlow.Studio.Tests/WorkflowRuntimeTests.cs new file mode 100644 index 00000000..bfb0972c --- /dev/null +++ b/tests/Workflows/SourceFlow.Studio.Tests/WorkflowRuntimeTests.cs @@ -0,0 +1,407 @@ +using System.Text.Json; +using System.Text.Json.Nodes; +using CsCheck; +using Microsoft.Extensions.Time.Testing; +using SourceFlow.Messaging; +using SourceFlow.Storage; +using SourceFlow.Studio.Dsl.Json; +using SourceFlow.Studio.Dsl.Model; +using SourceFlow.Studio.Dsl.Reading; +using SourceFlow.Studio.Dsl.Simulation; +using SourceFlow.Studio.Tests.Fixture; +using SourceFlow.Testing; +using SourceFlow.Workflows; +using SimStatus = SourceFlow.Studio.Dsl.Simulation.WorkflowStatus; + +namespace SourceFlow.Studio.Tests; + +/// +/// The generated workflow (WP-S.5): the doc 15 §5.1 workflow compiled from Fixture/order-fulfilment.sfflow.yaml into +/// OrderFulfilmentWorkflowV1, run in a host and compared with the simulator (WF-DIFF-01..06). +/// +[Trait("Category", "Unit")] +public sealed class WorkflowRuntimeTests +{ + private static readonly WorkflowDefinition Definition = WorkflowReader.Read(File.ReadAllText(Path.Combine(AppContext.BaseDirectory, "..", "..", "..", "Fixture", "order-fulfilment.sfflow.yaml"))).Workflow!; + + private static CancellationToken Ct => TestContext.Current.CancellationToken; + + // ================================================================ in a host + + [Fact] + [Trait("Id", "GEN-63")] + [Trait("Covers", "WFD-29")] + public async Task GeneratedWorkflow_RunsTheHappyPath_InAHost() + { + await using SourceFlowTestHost host = await Host(); + var order = OrderId.New(); + + await host.SendAsync(new PlaceOrder(order, 120m, ["sku-1"], "a@b.c", Priority: false), cancellationToken: Ct); + await host.WaitForIdleAsync(); + + (await Events(host, "fixture-order", order)).Select(e => e.GetType().Name).ShouldBe(["OrderPlaced", "OrderFulfilled"], "mark-fulfilled was sent on completion"); + (await Events(host, "fixture-stock", order)).ShouldHaveSingleItem().ShouldBeOfType(); + (await Events(host, "fixture-payment", order)).ShouldHaveSingleItem().ShouldBeOfType(); + (await Events(host, "fixture-shipment", order)).ShouldHaveSingleItem().ShouldBeOfType(); + ProcessState state = await State(host, order); + state.Completed.ShouldBeTrue(); + JsonDocument.Parse(state.State.ToArray()).RootElement.GetProperty("state").GetProperty("status").GetString().ShouldBe("Completed"); + } + + [Fact] + [Trait("Id", "GEN-63")] + public async Task GeneratedWorkflow_CompensatesInAHost_WhenStockIsOut() + { + await using SourceFlowTestHost host = await Host(); + var order = OrderId.New(); + + await host.SendAsync(new PlaceOrder(order, 120m, ["none"], "a@b.c", Priority: false), cancellationToken: Ct); + await host.WaitForIdleAsync(); + + ProcessState state = await State(host, order); + state.Completed.ShouldBeTrue(); + JsonElement engine = JsonDocument.Parse(state.State.ToArray()).RootElement.GetProperty("state"); + engine.GetProperty("status").GetString().ShouldBe("Compensated", "the rejection reply reached the workflow and nothing needed undoing"); + engine.GetProperty("failure").GetProperty("code").GetString().ShouldBe("inventory.out_of_stock"); + (await Events(host, "fixture-order", order)).Last().ShouldBe(new OrderCancelled(order, "inventory.out_of_stock"), "on.compensated maps $failure.code"); + } + + [Fact] + [Trait("Id", "GEN-63")] + public async Task GeneratedWorkflow_RetriesADecline_OnItsTimer() + { + var time = new FakeTimeProvider(new DateTimeOffset(2026, 1, 1, 0, 0, 0, TimeSpan.Zero)); + await using SourceFlowTestHost host = await Host(time); + var order = OrderId.New(); + + await host.SendAsync(new PlaceOrder(order, 200_000m, ["sku-1"], "a@b.c", Priority: false), cancellationToken: Ct); + await host.WaitForIdleAsync(); + + JsonElement engine = JsonDocument.Parse((await State(host, order)).State.ToArray()).RootElement.GetProperty("state"); + engine.GetProperty("status").GetString().ShouldBe("Running"); + engine.GetProperty("step").GetString().ShouldBe("charge-payment"); + engine.GetProperty("phase").GetString().ShouldBe("Retrying", "payments.declined has 3 retries every 10 minutes"); + engine.GetProperty("timer").GetProperty("kind").GetString().ShouldBe("retry"); + } + + // ================================================================ WF-DIFF: the generated workflow ≡ the simulator + + [Fact] + [Trait("Id", "WF-DIFF-01")] + [Trait("Covers", "WFD-NFR-2")] + public void HappyPath_MatchesTheSimulator() + { + var run = new Differential(); + run.Start(total: 6000m); + run.Apply(Choice.Success); // stock reserved + run.Apply(Choice.Success); // payment captured + run.Apply(Choice.Success); // large order approved + run.Apply(Choice.Success); // shipment created + run.Status.ShouldBe(SimStatus.Completed); + } + + [Fact] + [Trait("Id", "WF-DIFF-02")] + [Trait("Category", "Property")] + [Trait("Covers", "WFD-NFR-2")] + public void RandomOutcomeSequences_MatchTheSimulator() + { + Gen.Select(Gen.Bool, Gen.Int[0, 1_000].Array[1, 40]) + .Sample((large, choices) => + { + var run = new Differential(); + run.Start(total: large ? 6000m : 100m); + foreach (int choice in choices) + { + if (run.Terminal || run.Status == SimStatus.ManualIntervention) + { + break; + } + + run.ApplyRandom(choice); + } + }, iter: 10_000); + } + + [Fact] + [Trait("Id", "WF-DIFF-03")] + public void OperatorActions_MatchTheSimulator() + { + var resumed = new Differential(); + resumed.Start(total: 6000m); + resumed.Apply(Choice.Success); + resumed.Apply(Choice.Success); + resumed.Apply(Choice.Timer); // review times out: manual + resumed.Status.ShouldBe(SimStatus.ManualIntervention); + resumed.Control(WorkflowControl.ResumeAction, step: "create-shipment"); + resumed.Apply(Choice.Success); + resumed.Status.ShouldBe(SimStatus.Completed); + + var aborted = new Differential(); + aborted.Start(total: 100m); + aborted.Apply(Choice.Success); + aborted.Control(WorkflowControl.AbortAction, reason: "customer cancelled", compensate: true); + aborted.Apply(Choice.Success); + aborted.Status.ShouldBe(SimStatus.Aborted); + + var retried = new Differential(); + retried.Start(total: 6000m); + retried.Apply(Choice.Success); + retried.Apply(Choice.Success); + retried.Apply(Choice.Timer); + retried.Control(WorkflowControl.RetryStepAction); + retried.Status.ShouldBe(SimStatus.Running); + } + + [Fact] + [Trait("Id", "WF-DIFF-04")] + public void StaleTimersAndUnrelatedMessages_AreIgnoredByBoth() + { + var run = new Differential(); + run.Start(total: 100m); + run.Apply(Choice.Timer); // reserve-stock times out: re-sent as attempt 2 + run.Stale("timeout", "reserve-stock", 1).ShouldBeTrue(); // the attempt-1 timeout is stale + run.Unrelated("payments.payment-captured.v1").ShouldBeTrue("an event the instance doesn't wait for now"); + run.Apply(Choice.Success); + run.Status.ShouldBe(SimStatus.Running); + } + + [Fact] + [Trait("Id", "WF-DIFF-05")] + public void SendIds_AreDeterministicPerAttempt() + { + var first = new Differential(); + first.Start(total: 100m); + var second = new Differential(); + second.Start(total: 100m); + + first.Sent.Single().Id.ShouldBe(second.Sent.Single().Id, "the same instance and attempt: the same id, deduplicated by the owner's inbox"); + first.Sent.Single().Id.ShouldBe(new MessageId(WorkflowIds.Send(OrderFulfilmentWorkflowV1.ProcessName, first.Instance, "reserve-stock", 1))); + first.Apply(Choice.Timer); + first.Sent[^1].Id.ShouldBe(new MessageId(WorkflowIds.Send(OrderFulfilmentWorkflowV1.ProcessName, first.Instance, "reserve-stock", 2))); + } + + [Fact] + [Trait("Id", "WF-DIFF-06")] + [Trait("Covers", "doc 15 5.3;WFD-NFR-2")] + public void WithSeveralTimersScheduled_BothIgnoreEveryStaleOne() + { + var run = new Differential(); + run.Start(total: 6000m); + run.Apply(Choice.Success); // reserve-stock's timeout stays scheduled although cancelled + run.Apply(Choice.Timer); // charge-payment's attempt-1 timeout fires; attempt 2 has its own + run.Apply(Choice.Success); // payment captured: the review waits a day + run.Scheduled.ShouldBeGreaterThan(1, "the cancelled timers are still scheduled, as at the broker"); + + run.FireEveryStaleTimer().ShouldBeTrue("each one is ignored by the generated workflow and the simulator alike"); + run.Apply(Choice.Timer); // the review's own timeout counts: manual + run.Status.ShouldBe(SimStatus.ManualIntervention); + } + + // ================================================================ helpers + + // Version 1 only: with version 2 registered too, new orders would start on version 2 (doc 15 §5.6). + private static Task Host(TimeProvider? time = null) + { + return SourceFlowTestHost.StartAsync(sf => + { + sf.ServiceName = "orders"; + sf.AddModule>(); + }, time, cancellationToken: Ct); + } + + private static Task> Events(SourceFlowTestHost host, string aggregate, OrderId order) + { + return host.EventsAsync(StreamId.For(aggregate, order.ToStreamSegment())); + } + + private static async Task State(SourceFlowTestHost host, OrderId order) + { + await using IStorageSession session = await host.Store.BeginAsync(MessageEnvelope.DefaultTenant, Ct); + return (await session.LoadProcessStateAsync(OrderFulfilmentWorkflowV1.ProcessName, WorkflowInstanceId.From(order.ToString()).ToStreamSegment(), Ct)).ShouldNotBeNull(); + } + + private enum Choice + { + Success, + Timer, + } + + /// Drives the simulator and the generated workflow with the same inputs and compares them after every move. + private sealed class Differential + { + private readonly WorkflowSpec _spec = WorkflowSpec.For(); + private SimulationState? _sim; + private string _order = string.Empty; + + public string Instance => _order; + + public SimStatus Status => _sim!.Status; + + public bool Terminal => _sim!.IsTerminal; + + public IReadOnlyList<(ICommand Command, MessageId? Id)> Sent => _spec.Sent; + + public void Start(decimal total) + { + _order = new Guid(0x1234_5678, 0x1234, 0x5678, 0x9a, 0xbc, 0xde, 0xf0, 0x12, 0x34, 0x56, 0x78).ToString("D"); + var data = new JsonObject { ["orderId"] = _order, ["total"] = total, ["lines"] = new JsonArray("sku-1"), ["customerEmail"] = "a@b.c", ["priority"] = false }; + SimulationResult result = WorkflowSimulator.Start(Definition, Values(data), _spec.Now); + _spec.Start("orders.order-placed.v1", data.ToJsonString()); + Compare(result); + } + + public void Apply(Choice choice) + { + Apply(choice == Choice.Timer ? -1 : 0); + } + + // 0: the awaited success; 1..n: a declared failure; -1 (or no failures left): the pending timer. + public void ApplyRandom(int choice) + { + WorkflowStep? step = _sim!.Step is { } id ? Definition.Step(id) : null; + int failures = _sim.Status == SimStatus.Running ? step?.Await?.Failures.Count ?? 0 : 0; + int options = 1 + failures + (_sim.Timer is null ? 0 : 1); + int pick = choice % options; + Apply(pick <= failures ? pick : -1); + } + + public void Control(string action, string? step = null, string? reason = null, bool compensate = false) + { + SimulationInput input = action switch + { + WorkflowControl.ResumeAction => SimulationInput.Resume(step), + WorkflowControl.AbortAction => SimulationInput.Abort(reason!, compensate), + _ => SimulationInput.RetryStep(), + }; + SimulationResult result = WorkflowSimulator.Step(_sim!, input); + _spec.Control(action, step, reason, compensate); + Compare(result); + } + + public int Scheduled => _spec.Timers.Count; + + // Delivers every scheduled timer except the pending one, to both, as a broker would deliver cancelled timers. + public bool FireEveryStaleTimer() + { + bool ignored = true; + foreach (WorkflowTimer timer in _spec.Timers.ToArray()) + { + if (_sim!.Timer is { } pending && pending.Kind == timer.Kind && pending.Step == timer.Step && pending.Attempt == timer.Attempt && pending.Due == timer.Due) + { + continue; + } + + SimulationResult result = WorkflowSimulator.Step(_sim, SimulationInput.Timer(timer.Kind, timer.Step, timer.Attempt, timer.Due)); + int before = _spec.Sent.Count; + _spec.FireTimer(timer.Kind, timer.Step, timer.Attempt); + Compare(result); + ignored &= result.Effects.All(e => e.Kind == SimulationEffect.Ignored) && _spec.LastReaction is null && _spec.Sent.Count == before; + } + + return ignored; + } + + public bool Stale(string kind, string step, int attempt) + { + SimulationResult result = WorkflowSimulator.Step(_sim!, SimulationInput.Timer(kind, step, attempt)); + int before = _spec.Sent.Count; + Deliver(new WorkflowTimer(OrderFulfilmentWorkflowV1.ProcessName, _order, kind, step, attempt)); + Compare(result); + return result.Effects.All(e => e.Kind == SimulationEffect.Ignored) && _spec.LastReaction is null && _spec.Sent.Count == before; + } + + public bool Unrelated(string type) + { + var data = new JsonObject { ["paymentId"] = Guid.Empty.ToString("D"), ["orderId"] = _order, ["amount"] = 1m, ["cardHolder"] = "x" }; + SimulationResult result = WorkflowSimulator.Step(_sim!, SimulationInput.Receive(type, Values(data))); + _spec.Succeed(type, data.ToJsonString()); + Compare(result); + return _spec.LastReaction is null; + } + + private void Apply(int pick) + { + WorkflowStep step = Definition.Step(_sim!.Step!)!; + SimulationResult result; + if (pick < 0) + { + result = WorkflowSimulator.Step(_sim, SimulationInput.FireTimer()); + _spec.FireTimer(); + } + else if (pick == 0) + { + string type = _sim.Status == SimStatus.Compensating ? step.Compensate!.Await!.Success.On : step.Await!.Success.On; + JsonObject data = EventData(type); + result = WorkflowSimulator.Step(_sim, SimulationInput.Receive(type, Values(data))); + _spec.Succeed(type, data.ToJsonString()); + } + else + { + FailureSpec failure = step.Await!.Failures[pick - 1]; + if (failure.Rejected is { } code) + { + result = WorkflowSimulator.Step(_sim, SimulationInput.RejectedFor(step.Send!.Command, code, code)); + _spec.Reject(code); + } + else + { + JsonObject data = EventData(failure.On!); + result = WorkflowSimulator.Step(_sim, SimulationInput.Receive(failure.On!, Values(data))); + _spec.Fail(failure.On!, data.ToJsonString()); + } + } + + Compare(result); + } + + private void Deliver(WorkflowTimer timer) + { + // A stale timer: delivered through the operator path of the spec (the same React). + typeof(WorkflowSpec).GetMethod("Deliver", System.Reflection.BindingFlags.NonPublic | System.Reflection.BindingFlags.Instance)!.Invoke(_spec, [timer, null, false]); + } + + private JsonObject EventData(string type) + { + return type switch + { + "payments.payment-captured.v1" => new JsonObject { ["paymentId"] = "9b2f1f0e-7d1c-4b1a-9f3e-2a1b3c4d5e6f", ["orderId"] = _order, ["amount"] = 6000m, ["cardHolder"] = "card-holder" }, + "payments.refunded.v1" => new JsonObject { ["paymentId"] = "9b2f1f0e-7d1c-4b1a-9f3e-2a1b3c4d5e6f", ["orderId"] = _order }, + "shipping.shipment-created.v1" => new JsonObject { ["orderId"] = _order, ["shipmentId"] = _order }, + "orders.order-rejected-by-review.v1" => new JsonObject { ["orderId"] = _order, ["reason"] = "no" }, + _ => new JsonObject { ["orderId"] = _order }, + }; + } + + // The simulator's state and outbox must equal the generated workflow's after every move. + private void Compare(SimulationResult result) + { + _sim = result.State; + string? json = _spec.State.State; + json.ShouldNotBeNull(); + SimulationState generated = SimulationStateJson.Read(Definition, json); + string expected = SimulationStateJson.Write(result.State); + SimulationStateJson.Write(generated).ShouldBe(expected); + + SentCommand[] simulated = [.. result.Sent]; + (ICommand Command, MessageId? Id)[] sent = _spec.LastReaction is null ? [] : [.. _spec.Sent.TakeLast(_spec.LastReaction.Commands.Count)]; + sent.Length.ShouldBe(simulated.Length); + for (int i = 0; i < sent.Length; i++) + { + sent[i].Id.ShouldBe(new MessageId(simulated[i].MessageId)); + JsonNode actual = JsonSerializer.SerializeToNode(sent[i].Command, Options.GetTypeInfo(sent[i].Command.GetType()))!; + foreach (KeyValuePair field in simulated[i].Fields) + { + SimulationStateJson.ToJson(field.Value).ShouldBe(SimulationStateJson.ToJson(SimulationStateJson.FromJson(JsonLite.Parse(actual[field.Key]?.ToJsonString() ?? "null"))), simulated[i].Command + "." + field.Key); + } + } + } + + private static JsonSerializerOptions Options { get; } = new SourceFlow.Runtime.SourceFlowModelBuilder().AddModule().Build().Registry.Options; + + private static Dictionary Values(JsonObject data) + { + return (Dictionary)SimulationStateJson.FromJson(JsonLite.Parse(data.ToJsonString()))!; + } + } +} diff --git a/tests/Workflows/SourceFlow.Studio.Tests/WorkspaceTests.cs b/tests/Workflows/SourceFlow.Studio.Tests/WorkspaceTests.cs new file mode 100644 index 00000000..612d2b4e --- /dev/null +++ b/tests/Workflows/SourceFlow.Studio.Tests/WorkspaceTests.cs @@ -0,0 +1,238 @@ +using SourceFlow.Studio.Dsl.Json; +using SourceFlow.Studio.Dsl.Manifests; +using SourceFlow.Studio.Workspace; + +namespace SourceFlow.Studio.Tests; + +/// Service manifests and the business domain workspace (doc 15 §3–4, WP-S.2). +[Trait("Category", "Unit")] +public sealed class WorkspaceTests : IDisposable +{ + private const string Payments = """ + { + "manifestVersion": 1, + "service": "payments", + "endpoint": "payments", + "sourceflowVersion": "3.0.0", + "messages": [ + { "type": "payments.charge", "version": 1, "kind": "command", "clrType": "Payments.Charge", "aggregate": "payment", + "fields": [ { "name": "orderId", "type": "uuid" }, { "name": "amount", "type": "number" }, { "name": "card", "type": "string", "nullable": true, "personalData": true } ] }, + { "type": "payments.payment-captured", "version": 1, "kind": "event", "fields": [ { "name": "paymentId", "type": "uuid" } ] } + ], + "aggregates": [ + { "name": "payment", "clrType": "Payments.Payment", + "commands": [ { "type": "payments.charge", "version": 1, "emits": ["payments.payment-captured.v1"], "rejects": ["payments.declined", "payments.fraud_suspected"] } ], + "events": ["payments.payment-captured.v1"] } + ], + "processManagers": [ { "name": "refund-retry", "clrType": "Payments.RefundRetry", "handles": ["payments.refund-failed.v1"], "sends": ["payments.refund.v1"], "schedules": [] } ], + "projections": [ { "name": "payment-summary", "version": 2, "clrType": "Payments.Summary", "handles": ["payments.payment-captured.v1"] } ], + "publishes": [ { "domainEvent": "payments.payment-captured.v1", "as": "payments.payment-captured-v1.v1", "topic": "payments.events" } ], + "subscribes": [ { "topic": "orders.events", "only": ["orders.order-placed.v1"], "where": "source = 'orders'" } ], + "commandRoutes": [ { "command": "inventory.reserve-stock.v1", "to": "inventory", "replyOnReject": true } ], + "workflows": [ { "name": "refund", "version": 1, "file": "workflows/refund.sfflow.yaml" } ], + "schemas": "catalog://payments" + } + """; + + private readonly string _root = Path.Combine(Path.GetTempPath(), "sourceflow-workspace-" + Path.GetRandomFileName()); + + public WorkspaceTests() + { + Directory.CreateDirectory(_root); + } + + public void Dispose() + { + Directory.Delete(_root, recursive: true); + } + + [Fact] + [Trait("Id", "UT-MAN-12")] + [Trait("Covers", "WFD-10")] + public async Task Workspace_ResolvesRelativePaths_AndListsWorkflowFiles() + { + Write("services/payments/artifacts/sourceflow.manifest.json", Payments); + Write("services/orders/artifacts/sourceflow.manifest.json", Manifest("orders")); + Write("services/orders/workflows/order-fulfilment.sfflow.yaml", "sourceflow.workflow: 1\n"); + Write("services/orders/workflows/returns/refund.sfflow.yaml", "sourceflow.workflow: 1\n"); + Write("services/orders/workflows/notes.md", "not a workflow"); + Write("other-repo/shipping.json", Manifest("shipping")); + Write("domain/sourceflow.domain.yaml", """ + # The commerce domain. + domain: commerce + description: Order to delivery + services: + - name: orders + manifest: ../services/orders/artifacts/sourceflow.manifest.json + workflows: ../services/orders/workflows + project: ../services/orders/src + tests: ../services/orders/tests + module: Orders.OrdersModule + - name: payments + manifest: ../services/payments/artifacts/sourceflow.manifest.json + - name: shipping + manifest: ../other-repo/shipping.json + """); + + DomainWorkspace workspace = await DomainWorkspace.LoadAsync(Path.Combine(_root, "domain"), cancellationToken: TestContext.Current.CancellationToken); + + workspace.Domain.ShouldBe("commerce"); + workspace.Description.ShouldBe("Order to delivery"); + workspace.Path.ShouldBe(Path.Combine(_root, "domain", DomainWorkspace.FileName)); + workspace.Services.Select(s => s.Name).ShouldBe(["orders", "payments", "shipping"]); + workspace.Service("orders")!.WorkflowFiles.ShouldBe( + [ + "../services/orders/workflows/order-fulfilment.sfflow.yaml", + "../services/orders/workflows/returns/refund.sfflow.yaml", + ]); + workspace.Service("orders")!.ProjectLocation.ShouldBe("../services/orders/src"); + workspace.Service("orders")!.TestsLocation.ShouldBe("../services/orders/tests"); + workspace.Service("orders")!.ModuleType.ShouldBe("Orders.OrdersModule"); + workspace.Service("payments")!.TestsLocation.ShouldBeNull(); + workspace.Service("payments")!.ModuleType.ShouldBeNull(); + workspace.Service("payments")!.WorkflowsLocation.ShouldBeNull(); + workspace.Service("payments")!.WorkflowFiles.ShouldBeEmpty(); + workspace.Service("payments")!.Manifest.Aggregates.Single().Name.ShouldBe("payment"); + workspace.Manifests.Count().ShouldBe(3); + workspace.Service("billing").ShouldBeNull(); + } + + [Theory] + [Trait("Id", "UT-MAN-13")] + [Trait("Covers", "WFD-10")] + [InlineData("domain: d\nservices:\n - name: payments\n manifest: missing.json\n", "manifest 'missing.json' not found")] + [InlineData("domain: d\nservices:\n - name: payments\n manifest: p.json\n colour: red\n", "(5,5): unknown key 'colour'")] + [InlineData("domain: d\nowner: me\nservices: []\n", "(2,1): unknown key 'owner'")] + [InlineData("domain: d\nservices:\n - name: payments\n manifest: p.json\n - name: payments\n manifest: p.json\n", "service 'payments' is listed twice")] + [InlineData("domain: d\nservices: []\n", "'services' lists no service")] + [InlineData("services:\n - name: payments\n manifest: p.json\n", "'domain' is required")] + [InlineData("domain: d\nservices:\n - name: payments\n", "needs a 'name' and a 'manifest'")] + [InlineData("domain: d\nservices:\n - name: payments\n manifest: https://example.invalid/payments.json\n", "remote manifests are off")] + [InlineData("domain: d\nservices:\n - name: billing\n manifest: p.json\n", "is the manifest of service 'payments'")] + [InlineData("domain: d\nservices:\n - name: payments\n manifest: bad.json\n", "manifest 'bad.json' is invalid")] + [InlineData("domain: [d\n", "sourceflow.domain.yaml(")] + public async Task Workspace_ReportsInvalidFilesAndManifests(string yaml, string expected) + { + Write("p.json", Payments); + Write("bad.json", """{ "manifestVersion": 2 }"""); + Write(DomainWorkspace.FileName, yaml); + + WorkspaceException error = await Should.ThrowAsync(() => + DomainWorkspace.LoadAsync(Path.Combine(_root, DomainWorkspace.FileName), cancellationToken: TestContext.Current.CancellationToken)); + + error.Message.ShouldContain(expected); + } + + [Fact] + [Trait("Id", "UT-MAN-13")] + public async Task Workspace_FetchesRemoteManifests_OnlyThroughAConfiguredFetcher() + { + Write(DomainWorkspace.FileName, "domain: d\nservices:\n - name: payments\n manifest: https://manifests.example/payments.json\n"); + var fetched = new List(); + var options = new WorkspaceLoadOptions + { + FetchRemote = (uri, _) => + { + fetched.Add(uri); + return Task.FromResult(Payments); + }, + }; + + DomainWorkspace workspace = await DomainWorkspace.LoadAsync(_root, options, TestContext.Current.CancellationToken); + + fetched.ShouldBe([new Uri("https://manifests.example/payments.json")]); + workspace.Service("payments")!.Manifest.Service.ShouldBe("payments"); + await Should.ThrowAsync(() => DomainWorkspace.LoadAsync(Path.Combine(_root, "nowhere.yaml"), cancellationToken: TestContext.Current.CancellationToken)); + } + + [Fact] + [Trait("Id", "UT-MAN-14")] + [Trait("Covers", "WFD-11")] + public void Manifest_ParsesEverySection() + { + ServiceManifest manifest = ServiceManifest.Parse(Payments); + + manifest.Service.ShouldBe("payments"); + manifest.Endpoint.ShouldBe("payments"); + manifest.SourceFlowVersion.ShouldBe("3.0.0"); + manifest.Schemas.ShouldBe("catalog://payments"); + ManifestMessage charge = manifest.FindMessage("payments.charge.v1")!; + charge.Kind.ShouldBe("command"); + charge.Aggregate.ShouldBe("payment"); + charge.Field("card").ShouldBe(new ManifestField("card", "string", Nullable: true, PersonalData: true)); + charge.Field("nope").ShouldBeNull(); + manifest.TryGetCommand("payments.charge.v1", out ManifestAggregate? aggregate, out ManifestCommand? command).ShouldBeTrue(); + aggregate!.Name.ShouldBe("payment"); + command!.Emits.ShouldBe(["payments.payment-captured.v1"]); + command.Rejects.ShouldBe(["payments.declined", "payments.fraud_suspected"]); + manifest.TryGetCommand("payments.refund.v1", out _, out _).ShouldBeFalse(); + manifest.ProcessManagers.Single().Sends.ShouldBe(["payments.refund.v1"]); + manifest.Projections.Single().Version.ShouldBe(2); + manifest.Publishes.Single().ShouldBe(new ManifestPublication("payments.payment-captured.v1", "payments.payment-captured-v1.v1", "payments.events")); + manifest.Subscribes.Single().Only.ShouldBe(["orders.order-placed.v1"]); + manifest.Subscribes.Single().Where.ShouldBe("source = 'orders'"); + manifest.CommandRoutes.Single().ShouldBe(new ManifestCommandRoute("inventory.reserve-stock.v1", "inventory", ReplyOnReject: true)); + manifest.Workflows.Single().ShouldBe(new ManifestWorkflow("refund", 1, "workflows/refund.sfflow.yaml")); + + // A static manifest (from the generator's attribute) has no service or routing. + ServiceManifest staticPart = ServiceManifest.Parse("""{"manifestVersion":1,"assembly":"Payments","sourceflowVersion":"3.0.0","messages":[],"aggregates":[],"processManagers":[],"projections":[]}"""); + staticPart.Service.ShouldBeNull(); + staticPart.Assembly.ShouldBe("Payments"); + staticPart.CommandRoutes.ShouldBeEmpty(); + + MessageRef.Of("payments.charge", 2).ShouldBe("payments.charge.v2"); + MessageRef.TryParse("payments.charge.v2", out string name, out int version).ShouldBeTrue(); + (name, version).ShouldBe(("payments.charge", 2)); + MessageRef.TryParse("payments.charge", out _, out _).ShouldBeFalse(); + } + + [Theory] + [Trait("Id", "UT-MAN-14")] + [InlineData("""{ "manifestVersion": 2 }""", "Unsupported manifestVersion 2")] + [InlineData("""{ "service": "x" }""", "manifestVersion (missing)")] + [InlineData("""[1, 2]""", "is a JSON object")] + [InlineData("""{ "manifestVersion": 1, "manifestVersion": 1 }""", "duplicate property 'manifestVersion'")] + [InlineData("""{ "manifestVersion": 1, "aggregates": [ { "clrType": "X" } ] }""", "has no 'name'")] + [InlineData("""{ "manifestVersion": 1, """, "line 1")] + [InlineData("""{ "manifestVersion": 1 } x""", "after the value")] + [InlineData("""{ "manifestVersion": 01 }""", "expected '}'")] + [InlineData("""{ "a": "\q" }""", "invalid escape")] + [InlineData("""{ "a": tru }""", "invalid literal")] + public void Manifest_RejectsInvalidInput(string json, string expected) + { + Should.Throw(() => ServiceManifest.Parse(json)).Message.ShouldContain(expected); + } + + [Fact] + [Trait("Id", "UT-MAN-14")] + public void JsonLite_ReadsEveryValueKind() + { + JsonValue value = JsonLite.Parse(""" + { "s": "a\"b\\c\/d\né", "i": -12, "d": 1.5e2, "t": true, "f": false, "n": null, "a": [1, [], {}], "o": { "x": 0 } } + """); + + value["s"]!.AsString.ShouldBe("a\"b\\c/d\né"); + value["i"]!.AsInteger.ShouldBe(-12); + value["d"]!.AsNumber.ShouldBe(150); + value["d"]!.AsInteger.ShouldBeNull(); + value["t"]!.AsBoolean.ShouldBe(true); + value["f"]!.AsBoolean.ShouldBe(false); + value["n"]!.AsString.ShouldBeNull(); + value["a"]!.Items.Count.ShouldBe(3); + value["o"]!.Members.Single().Key.ShouldBe("x"); + value["missing"].ShouldBeNull(); + Should.Throw(() => JsonLite.Parse(new string('[', 70) + new string(']', 70))).Message.ShouldContain("nested too deeply"); + } + + private static string Manifest(string service) + { + return Payments.Replace("\"payments\"", "\"" + service + "\"", StringComparison.Ordinal); + } + + private void Write(string relative, string content) + { + string path = Path.Combine(_root, relative); + Directory.CreateDirectory(Path.GetDirectoryName(path)!); + File.WriteAllText(path, content); + } +} diff --git a/tests/traceability.csv b/tests/traceability.csv new file mode 100644 index 00000000..d8b7dd3d --- /dev/null +++ b/tests/traceability.csv @@ -0,0 +1,66 @@ +id,source,description +# Ids are added by the work package that implements them; ARCH-08 fails while any listed id has no covering test. +ARCH-01,ADR-027,Core references only the BCL Microsoft.Extensions and Polly +ARCH-02,ADR-027,Core never references an adapter +ARCH-03,ADR-027,Adapters reference the core only +ARCH-05,plan 06 9,No reflection activation in runtime packages +ARCH-06,plan 09 IR-08,Every AOT-marked package is published with PublishAot by a CI AOT check +ARCH-07,plan 06 9,Public adapter classes are sealed +ARCH-08,plan 04 7,Traceability ids are covered +ARCH-10,ADR-013,No hand-written backoff outside the resilience engine +ADR-027,ADRs,Single core package with extensibility SPIs +ADR-003,ADRs,Aggregates as pure deciders +ADR-004,ADRs,Source generation instead of reflection +ADR-005,ADRs,Logical message type names and registry +ADR-006,ADRs,Transactional outbox and inbox (idempotency ids) +ADR-011,ADRs,CloudEvents envelope and W3C trace context +ADR-015,ADRs,Strongly typed caller-assigned ids +ADR-016,ADRs,Projections +ADR-018,ADRs,Business rejections are values +ADR-020,ADRs,Process managers +DM-R3,doc 03 2,Command target id rule +DC-1,ADR-004,Module-declared JSON context +DC-3,doc 03 6.1,Reaction API shape +GAP-09,product 06,Idempotency key scoping +GAP-10,product 06,Unknown types are never deserialized +GAP-16,product 06,No assembly scanning +NFR-PERF-07,product 05,Size limits before the outbox insert +ADR-008,ADRs,Optimistic concurrency +ADR-010,ADRs,Commit-ordered global position +ES-R1,doc 05 5.3,Stream write first +ES-R2,doc 05 3.1,One stream per session +GAP-15,product 06,Not-found semantics +ADR-002,ADRs,Event sourcing +ADR-007,ADRs,Single command ownership +ADR-012,ADRs,One middleware abstraction +RT-R1,doc 04 3,Owned xor routed +RT-R4,doc 04 3,One subscription per service +RT-R5,doc 04 3,Logical names +GAP-03,product 06,No inert options +GAP-05,product 06,Concurrency on append +GAP-11,product 06,One dead-letter view +GAP-13,product 06,Per-service fan-out +GAP-20,product 06,Default ids rejected +ARCH-04,ADR-027,Domain code uses only contract namespaces +ADR-014,ADRs,Transport SPI and conformance kit +doc 05 8.1,doc 05,Snapshots with schema hash +ADR-009,ADRs,Event store on ADO.NET with PostgreSQL first +ADR-028,ADRs,PostgreSQL payload columns keep exact JSON bytes +GAP-04,product 06,Versioned schema migrations without swallowed errors +ADR-022,ADRs,Conjoined multi-tenancy with row-level security +doc 05 8.2,doc 05,Aggregate state cache +ADR-023,ADRs,SFQL query language with CESQL predicates +ADR-026,ADRs,Per-service query API with SQL syntax and injection-proof compilation +doc 14 6,doc 14,Query consistency levels and at_least tokens +doc 14 7.4,doc 14,Keyset pagination with continuation tokens +doc 14 9.5,doc 14,In-process IQueryService +doc 14 12,doc 14,Cross-provider query equivalence and injection corpus +doc 14 2.1,doc 14,Schema catalog generation +doc 14 2.2,doc 14,Schema registration, compatibility and export +Q-R1,doc 14,Writes never read through the query side (SF0015/SF0016) +Q-B4,doc 14,Named domain queries +GAP-02,product 06,One AWS endpoint and receiver per service with raw delivery +ADR-017,ADRs,Provisioning modes and topology as data +doc 07 6,doc 07,Transport options are honoured +doc 07 3,doc 07,Topology model, ordering declarations, naming and the broker dead-letter ingestor +doc 07 5,doc 07,Provisioning modes, topology export and IaC modules diff --git a/web/.gitignore b/web/.gitignore new file mode 100644 index 00000000..5cfc17c4 --- /dev/null +++ b/web/.gitignore @@ -0,0 +1,9 @@ +node_modules/ +dist/ +coverage/ +*.tsbuildinfo +test-results/ +playwright-report/ + +# The static-site CLI (npx @sourceflow/studio build) lives in app/bin, which the repository-wide .NET rule ignores. +!app/bin/ diff --git a/web/actions/workflow-diff/README.md b/web/actions/workflow-diff/README.md new file mode 100644 index 00000000..e71ef63c --- /dev/null +++ b/web/actions/workflow-diff/README.md @@ -0,0 +1,54 @@ +# SourceFlow workflow diff + +A GitHub Action for pull requests that change SourceFlow workflow files (`*.sfflow.yaml`). For each changed workflow it: + +- draws the statechart before and after the change, as SVG files, with what was added (+), removed (−) or changed (△) marked by a word as well as a colour; +- lists the changes in words; +- comments once on the pull request with that list and Mermaid diagrams (GitHub draws them), and updates the same comment on every push. + +It uses the same core as SourceFlow Studio and the build (the workflow engine compiled to WebAssembly), so the picture is what the generated process manager runs. Nothing leaves the runner except the comment. + +## Usage + +```yaml +on: + pull_request: + paths: [ "**/*.sfflow.yaml" ] + +permissions: + contents: read + pull-requests: write + +jobs: + diff: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 # the base commit's files too + - uses: sourceflow/workflow-diff@v1 + with: + out: workflow-diff + - uses: actions/upload-artifact@v4 + with: + name: workflow-diff + path: workflow-diff + if-no-files-found: ignore +``` + +| Input | Default | | +|-------|---------|--| +| `token` | `github.token` | Comments with it (needs `pull-requests: write`). | +| `base`, `head` | the pull request's | The commits to compare. | +| `out` | `workflow-diff` | Where the SVGs go: `.before.svg` and `.after.svg`. | +| `theme` | `light` | `light` or `dark`. | +| `comment` | `true` | `false` only writes the SVGs (for example on pull requests from forks, whose token is read-only). | +| `artifact` | `workflow-diff` | The artifact name the comment points to. | + +Outputs: `changed` (how many workflow files changed) and `out`. + +A workflow that can't be read is reported in the comment with the core's message, without a picture. A change to comments or formatting only is reported as "no change to the statechart". + +## Building + +In `web/`: `npm run build:wasm`, then `npm run build:action`. That writes `dist/main.js` (everything bundled) and `dist/framework` (the WebAssembly core); `action.yml` runs `dist/main.js` on Node 24. This repository runs it from source in `.github/workflows/workflow-diff.yml`. Publishing it as `sourceflow/workflow-diff` means pushing `action.yml`, `README.md` and `dist/` to that repository and tagging a release. diff --git a/web/actions/workflow-diff/action.yml b/web/actions/workflow-diff/action.yml new file mode 100644 index 00000000..7a9468b9 --- /dev/null +++ b/web/actions/workflow-diff/action.yml @@ -0,0 +1,38 @@ +# SourceFlow workflow diff (doc 15 §6.3, WFD-36): on a pull request, draws the statechart of every changed +# *.sfflow.yaml before and after the change, marks what was added, removed and changed, writes the SVGs to a folder +# (upload it as an artifact) and comments a summary with Mermaid diagrams on the pull request. +name: SourceFlow workflow diff +description: Before/after statecharts of the workflow files a pull request changes, as SVGs and a PR comment. +branding: + icon: git-pull-request + color: blue +inputs: + token: + description: Token to comment with (needs pull-requests write). + default: ${{ github.token }} + base: + description: The base commit (default the pull request's base). + required: false + head: + description: The head commit (default the pull request's head). + required: false + out: + description: Where to write the SVGs. + default: workflow-diff + theme: + description: light or dark. + default: light + comment: + description: Comment on the pull request (true or false). + default: "true" + artifact: + description: The artifact name the SVGs are uploaded as, named in the comment. + default: workflow-diff +outputs: + changed: + description: How many workflow files changed. + out: + description: The folder with the SVGs. +runs: + using: node24 + main: dist/main.js diff --git a/web/actions/workflow-diff/package.json b/web/actions/workflow-diff/package.json new file mode 100644 index 00000000..7f3ea3f1 --- /dev/null +++ b/web/actions/workflow-diff/package.json @@ -0,0 +1,23 @@ +{ + "name": "@sourceflow/workflow-diff", + "version": "0.1.0", + "private": true, + "description": "GitHub Action: before/after statecharts of the *.sfflow.yaml files a pull request changes, as SVG files and a PR comment (doc 15 §6.3, WFD-36).", + "license": "MIT", + "type": "module", + "scripts": { + "build": "vite build && node scripts/bundle-framework.mjs", + "typecheck": "tsc --noEmit -p .", + "test": "vitest run" + }, + "dependencies": { + "@sourceflow/core-client": "*", + "elkjs": "0.12.1" + }, + "devDependencies": { + "@types/node": "22.20.5", + "typescript": "6.0.3", + "vite": "8.3.5", + "vitest": "5.0.5" + } +} diff --git a/web/actions/workflow-diff/scripts/bundle-framework.mjs b/web/actions/workflow-diff/scripts/bundle-framework.mjs new file mode 100644 index 00000000..182705a9 --- /dev/null +++ b/web/actions/workflow-diff/scripts/bundle-framework.mjs @@ -0,0 +1,22 @@ +// Copies the WebAssembly core into dist/framework for the bundled action: dotnet.js and the files it names (a publish +// folder can hold stale fingerprinted copies). The source is SOURCEFLOW_STUDIO_WASM or the repository's artifacts. +import { copyFileSync, existsSync, mkdirSync } from 'node:fs'; +import { dirname, join, resolve } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { frameworkFiles } from '../../../app/bin/studio.mjs'; + +const here = dirname(fileURLToPath(import.meta.url)); +const source = resolve(process.env.SOURCEFLOW_STUDIO_WASM ?? join(here, '..', '..', '..', '..', 'artifacts', 'studio-wasm', 'wwwroot', '_framework')); +if (!existsSync(join(source, 'dotnet.js'))) { + console.error(`No WebAssembly core in ${source}: run 'npm run build:wasm' in web/ first.`); + process.exit(1); +} + +const target = join(here, '..', 'dist', 'framework'); +mkdirSync(target, { recursive: true }); +const files = frameworkFiles(source); +for (const name of files) { + copyFileSync(join(source, name), join(target, name)); +} + +console.log(`Bundled the core (${files.length} files) into ${target}`); diff --git a/web/actions/workflow-diff/src/diff.ts b/web/actions/workflow-diff/src/diff.ts new file mode 100644 index 00000000..b4d17f0f --- /dev/null +++ b/web/actions/workflow-diff/src/diff.ts @@ -0,0 +1,220 @@ +// What the workflow-diff action computes for a pull request (doc 15 §6.3, WFD-36): for every *.sfflow.yaml the range +// changes, the statechart before and after (drawn by the Studio's own SVG renderer, with the changes marked), the +// changes in words, and Mermaid diagrams for the comment. Git gives the two texts; the core draws the graphs. +import type { GraphResult, StudioCoreClient } from '@sourceflow/core-client'; +import { execFileSync } from 'node:child_process'; +import { mkdirSync, writeFileSync } from 'node:fs'; +import { join } from 'node:path'; +import { describeDiff, diffGraphs, type GraphDiff } from '../../../app/src/graph/diff.ts'; +import type { LayoutEngine } from '../../../app/src/graph/layout.ts'; +import { statechartPositions } from '../../../app/src/graph/statechart.ts'; +import { statechartSvg, type Mark, type SvgTheme } from '../../../app/src/graph/svg.ts'; + +export const MARKER = ''; + +/** GitHub's limit on a comment's length. */ +export const COMMENT_LIMIT = 65_536; + +export type Core = Pick; + +export interface DiffOptions { + /** The repository's working folder. */ + cwd: string; + base: string; + head: string; + core: Core; + layout: LayoutEngine; + /** Where to write the SVGs (none: not written). */ + out?: string; + theme?: SvgTheme; +} + +export interface Side { + graph?: GraphResult; + svg?: string; + mermaid?: string; + /** Why it can't be drawn (the core's message). */ + error?: string; +} + +export interface FileDiff { + path: string; + status: 'added' | 'removed' | 'modified'; + before?: Side; + after?: Side; + changes: string[]; + /** The statechart is the same (the text changed in comments or layout only). */ + unchanged: boolean; + /** The SVG files written, relative to `out`. */ + files: string[]; +} + +function git(cwd: string, args: string[]): string { + return execFileSync('git', args, { cwd, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'] }); +} + +/** The workflow files the range changes, sorted. */ +export function changedWorkflows(cwd: string, base: string, head: string): string[] { + return git(cwd, ['diff', '--name-only', '--no-renames', '-z', base, head, '--', '*.sfflow.yaml']) + .split('\0') + .filter((p) => p.endsWith('.sfflow.yaml')) + .sort(); +} + +function textAt(cwd: string, commit: string, path: string): string | undefined { + try { + return git(cwd, ['show', `${commit}:${path}`]); + } catch { + return undefined; // not in that commit + } +} + +async function draw(core: Core, layout: LayoutEngine, text: string): Promise { + try { + const graph = await core.graph({ yaml: text }); + return { graph, mermaid: (await core.toMermaid({ yaml: text })).text }; + } catch (error) { + return { error: (error as Error).message }; + } +} + +async function picture(side: Side, layout: LayoutEngine, marks: Map, theme: SvgTheme, title: string): Promise { + if (side.graph !== undefined) { + side.svg = statechartSvg(side.graph, await statechartPositions(side.graph, layout), { theme, title, marks }); + } +} + +/** A file name for a workflow path: its folders joined with '__'. */ +export function svgName(path: string, side: 'before' | 'after'): string { + return `${path.replace(/\.sfflow\.yaml$/, '').replace(/[\\/]/g, '__').replace(/[^A-Za-z0-9_.-]/g, '-')}.${side}.svg`; +} + +/** Diffs every changed workflow of `base..head`. */ +export async function workflowDiff(options: DiffOptions): Promise { + const theme = options.theme ?? 'light'; + const results: FileDiff[] = []; + for (const path of changedWorkflows(options.cwd, options.base, options.head)) { + const beforeText = textAt(options.cwd, options.base, path); + const afterText = textAt(options.cwd, options.head, path); + const before = beforeText === undefined ? undefined : await draw(options.core, options.layout, beforeText); + const after = afterText === undefined ? undefined : await draw(options.core, options.layout, afterText); + const diff: GraphDiff = diffGraphs(before?.graph, after?.graph); + if (before !== undefined) { + await picture(before, options.layout, diff.before, theme, `${path} before`); + } + + if (after !== undefined) { + await picture(after, options.layout, diff.after, theme, `${path} after`); + } + + const file: FileDiff = { + path, + status: before === undefined ? 'added' : after === undefined ? 'removed' : 'modified', + ...(before === undefined ? {} : { before: { ...before, ...(before.mermaid === undefined ? {} : { mermaid: markMermaid(before.mermaid, before.graph!, diff.before) }) } }), + ...(after === undefined ? {} : { after: { ...after, ...(after.mermaid === undefined ? {} : { mermaid: markMermaid(after.mermaid, after.graph!, diff.after) }) } }), + changes: before?.error !== undefined || after?.error !== undefined ? [] : describeDiff(diff), + unchanged: before?.graph !== undefined && after?.graph !== undefined && diff.unchanged, + files: [], + }; + if (options.out !== undefined) { + mkdirSync(options.out, { recursive: true }); + for (const side of ['before', 'after'] as const) { + const svg = file[side]?.svg; + if (svg !== undefined) { + const name = svgName(path, side); + writeFileSync(join(options.out, name), svg); + file.files.push(name); + } + } + } + + results.push(file); + } + + return results; +} + +const MERMAID_CLASSES = [ + ' classDef added fill:#dafbe1,stroke:#1a7f37,stroke-width:3px', + ' classDef removed fill:#ffebe9,stroke:#b42318,stroke-width:3px,stroke-dasharray:5 3', + ' classDef changed fill:#fff8c5,stroke:#9a6700,stroke-width:3px', +]; + +/** Adds Mermaid classes for the marked states (Mermaid can't style transitions, so the comment lists those in words). */ +export function markMermaid(mermaid: string, graph: GraphResult, marks: ReadonlyMap): string { + const ids = new Map(); + for (const match of mermaid.matchAll(/^\s*state "([^"]+)" as (\S+)/gm)) { + ids.set(match[1]!, match[2]!); + } + + const byMark = new Map(); + for (const node of graph.nodes) { + const mark = marks.get(node.id); + const id = ids.get(node.label) ?? ids.get(node.id) ?? (/^[A-Za-z_][A-Za-z0-9_]*$/.test(node.id) && mermaid.includes(node.id) ? node.id : undefined); + if (mark !== undefined && id !== undefined) { + byMark.set(mark, [...(byMark.get(mark) ?? []), id]); + } + } + + if (byMark.size === 0) { + return mermaid; + } + + const lines = [...MERMAID_CLASSES, ...[...byMark].map(([mark, list]) => ` class ${list.join(',')} ${mark}`)]; + return mermaid.replace(/\s*$/, '\n') + lines.join('\n') + '\n'; +} + +export interface CommentOptions { + /** The artifact the SVGs are uploaded as. */ + artifact?: string; + /** A link to the run (its artifacts). */ + runUrl?: string; +} + +function mermaidBlock(title: string, side: Side | undefined, open: boolean): string { + if (side?.mermaid === undefined) { + return ''; + } + + return `${title}\n\n\`\`\`mermaid\n${side.mermaid.trimEnd()}\n\`\`\`\n\n\n`; +} + +/** The pull request comment. */ +export function comment(files: readonly FileDiff[], options: CommentOptions = {}, withDiagrams = true): string { + const parts = [MARKER, '## Workflow changes', '']; + if (files.length === 0) { + parts.push('This pull request no longer changes any workflow.'); + return parts.join('\n') + '\n'; + } + + parts.push(`${files.length} workflow file${files.length === 1 ? '' : 's'} changed. Legend: + added, − removed, △ changed.`, ''); + for (const file of files) { + parts.push(`### \`${file.path}\` · ${file.status}`, ''); + const broken = [file.before?.error === undefined ? undefined : `before: ${file.before.error}`, file.after?.error === undefined ? undefined : `after: ${file.after.error}`] + .filter((e) => e !== undefined); + if (broken.length > 0) { + parts.push(...broken.map((b) => `> ✕ The statechart can't be drawn ${b}`), ''); + } else if (file.unchanged) { + parts.push('No change to the statechart (comments or formatting only).', ''); + } else { + const shown = file.changes.slice(0, 50); + parts.push(...shown.map((c) => `- ${c}`)); + if (file.changes.length > shown.length) { + parts.push(`- … and ${file.changes.length - shown.length} more`); + } + + parts.push(''); + } + + if (withDiagrams && !file.unchanged) { + parts.push(mermaidBlock('Before', file.before, false) + mermaidBlock('After', file.after, true)); + } + } + + if (options.artifact !== undefined) { + parts.push(`The before and after SVGs are in the \`${options.artifact}\` artifact${options.runUrl === undefined ? '' : ` of [this run](${options.runUrl})`}.`); + } + + const body = parts.join('\n') + '\n'; + return body.length > COMMENT_LIMIT && withDiagrams ? comment(files, options, false).replace('## Workflow changes\n', '## Workflow changes\n\n(The diagrams are left out: the comment would be too long. See the SVGs.)\n') : body; +} diff --git a/web/actions/workflow-diff/src/github.ts b/web/actions/workflow-diff/src/github.ts new file mode 100644 index 00000000..d51bec0c --- /dev/null +++ b/web/actions/workflow-diff/src/github.ts @@ -0,0 +1,68 @@ +// The one comment the action keeps on a pull request: found by its marker, updated in place, created once. +import { MARKER } from './diff.ts'; + +export interface GitHubTarget { + /** https://api.github.com, or the GitHub Enterprise API. */ + api: string; + token: string; + /** owner/name */ + repository: string; + issue: number; +} + +export type Fetcher = (url: string, init?: RequestInit) => Promise; + +async function call(fetcher: Fetcher, target: GitHubTarget, method: string, path: string, body?: unknown): Promise { + const response = await fetcher(target.api.replace(/\/$/, '') + path, { + method, + headers: { + Accept: 'application/vnd.github+json', + Authorization: `Bearer ${target.token}`, + 'X-GitHub-Api-Version': '2022-11-28', + 'User-Agent': 'sourceflow-workflow-diff', + ...(body === undefined ? {} : { 'Content-Type': 'application/json' }), + }, + ...(body === undefined ? {} : { body: JSON.stringify(body) }), + }); + if (!response.ok) { + throw new Error(`GitHub ${method} ${path}: ${response.status} ${await response.text()}`); + } + + return response.status === 204 ? undefined : response.json(); +} + +/** The action's earlier comment on the pull request, if any. */ +export async function findComment(target: GitHubTarget, fetcher: Fetcher = fetch): Promise { + for (let page = 1; page <= 50; page++) { + const comments = (await call(fetcher, target, 'GET', `/repos/${target.repository}/issues/${target.issue}/comments?per_page=100&page=${page}`)) as Array<{ id: number; body?: string }>; + const found = comments.find((c) => c.body?.startsWith(MARKER) === true); + if (found !== undefined) { + return found.id; + } + + if (comments.length < 100) { + return undefined; + } + } + + return undefined; +} + +/** + * Writes the comment: updates the earlier one, or creates it. With nothing to say (`create` false) and no earlier + * comment, it does nothing. Returns what it did. + */ +export async function upsertComment(target: GitHubTarget, body: string, create = true, fetcher: Fetcher = fetch): Promise<'created' | 'updated' | 'skipped'> { + const existing = await findComment(target, fetcher); + if (existing !== undefined) { + await call(fetcher, target, 'PATCH', `/repos/${target.repository}/issues/comments/${existing}`, { body }); + return 'updated'; + } + + if (!create) { + return 'skipped'; + } + + await call(fetcher, target, 'POST', `/repos/${target.repository}/issues/${target.issue}/comments`, { body }); + return 'created'; +} diff --git a/web/actions/workflow-diff/src/main.ts b/web/actions/workflow-diff/src/main.ts new file mode 100644 index 00000000..11570cef --- /dev/null +++ b/web/actions/workflow-diff/src/main.ts @@ -0,0 +1,78 @@ +// The action's entry point: inputs from the runner, the pull request from its event, then diff, SVGs and the comment. +import { createInProcessClient } from '@sourceflow/core-client/node'; +import ELK from 'elkjs/lib/elk.bundled.js'; +import { appendFileSync, readFileSync } from 'node:fs'; +import { resolve } from 'node:path'; +import { pathToFileURL } from 'node:url'; +import { elkEngine } from '../../../app/src/graph/layout.ts'; +import { comment, workflowDiff, type FileDiff } from './diff.ts'; +import { upsertComment, type Fetcher } from './github.ts'; + +export interface RunEnvironment { + env: Record; + log: (line: string) => void; + fetcher?: Fetcher; + /** The core's _framework folder as a URL (default: the one bundled beside the action). */ + frameworkUrl?: string; +} + +function input(env: Record, name: string): string | undefined { + const value = env[`INPUT_${name.toUpperCase()}`]?.trim(); + return value === undefined || value === '' ? undefined : value; +} + +interface PullRequestEvent { + number?: number; + pull_request?: { number: number; base: { sha: string }; head: { sha: string } }; +} + +/** Runs the action; returns the changed files. */ +export async function run({ env, log, fetcher, frameworkUrl }: RunEnvironment): Promise { + const event = env.GITHUB_EVENT_PATH === undefined ? {} : (JSON.parse(readFileSync(env.GITHUB_EVENT_PATH, 'utf8')) as PullRequestEvent); + const base = input(env, 'base') ?? event.pull_request?.base.sha; + const head = input(env, 'head') ?? event.pull_request?.head.sha; + if (base === undefined || head === undefined) { + throw new Error('No base and head: run the action on pull_request, or give it the base and head inputs.'); + } + + const cwd = env.GITHUB_WORKSPACE ?? process.cwd(); + const out = resolve(cwd, input(env, 'out') ?? 'workflow-diff'); + const theme = input(env, 'theme') === 'dark' ? 'dark' : 'light'; + const core = createInProcessClient(frameworkUrl ?? new URL('./framework/', import.meta.url).href); + try { + const files = await workflowDiff({ cwd, base, head, core, layout: elkEngine(new ELK()), out, theme }); + log(`${files.length} workflow file(s) changed between ${base.slice(0, 7)} and ${head.slice(0, 7)}.`); + for (const file of files) { + log(` ${file.status} ${file.path}: ${file.unchanged ? 'same statechart' : `${file.changes.length} change(s)`}${file.files.length > 0 ? ` -> ${file.files.join(', ')}` : ''}`); + } + + const issue = event.pull_request?.number ?? event.number; + if (input(env, 'comment') !== 'false' && issue !== undefined && env.GITHUB_REPOSITORY !== undefined) { + const runUrl = env.GITHUB_RUN_ID === undefined ? undefined : `${env.GITHUB_SERVER_URL ?? 'https://github.com'}/${env.GITHUB_REPOSITORY}/actions/runs/${env.GITHUB_RUN_ID}`; + const body = comment(files, { artifact: input(env, 'artifact') ?? 'workflow-diff', ...(runUrl === undefined ? {} : { runUrl }) }); + const done = await upsertComment( + { api: env.GITHUB_API_URL ?? 'https://api.github.com', token: input(env, 'token') ?? '', repository: env.GITHUB_REPOSITORY, issue }, + body, + files.length > 0, + fetcher, + ); + log(`Comment ${done}.`); + } + + if (env.GITHUB_OUTPUT !== undefined) { + appendFileSync(env.GITHUB_OUTPUT, `changed=${files.length}\nout=${out}\n`); + } + + return files; + } finally { + core.dispose(); + } +} + +// Started by the runner (dist/main.js), not imported by the tests. +if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) { + run({ env: process.env, log: (line) => console.log(line) }).catch((error: unknown) => { + console.log(`::error::${(error as Error).message}`); + process.exitCode = 1; + }); +} diff --git a/web/actions/workflow-diff/test/action.test.ts b/web/actions/workflow-diff/test/action.test.ts new file mode 100644 index 00000000..e1c13d2e --- /dev/null +++ b/web/actions/workflow-diff/test/action.test.ts @@ -0,0 +1,213 @@ +// The workflow-diff action against a fixture repository (plan 10 WP-S.12): a git repository whose pull request adds, +// removes, changes and breaks workflows; the real core (WebAssembly in Node) and ELK; and a fake GitHub API that keeps +// the comments, so the action's comment is created once and then updated. +import { execFileSync } from 'node:child_process'; +import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs'; +import { createServer, type Server } from 'node:http'; +import type { AddressInfo } from 'node:net'; +import { tmpdir } from 'node:os'; +import { dirname, join, resolve } from 'node:path'; +import { fileURLToPath, pathToFileURL } from 'node:url'; +import { afterAll, beforeAll, describe, expect, it } from 'vitest'; +import { comment, COMMENT_LIMIT, MARKER, type FileDiff } from '../src/diff.ts'; +import { run } from '../src/main.ts'; + +const repository = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', '..', '..'); +const golden = (name: string) => readFileSync(join(repository, 'tests', 'Golden', 'cases', name, 'workflow.sfflow.yaml'), 'utf8'); +const frameworkDir = process.env.SOURCEFLOW_STUDIO_WASM ?? join(repository, 'artifacts', 'studio-wasm', 'wwwroot', '_framework'); +const frameworkUrl = pathToFileURL(frameworkDir).href + '/'; + +interface Stored { + id: number; + body: string; +} + +let root: string; +let repo: string; +let server: Server; +let api: string; +const comments: Stored[] = []; +const requests: Array<{ method: string; url: string; auth: string | undefined }> = []; + +function git(...args: string[]): string { + return execFileSync('git', ['-c', 'user.name=Fixture', '-c', 'user.email=fixture@example.invalid', '-c', 'commit.gpgsign=false', ...args], { cwd: repo, encoding: 'utf8' }).trim(); +} + +function write(path: string, text: string) { + mkdirSync(dirname(join(repo, path)), { recursive: true }); + writeFileSync(join(repo, path), text); +} + +function event(base: string, head: string, number = 7): string { + const file = join(root, `event-${number}-${head}.json`); + writeFileSync(file, JSON.stringify({ number, pull_request: { number, base: { sha: base }, head: { sha: head } } })); + return file; +} + +function env(eventPath: string, extra: Record = {}) { + return { + GITHUB_EVENT_PATH: eventPath, + GITHUB_WORKSPACE: repo, + GITHUB_REPOSITORY: 'acme/shop', + GITHUB_API_URL: api, + GITHUB_SERVER_URL: 'https://github.example', + GITHUB_RUN_ID: '42', + GITHUB_OUTPUT: join(root, 'output.txt'), + INPUT_TOKEN: 'secret-token', + INPUT_OUT: 'diff', + ...extra, + }; +} + +let base: string; +let head: string; + +beforeAll(async () => { + root = mkdtempSync(join(tmpdir(), 'sourceflow-diff-')); + repo = join(root, 'repo'); + mkdirSync(repo); + git('init', '-q', '-b', 'main'); + write('README.md', '# shop\n'); + write('orders/workflows/order-fulfilment.sfflow.yaml', golden('01-order-fulfilment')); + write('orders/workflows/minimal.sfflow.yaml', golden('02-minimal')); + write('orders/workflows/retired.sfflow.yaml', golden('28-retries-and-backoff')); + git('add', '.'); + git('commit', '-q', '-m', 'base'); + base = git('rev-parse', 'HEAD'); + + // The pull request: a changed timeout and a timeout that now compensates, a comment-only edit, a new workflow, a + // deleted one, and one that no longer parses. + write('orders/workflows/order-fulfilment.sfflow.yaml', golden('01-order-fulfilment') + .replace('timeout: { after: PT5M, retry: { max: 2 }, then: fail }', 'timeout: { after: PT10M, retry: { max: 2 }, then: fail }') + .replace('timeout: { after: P1D, then: manual }', 'timeout: { after: P1D, then: fail }')); + write('orders/workflows/minimal.sfflow.yaml', '# Approves orders.\n' + golden('02-minimal')); + write('orders/workflows/returns.sfflow.yaml', golden('27-local-steps')); + rmSync(join(repo, 'orders/workflows/retired.sfflow.yaml')); + write('orders/workflows/broken.sfflow.yaml', golden('03-s01-invalid-yaml')); + write('docs/notes.md', 'not a workflow\n'); + git('add', '-A'); + git('commit', '-q', '-m', 'change workflows'); + head = git('rev-parse', 'HEAD'); + + server = createServer((request, response) => { + let body = ''; + request.on('data', (chunk: Buffer) => (body += chunk.toString('utf8'))); + request.on('end', () => { + requests.push({ method: request.method!, url: request.url!, auth: request.headers.authorization }); + const url = new URL(request.url!, 'http://localhost'); + if (request.method === 'GET' && url.pathname === '/repos/acme/shop/issues/7/comments') { + response.writeHead(200, { 'Content-Type': 'application/json' }).end(JSON.stringify([{ id: 1, body: 'LGTM' }, ...comments])); + } else if (request.method === 'GET' && url.pathname.startsWith('/repos/acme/shop/issues/')) { + response.writeHead(200, { 'Content-Type': 'application/json' }).end('[]'); + } else if (request.method === 'POST' && url.pathname === '/repos/acme/shop/issues/7/comments') { + comments.push({ id: 100 + comments.length, body: (JSON.parse(body) as { body: string }).body }); + response.writeHead(201, { 'Content-Type': 'application/json' }).end('{}'); + } else if (request.method === 'PATCH' && url.pathname.startsWith('/repos/acme/shop/issues/comments/')) { + const stored = comments.find((c) => c.id === Number(url.pathname.split('/').at(-1)))!; + stored.body = (JSON.parse(body) as { body: string }).body; + response.writeHead(200, { 'Content-Type': 'application/json' }).end('{}'); + } else { + response.writeHead(404).end('{}'); + } + }); + }); + await new Promise((done) => server.listen(0, '127.0.0.1', done)); + api = `http://127.0.0.1:${(server.address() as AddressInfo).port}`; +}); + +afterAll(async () => { + await new Promise((done) => server.close(() => done())); + rmSync(root, { recursive: true, force: true }); +}); + +describe('the workflow-diff action', () => { + it('draws before and after, marks the changes, and comments once on the pull request', async () => { + const logs: string[] = []; + const files = await run({ env: env(event(base, head)), log: (l) => logs.push(l), frameworkUrl }); + + expect(files.map((f) => [f.path, f.status])).toEqual([ + ['orders/workflows/broken.sfflow.yaml', 'added'], + ['orders/workflows/minimal.sfflow.yaml', 'modified'], + ['orders/workflows/order-fulfilment.sfflow.yaml', 'modified'], + ['orders/workflows/retired.sfflow.yaml', 'removed'], + ['orders/workflows/returns.sfflow.yaml', 'added'], + ]); + const [broken, minimal, fulfilment, retired, returns] = files as [FileDiff, FileDiff, FileDiff, FileDiff, FileDiff]; + expect(broken.after?.error).toBeDefined(); + expect(minimal.unchanged).toBe(true); + expect(fulfilment.changes).toContain('△ Changed step reserve-stock: timeout PT5M → PT10M'); + expect(fulfilment.changes.some((c) => c.startsWith('+ Added timeout review-large-order → Compensating'))).toBe(true); + expect(fulfilment.changes.some((c) => c.startsWith('− Removed timeout review-large-order → ManualIntervention'))).toBe(true); + expect(retired.changes.every((c) => c.startsWith('− Removed'))).toBe(true); + expect(returns.changes.every((c) => c.startsWith('+ Added'))).toBe(true); + + // The SVGs, with the changes marked on each side. + const out = join(repo, 'diff'); + expect(readdirSync(out).sort()).toEqual([ + 'orders__workflows__minimal.after.svg', 'orders__workflows__minimal.before.svg', + 'orders__workflows__order-fulfilment.after.svg', 'orders__workflows__order-fulfilment.before.svg', + 'orders__workflows__retired.before.svg', 'orders__workflows__returns.after.svg', + ]); + const after = readFileSync(join(out, 'orders__workflows__order-fulfilment.after.svg'), 'utf8'); + expect(after).toContain('orders/workflows/order-fulfilment.sfflow.yaml after'); + expect(after).toContain('△ changed'); + expect(after).toContain('+ added'); + expect(readFileSync(join(out, 'orders__workflows__order-fulfilment.before.svg'), 'utf8')).toContain('− removed'); + expect(readFileSync(join(out, 'orders__workflows__minimal.after.svg'), 'utf8')).not.toMatch(/added|removed|changed/); + + // One comment, with the summary, the Mermaid diagrams and the way to the SVGs. + expect(comments).toHaveLength(1); + const body = comments[0]!.body; + expect(body.startsWith(MARKER)).toBe(true); + expect(body).toContain('5 workflow files changed.'); + expect(body).toContain('### `orders/workflows/order-fulfilment.sfflow.yaml` · modified'); + expect(body).toContain('- △ Changed step reserve-stock: timeout PT5M → PT10M'); + expect(body).toContain('No change to the statechart (comments or formatting only).'); + expect(body).toMatch(/> ✕ The statechart can't be drawn after: /); + expect(body).toContain('```mermaid\n---\ntitle: order-fulfilment@1 (orders)'); + expect(body).toContain(' classDef changed fill:#fff8c5'); + expect(body).toContain(' class reserve_stock changed'); + expect(body).toContain('The before and after SVGs are in the `workflow-diff` artifact of [this run](https://github.example/acme/shop/actions/runs/42).'); + expect(requests.every((r) => r.auth === 'Bearer secret-token')).toBe(true); + expect(readFileSync(join(root, 'output.txt'), 'utf8')).toContain('changed=5\n'); + expect(logs[0]).toBe(`5 workflow file(s) changed between ${base.slice(0, 7)} and ${head.slice(0, 7)}.`); + + // A new push updates the same comment. + write('orders/workflows/returns.sfflow.yaml', golden('27-local-steps').replace(/^description: .*$/m, 'description: Returns.')); + git('commit', '-q', '-am', 'tweak'); + const next = git('rev-parse', 'HEAD'); + await run({ env: env(event(base, next)), log: () => undefined, frameworkUrl }); + expect(comments).toHaveLength(1); + expect(requests.filter((r) => r.method === 'PATCH')).toHaveLength(1); + + // A pull request that no longer changes workflows says so; one that never did gets no comment. + await run({ env: env(event(base, base)), log: () => undefined, frameworkUrl }); + expect(comments[0]!.body).toContain('This pull request no longer changes any workflow.'); + const before = requests.length; + await run({ env: env(event(base, base, 8)), log: () => undefined, frameworkUrl }); + expect(requests.slice(before).map((r) => r.method)).toEqual(['GET']); + expect(comments).toHaveLength(1); + + // comment: false only writes the SVGs. + const quiet = requests.length; + rmSync(join(repo, 'diff'), { recursive: true }); + await run({ env: env(event(base, head), { INPUT_COMMENT: 'false', INPUT_THEME: 'dark' }), log: () => undefined, frameworkUrl }); + expect(requests.length).toBe(quiet); + expect(readFileSync(join(out, 'orders__workflows__returns.after.svg'), 'utf8')).toContain('fill="#15181c"'); + }); + + it('needs a pull request or the base and head', async () => { + await expect(run({ env: { GITHUB_WORKSPACE: repo }, log: () => undefined, frameworkUrl })).rejects.toThrow('No base and head'); + const files = await run({ env: { GITHUB_WORKSPACE: repo, INPUT_BASE: base, INPUT_HEAD: head, INPUT_OUT: 'by-input' }, log: () => undefined, frameworkUrl }); + expect(files).toHaveLength(5); + expect(existsSync(join(repo, 'by-input', 'orders__workflows__returns.after.svg'))).toBe(true); + }); + + it('leaves the diagrams out of a comment that would be too long', () => { + const big: FileDiff = { path: 'a.sfflow.yaml', status: 'modified', changes: ['△ x'], unchanged: false, files: [], after: { mermaid: 'stateDiagram-v2\n' + 'x\n'.repeat(COMMENT_LIMIT) } }; + const body = comment([big], { artifact: 'workflow-diff' }); + expect(body.length).toBeLessThan(COMMENT_LIMIT); + expect(body).toContain('(The diagrams are left out: the comment would be too long. See the SVGs.)'); + expect(body).not.toContain('```mermaid'); + }); +}); diff --git a/web/actions/workflow-diff/tsconfig.json b/web/actions/workflow-diff/tsconfig.json new file mode 100644 index 00000000..98b2147d --- /dev/null +++ b/web/actions/workflow-diff/tsconfig.json @@ -0,0 +1,19 @@ +{ + "compilerOptions": { + "target": "ES2022", + "lib": ["ES2022", "DOM"], + "module": "ESNext", + "moduleResolution": "Bundler", + "allowImportingTsExtensions": true, + "verbatimModuleSyntax": true, + "erasableSyntaxOnly": true, + "noEmit": true, + "strict": true, + "noUncheckedIndexedAccess": true, + "exactOptionalPropertyTypes": true, + "noImplicitOverride": true, + "skipLibCheck": true, + "types": ["node"] + }, + "include": ["src", "test", "vitest.config.ts", "vite.config.ts"] +} diff --git a/web/actions/workflow-diff/vite.config.ts b/web/actions/workflow-diff/vite.config.ts new file mode 100644 index 00000000..92e68ab7 --- /dev/null +++ b/web/actions/workflow-diff/vite.config.ts @@ -0,0 +1,14 @@ +import { defineConfig } from 'vite'; + +// The action runs as one file on the runner's Node (action.yml: node24): everything is bundled except the WebAssembly +// core, which scripts/bundle-framework.mjs copies beside it (dist/framework) and main.ts loads at run time. +export default defineConfig({ + build: { + ssr: 'src/main.ts', + outDir: 'dist', + emptyOutDir: true, + target: 'node22', + rollupOptions: { output: { entryFileNames: 'main.js', format: 'es' } }, + }, + ssr: { noExternal: true, target: 'node' }, +}); diff --git a/web/actions/workflow-diff/vitest.config.ts b/web/actions/workflow-diff/vitest.config.ts new file mode 100644 index 00000000..a3108db4 --- /dev/null +++ b/web/actions/workflow-diff/vitest.config.ts @@ -0,0 +1,13 @@ +import { defineConfig } from 'vitest/config'; + +// The workflow-diff action against a fixture repository: real git, the real core (WebAssembly in Node), real ELK, and a +// fake GitHub API. +export default defineConfig({ + test: { + include: ['test/**/*.test.ts'], + testTimeout: 120_000, + hookTimeout: 120_000, + pool: 'forks', + server: { deps: { external: [/_framework[\/]/] } }, + }, +}); diff --git a/web/app/bin/studio.mjs b/web/app/bin/studio.mjs new file mode 100644 index 00000000..a9eb68ae --- /dev/null +++ b/web/app/bin/studio.mjs @@ -0,0 +1,151 @@ +#!/usr/bin/env node +// npx @sourceflow/studio build: a read-only static site of a domain workspace (doc 15 §6.3), for docs portals and +// static hosts. It writes the built Studio app, the WebAssembly core and a snapshot of the workspace (its manifests, +// workflows and layouts); the app opens it read-only, with hash routes, from any folder of any static host. +import { copyFileSync, cpSync, existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs'; +import { dirname, join, resolve } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { loadWorkspace, WorkspaceError } from './workspace.mjs'; + +const MARKER = '.sourceflow-site'; +const here = dirname(fileURLToPath(import.meta.url)); +const pkg = resolve(here, '..'); + +const USAGE = `Usage: npx @sourceflow/studio build [options] + +Builds a read-only static site of a domain workspace. + +Options: + --workspace sourceflow.domain.yaml, or the folder holding it (default: .) + --out where to write the site (default: site) + --assets the built Studio app (default: the package's dist) + --framework the WebAssembly core's _framework folder (default: the package's framework) + --help show this help`; + +export function parseArgs(argv) { + const [command, ...rest] = argv[0]?.startsWith('--') ? [undefined, ...argv] : argv; + const options = { command, workspace: '.', out: 'site', assets: undefined, framework: undefined }; + for (let i = 0; i < rest.length; i++) { + const arg = rest[i]; + const value = () => { + const next = rest[++i]; + if (next === undefined || next.startsWith('--')) { + throw new WorkspaceError(`${arg} needs a value.`); + } + + return next; + }; + switch (arg) { + case '--workspace': options.workspace = value(); break; + case '--out': options.out = value(); break; + case '--assets': options.assets = value(); break; + case '--framework': options.framework = value(); break; + case '--help': options.command = 'help'; break; + default: throw new WorkspaceError(`Unknown option '${arg}'.\n\n${USAGE}`); + } + } + + return options; +} + +function firstExisting(...candidates) { + return candidates.find((c) => c !== undefined && existsSync(c)); +} + +/** The core files the site needs: dotnet.js and every file it names (a publish folder can hold stale fingerprinted copies). */ +export function frameworkFiles(framework) { + const loader = readFileSync(join(framework, 'dotnet.js'), 'utf8'); + return readdirSync(framework).filter((name) => name === 'dotnet.js' || (!/\.(br|gz)$/.test(name) && loader.includes(name))); +} + +/** index.html for a static site: assets from its own folder, and the mark that switches the app to static mode. */ +export function staticIndex(html) { + const mark = ''; + const marked = html + .replace(/\s*/, '') // the local host's root; a static site is wherever it is served + .replace(/(src|href)="\/(assets\/)/g, '$1="./$2'); + return //i.test(marked) + ? marked.replace(/()/i, `$1\n ${mark}`) + : marked.replace('', `\n ${mark}`); +} + +/** Builds the site; returns what it wrote. */ +export function build(options, log = () => {}) { + const assets = resolve(options.assets ?? firstExisting(join(pkg, 'dist')) ?? join(pkg, 'dist')); + const framework = resolve(options.framework ?? firstExisting(join(pkg, 'framework'), join(pkg, '..', '..', 'artifacts', 'studio-wasm', 'wwwroot', '_framework')) ?? join(pkg, 'framework')); + if (!existsSync(join(assets, 'index.html'))) { + throw new WorkspaceError(`No built Studio app in ${assets}: run 'npm run build' in web/, or pass --assets.`); + } + + if (!existsSync(join(framework, 'dotnet.js'))) { + throw new WorkspaceError(`No WebAssembly core in ${framework}: run 'npm run build:wasm' in web/, or pass --framework.`); + } + + const { workspace, files } = loadWorkspace(options.workspace); + const out = resolve(options.out); + if (existsSync(out) && readdirSync(out).length > 0 && !existsSync(join(out, MARKER))) { + throw new WorkspaceError(`${out} isn't empty and isn't a Studio site: choose another --out, or empty it first.`); + } + + rmSync(out, { recursive: true, force: true }); + mkdirSync(out, { recursive: true }); + cpSync(assets, out, { recursive: true }); + writeFileSync(join(out, 'index.html'), staticIndex(readFileSync(join(assets, 'index.html'), 'utf8'))); + mkdirSync(join(out, '_framework')); + const core = frameworkFiles(framework); + for (const name of core) { + copyFileSync(join(framework, name), join(out, '_framework', name)); + } + + mkdirSync(join(out, 'data')); + writeFileSync(join(out, 'data', 'workspace.json'), JSON.stringify(workspace, null, 2) + '\n'); + writeFileSync(join(out, 'data', 'files.json'), JSON.stringify(files, null, 2) + '\n'); + writeFileSync(join(out, '.nojekyll'), ''); // GitHub Pages would drop _framework otherwise + writeFileSync(join(out, MARKER), 'Written by npx @sourceflow/studio build; the next build replaces this folder.\n'); + const workflows = workspace.services.reduce((n, s) => n + s.workflowFiles.length, 0); + log(`SourceFlow Studio site for '${workspace.domain}': ${workspace.services.length} services, ${workflows} workflows -> ${out}`); + return { out, workspace, files, core }; +} + +export function main(argv, log = console.log, error = console.error) { + try { + const options = parseArgs(argv); + if (options.command === 'help' || options.command === undefined) { + log(USAGE); + return options.command === 'help' ? 0 : 2; + } + + if (options.command !== 'build') { + error(`Unknown command '${options.command}'.\n\n${USAGE}`); + return 2; + } + + build(options, log); + return 0; + } catch (failure) { + if (failure instanceof WorkspaceError) { + error(failure.message); + return 1; + } + + throw failure; + } +} + +// Run when started as a program (npx links the package, so compare real paths), not when imported by the tests. +function isEntry() { + if (process.argv[1] === undefined) { + return false; + } + + try { + const same = (a, b) => (process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b); + return same(realpathSync(resolve(process.argv[1])), realpathSync(fileURLToPath(import.meta.url))); + } catch { + return false; + } +} + +if (isEntry()) { + process.exitCode = main(process.argv.slice(2)); +} diff --git a/web/app/bin/workspace.mjs b/web/app/bin/workspace.mjs new file mode 100644 index 00000000..c0297bbd --- /dev/null +++ b/web/app/bin/workspace.mjs @@ -0,0 +1,177 @@ +// Reads sourceflow.domain.yaml for the static build, with the rules of SourceFlow.Studio's DomainWorkspace (doc 15 §4): +// paths relative to the workspace file, unknown keys are errors, remote manifests are refused (the build is offline), +// and every service's *.sfflow.yaml files are listed recursively, sorted, relative to the workspace with '/'. +import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'; +import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'; +import { LineCounter, parseDocument, isMap, isScalar, isSeq } from 'yaml'; + +export const FILE_NAME = 'sourceflow.domain.yaml'; +export const WORKFLOW_SUFFIX = '.sfflow.yaml'; +export const LAYOUT_SUFFIX = '.sfflow.layout.json'; + +const WORKSPACE_KEYS = ['domain', 'description', 'services']; +const SERVICE_KEYS = ['name', 'manifest', 'workflows', 'project', 'tests', 'module']; + +export class WorkspaceError extends Error { + constructor(message) { + super(message); + this.name = 'WorkspaceError'; + } +} + +function at(file, lines, node) { + const offset = node?.range?.[0] ?? 0; + const { line, col } = lines.linePos(offset); + return `${file}(${line},${col})`; +} + +function scalar(file, lines, node) { + if (!isScalar(node)) { + throw new WorkspaceError(`${at(file, lines, node)}: expected a single value.`); + } + + return node.value === null ? undefined : String(node.value); +} + +function listWorkflows(root, folder) { + if (!existsSync(folder) || !statSync(folder).isDirectory()) { + return []; + } + + const found = []; + const visit = (dir) => { + for (const entry of readdirSync(dir, { withFileTypes: true })) { + const full = join(dir, entry.name); + if (entry.isDirectory()) { + visit(full); + } else if (entry.isFile() && entry.name.endsWith(WORKFLOW_SUFFIX)) { + found.push(relative(root, full).split(sep).join('/')); + } + } + }; + visit(folder); + return found.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)); +} + +/** + * Loads a workspace (the file, or a folder holding sourceflow.domain.yaml) into the Studio API's workspace shape, with + * each service's manifest JSON, and the text of every workflow file and the layout file beside it. + */ +export function loadWorkspace(path) { + const file = resolve(existsSync(path) && statSync(path).isDirectory() ? join(path, FILE_NAME) : path); + if (!existsSync(file)) { + throw new WorkspaceError(`Workspace file '${file}' not found.`); + } + + const root = dirname(file); + const lines = new LineCounter(); + const doc = parseDocument(readFileSync(file, 'utf8'), { lineCounter: lines, uniqueKeys: true }); + if (doc.errors.length > 0) { + const error = doc.errors[0]; + const { line, col } = error.linePos?.[0] ?? { line: 1, col: 1 }; + throw new WorkspaceError(`${file}(${line},${col}): ${error.message.split('\n')[0]}`); + } + + if (!isMap(doc.contents)) { + throw new WorkspaceError(`${file}: the workspace file must be a mapping with 'domain' and 'services'.`); + } + + const workspace = { domain: undefined, description: undefined, services: undefined }; + for (const pair of doc.contents.items) { + const key = scalar(file, lines, pair.key); + if (!WORKSPACE_KEYS.includes(key)) { + throw new WorkspaceError(`${at(file, lines, pair.key)}: unknown key '${key}' (expected domain, description or services).`); + } + + if (key === 'services') { + if (!isSeq(pair.value)) { + throw new WorkspaceError(`${at(file, lines, pair.value)}: expected a list.`); + } + + workspace.services = pair.value.items.map((item) => { + if (!isMap(item)) { + throw new WorkspaceError(`${at(file, lines, item)}: a service is a mapping with 'name', 'manifest' and optionally 'workflows', 'project', 'tests' and 'module'.`); + } + + const service = {}; + for (const entry of item.items) { + const name = scalar(file, lines, entry.key); + if (!SERVICE_KEYS.includes(name)) { + throw new WorkspaceError(`${at(file, lines, entry.key)}: unknown key '${name}' (expected name, manifest, workflows, project, tests or module).`); + } + + service[name] = scalar(file, lines, entry.value); + } + + return service; + }); + } else { + workspace[key] = scalar(file, lines, pair.value); + } + } + + if (!workspace.domain) { + throw new WorkspaceError(`${file}: 'domain' is required.`); + } + + if (!workspace.services || workspace.services.length === 0) { + throw new WorkspaceError(`${file}: 'services' lists no service.`); + } + + const names = new Set(); + const files = {}; + const services = workspace.services.map((service) => { + if (!service.name || !service.manifest) { + throw new WorkspaceError(`${file}: every service needs a 'name' and a 'manifest'.`); + } + + if (names.has(service.name)) { + throw new WorkspaceError(`${file}: service '${service.name}' is listed twice.`); + } + + names.add(service.name); + if (/^https?:\/\//i.test(service.manifest)) { + throw new WorkspaceError(`Service '${service.name}': the manifest '${service.manifest}' is remote; the static build reads local files only.`); + } + + const manifestPath = isAbsolute(service.manifest) ? service.manifest : resolve(root, service.manifest); + if (!existsSync(manifestPath)) { + throw new WorkspaceError(`Service '${service.name}': manifest '${service.manifest}' not found (${manifestPath}). Run 'dotnet sourceflow manifest export --project ' to create it.`); + } + + const manifestJson = readFileSync(manifestPath, 'utf8'); + let declared; + try { + declared = JSON.parse(manifestJson).service; + } catch (error) { + throw new WorkspaceError(`Service '${service.name}': manifest '${service.manifest}' is invalid: ${error.message}`); + } + + if (declared !== undefined && declared !== service.name) { + throw new WorkspaceError(`Service '${service.name}': '${service.manifest}' is the manifest of service '${declared}'.`); + } + + const workflowFiles = service.workflows === undefined ? [] : listWorkflows(root, resolve(root, service.workflows)); + for (const workflow of workflowFiles) { + files[workflow] = readFileSync(resolve(root, workflow), 'utf8'); + const layout = workflow.slice(0, -WORKFLOW_SUFFIX.length) + LAYOUT_SUFFIX; + if (existsSync(resolve(root, layout))) { + files[layout] = readFileSync(resolve(root, layout), 'utf8'); + } + } + + const dto = { name: service.name, manifest: service.manifest, manifestJson, workflowFiles }; + for (const optional of ['workflows', 'project', 'tests', 'module']) { + if (service[optional] !== undefined) { + dto[optional] = service[optional]; + } + } + + return dto; + }); + + return { + workspace: { domain: workspace.domain, ...(workspace.description === undefined ? {} : { description: workspace.description }), file: basename(file), readOnly: true, staticSite: true, services }, + files, + }; +} diff --git a/web/app/e2e/editing.spec.ts b/web/app/e2e/editing.spec.ts new file mode 100644 index 00000000..0879101d --- /dev/null +++ b/web/app/e2e/editing.spec.ts @@ -0,0 +1,192 @@ +// STU-E2E-07..10 and STU-A11Y-05 (plan 10 §3.3): editing in the browser against a writable host on a fresh copy of the golden workspace +// (e2e/generate.mjs editable-workspace): an error typed in Monaco shows everywhere, a visual fix clears it, visual edits +// save with the file's comments, and an add → save → undo → save round trip gives back the file byte for byte. +import { expect, test, type Page } from '@playwright/test'; +import { readdirSync, readFileSync } from 'node:fs'; +import { join } from 'node:path'; +import { fileURLToPath } from 'node:url'; + +const base = 'http://127.0.0.1:5196'; +const golden = fileURLToPath(new URL('../../../tests/Golden/cases', import.meta.url)); +const original = (name: string) => readFileSync(join(golden, name, 'workflow.sfflow.yaml'), 'utf8'); +const file = (name: string) => `orders/workflows/${name}.sfflow.yaml`; + +async function openWorkflow(page: Page, name: string) { + await page.goto(base + '/'); + await page.getByRole('navigation', { name: 'Workspace' }).getByRole('link', { name: `Workflow ${name}` }).click(); + await expect(page.getByRole('heading', { level: 1, name: `${name}.sfflow.yaml` })).toBeVisible(); + // The statechart, or why it can't be drawn: the text stays editable either way. + await expect(page.locator('.flow[data-ready="true"], [role="tabpanel"] [role="alert"]').first()).toBeVisible({ timeout: 30_000 }); +} + +async function stored(page: Page, name: string): Promise { + const response = await page.request.get(`${base}/api/files?path=${encodeURIComponent(file(name))}`); + expect(response.ok()).toBe(true); + return response.text(); +} + +async function selectStep(page: Page, id: string) { + await page.getByRole('tab', { name: 'Statechart' }).click(); + await page.locator(`.react-flow__node[data-id="${id}"]`).click(); + const form = page.getByRole('form', { name: `Properties of ${id}` }); + await expect(form).toBeVisible(); + return form; +} + +const status = (page: Page) => page.getByRole('toolbar', { name: 'Edit' }).getByRole('status'); +const diagnostics = (page: Page) => page.getByRole('region', { name: 'Diagnostics' }); + +test('STU-E2E-07 an error typed in Monaco shows in the panel, on the step and as a marker', async ({ page }) => { + await openWorkflow(page, '01-order-fulfilment'); + await expect(diagnostics(page).getByRole('status')).toHaveText('No problems.', { timeout: 30_000 }); + await page.getByRole('tab', { name: 'YAML' }).click(); + const monaco = page.getByTestId('monaco'); + await expect(monaco.locator('.view-lines')).toContainText('sourceflow.workflow', { timeout: 30_000 }); + + // Type the error as a person would: find the command, then type over it. + await monaco.locator('.view-lines').click(); + await page.keyboard.press('ControlOrMeta+Home'); + await page.keyboard.press('ControlOrMeta+F'); + await page.keyboard.type('reserve-stock.v1'); + await page.keyboard.press('Enter'); + await page.keyboard.press('Escape'); + await page.keyboard.type('reserve-stocks.v1'); + await expect(status(page)).toHaveText('Unsaved changes'); + + await expect(diagnostics(page).getByRole('button', { name: /Error WF-V01/ }).first()).toBeVisible({ timeout: 30_000 }); + await expect(monaco.locator('.squiggly-error').first()).toBeAttached({ timeout: 10_000 }); + await page.getByRole('tab', { name: 'Statechart' }).click(); + await expect(page.locator('.react-flow__node[data-id="reserve-stock"] .state-problems')).toBeVisible({ timeout: 30_000 }); + await expect(page.locator('.react-flow__node[data-id="reserve-stock"]')).toHaveAttribute('aria-label', /problem/); + + // STU-E2E-08: fixed visually, the text is the file again. + const form = await selectStep(page, 'reserve-stock'); + await form.getByRole('combobox', { name: 'Command', exact: true }).selectOption('inventory.reserve-stock.v1'); + await expect(diagnostics(page).getByRole('status')).toHaveText('No problems.', { timeout: 30_000 }); + await expect(page.locator('.react-flow__node[data-id="reserve-stock"] .state-problems')).toHaveCount(0); + await expect(status(page)).toHaveText('No changes'); + await expect(page.getByRole('button', { name: 'Save' })).toBeDisabled(); +}); + +test('STU-E2E-08 a visual fix of an invalid workflow clears its diagnostic', async ({ page }) => { + await openWorkflow(page, '09-v01-unknown-type'); + // An unknown command, and a command where the success event belongs. + const error = diagnostics(page).getByRole('button', { name: /Error WF-V01/ }); + await expect(error).toHaveCount(2, { timeout: 30_000 }); + await expect(page.locator('.react-flow__node[data-id="approve"] .state-problems')).toHaveText(/2/); + let form = await selectStep(page, 'approve'); + await form.getByRole('combobox', { name: 'Command', exact: true }).selectOption('orders.approve-order.v1'); + await expect(error).toHaveCount(1, { timeout: 30_000 }); + form = page.getByRole('form', { name: 'Properties of approve' }); + await form.getByRole('combobox', { name: 'Success event' }).selectOption('orders.order-approved.v1'); + await expect(diagnostics(page).getByRole('status')).toHaveText('No problems.', { timeout: 30_000 }); + await expect(page.locator('.react-flow__node[data-id="approve"] .state-problems')).toHaveCount(0); + await expect(status(page)).toHaveText('Unsaved changes'); +}); + +test('STU-E2E-09 a retry and a compensation added visually save with the file and its comments', async ({ page }) => { + await openWorkflow(page, 'visual-edits'); + const form = await selectStep(page, 'review-large-order'); + const retries = form.getByRole('textbox', { name: 'Retry (timeout): retries' }); + await retries.fill('2'); + await retries.press('Enter'); + await form.getByRole('combobox', { name: 'Undo command' }).selectOption('orders.cancel-order.v1'); + await expect(status(page)).toHaveText('Unsaved changes'); + await page.getByRole('button', { name: 'Save' }).click(); + await expect(status(page)).toHaveText('Saved.'); + + const text = await stored(page, 'visual-edits'); + const review = text.slice(text.indexOf('- id: review-large-order'), text.indexOf('- id: create-shipment')); + expect(review).toContain('timeout: { after: P1D, then: manual, retry: { max: 2 } }'); + expect(review).toMatch(/compensate:[\s\S]*orders\.cancel-order\.v1/); + for (const comment of ['# generated into the orders service', '# CESQL guard; skipped when false', '# point of no return', '# business retry']) { + expect(text).toContain(comment); + } + + // Everything outside the edited step is the file as it was. + const before = original('01-order-fulfilment'); + const cut = (t: string) => t.slice(0, t.indexOf('- id: review-large-order')) + t.slice(t.indexOf('- id: create-shipment')); + expect(cut(text)).toBe(cut(before)); + + // The core checks the new compensation like any other: it still needs its map and a timeout. + await expect(diagnostics(page).getByRole('button', { name: /Error WF-V12 .*orders\.cancel-order\.v1 needs 'orderId'/ })).toBeVisible({ timeout: 30_000 }); + await expect(diagnostics(page).getByRole('button', { name: /Error WF-V06 .*compensation of 'review-large-order'/ })).toBeVisible(); +}); + +test('STU-A11Y-05 keyboard only: add a step, connect it, give it a failure, save', async ({ page }) => { + // Focus moves between controls (as Tab or a screen reader would take it); every action is a key press. + await page.goto(base + '/'); + await expect(page.getByRole('navigation', { name: 'Workspace' }).getByRole('link', { name: 'Workflow keyboard-edits' })).toBeVisible(); + await page.keyboard.press('Alt+1'); + await expect(page.getByRole('navigation', { name: 'Workspace' })).toBeFocused(); + await page.getByRole('navigation', { name: 'Workspace' }).getByRole('link', { name: 'Workflow keyboard-edits' }).focus(); + await page.keyboard.press('Enter'); + await expect(page.getByRole('heading', { level: 1, name: 'keyboard-edits.sfflow.yaml' })).toBeVisible(); + await expect(page.locator('.flow[data-ready="true"]')).toBeVisible({ timeout: 30_000 }); + + // Add a step: choose its command by typing, Tab past the event it waits for, Enter on Add step. + const palette = page.getByRole('region', { name: 'Palette' }); + const command = palette.getByRole('combobox', { name: 'Command', exact: true }); + await command.focus(); + await page.keyboard.type('payments.charge.v1'); + await expect(command).toHaveValue('payments.charge.v1'); + await page.keyboard.press('Tab'); + await expect(palette.getByRole('combobox', { name: 'Waits for' })).toBeFocused(); + await expect(palette.getByRole('combobox', { name: 'Waits for' })).toHaveValue('payments.payment-captured.v1'); + await page.keyboard.press('Tab'); + await expect(palette.getByRole('button', { name: 'Add step' })).toBeFocused(); + await page.keyboard.press('Enter'); + const form = page.getByRole('form', { name: 'Properties of charge' }); + await expect(form).toBeVisible(); + + // Give it a failure, and connect the failure to another step. + await form.getByRole('combobox', { name: 'Add a failure' }).focus(); + await page.keyboard.type('rejected payments.declined'); + const then = form.getByRole('combobox', { name: 'Then (rejection payments.declined)' }); + await expect(then).toBeVisible(); + await then.focus(); + await page.keyboard.type('go to create-shipment'); + await expect(then).toHaveValue('goto:create-shipment'); + + await page.keyboard.press('ControlOrMeta+S'); + await expect(status(page)).toHaveText('Saved.'); + const text = await stored(page, 'keyboard-edits'); + const step = text.slice(text.indexOf(' - id: charge\n')); + expect(step).toContain('command: payments.charge.v1'); + expect(step).toContain('success: payments.payment-captured.v1'); + expect(step).toMatch(/rejected: payments\.declined[\s\S]*then: \{ goto: create-shipment \}/); + await expect(page.locator('.react-flow__node[data-id="charge"]')).toBeAttached({ timeout: 30_000 }); +}); + +// STU-E2E-10 on every golden workflow. +const cases = readdirSync(golden); +for (const name of cases) { + test(`STU-E2E-10 add, save, undo and save gives back ${name} byte for byte`, async ({ page }) => { + await openWorkflow(page, name); + const palette = page.getByRole('region', { name: 'Palette' }); + await expect(palette).toContainText('At the end of the workflow.'); + await palette.getByRole('combobox', { name: 'Command', exact: true }).selectOption('payments.refund.v1'); + await palette.getByRole('button', { name: 'Add step' }).click(); + if (readFileSync(join(golden, name, 'expected.diagnostics.json'), 'utf8').includes('Invalid YAML')) { + // Nothing is spliced into a file that doesn't parse: the edit is refused, with the way out. + await expect(page.getByRole('alert').filter({ hasText: "The YAML doesn't parse" })).toContainText('fix it in the YAML tab first'); + await expect(status(page)).toHaveText('No changes'); + await expect(page.getByRole('button', { name: 'Save' })).toBeDisabled(); + expect(await stored(page, name)).toBe(original(name)); + return; + } + + await expect(page.getByRole('form', { name: 'Properties of refund' })).toBeVisible(); + await page.getByRole('button', { name: 'Save' }).click(); + await expect(status(page)).toHaveText('Saved.'); + const added = await stored(page, name); + expect(added).toContain(' - id: refund\n'); + expect(added.length).toBeGreaterThan(original(name).length); + + await page.getByRole('button', { name: 'Undo' }).click(); + await expect(status(page)).toHaveText('Unsaved changes'); + await page.keyboard.press('ControlOrMeta+S'); + await expect(status(page)).toHaveText('Saved.'); + expect(await stored(page, name)).toBe(original(name)); + }); +} diff --git a/web/app/e2e/exports.spec.ts b/web/app/e2e/exports.spec.ts new file mode 100644 index 00000000..f60f810c --- /dev/null +++ b/web/app/e2e/exports.spec.ts @@ -0,0 +1,106 @@ +// STU-E2E-14 (exports: SVG, PNG, Mermaid, BPMN) and STU-E2E-15 (the static site renders read-only) (plan 10 §3.3). +import AxeBuilder from '@axe-core/playwright'; +import { expect, test, type Page } from '@playwright/test'; +import { readFileSync } from 'node:fs'; +import { fileURLToPath } from 'node:url'; + +const golden = (name: string) => readFileSync(fileURLToPath(new URL(`../../../tests/Golden/cases/01-order-fulfilment/${name}`, import.meta.url)), 'utf8'); +const site = 'http://127.0.0.1:5195/docs/studio/'; + +async function openWorkflow(page: Page, url = '/') { + await page.goto(url); + await page.getByRole('navigation', { name: 'Workspace' }).getByRole('link', { name: 'Workflow order-fulfilment' }).click(); + await expect(page.getByRole('heading', { level: 1, name: 'order-fulfilment.sfflow.yaml' })).toBeVisible(); + await expect(page.locator('.flow[data-ready="true"]')).toBeVisible({ timeout: 30_000 }); +} + +async function exported(page: Page, label: string): Promise<{ name: string; bytes: Buffer }> { + const download = page.waitForEvent('download'); + await page.getByRole('group', { name: 'Export' }).getByRole('button', { name: `Export ${label}` }).click(); + const file = await download; + return { name: file.suggestedFilename(), bytes: readFileSync((await file.path())!) }; +} + +test('STU-E2E-14 exports the statechart as SVG and PNG, and the workflow as Mermaid and BPMN', async ({ page }) => { + await openWorkflow(page); + + const svg = await exported(page, 'SVG'); + expect(svg.name).toBe('order-fulfilment.svg'); + const text = svg.bytes.toString('utf8'); + expect(text).toMatch(/^Statechart of order-fulfilment.sfflow.yaml'); + expect(text.match(/ { + // Everything the site loads comes from its own folder (other origins, such as a local security product's injected + // scripts, aren't the site's). + const outside: string[] = []; + page.on('request', (request) => { + const url = request.url(); + if (url.startsWith(new URL(site).origin) && !url.startsWith(site)) { + outside.push(url); + } + }); + + await page.goto(site); + await expect(page.getByRole('heading', { level: 1, name: 'commerce' })).toBeVisible({ timeout: 30_000 }); + await expect(page.getByRole('note')).toHaveText('Read-only'); + await expect(page.locator('.flow-map[data-ready="true"]')).toBeVisible({ timeout: 30_000 }); + + await openWorkflow(page, site); + expect(page.url()).toBe(`${site}#/workflows/orders/workflows/order-fulfilment.sfflow.yaml`); + await expect(page.getByRole('region', { name: 'Diagnostics' }).getByRole('status')).toHaveText('No problems.', { timeout: 30_000 }); + await expect(page.getByRole('button', { name: 'Save' })).toBeDisabled(); + await expect(page.getByRole('toolbar', { name: 'Edit' }).getByRole('status')).toHaveText('Read-only'); + + // The core runs from the site's own folder: simulate, and list the paths (specs need the local host). + await page.getByRole('tab', { name: 'Simulate' }).click(); + await page.getByRole('region', { name: 'Simulate' }).getByRole('button', { name: 'Start' }).click(); + await expect(page.getByTestId('sim-status')).toHaveText('Running', { timeout: 30_000 }); + await page.getByRole('tab', { name: 'Paths' }).click(); + await expect(page.getByText(/This static site can't write specs/)).toBeVisible({ timeout: 30_000 }); + await expect(page.getByRole('button', { name: 'Preview specs' })).toBeDisabled(); + await page.getByRole('tab', { name: 'YAML' }).click(); + await expect(page.getByTestId('monaco').locator('.view-lines')).toContainText('sourceflow.workflow', { timeout: 30_000 }); + expect((await exported(page, 'Mermaid')).bytes.toString('utf8')).toBe(golden('expected.mmd')); + + // A hash route survives a reload on a host with no fallback to index.html. + await page.reload(); + await expect(page.getByRole('heading', { level: 1, name: 'order-fulfilment.sfflow.yaml' })).toBeVisible({ timeout: 30_000 }); + await expect(page.locator('.flow[data-ready="true"]')).toBeVisible({ timeout: 30_000 }); + const write = await page.request.put(`${site}api/files?path=x.sfflow.yaml`, { data: { content: 'x' } }); + expect(write.status()).toBe(404); // nothing to write to + expect(outside).toEqual([]); + + const scan = await new AxeBuilder({ page }).withTags(['wcag2a', 'wcag2aa']).analyze(); + expect(scan.violations.filter((v) => v.impact === 'serious' || v.impact === 'critical').map((v) => v.id)).toEqual([]); +}); diff --git a/web/app/e2e/generate.mjs b/web/app/e2e/generate.mjs new file mode 100644 index 00000000..b5cfbb71 --- /dev/null +++ b/web/app/e2e/generate.mjs @@ -0,0 +1,118 @@ +// Generates the performance fixtures (STU-PERF-01..02), deterministically: +// node e2e/generate.mjs large-workflow a 200-state workflow (200 steps, with retries and compensations) +// node e2e/generate.mjs large-workspace a workspace of 20 services and 50 workflows +// node e2e/generate.mjs editable-workspace a fresh copy of the commerce workspace for the editing, simulation +// and specs tests (STU-E2E-07..13): saves change these copies, never the +// committed files; orders has a test project for the specs +import { copyFileSync, mkdirSync, readdirSync, rmSync, writeFileSync } from 'node:fs'; +import { dirname, join, resolve } from 'node:path'; +import { fileURLToPath } from 'node:url'; + +const [, , what, target] = process.argv; + +function workflow(name, owner, steps, prefix) { + const lines = [ + 'sourceflow.workflow: 1', + `name: ${name}`, + 'version: 1', + `owner: ${owner}`, + 'start:', + ` on: ${prefix}.started.v1`, + ' correlate: data.id', + 'data:', + ' id: { from: start.data.id }', + 'steps:', + ]; + for (let i = 1; i <= steps; i++) { + const id = `step-${String(i).padStart(3, '0')}`; + lines.push(` - id: ${id}`); + lines.push(` send: { command: ${prefix}.do-${i % 5}.v1, map: { id: $data.id } }`); + lines.push(' await:'); + lines.push(` success: ${prefix}.done-${i % 5}.v1`); + if (i % 4 === 0) { + lines.push(' failure:'); + lines.push(` - rejected: ${prefix}.refused`); + lines.push(' retry: { max: 2 }'); + lines.push(' then: fail'); + } + + if (i % 10 === 0) { + lines.push(' timeout: { after: PT5M, then: manual }'); + } + + if (i % 6 === 0) { + lines.push(` compensate: { send: { command: ${prefix}.undo-${i % 5}.v1, map: { id: $data.id } }, await: { success: ${prefix}.undone-${i % 5}.v1 } }`); + } + } + + return lines.join('\n') + '\n'; +} + +function manifest(service, index, services) { + const commands = [0, 1, 2, 3, 4].map((i) => ({ type: `${service}.do-${i}`, version: 1, emits: [`${service}.done-${i}.v1`], rejects: [`${service}.refused`] })); + const next = services[(index + 1) % services.length]; + return { + manifestVersion: 1, + service, + endpoint: service, + sourceflowVersion: '3.0.0', + messages: [], + aggregates: [{ name: `${service}-root`, commands, events: commands.map((c) => c.emits[0]) }], + processManagers: [], + projections: [], + publishes: [{ domainEvent: `${service}.done-0.v1`, as: `${service}.done-0.v1`, topic: `${service}.events` }], + subscribes: [{ topic: `${next}.events` }], + commandRoutes: [{ command: `${next}.do-0.v1`, to: next, replyOnReject: true }], + workflows: [], + schemas: [], + }; +} + +if (what === 'large-workflow') { + writeFileSync(target, '# Generated by e2e/generate.mjs (STU-PERF-01): 200 steps, retries, timeouts and compensations.\n' + workflow('large', 'orders', 200, 'orders')); +} else if (what === 'large-workspace') { + const services = Array.from({ length: 20 }, (_, i) => `service-${String(i + 1).padStart(2, '0')}`); + mkdirSync(join(target, 'manifests'), { recursive: true }); + const yaml = ['# Generated by e2e/generate.mjs (STU-PERF-02): 20 services, 50 workflows.', 'domain: large', 'description: A large generated domain', 'services:']; + services.forEach((service, index) => { + writeFileSync(join(target, 'manifests', `${service}.manifest.json`), JSON.stringify(manifest(service, index, services), null, 2) + '\n'); + yaml.push(` - name: ${service}`, ` manifest: manifests/${service}.manifest.json`, ` workflows: ${service}/workflows`); + const count = index < 10 ? 3 : 2; // 10 × 3 + 10 × 2 = 50 + mkdirSync(join(target, service, 'workflows'), { recursive: true }); + for (let w = 1; w <= count; w++) { + writeFileSync(join(target, service, 'workflows', `flow-${w}.sfflow.yaml`), workflow(`${service}-flow-${w}`, service, 6, service)); + } + }); + writeFileSync(join(target, 'sourceflow.domain.yaml'), yaml.join('\n') + '\n'); +} else if (what === 'editable-workspace') { + const golden = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', '..', 'tests', 'Golden'); + rmSync(target, { recursive: true, force: true }); + const workflows = join(target, 'orders', 'workflows'); + mkdirSync(workflows, { recursive: true }); + // Every golden case under its case name, and copies of order-fulfilment for the visual edits that are saved (E2E-09, and + // keyboard-only A11Y-05), for the simulation and specs (E2E-11..13) and for the validation timing (PERF-03), so no test + // reads a file another one is changing. + for (const name of readdirSync(join(golden, 'cases'))) { + copyFileSync(join(golden, 'cases', name, 'workflow.sfflow.yaml'), join(workflows, `${name}.sfflow.yaml`)); + } + + copyFileSync(join(golden, 'cases', '01-order-fulfilment', 'workflow.sfflow.yaml'), join(workflows, 'visual-edits.sfflow.yaml')); + copyFileSync(join(golden, 'cases', '01-order-fulfilment', 'workflow.sfflow.yaml'), join(workflows, 'keyboard-edits.sfflow.yaml')); + copyFileSync(join(golden, 'cases', '01-order-fulfilment', 'workflow.sfflow.yaml'), join(workflows, 'perf.sfflow.yaml')); + copyFileSync(join(golden, 'cases', '01-order-fulfilment', 'workflow.sfflow.yaml'), join(workflows, 'simulation.sfflow.yaml')); + mkdirSync(join(target, 'orders', 'tests'), { recursive: true }); + writeFileSync(join(target, 'orders', 'tests', 'Orders.Tests.csproj'), '\n'); + + const yaml = ['# Generated by e2e/generate.mjs (STU-E2E-07..13): the golden commerce domain, editable.', 'domain: commerce', 'description: Order to delivery', 'services:']; + for (const service of ['orders', 'inventory', 'payments', 'shipping']) { + yaml.push(` - name: ${service}`, ` manifest: ${JSON.stringify(join(golden, 'domain', `${service}.manifest.json`))}`); + if (service === 'orders') { + yaml.push(' workflows: orders/workflows', ' tests: orders/tests', ' module: Orders.OrdersModule'); + } + } + + writeFileSync(join(target, 'sourceflow.domain.yaml'), yaml.join('\n') + '\n'); +} else { + console.error('usage: node e2e/generate.mjs large-workflow | large-workspace | editable-workspace '); + process.exit(2); +} diff --git a/web/app/e2e/perf.spec.ts b/web/app/e2e/perf.spec.ts new file mode 100644 index 00000000..4ba16850 --- /dev/null +++ b/web/app/e2e/perf.spec.ts @@ -0,0 +1,101 @@ +// STU-PERF-01..03 (plan 10 §3.3): the Playwright project 'perf' runs these after every other test, alone, so they +// measure the app rather than the test load. +import { expect, test, type Page } from '@playwright/test'; + +async function openWorkflow(page: Page, name: string) { + await page.goto('/'); + await page.getByRole('navigation', { name: 'Workspace' }).getByRole('link', { name: `Workflow ${name}` }).click(); + await expect(page.getByRole('heading', { level: 1, name: `${name}.sfflow.yaml` })).toBeVisible(); +} + +async function statechartReady(page: Page) { + await expect(page.locator('.flow[data-ready="true"]')).toBeVisible({ timeout: 30_000 }); + await expect(page.locator('.react-flow__edge').first()).toBeAttached(); +} + +test('STU-PERF-01 a 200-state workflow lays out and renders in under a second', async ({ page }) => { + await openWorkflow(page, 'order-fulfilment'); // the core and ELK workers are warm + await statechartReady(page); + const started = Date.now(); + await page.getByRole('navigation', { name: 'Workspace' }).getByRole('link', { name: 'Workflow large' }).click(); + await expect(page.getByRole('heading', { level: 1, name: 'large.sfflow.yaml' })).toBeVisible(); + const flow = page.locator('.flow[data-ready="true"]'); + await expect(flow).toBeVisible({ timeout: 30_000 }); + const states = Number(await flow.getAttribute('data-nodes')); + expect(states).toBeGreaterThan(200); // 200 steps, their compensations, the start and the end states + await expect(page.locator('.react-flow__node')).toHaveCount(states); + const elapsed = Date.now() - started; + console.info(`STU-PERF-01: 200 steps laid out and rendered in ${elapsed} ms`); + // The budget is 1 s on a developer machine (plan 10 §3.3); a shared 4-vCPU hosted runner is up to a third slower. + expect(elapsed).toBeLessThan(process.env.CI ? 1_500 : 1_000); +}); + +test('STU-PERF-02 a workspace of 20 services and 50 workflows opens in under three seconds', async ({ page }) => { + const started = Date.now(); + await page.goto('http://127.0.0.1:5197/'); + await expect(page.getByRole('heading', { level: 1, name: 'large' })).toBeVisible(); + await expect(page.getByRole('navigation', { name: 'Workspace' }).getByRole('link', { name: /^Workflow / })).toHaveCount(50); + await expect(page.locator('.flow-map[data-ready="true"]')).toBeVisible({ timeout: 30_000 }); + const elapsed = Date.now() - started; + console.info(`STU-PERF-02: 20 services and 50 workflows opened in ${elapsed} ms`); + expect(elapsed).toBeLessThan(3_000); +}); + +// From a key press in the YAML editor to the diagnostics panel showing the core's answer, measured in the page (a +// keydown listener and a MutationObserver on the panel), on a copy of the commerce workflow in the editable workspace. +test('STU-PERF-03 a validation round trip (edit to diagnostics) takes under 100 ms', async ({ page }) => { + const base = 'http://127.0.0.1:5196'; + await page.goto(base + '/'); + await page.getByRole('navigation', { name: 'Workspace' }).getByRole('link', { name: 'Workflow perf' }).click(); + const panel = page.getByRole('region', { name: 'Diagnostics' }); + await expect(panel.getByRole('status')).toHaveText('No problems.', { timeout: 30_000 }); + await page.getByRole('tab', { name: 'YAML' }).click(); + const monaco = page.getByTestId('monaco'); + await expect(monaco.locator('.view-lines')).toContainText('sourceflow.workflow', { timeout: 30_000 }); + await monaco.locator('.view-lines').click(); + await page.keyboard.press('ControlOrMeta+Home'); + await page.keyboard.press('ControlOrMeta+F'); + await page.keyboard.type('inventory.reserve-stock.v1'); + await page.keyboard.press('Enter'); + await page.keyboard.press('Escape'); + await page.keyboard.press('ArrowRight'); // the cursor right after the command: typing breaks it, Backspace mends it + + await page.evaluate(() => { + const region = document.querySelector('[aria-label="Diagnostics"]')!; + const state = { armed: false, start: 0, expect: '', times: [] as number[] }; + (window as unknown as { roundTrip: typeof state }).roundTrip = state; + window.addEventListener('keydown', () => { + if (state.armed) { + state.start = performance.now(); + state.armed = false; + } + }, true); + new MutationObserver(() => { + if (state.start > 0 && new RegExp(state.expect).test(region.textContent ?? '')) { + state.times.push(performance.now() - state.start); + state.start = 0; + } + }).observe(region, { subtree: true, childList: true, characterData: true }); + }); + + const rounds: Array<{ key: string; expect: string }> = []; + for (let i = 0; i < 5; i++) { + rounds.push({ key: 'x', expect: 'Error WF-' }, { key: 'Backspace', expect: 'No problems' }); + } + + for (const [n, round] of rounds.entries()) { + await page.evaluate((r) => { + const state = (window as unknown as { roundTrip: { armed: boolean; expect: string } }).roundTrip; + state.expect = r.expect; + state.armed = true; + }, round); + await page.keyboard.press(round.key); + await expect.poll(() => page.evaluate(() => (window as unknown as { roundTrip: { times: number[] } }).roundTrip.times.length), { timeout: 10_000 }).toBe(n + 1); + } + + const times = await page.evaluate(() => (window as unknown as { roundTrip: { times: number[] } }).roundTrip.times); + const warm = times.slice(2).sort((a, b) => a - b); // the first error and fix warm the worker and the panel + const median = warm[Math.floor(warm.length / 2)] ?? Number.POSITIVE_INFINITY; + console.info(`STU-PERF-03: validation round trips ${times.map((t) => t.toFixed(0)).join(', ')} ms (median after warm-up ${median.toFixed(0)} ms)`); + expect(median).toBeLessThan(100); +}); diff --git a/web/app/e2e/playwright.config.ts b/web/app/e2e/playwright.config.ts new file mode 100644 index 00000000..71984484 --- /dev/null +++ b/web/app/e2e/playwright.config.ts @@ -0,0 +1,58 @@ +import { defineConfig } from '@playwright/test'; +import { fileURLToPath } from 'node:url'; + +// STU-E2E-01..15, STU-A11Y-01..05 and STU-PERF-01..03 (plan 10 §3.3): the built app in a browser, served by `dotnet sourceflow studio` (a writable host and a +// read-only one) with the published WebAssembly core. Build first: npm run build:wasm && npm run build, and +// dotnet build src/Tooling/SourceFlow.Tool. Locally, PW_CHANNEL=chrome (or msedge) uses an installed browser. +const app = fileURLToPath(new URL('..', import.meta.url)); +const framework = '../../artifacts/studio-wasm/wwwroot/_framework'; +const tool = '../../src/Tooling/SourceFlow.Tool'; + +function host(port: number, readOnly: boolean, workspace = 'e2e/workspace', before = '') { + return { + command: `${before}dotnet run --project ${tool} --no-build -- studio --workspace ${workspace} --port ${port} --assets dist --framework ${framework}${readOnly ? ' --read-only' : ''}`, + cwd: app, + url: `http://127.0.0.1:${port}/api/workspace`, + reuseExistingServer: false, + timeout: 120_000, + stdout: 'ignore' as const, + stderr: 'pipe' as const, + }; +} + +export default defineConfig({ + testDir: '.', + testMatch: '*.spec.ts', + timeout: 60_000, + retries: process.env.CI ? 1 : 0, + reporter: process.env.CI ? 'github' : 'list', + use: { + baseURL: 'http://127.0.0.1:5199', + ...(process.env.PW_CHANNEL ? { channel: process.env.PW_CHANNEL } : {}), + trace: 'retain-on-failure', + }, + projects: [ + { name: 'chromium', use: { browserName: 'chromium' }, testIgnore: 'perf.spec.ts' }, + { name: 'perf', use: { browserName: 'chromium' }, testMatch: 'perf.spec.ts', dependencies: ['chromium'] }, + ], + webServer: [ + host(5199, false), + host(5198, true), + // STU-PERF-02: a generated workspace of 20 services and 50 workflows. + host(5197, true, '../../artifacts/studio-e2e/large', 'node e2e/generate.mjs large-workspace ../../artifacts/studio-e2e/large && '), + // STU-E2E-01 and STU-A11Y-04: the OrderFulfilment sample's workspace, as committed (read-only). + host(5194, true, '../../samples/OrderFulfilment'), + // STU-E2E-07..10: a fresh, writable copy of the golden workspace for each run. + host(5196, false, '../../artifacts/studio-e2e/editable', 'node e2e/generate.mjs editable-workspace ../../artifacts/studio-e2e/editable && '), + // STU-E2E-15: the static site of e2e/workspace (npx @sourceflow/studio build), on a plain file server under a sub-path. + { + command: 'node bin/studio.mjs build --workspace e2e/workspace --out ../../artifacts/studio-e2e/site && node e2e/serve-static.mjs ../../artifacts/studio-e2e/site 5195 /docs/studio/', + cwd: app, + url: 'http://127.0.0.1:5195/docs/studio/index.html', + reuseExistingServer: false, + timeout: 120_000, + stdout: 'ignore' as const, + stderr: 'pipe' as const, + }, + ], +}); diff --git a/web/app/e2e/sample.spec.ts b/web/app/e2e/sample.spec.ts new file mode 100644 index 00000000..0aacb00b --- /dev/null +++ b/web/app/e2e/sample.spec.ts @@ -0,0 +1,116 @@ +// STU-E2E-01 on the OrderFulfilment workspace (samples/OrderFulfilment, WP-S.13) and STU-A11Y-04 (plan 10 §3.3): the real +// four-service workspace opens, its workflow is valid against every manifest and has the doc 15 §5.1 path set; and what +// the views draw meets WCAG 2.1 AA contrast in both themes (text 4.5:1, the boundaries of states, edges and controls 3:1), +// measured on the rendered elements against what is behind them. +import AxeBuilder from '@axe-core/playwright'; +import { expect, test, type Page } from '@playwright/test'; +import { contrast, GRAPHIC, over, parseColor, TEXT, type Rgba } from '../src/a11y/contrast'; + +const base = 'http://127.0.0.1:5194'; + +async function openWorkflow(page: Page) { + await page.goto(base + '/'); + await page.getByRole('navigation', { name: 'Workspace' }).getByRole('link', { name: 'Workflow order-fulfilment' }).click(); + await expect(page.getByRole('heading', { level: 1, name: 'order-fulfilment.sfflow.yaml' })).toBeVisible(); + await expect(page.locator('.flow[data-ready="true"]')).toBeVisible({ timeout: 30_000 }); +} + +test('STU-E2E-01 the OrderFulfilment sample opens: four services, a valid workflow, the doc example paths', async ({ page }) => { + await page.goto(base + '/'); + await expect(page.getByRole('heading', { level: 1, name: 'commerce' })).toBeVisible(); + const map = page.getByRole('region', { name: 'Domain map of commerce' }); + await expect(map.locator('.flow[data-ready="true"]')).toBeVisible({ timeout: 30_000 }); + for (const service of ['orders', 'inventory', 'payments', 'shipping']) { + await expect(map.locator(`.react-flow__node[data-id="service:${service}"]`)).toBeVisible(); + } + + await expect(map.locator('[aria-label^="Topic inventory.events"]')).toBeVisible(); + await expect(map.locator('[aria-label="orders commands payment: payments.charge.v1, payments.refund.v1"]')).toBeAttached(); + + await openWorkflow(page); + await expect(page.getByRole('region', { name: 'Diagnostics' }).getByRole('status')).toHaveText('No problems.', { timeout: 30_000 }); + await expect(page.locator('.react-flow__node[data-id="create-shipment"]')).toHaveAttribute('aria-label', /^Pivot \(point of no return\): create-shipment/); + await page.getByRole('tab', { name: 'Paths' }).click(); + await expect(page.getByRole('region', { name: 'Paths' }).getByRole('status').first()) + .toContainText('437 paths · ', { timeout: 30_000 }); + await expect(page.getByRole('region', { name: 'Paths' }).getByRole('status').first()).toContainText('a minimal cover of 6'); + const scan = await new AxeBuilder({ page }).withTags(['wcag2a', 'wcag2aa']).analyze(); + expect(scan.violations.filter((v) => v.impact === 'serious' || v.impact === 'critical').map((v) => v.id)).toEqual([]); +}); + +interface Measured { + what: string; + color: string; + layers: string[]; +} + +// Every element's colour (a stroke, a border, text) and the backgrounds behind it, from itself (or its parent, for a +// border, which sits on the outside) up to the page. +async function measure(page: Page, rules: { selector: string; property: 'stroke' | 'border-top-color' | 'color'; from: 'self' | 'parent' }[]): Promise { + return page.evaluate((list) => list.flatMap(({ selector, property, from }) => + [...document.querySelectorAll(selector)] + .filter((element) => { + const box = element.getBoundingClientRect(); + return box.width > 0 && box.height > 0 && !(element as HTMLButtonElement).disabled; + }) + .slice(0, 40) + .map((element) => { + const layers: string[] = []; + for (let e: Element | null = from === 'self' ? element : element.parentElement; e !== null; e = e.parentElement) { + layers.push(getComputedStyle(e).backgroundColor); + } + + const label = element.getAttribute('aria-label') ?? element.closest('[aria-label]')?.getAttribute('aria-label') ?? element.textContent?.slice(0, 30) ?? ''; + return { what: `${selector} (${label})`, color: getComputedStyle(element).getPropertyValue(property), layers }; + })), rules); +} + +function behind(layers: string[]): Rgba { + const parsed = layers.map((l) => parseColor(l) ?? { r: 0, g: 0, b: 0, a: 0 }); + const opaque = parsed.findIndex((c) => c.a >= 1); + const above = opaque < 0 ? parsed : parsed.slice(0, opaque); + return above.reduceRight((result, layer) => over(layer, result), parsed[opaque] ?? { r: 255, g: 255, b: 255, a: 1 }); +} + +function failing(measured: Measured[], minimum: number): string[] { + return measured.flatMap((m) => { + const color = parseColor(m.color); + if (color === undefined || color.a === 0) { + return []; + } + + const back = behind(m.layers); + const ratio = contrast(over(color, back), back); + return ratio < minimum ? [`${m.what}: ${ratio.toFixed(2)}:1`] : []; + }); +} + +for (const theme of ['Light', 'Dark']) { + test(`STU-A11Y-04 states, edges, controls and labels meet WCAG contrast (${theme})`, async ({ page }) => { + await page.goto(base + '/'); + await page.getByRole('radio', { name: theme }).check(); + await expect(page.locator('.flow[data-ready="true"]')).toBeVisible({ timeout: 30_000 }); + const map = await measure(page, [ + { selector: '.map-service', property: 'border-top-color', from: 'parent' }, + { selector: '.map-aggregate', property: 'border-top-color', from: 'parent' }, + { selector: '.map-topic', property: 'border-top-color', from: 'parent' }, + { selector: 'path.map-edge', property: 'stroke', from: 'parent' }, + ]); + + await openWorkflow(page); + const chart = await measure(page, [ + { selector: '.state', property: 'border-top-color', from: 'parent' }, + { selector: '.react-flow__edge-path', property: 'stroke', from: 'parent' }, + { selector: '.button', property: 'border-top-color', from: 'parent' }, + { selector: 'select', property: 'border-top-color', from: 'parent' }, + ]); + const labels = await measure(page, [ + { selector: '.edge-label', property: 'color', from: 'self' }, + { selector: '.state-detail', property: 'color', from: 'self' }, + ]); + + expect(map.length + chart.length).toBeGreaterThan(30); + expect(labels.length).toBeGreaterThan(10); + expect([...failing(map, GRAPHIC), ...failing(chart, GRAPHIC), ...failing(labels, TEXT)]).toEqual([]); + }); +} diff --git a/web/app/e2e/serve-static.mjs b/web/app/e2e/serve-static.mjs new file mode 100644 index 00000000..06412df1 --- /dev/null +++ b/web/app/e2e/serve-static.mjs @@ -0,0 +1,31 @@ +// A plain static file server for STU-E2E-15: it serves a folder under a sub-path, with no fallback to index.html (like +// GitHub Pages or a docs portal), so the static site must work with relative URLs and hash routes. +// node e2e/serve-static.mjs [/prefix/] +import { createReadStream, existsSync, statSync } from 'node:fs'; +import { createServer } from 'node:http'; +import { extname, join, normalize, resolve, sep } from 'node:path'; + +const [, , dir, port = '5195', prefix = '/'] = process.argv; +const root = resolve(dir); +const TYPES = { + '.html': 'text/html; charset=utf-8', '.js': 'text/javascript', '.mjs': 'text/javascript', '.css': 'text/css', '.json': 'application/json', + '.wasm': 'application/wasm', '.svg': 'image/svg+xml', '.ttf': 'font/ttf', '.dat': 'application/octet-stream', '.png': 'image/png', +}; + +createServer((request, response) => { + const path = decodeURIComponent(new URL(request.url ?? '/', 'http://localhost').pathname); + if (!path.startsWith(prefix)) { + response.writeHead(404).end('Not found'); + return; + } + + const relative = normalize(path.slice(prefix.length) || 'index.html'); + const file = join(root, relative.endsWith(sep) || relative === '.' ? join(relative, 'index.html') : relative); + if (!file.startsWith(root) || !existsSync(file) || !statSync(file).isFile()) { + response.writeHead(404).end('Not found'); + return; + } + + response.writeHead(200, { 'Content-Type': TYPES[extname(file)] ?? 'application/octet-stream', 'Cache-Control': 'no-cache' }); + createReadStream(file).pipe(response); +}).listen(Number(port), '127.0.0.1'); diff --git a/web/app/e2e/shell.spec.ts b/web/app/e2e/shell.spec.ts new file mode 100644 index 00000000..76f02469 --- /dev/null +++ b/web/app/e2e/shell.spec.ts @@ -0,0 +1,61 @@ +// STU-E2E-01..03: open the workspace, open workflows with diagnostics from the WebAssembly core, and the read-only host. +import { expect, test } from '@playwright/test'; + +test('STU-E2E-01 opens the workspace: the domain, its services and their workflows', async ({ page }) => { + await page.goto('/'); + await expect(page.getByRole('heading', { level: 1, name: 'commerce' })).toBeVisible(); + const explorer = page.getByRole('navigation', { name: 'Workspace' }); + for (const service of ['orders', 'inventory', 'payments', 'shipping']) { + await expect(explorer.getByRole('link', { name: `Service ${service}` })).toBeVisible(); + } + + await expect(explorer.getByRole('link', { name: 'Workflow order-fulfilment' })).toBeVisible(); + await expect(explorer.getByRole('link', { name: 'Workflow unknown-type' })).toBeVisible(); + await explorer.getByRole('link', { name: 'Service payments' }).click(); + await expect(page).toHaveURL(/\/services\/payments$/); + await expect(page.getByRole('heading', { level: 1, name: 'payments' })).toBeVisible(); + + // A client route reloads into the SPA. + await page.reload(); + await expect(page.getByRole('heading', { level: 1, name: 'payments' })).toBeVisible(); +}); + +test('STU-E2E-02 opens workflows: the WebAssembly core validates them in a worker', async ({ page }) => { + await page.goto('/'); + const explorer = page.getByRole('navigation', { name: 'Workspace' }); + await explorer.getByRole('link', { name: 'Workflow order-fulfilment' }).click(); + await expect(page.getByRole('heading', { level: 1, name: 'order-fulfilment.sfflow.yaml' })).toBeVisible(); + const diagnostics = page.getByRole('region', { name: 'Diagnostics' }); + await expect(diagnostics.getByRole('status')).toHaveText('No problems.', { timeout: 30_000 }); + + await explorer.getByRole('link', { name: 'Workflow unknown-type' }).click(); + const error = diagnostics.getByRole('button', { name: /Error WF-V01/ }).first(); + await expect(error).toBeVisible({ timeout: 30_000 }); + const line = /line (\d+)/.exec((await error.textContent()) ?? '')?.[1]; + await error.click(); + // The YAML tab opens in Monaco on the diagnostic's line, with the core's diagnostics as markers. + await expect(page.getByRole('tab', { name: 'YAML' })).toHaveAttribute('aria-selected', 'true'); + const monaco = page.getByTestId('monaco'); + await expect(monaco).toHaveAttribute('data-cursor-line', line ?? /\d+/, { timeout: 30_000 }); + await expect(monaco.locator('.squiggly-error').first()).toBeAttached(); + + await page.keyboard.press('Shift+?'); + await expect(page.getByRole('dialog', { name: 'Keyboard map' })).toBeVisible(); + await page.keyboard.press('Escape'); + await expect(page.getByRole('dialog')).toHaveCount(0); +}); + +test('STU-E2E-03 a read-only host shows it and refuses writes', async ({ page }) => { + await page.goto('http://127.0.0.1:5198/services/orders'); + await expect(page.getByRole('note')).toHaveText('Read-only'); + await expect(page.getByRole('button', { name: 'Export the manifest again' })).toBeDisabled(); + + const write = await page.request.put('http://127.0.0.1:5198/api/files?path=orders%2Fworkflows%2Forder-fulfilment.sfflow.yaml', { + data: { content: 'name: changed' }, + }); + expect(write.status()).toBe(403); + expect(await write.text()).toContain('--read-only'); + + const rebinding = await page.request.get('http://127.0.0.1:5198/api/workspace', { headers: { Host: 'evil.example' } }); + expect(rebinding.status()).toBe(403); +}); diff --git a/web/app/e2e/simulation.spec.ts b/web/app/e2e/simulation.spec.ts new file mode 100644 index 00000000..cc522768 --- /dev/null +++ b/web/app/e2e/simulation.spec.ts @@ -0,0 +1,126 @@ +// STU-E2E-11..13 (plan 10 §3.3): the simulation panel, the path explorer and spec generation in the browser, on the +// real WebAssembly core and the writable host over a fresh copy of the golden workspace (e2e/generate.mjs +// editable-workspace), whose orders service has a test project. +import AxeBuilder from '@axe-core/playwright'; +import { expect, test, type Page } from '@playwright/test'; +import { readFileSync } from 'node:fs'; +import { fileURLToPath } from 'node:url'; + +const base = 'http://127.0.0.1:5196'; +const specsFile = fileURLToPath(new URL('../../../artifacts/studio-e2e/editable/orders/tests/Workflows/OrderFulfilmentV1PathTests.cs', import.meta.url)); +const order = '{ "orderId": "o-1", "total": 100, "lines": ["sku"] }'; + +async function openWorkflow(page: Page, name: string, host = base) { + await page.goto(host + '/'); + await page.getByRole('navigation', { name: 'Workspace' }).getByRole('link', { name: `Workflow ${name}` }).click(); + await expect(page.getByRole('heading', { level: 1, name: `${name}.sfflow.yaml` })).toBeVisible(); + await expect(page.locator('.flow[data-ready="true"]')).toBeVisible({ timeout: 30_000 }); +} + +const panel = (page: Page) => page.getByRole('region', { name: 'Simulate' }); +const state = (page: Page, term: string) => panel(page).getByRole('definition').filter({ has: page.locator(`xpath=preceding-sibling::dt[1][text()="${term}"]`) }); +const status = (page: Page) => panel(page).getByTestId('sim-status'); +const active = (page: Page, node: string) => page.locator(`.react-flow__node[data-id="${node}"] [data-active="true"]`); + +async function start(page: Page) { + await page.getByRole('tab', { name: 'Simulate' }).click(); + await panel(page).getByRole('textbox', { name: 'Start event data (JSON)' }).fill(order); + await panel(page).getByRole('button', { name: /^(Start|Restart)$/ }).click(); + await expect(status(page)).toHaveText('Running', { timeout: 30_000 }); +} + +test('STU-E2E-11 steps an instance through retries to completion, with its timer, outbox and data', async ({ page }) => { + await openWorkflow(page, 'simulation'); + await start(page); + await expect(state(page, 'Step')).toHaveText('reserve-stock'); + await expect(active(page, 'reserve-stock')).toBeVisible(); + await expect(panel(page).getByRole('region', { name: 'Timers' })).toContainText('⏱ timeout for reserve-stock, attempt 1, due 2026-01-01T00:05:00'); + await expect(panel(page).getByRole('region', { name: 'Outbox' })).toContainText('→ inventory.reserve-stock.v1'); + + await panel(page).getByRole('button', { name: 'Step' }).click(); + await expect(state(page, 'Step')).toHaveText('charge-payment'); + await panel(page).getByRole('combobox', { name: 'Next outcome' }).selectOption('rejected:payments.declined'); + await panel(page).getByRole('button', { name: 'Step' }).click(); + await expect(state(page, 'Phase')).toHaveText('Retrying'); + await expect(panel(page).getByRole('region', { name: 'Timers' })).toContainText('⏱ retry for charge-payment'); + await expect(panel(page).getByRole('combobox', { name: 'Next outcome' })).toHaveValue('retry'); + await panel(page).getByRole('button', { name: 'Step' }).click(); + await expect(state(page, 'Attempt')).toHaveText('2'); + const charges = panel(page).getByRole('region', { name: 'Outbox' }).getByRole('listitem').filter({ hasText: 'payments.charge.v1' }); + await expect(charges).toHaveCount(2); + const ids = await charges.locator('code').evaluateAll((codes) => codes.map((c) => c.getAttribute('title'))); + expect(new Set(ids).size).toBe(2); // a re-sent attempt has its own deterministic id + + await panel(page).getByRole('button', { name: 'Run to the end' }).click(); + await expect(status(page)).toHaveText('Completed', { timeout: 30_000 }); + await expect(panel(page).getByRole('status').filter({ hasText: 'The instance has ended: Completed.' })).toBeVisible(); + await expect(panel(page).getByRole('region', { name: 'Outbox' }).getByRole('listitem').last()).toContainText('orders.mark-fulfilled.v1'); + await expect(panel(page).getByRole('region', { name: 'Data' })).toContainText('"orderId": "o-1"'); + await expect(active(page, 'Completed')).toBeVisible(); + + const scan = await new AxeBuilder({ page }).withTags(['wcag2a', 'wcag2aa']).analyze(); + const serious = scan.violations.filter((v) => v.impact === 'serious' || v.impact === 'critical'); + expect(serious.map((v) => `${v.id}: ${v.nodes.map((n) => n.target.join(' ')).slice(0, 3).join(', ')}`)).toEqual([]); +}); + +test('STU-E2E-12 simulates the compensated paths: from the path explorer, and from a plan', async ({ page }) => { + await openWorkflow(page, 'simulation'); + await page.getByRole('tab', { name: 'Paths' }).click(); + const explorer = page.getByRole('region', { name: 'Paths' }); + await expect(explorer.getByRole('status').first()).toContainText('paths ·', { timeout: 30_000 }); + await explorer.getByRole('combobox', { name: 'Show' }).selectOption('Compensated'); + const first = explorer.getByRole('list', { name: 'Paths of simulation.sfflow.yaml' }).getByRole('listitem').first(); + const id = (await first.locator('strong').textContent())!; + await first.getByRole('button', { name: `Simulate ${id}` }).click(); + + await expect(page.getByRole('tab', { name: 'Simulate' })).toHaveAttribute('aria-selected', 'true'); + await expect(status(page)).toHaveText('Compensated', { timeout: 30_000 }); + await expect(state(page, 'Path')).toHaveText(id); + await page.getByRole('tab', { name: 'Statechart' }).click(); + await expect(active(page, 'Compensated')).toBeVisible({ timeout: 30_000 }); + await expect(panel(page).getByRole('region', { name: 'Outbox' })).toContainText('orders.cancel-order.v1'); + + // The same unwinding from a plan: fraud at the payment undoes the stock reservation. + await panel(page).getByRole('combobox', { name: 'Outcome of charge-payment' }).selectOption('rejected:payments.fraud_suspected'); + await start(page); + await panel(page).getByRole('button', { name: 'Step' }).click(); + await panel(page).getByRole('combobox', { name: 'Next outcome' }).selectOption('rejected:payments.fraud_suspected'); + await panel(page).getByRole('button', { name: 'Step' }).click(); + await expect(status(page)).toHaveText('Compensating'); + await expect(panel(page).getByRole('region', { name: 'Compensation stack' })).toContainText('⟲ undo reserve-stock'); + await expect(active(page, 'undo:reserve-stock')).toBeVisible(); + await expect(panel(page).getByRole('region', { name: 'Outbox' }).getByRole('listitem').last()).toContainText('inventory.release-stock.v1'); + await panel(page).getByRole('button', { name: 'Run to the end' }).click(); + await expect(status(page)).toHaveText('Compensated', { timeout: 30_000 }); + await expect(state(page, 'Failure')).toContainText('payments.fraud_suspected at charge-payment'); +}); + +test('STU-E2E-13 generates specs for the selected paths into the owner test project', async ({ page }) => { + await openWorkflow(page, 'simulation'); + await page.getByRole('tab', { name: 'Paths' }).click(); + const explorer = page.getByRole('region', { name: 'Paths' }); + await expect(explorer.getByText(/paths selected, covering/)).toBeVisible({ timeout: 30_000 }); + await explorer.getByRole('button', { name: 'Preview specs' }).click(); + const preview = explorer.getByLabel('Specs preview'); + await expect(preview).toContainText('namespace Orders.Tests.Workflows;', { timeout: 30_000 }); + await expect(preview).toContainText('WorkflowSpec.For()'); + await expect(explorer.getByRole('status', { name: 'Specs' })).toHaveText(/^\d+ tests for orders\/tests\/Workflows\/OrderFulfilmentV1PathTests\.cs\.$/); + + await explorer.getByRole('button', { name: 'Write specs' }).click(); + await expect(explorer.getByRole('status', { name: 'Specs' })).toHaveText(/^Wrote \d+ tests to orders\/tests\/Workflows\/OrderFulfilmentV1PathTests\.cs\.$/); + expect(readFileSync(specsFile, 'utf8')).toBe(await preview.textContent()); + + // One path only: the file is regenerated with one test. + await explorer.getByRole('button', { name: 'Clear the selection' }).click(); + await explorer.getByRole('checkbox', { name: 'Select P01' }).check(); + await explorer.getByRole('button', { name: 'Write specs' }).click(); + await expect(explorer.getByRole('status', { name: 'Specs' })).toHaveText('Wrote 1 test to orders/tests/Workflows/OrderFulfilmentV1PathTests.cs.'); + expect(readFileSync(specsFile, 'utf8').match(/\[Fact/g)).toHaveLength(1); + + // A workspace whose service has no test project says what to add. + await openWorkflow(page, 'order-fulfilment', 'http://127.0.0.1:5198'); + await page.getByRole('tab', { name: 'Paths' }).click(); + const readOnly = page.getByRole('region', { name: 'Paths' }); + await expect(readOnly.getByText(/To write specs, give orders a tests folder/)).toBeVisible({ timeout: 30_000 }); + await expect(readOnly.getByRole('button', { name: 'Write specs' })).toBeDisabled(); +}); diff --git a/web/app/e2e/views.spec.ts b/web/app/e2e/views.spec.ts new file mode 100644 index 00000000..960fb1fe --- /dev/null +++ b/web/app/e2e/views.spec.ts @@ -0,0 +1,104 @@ +// STU-E2E-04..06 (the domain map, the statechart, the swimlane) and STU-A11Y-01..03 (plan 10 §3.3). +import AxeBuilder from '@axe-core/playwright'; +import { expect, test, type Page } from '@playwright/test'; + +async function openWorkflow(page: Page, name: string) { + await page.goto('/'); + await page.getByRole('navigation', { name: 'Workspace' }).getByRole('link', { name: `Workflow ${name}` }).click(); + await expect(page.getByRole('heading', { level: 1, name: `${name}.sfflow.yaml` })).toBeVisible(); +} + +async function statechartReady(page: Page) { + await expect(page.locator('.flow[data-ready="true"]')).toBeVisible({ timeout: 30_000 }); + await expect(page.locator('.react-flow__edge').first()).toBeAttached(); +} + +test('STU-E2E-04 the domain map shows who owns what, and highlights a choreography chain', async ({ page }) => { + await page.goto('/'); + const map = page.getByRole('region', { name: 'Domain map of commerce' }); + await expect(map.locator('.flow[data-ready="true"]')).toBeVisible({ timeout: 30_000 }); + await expect(map.getByLabel('Aggregate stock: inventory.release-stock.v1, inventory.reserve-stock.v1')).toBeVisible(); + await expect(map.locator('[aria-label="orders commands stock: inventory.release-stock.v1, inventory.reserve-stock.v1"]')).toBeAttached(); + await expect(map.locator('[aria-label^="Topic orders.events"]')).toBeVisible(); + + // Keyboard: focus a service and press Enter to select it; its chain stays highlighted. + await map.locator('.react-flow__node[data-id="service:payments"]').focus(); + await page.keyboard.press('Enter'); + await expect(map.locator('.flow-map')).not.toHaveAttribute('data-highlighted', '0'); + await expect(map.locator('path.map-edge.highlighted').first()).toBeAttached(); +}); + +test('STU-E2E-05 the statechart draws every state and transition kind with its encoding', async ({ page }) => { + await openWorkflow(page, 'order-fulfilment'); + await statechartReady(page); + const chart = page.getByRole('region', { name: 'Statechart of order-fulfilment.sfflow.yaml' }); + await expect(chart.locator('[data-kind="pivot"]')).toContainText('◆ create-shipment'); + await expect(chart.locator('[aria-label="Retry: charge-payment is retried 3× every PT10M on payments.declined"]')).toBeAttached(); + await expect(chart.locator('[aria-label="Failure: shipping.address_invalid at create-shipment leads to await-address-fix"]')).toBeAttached(); + await expect(chart.locator('.edge-label.kind-timeout').filter({ hasText: '⏱ P1D' })).toBeVisible(); + await expect(chart.getByRole('figure', { name: 'Legend' })).toContainText('⟲ Compensation'); + const nodes = await chart.locator('.react-flow__node').count(); + expect(nodes).toBe(12); +}); + +test('STU-E2E-06 the swimlane replays a compensated path between the services', async ({ page }) => { + await openWorkflow(page, 'order-fulfilment'); + await page.getByRole('tab', { name: 'Swimlane' }).click(); + const picker = page.getByRole('combobox', { name: 'Path' }); + const compensated = await picker.locator('option', { hasText: 'Compensated' }).first().getAttribute('value'); + await picker.selectOption(compensated!); + const messages = page.getByRole('list', { name: `Messages of ${compensated}` }); + await expect(messages).toBeVisible({ timeout: 30_000 }); + await expect(messages.getByRole('listitem').filter({ hasText: '⟲' }).first()).toBeVisible(); + await expect(messages.locator('[aria-label^="command from order-fulfilment@1 (orders) to inventory"]').first()).toBeAttached(); + await expect(page.locator('.lane-head')).toContainText(['order-fulfilment@1 (orders)']); +}); + +for (const theme of ['Light', 'Dark']) { + test(`STU-A11Y-01 no serious accessibility violations in the views (${theme})`, async ({ page }) => { + await page.goto('/'); + await page.getByRole('radio', { name: theme }).check(); + await expect(page.locator('.flow[data-ready="true"]')).toBeVisible({ timeout: 30_000 }); + const scans = [await new AxeBuilder({ page }).withTags(['wcag2a', 'wcag2aa']).analyze()]; + await openWorkflow(page, 'order-fulfilment'); + await statechartReady(page); + scans.push(await new AxeBuilder({ page }).withTags(['wcag2a', 'wcag2aa']).analyze()); + await page.getByRole('tab', { name: 'Swimlane' }).click(); + await expect(page.locator('.lanes')).toBeVisible({ timeout: 30_000 }); + scans.push(await new AxeBuilder({ page }).withTags(['wcag2a', 'wcag2aa']).analyze()); + const serious = scans.flatMap((s) => s.violations).filter((v) => v.impact === 'serious' || v.impact === 'critical'); + expect(serious.map((v) => `${v.id}: ${v.nodes.map((n) => n.target.join(' ')).slice(0, 3).join(', ')}`)).toEqual([]); + }); +} + +test('STU-A11Y-02 keyboard users reach states and transitions by name', async ({ page }) => { + await openWorkflow(page, 'order-fulfilment'); + await statechartReady(page); + await page.locator('.react-flow__node').first().focus(); + await expect(page.locator('.react-flow__node:focus')).toHaveAttribute('aria-label', /^Start: /); + let names: string[] = []; + for (let i = 0; i < 40; i++) { + await page.keyboard.press('Tab'); + names.push((await page.evaluate(() => document.activeElement?.getAttribute('aria-label'))) ?? ''); + } + + names = names.filter((n) => n.length > 0); + expect(names.some((n) => n.startsWith('Pivot (point of no return): create-shipment'))).toBe(true); + expect(names.some((n) => /^(Success|Failure|Retry|Timeout|Compensation|Manual): /.test(n))).toBe(true); + await page.keyboard.press('Alt+3'); + await expect(page.getByRole('region', { name: 'Diagnostics' })).toBeFocused(); +}); + +test('STU-A11Y-03 reduced motion turns animation off, and labels never rely on colour', async ({ page }) => { + await page.emulateMedia({ reducedMotion: 'reduce' }); + await openWorkflow(page, 'order-fulfilment'); + await statechartReady(page); + const animated = await page.evaluate(() => [...document.querySelectorAll('*')].filter((e) => { + const style = getComputedStyle(e); + return style.animationName !== 'none' || parseFloat(style.transitionDuration) > 0; + }).length); + expect(animated).toBe(0); + const labels = await page.locator('.edge-label').allTextContents(); + expect(labels.length).toBeGreaterThan(10); + expect(labels.every((l) => /^[▶✓✕↻⏱⟲✋⤼]/u.test(l))).toBe(true); +}); diff --git a/web/app/e2e/workspace/orders/workflows/large.sfflow.yaml b/web/app/e2e/workspace/orders/workflows/large.sfflow.yaml new file mode 100644 index 00000000..684d6a6c --- /dev/null +++ b/web/app/e2e/workspace/orders/workflows/large.sfflow.yaml @@ -0,0 +1,1064 @@ +# Generated by e2e/generate.mjs (STU-PERF-01): 200 steps, retries, timeouts and compensations. +sourceflow.workflow: 1 +name: large +version: 1 +owner: orders +start: + on: orders.started.v1 + correlate: data.id +data: + id: { from: start.data.id } +steps: + - id: step-001 + send: { command: orders.do-1.v1, map: { id: $data.id } } + await: + success: orders.done-1.v1 + - id: step-002 + send: { command: orders.do-2.v1, map: { id: $data.id } } + await: + success: orders.done-2.v1 + - id: step-003 + send: { command: orders.do-3.v1, map: { id: $data.id } } + await: + success: orders.done-3.v1 + - id: step-004 + send: { command: orders.do-4.v1, map: { id: $data.id } } + await: + success: orders.done-4.v1 + failure: + - rejected: orders.refused + retry: { max: 2 } + then: fail + - id: step-005 + send: { command: orders.do-0.v1, map: { id: $data.id } } + await: + success: orders.done-0.v1 + - id: step-006 + send: { command: orders.do-1.v1, map: { id: $data.id } } + await: + success: orders.done-1.v1 + compensate: { send: { command: orders.undo-1.v1, map: { id: $data.id } }, await: { success: orders.undone-1.v1 } } + - id: step-007 + send: { command: orders.do-2.v1, map: { id: $data.id } } + await: + success: orders.done-2.v1 + - id: step-008 + send: { command: orders.do-3.v1, map: { id: $data.id } } + await: + success: orders.done-3.v1 + failure: + - rejected: orders.refused + retry: { max: 2 } + then: fail + - id: step-009 + send: { command: orders.do-4.v1, map: { id: $data.id } } + await: + success: orders.done-4.v1 + - id: step-010 + send: { command: orders.do-0.v1, map: { id: $data.id } } + await: + success: orders.done-0.v1 + timeout: { after: PT5M, then: manual } + - id: step-011 + send: { command: orders.do-1.v1, map: { id: $data.id } } + await: + success: orders.done-1.v1 + - id: step-012 + send: { command: orders.do-2.v1, map: { id: $data.id } } + await: + success: orders.done-2.v1 + failure: + - rejected: orders.refused + retry: { max: 2 } + then: fail + compensate: { send: { command: orders.undo-2.v1, map: { id: $data.id } }, await: { success: orders.undone-2.v1 } } + - id: step-013 + send: { command: orders.do-3.v1, map: { id: $data.id } } + await: + success: orders.done-3.v1 + - id: step-014 + send: { command: orders.do-4.v1, map: { id: $data.id } } + await: + success: orders.done-4.v1 + - id: step-015 + send: { command: orders.do-0.v1, map: { id: $data.id } } + await: + success: orders.done-0.v1 + - id: step-016 + send: { command: orders.do-1.v1, map: { id: $data.id } } + await: + success: orders.done-1.v1 + failure: + - rejected: orders.refused + retry: { max: 2 } + then: fail + - id: step-017 + send: { command: orders.do-2.v1, map: { id: $data.id } } + await: + success: orders.done-2.v1 + - id: step-018 + send: { command: orders.do-3.v1, map: { id: $data.id } } + await: + success: orders.done-3.v1 + compensate: { send: { command: orders.undo-3.v1, map: { id: $data.id } }, await: { success: orders.undone-3.v1 } } + - id: step-019 + send: { command: orders.do-4.v1, map: { id: $data.id } } + await: + success: orders.done-4.v1 + - id: step-020 + send: { command: orders.do-0.v1, map: { id: $data.id } } + await: + success: orders.done-0.v1 + failure: + - rejected: orders.refused + retry: { max: 2 } + then: fail + timeout: { after: PT5M, then: manual } + - id: step-021 + send: { command: orders.do-1.v1, map: { id: $data.id } } + await: + success: orders.done-1.v1 + - id: step-022 + send: { command: orders.do-2.v1, map: { id: $data.id } } + await: + success: orders.done-2.v1 + - id: step-023 + send: { command: orders.do-3.v1, map: { id: $data.id } } + await: + success: orders.done-3.v1 + - id: step-024 + send: { command: orders.do-4.v1, map: { id: $data.id } } + await: + success: orders.done-4.v1 + failure: + - rejected: orders.refused + retry: { max: 2 } + then: fail + compensate: { send: { command: orders.undo-4.v1, map: { id: $data.id } }, await: { success: orders.undone-4.v1 } } + - id: step-025 + send: { command: orders.do-0.v1, map: { id: $data.id } } + await: + success: orders.done-0.v1 + - id: step-026 + send: { command: orders.do-1.v1, map: { id: $data.id } } + await: + success: orders.done-1.v1 + - id: step-027 + send: { command: orders.do-2.v1, map: { id: $data.id } } + await: + success: orders.done-2.v1 + - id: step-028 + send: { command: orders.do-3.v1, map: { id: $data.id } } + await: + success: orders.done-3.v1 + failure: + - rejected: orders.refused + retry: { max: 2 } + then: fail + - id: step-029 + send: { command: orders.do-4.v1, map: { id: $data.id } } + await: + success: orders.done-4.v1 + - id: step-030 + send: { command: orders.do-0.v1, map: { id: $data.id } } + await: + success: orders.done-0.v1 + timeout: { after: PT5M, then: manual } + compensate: { send: { command: orders.undo-0.v1, map: { id: $data.id } }, await: { success: orders.undone-0.v1 } } + - id: step-031 + send: { command: orders.do-1.v1, map: { id: $data.id } } + await: + success: orders.done-1.v1 + - id: step-032 + send: { command: orders.do-2.v1, map: { id: $data.id } } + await: + success: orders.done-2.v1 + failure: + - rejected: orders.refused + retry: { max: 2 } + then: fail + - id: step-033 + send: { command: orders.do-3.v1, map: { id: $data.id } } + await: + success: orders.done-3.v1 + - id: step-034 + send: { command: orders.do-4.v1, map: { id: $data.id } } + await: + success: orders.done-4.v1 + - id: step-035 + send: { command: orders.do-0.v1, map: { id: $data.id } } + await: + success: orders.done-0.v1 + - id: step-036 + send: { command: orders.do-1.v1, map: { id: $data.id } } + await: + success: orders.done-1.v1 + failure: + - rejected: orders.refused + retry: { max: 2 } + then: fail + compensate: { send: { command: orders.undo-1.v1, map: { id: $data.id } }, await: { success: orders.undone-1.v1 } } + - id: step-037 + send: { command: orders.do-2.v1, map: { id: $data.id } } + await: + success: orders.done-2.v1 + - id: step-038 + send: { command: orders.do-3.v1, map: { id: $data.id } } + await: + success: orders.done-3.v1 + - id: step-039 + send: { command: orders.do-4.v1, map: { id: $data.id } } + await: + success: orders.done-4.v1 + - id: step-040 + send: { command: orders.do-0.v1, map: { id: $data.id } } + await: + success: orders.done-0.v1 + failure: + - rejected: orders.refused + retry: { max: 2 } + then: fail + timeout: { after: PT5M, then: manual } + - id: step-041 + send: { command: orders.do-1.v1, map: { id: $data.id } } + await: + success: orders.done-1.v1 + - id: step-042 + send: { command: orders.do-2.v1, map: { id: $data.id } } + await: + success: orders.done-2.v1 + compensate: { send: { command: orders.undo-2.v1, map: { id: $data.id } }, await: { success: orders.undone-2.v1 } } + - id: step-043 + send: { command: orders.do-3.v1, map: { id: $data.id } } + await: + success: orders.done-3.v1 + - id: step-044 + send: { command: orders.do-4.v1, map: { id: $data.id } } + await: + success: orders.done-4.v1 + failure: + - rejected: orders.refused + retry: { max: 2 } + then: fail + - id: step-045 + send: { command: orders.do-0.v1, map: { id: $data.id } } + await: + success: orders.done-0.v1 + - id: step-046 + send: { command: orders.do-1.v1, map: { id: $data.id } } + await: + success: orders.done-1.v1 + - id: step-047 + send: { command: orders.do-2.v1, map: { id: $data.id } } + await: + success: orders.done-2.v1 + - id: step-048 + send: { command: orders.do-3.v1, map: { id: $data.id } } + await: + success: orders.done-3.v1 + failure: + - rejected: orders.refused + retry: { max: 2 } + then: fail + compensate: { send: { command: orders.undo-3.v1, map: { id: $data.id } }, await: { success: orders.undone-3.v1 } } + - id: step-049 + send: { command: orders.do-4.v1, map: { id: $data.id } } + await: + success: orders.done-4.v1 + - id: step-050 + send: { command: orders.do-0.v1, map: { id: $data.id } } + await: + success: orders.done-0.v1 + timeout: { after: PT5M, then: manual } + - id: step-051 + send: { command: orders.do-1.v1, map: { id: $data.id } } + await: + success: orders.done-1.v1 + - id: step-052 + send: { command: orders.do-2.v1, map: { id: $data.id } } + await: + success: orders.done-2.v1 + failure: + - rejected: orders.refused + retry: { max: 2 } + then: fail + - id: step-053 + send: { command: orders.do-3.v1, map: { id: $data.id } } + await: + success: orders.done-3.v1 + - id: step-054 + send: { command: orders.do-4.v1, map: { id: $data.id } } + await: + success: orders.done-4.v1 + compensate: { send: { command: orders.undo-4.v1, map: { id: $data.id } }, await: { success: orders.undone-4.v1 } } + - id: step-055 + send: { command: orders.do-0.v1, map: { id: $data.id } } + await: + success: orders.done-0.v1 + - id: step-056 + send: { command: orders.do-1.v1, map: { id: $data.id } } + await: + success: orders.done-1.v1 + failure: + - rejected: orders.refused + retry: { max: 2 } + then: fail + - id: step-057 + send: { command: orders.do-2.v1, map: { id: $data.id } } + await: + success: orders.done-2.v1 + - id: step-058 + send: { command: orders.do-3.v1, map: { id: $data.id } } + await: + success: orders.done-3.v1 + - id: step-059 + send: { command: orders.do-4.v1, map: { id: $data.id } } + await: + success: orders.done-4.v1 + - id: step-060 + send: { command: orders.do-0.v1, map: { id: $data.id } } + await: + success: orders.done-0.v1 + failure: + - rejected: orders.refused + retry: { max: 2 } + then: fail + timeout: { after: PT5M, then: manual } + compensate: { send: { command: orders.undo-0.v1, map: { id: $data.id } }, await: { success: orders.undone-0.v1 } } + - id: step-061 + send: { command: orders.do-1.v1, map: { id: $data.id } } + await: + success: orders.done-1.v1 + - id: step-062 + send: { command: orders.do-2.v1, map: { id: $data.id } } + await: + success: orders.done-2.v1 + - id: step-063 + send: { command: orders.do-3.v1, map: { id: $data.id } } + await: + success: orders.done-3.v1 + - id: step-064 + send: { command: orders.do-4.v1, map: { id: $data.id } } + await: + success: orders.done-4.v1 + failure: + - rejected: orders.refused + retry: { max: 2 } + then: fail + - id: step-065 + send: { command: orders.do-0.v1, map: { id: $data.id } } + await: + success: orders.done-0.v1 + - id: step-066 + send: { command: orders.do-1.v1, map: { id: $data.id } } + await: + success: orders.done-1.v1 + compensate: { send: { command: orders.undo-1.v1, map: { id: $data.id } }, await: { success: orders.undone-1.v1 } } + - id: step-067 + send: { command: orders.do-2.v1, map: { id: $data.id } } + await: + success: orders.done-2.v1 + - id: step-068 + send: { command: orders.do-3.v1, map: { id: $data.id } } + await: + success: orders.done-3.v1 + failure: + - rejected: orders.refused + retry: { max: 2 } + then: fail + - id: step-069 + send: { command: orders.do-4.v1, map: { id: $data.id } } + await: + success: orders.done-4.v1 + - id: step-070 + send: { command: orders.do-0.v1, map: { id: $data.id } } + await: + success: orders.done-0.v1 + timeout: { after: PT5M, then: manual } + - id: step-071 + send: { command: orders.do-1.v1, map: { id: $data.id } } + await: + success: orders.done-1.v1 + - id: step-072 + send: { command: orders.do-2.v1, map: { id: $data.id } } + await: + success: orders.done-2.v1 + failure: + - rejected: orders.refused + retry: { max: 2 } + then: fail + compensate: { send: { command: orders.undo-2.v1, map: { id: $data.id } }, await: { success: orders.undone-2.v1 } } + - id: step-073 + send: { command: orders.do-3.v1, map: { id: $data.id } } + await: + success: orders.done-3.v1 + - id: step-074 + send: { command: orders.do-4.v1, map: { id: $data.id } } + await: + success: orders.done-4.v1 + - id: step-075 + send: { command: orders.do-0.v1, map: { id: $data.id } } + await: + success: orders.done-0.v1 + - id: step-076 + send: { command: orders.do-1.v1, map: { id: $data.id } } + await: + success: orders.done-1.v1 + failure: + - rejected: orders.refused + retry: { max: 2 } + then: fail + - id: step-077 + send: { command: orders.do-2.v1, map: { id: $data.id } } + await: + success: orders.done-2.v1 + - id: step-078 + send: { command: orders.do-3.v1, map: { id: $data.id } } + await: + success: orders.done-3.v1 + compensate: { send: { command: orders.undo-3.v1, map: { id: $data.id } }, await: { success: orders.undone-3.v1 } } + - id: step-079 + send: { command: orders.do-4.v1, map: { id: $data.id } } + await: + success: orders.done-4.v1 + - id: step-080 + send: { command: orders.do-0.v1, map: { id: $data.id } } + await: + success: orders.done-0.v1 + failure: + - rejected: orders.refused + retry: { max: 2 } + then: fail + timeout: { after: PT5M, then: manual } + - id: step-081 + send: { command: orders.do-1.v1, map: { id: $data.id } } + await: + success: orders.done-1.v1 + - id: step-082 + send: { command: orders.do-2.v1, map: { id: $data.id } } + await: + success: orders.done-2.v1 + - id: step-083 + send: { command: orders.do-3.v1, map: { id: $data.id } } + await: + success: orders.done-3.v1 + - id: step-084 + send: { command: orders.do-4.v1, map: { id: $data.id } } + await: + success: orders.done-4.v1 + failure: + - rejected: orders.refused + retry: { max: 2 } + then: fail + compensate: { send: { command: orders.undo-4.v1, map: { id: $data.id } }, await: { success: orders.undone-4.v1 } } + - id: step-085 + send: { command: orders.do-0.v1, map: { id: $data.id } } + await: + success: orders.done-0.v1 + - id: step-086 + send: { command: orders.do-1.v1, map: { id: $data.id } } + await: + success: orders.done-1.v1 + - id: step-087 + send: { command: orders.do-2.v1, map: { id: $data.id } } + await: + success: orders.done-2.v1 + - id: step-088 + send: { command: orders.do-3.v1, map: { id: $data.id } } + await: + success: orders.done-3.v1 + failure: + - rejected: orders.refused + retry: { max: 2 } + then: fail + - id: step-089 + send: { command: orders.do-4.v1, map: { id: $data.id } } + await: + success: orders.done-4.v1 + - id: step-090 + send: { command: orders.do-0.v1, map: { id: $data.id } } + await: + success: orders.done-0.v1 + timeout: { after: PT5M, then: manual } + compensate: { send: { command: orders.undo-0.v1, map: { id: $data.id } }, await: { success: orders.undone-0.v1 } } + - id: step-091 + send: { command: orders.do-1.v1, map: { id: $data.id } } + await: + success: orders.done-1.v1 + - id: step-092 + send: { command: orders.do-2.v1, map: { id: $data.id } } + await: + success: orders.done-2.v1 + failure: + - rejected: orders.refused + retry: { max: 2 } + then: fail + - id: step-093 + send: { command: orders.do-3.v1, map: { id: $data.id } } + await: + success: orders.done-3.v1 + - id: step-094 + send: { command: orders.do-4.v1, map: { id: $data.id } } + await: + success: orders.done-4.v1 + - id: step-095 + send: { command: orders.do-0.v1, map: { id: $data.id } } + await: + success: orders.done-0.v1 + - id: step-096 + send: { command: orders.do-1.v1, map: { id: $data.id } } + await: + success: orders.done-1.v1 + failure: + - rejected: orders.refused + retry: { max: 2 } + then: fail + compensate: { send: { command: orders.undo-1.v1, map: { id: $data.id } }, await: { success: orders.undone-1.v1 } } + - id: step-097 + send: { command: orders.do-2.v1, map: { id: $data.id } } + await: + success: orders.done-2.v1 + - id: step-098 + send: { command: orders.do-3.v1, map: { id: $data.id } } + await: + success: orders.done-3.v1 + - id: step-099 + send: { command: orders.do-4.v1, map: { id: $data.id } } + await: + success: orders.done-4.v1 + - id: step-100 + send: { command: orders.do-0.v1, map: { id: $data.id } } + await: + success: orders.done-0.v1 + failure: + - rejected: orders.refused + retry: { max: 2 } + then: fail + timeout: { after: PT5M, then: manual } + - id: step-101 + send: { command: orders.do-1.v1, map: { id: $data.id } } + await: + success: orders.done-1.v1 + - id: step-102 + send: { command: orders.do-2.v1, map: { id: $data.id } } + await: + success: orders.done-2.v1 + compensate: { send: { command: orders.undo-2.v1, map: { id: $data.id } }, await: { success: orders.undone-2.v1 } } + - id: step-103 + send: { command: orders.do-3.v1, map: { id: $data.id } } + await: + success: orders.done-3.v1 + - id: step-104 + send: { command: orders.do-4.v1, map: { id: $data.id } } + await: + success: orders.done-4.v1 + failure: + - rejected: orders.refused + retry: { max: 2 } + then: fail + - id: step-105 + send: { command: orders.do-0.v1, map: { id: $data.id } } + await: + success: orders.done-0.v1 + - id: step-106 + send: { command: orders.do-1.v1, map: { id: $data.id } } + await: + success: orders.done-1.v1 + - id: step-107 + send: { command: orders.do-2.v1, map: { id: $data.id } } + await: + success: orders.done-2.v1 + - id: step-108 + send: { command: orders.do-3.v1, map: { id: $data.id } } + await: + success: orders.done-3.v1 + failure: + - rejected: orders.refused + retry: { max: 2 } + then: fail + compensate: { send: { command: orders.undo-3.v1, map: { id: $data.id } }, await: { success: orders.undone-3.v1 } } + - id: step-109 + send: { command: orders.do-4.v1, map: { id: $data.id } } + await: + success: orders.done-4.v1 + - id: step-110 + send: { command: orders.do-0.v1, map: { id: $data.id } } + await: + success: orders.done-0.v1 + timeout: { after: PT5M, then: manual } + - id: step-111 + send: { command: orders.do-1.v1, map: { id: $data.id } } + await: + success: orders.done-1.v1 + - id: step-112 + send: { command: orders.do-2.v1, map: { id: $data.id } } + await: + success: orders.done-2.v1 + failure: + - rejected: orders.refused + retry: { max: 2 } + then: fail + - id: step-113 + send: { command: orders.do-3.v1, map: { id: $data.id } } + await: + success: orders.done-3.v1 + - id: step-114 + send: { command: orders.do-4.v1, map: { id: $data.id } } + await: + success: orders.done-4.v1 + compensate: { send: { command: orders.undo-4.v1, map: { id: $data.id } }, await: { success: orders.undone-4.v1 } } + - id: step-115 + send: { command: orders.do-0.v1, map: { id: $data.id } } + await: + success: orders.done-0.v1 + - id: step-116 + send: { command: orders.do-1.v1, map: { id: $data.id } } + await: + success: orders.done-1.v1 + failure: + - rejected: orders.refused + retry: { max: 2 } + then: fail + - id: step-117 + send: { command: orders.do-2.v1, map: { id: $data.id } } + await: + success: orders.done-2.v1 + - id: step-118 + send: { command: orders.do-3.v1, map: { id: $data.id } } + await: + success: orders.done-3.v1 + - id: step-119 + send: { command: orders.do-4.v1, map: { id: $data.id } } + await: + success: orders.done-4.v1 + - id: step-120 + send: { command: orders.do-0.v1, map: { id: $data.id } } + await: + success: orders.done-0.v1 + failure: + - rejected: orders.refused + retry: { max: 2 } + then: fail + timeout: { after: PT5M, then: manual } + compensate: { send: { command: orders.undo-0.v1, map: { id: $data.id } }, await: { success: orders.undone-0.v1 } } + - id: step-121 + send: { command: orders.do-1.v1, map: { id: $data.id } } + await: + success: orders.done-1.v1 + - id: step-122 + send: { command: orders.do-2.v1, map: { id: $data.id } } + await: + success: orders.done-2.v1 + - id: step-123 + send: { command: orders.do-3.v1, map: { id: $data.id } } + await: + success: orders.done-3.v1 + - id: step-124 + send: { command: orders.do-4.v1, map: { id: $data.id } } + await: + success: orders.done-4.v1 + failure: + - rejected: orders.refused + retry: { max: 2 } + then: fail + - id: step-125 + send: { command: orders.do-0.v1, map: { id: $data.id } } + await: + success: orders.done-0.v1 + - id: step-126 + send: { command: orders.do-1.v1, map: { id: $data.id } } + await: + success: orders.done-1.v1 + compensate: { send: { command: orders.undo-1.v1, map: { id: $data.id } }, await: { success: orders.undone-1.v1 } } + - id: step-127 + send: { command: orders.do-2.v1, map: { id: $data.id } } + await: + success: orders.done-2.v1 + - id: step-128 + send: { command: orders.do-3.v1, map: { id: $data.id } } + await: + success: orders.done-3.v1 + failure: + - rejected: orders.refused + retry: { max: 2 } + then: fail + - id: step-129 + send: { command: orders.do-4.v1, map: { id: $data.id } } + await: + success: orders.done-4.v1 + - id: step-130 + send: { command: orders.do-0.v1, map: { id: $data.id } } + await: + success: orders.done-0.v1 + timeout: { after: PT5M, then: manual } + - id: step-131 + send: { command: orders.do-1.v1, map: { id: $data.id } } + await: + success: orders.done-1.v1 + - id: step-132 + send: { command: orders.do-2.v1, map: { id: $data.id } } + await: + success: orders.done-2.v1 + failure: + - rejected: orders.refused + retry: { max: 2 } + then: fail + compensate: { send: { command: orders.undo-2.v1, map: { id: $data.id } }, await: { success: orders.undone-2.v1 } } + - id: step-133 + send: { command: orders.do-3.v1, map: { id: $data.id } } + await: + success: orders.done-3.v1 + - id: step-134 + send: { command: orders.do-4.v1, map: { id: $data.id } } + await: + success: orders.done-4.v1 + - id: step-135 + send: { command: orders.do-0.v1, map: { id: $data.id } } + await: + success: orders.done-0.v1 + - id: step-136 + send: { command: orders.do-1.v1, map: { id: $data.id } } + await: + success: orders.done-1.v1 + failure: + - rejected: orders.refused + retry: { max: 2 } + then: fail + - id: step-137 + send: { command: orders.do-2.v1, map: { id: $data.id } } + await: + success: orders.done-2.v1 + - id: step-138 + send: { command: orders.do-3.v1, map: { id: $data.id } } + await: + success: orders.done-3.v1 + compensate: { send: { command: orders.undo-3.v1, map: { id: $data.id } }, await: { success: orders.undone-3.v1 } } + - id: step-139 + send: { command: orders.do-4.v1, map: { id: $data.id } } + await: + success: orders.done-4.v1 + - id: step-140 + send: { command: orders.do-0.v1, map: { id: $data.id } } + await: + success: orders.done-0.v1 + failure: + - rejected: orders.refused + retry: { max: 2 } + then: fail + timeout: { after: PT5M, then: manual } + - id: step-141 + send: { command: orders.do-1.v1, map: { id: $data.id } } + await: + success: orders.done-1.v1 + - id: step-142 + send: { command: orders.do-2.v1, map: { id: $data.id } } + await: + success: orders.done-2.v1 + - id: step-143 + send: { command: orders.do-3.v1, map: { id: $data.id } } + await: + success: orders.done-3.v1 + - id: step-144 + send: { command: orders.do-4.v1, map: { id: $data.id } } + await: + success: orders.done-4.v1 + failure: + - rejected: orders.refused + retry: { max: 2 } + then: fail + compensate: { send: { command: orders.undo-4.v1, map: { id: $data.id } }, await: { success: orders.undone-4.v1 } } + - id: step-145 + send: { command: orders.do-0.v1, map: { id: $data.id } } + await: + success: orders.done-0.v1 + - id: step-146 + send: { command: orders.do-1.v1, map: { id: $data.id } } + await: + success: orders.done-1.v1 + - id: step-147 + send: { command: orders.do-2.v1, map: { id: $data.id } } + await: + success: orders.done-2.v1 + - id: step-148 + send: { command: orders.do-3.v1, map: { id: $data.id } } + await: + success: orders.done-3.v1 + failure: + - rejected: orders.refused + retry: { max: 2 } + then: fail + - id: step-149 + send: { command: orders.do-4.v1, map: { id: $data.id } } + await: + success: orders.done-4.v1 + - id: step-150 + send: { command: orders.do-0.v1, map: { id: $data.id } } + await: + success: orders.done-0.v1 + timeout: { after: PT5M, then: manual } + compensate: { send: { command: orders.undo-0.v1, map: { id: $data.id } }, await: { success: orders.undone-0.v1 } } + - id: step-151 + send: { command: orders.do-1.v1, map: { id: $data.id } } + await: + success: orders.done-1.v1 + - id: step-152 + send: { command: orders.do-2.v1, map: { id: $data.id } } + await: + success: orders.done-2.v1 + failure: + - rejected: orders.refused + retry: { max: 2 } + then: fail + - id: step-153 + send: { command: orders.do-3.v1, map: { id: $data.id } } + await: + success: orders.done-3.v1 + - id: step-154 + send: { command: orders.do-4.v1, map: { id: $data.id } } + await: + success: orders.done-4.v1 + - id: step-155 + send: { command: orders.do-0.v1, map: { id: $data.id } } + await: + success: orders.done-0.v1 + - id: step-156 + send: { command: orders.do-1.v1, map: { id: $data.id } } + await: + success: orders.done-1.v1 + failure: + - rejected: orders.refused + retry: { max: 2 } + then: fail + compensate: { send: { command: orders.undo-1.v1, map: { id: $data.id } }, await: { success: orders.undone-1.v1 } } + - id: step-157 + send: { command: orders.do-2.v1, map: { id: $data.id } } + await: + success: orders.done-2.v1 + - id: step-158 + send: { command: orders.do-3.v1, map: { id: $data.id } } + await: + success: orders.done-3.v1 + - id: step-159 + send: { command: orders.do-4.v1, map: { id: $data.id } } + await: + success: orders.done-4.v1 + - id: step-160 + send: { command: orders.do-0.v1, map: { id: $data.id } } + await: + success: orders.done-0.v1 + failure: + - rejected: orders.refused + retry: { max: 2 } + then: fail + timeout: { after: PT5M, then: manual } + - id: step-161 + send: { command: orders.do-1.v1, map: { id: $data.id } } + await: + success: orders.done-1.v1 + - id: step-162 + send: { command: orders.do-2.v1, map: { id: $data.id } } + await: + success: orders.done-2.v1 + compensate: { send: { command: orders.undo-2.v1, map: { id: $data.id } }, await: { success: orders.undone-2.v1 } } + - id: step-163 + send: { command: orders.do-3.v1, map: { id: $data.id } } + await: + success: orders.done-3.v1 + - id: step-164 + send: { command: orders.do-4.v1, map: { id: $data.id } } + await: + success: orders.done-4.v1 + failure: + - rejected: orders.refused + retry: { max: 2 } + then: fail + - id: step-165 + send: { command: orders.do-0.v1, map: { id: $data.id } } + await: + success: orders.done-0.v1 + - id: step-166 + send: { command: orders.do-1.v1, map: { id: $data.id } } + await: + success: orders.done-1.v1 + - id: step-167 + send: { command: orders.do-2.v1, map: { id: $data.id } } + await: + success: orders.done-2.v1 + - id: step-168 + send: { command: orders.do-3.v1, map: { id: $data.id } } + await: + success: orders.done-3.v1 + failure: + - rejected: orders.refused + retry: { max: 2 } + then: fail + compensate: { send: { command: orders.undo-3.v1, map: { id: $data.id } }, await: { success: orders.undone-3.v1 } } + - id: step-169 + send: { command: orders.do-4.v1, map: { id: $data.id } } + await: + success: orders.done-4.v1 + - id: step-170 + send: { command: orders.do-0.v1, map: { id: $data.id } } + await: + success: orders.done-0.v1 + timeout: { after: PT5M, then: manual } + - id: step-171 + send: { command: orders.do-1.v1, map: { id: $data.id } } + await: + success: orders.done-1.v1 + - id: step-172 + send: { command: orders.do-2.v1, map: { id: $data.id } } + await: + success: orders.done-2.v1 + failure: + - rejected: orders.refused + retry: { max: 2 } + then: fail + - id: step-173 + send: { command: orders.do-3.v1, map: { id: $data.id } } + await: + success: orders.done-3.v1 + - id: step-174 + send: { command: orders.do-4.v1, map: { id: $data.id } } + await: + success: orders.done-4.v1 + compensate: { send: { command: orders.undo-4.v1, map: { id: $data.id } }, await: { success: orders.undone-4.v1 } } + - id: step-175 + send: { command: orders.do-0.v1, map: { id: $data.id } } + await: + success: orders.done-0.v1 + - id: step-176 + send: { command: orders.do-1.v1, map: { id: $data.id } } + await: + success: orders.done-1.v1 + failure: + - rejected: orders.refused + retry: { max: 2 } + then: fail + - id: step-177 + send: { command: orders.do-2.v1, map: { id: $data.id } } + await: + success: orders.done-2.v1 + - id: step-178 + send: { command: orders.do-3.v1, map: { id: $data.id } } + await: + success: orders.done-3.v1 + - id: step-179 + send: { command: orders.do-4.v1, map: { id: $data.id } } + await: + success: orders.done-4.v1 + - id: step-180 + send: { command: orders.do-0.v1, map: { id: $data.id } } + await: + success: orders.done-0.v1 + failure: + - rejected: orders.refused + retry: { max: 2 } + then: fail + timeout: { after: PT5M, then: manual } + compensate: { send: { command: orders.undo-0.v1, map: { id: $data.id } }, await: { success: orders.undone-0.v1 } } + - id: step-181 + send: { command: orders.do-1.v1, map: { id: $data.id } } + await: + success: orders.done-1.v1 + - id: step-182 + send: { command: orders.do-2.v1, map: { id: $data.id } } + await: + success: orders.done-2.v1 + - id: step-183 + send: { command: orders.do-3.v1, map: { id: $data.id } } + await: + success: orders.done-3.v1 + - id: step-184 + send: { command: orders.do-4.v1, map: { id: $data.id } } + await: + success: orders.done-4.v1 + failure: + - rejected: orders.refused + retry: { max: 2 } + then: fail + - id: step-185 + send: { command: orders.do-0.v1, map: { id: $data.id } } + await: + success: orders.done-0.v1 + - id: step-186 + send: { command: orders.do-1.v1, map: { id: $data.id } } + await: + success: orders.done-1.v1 + compensate: { send: { command: orders.undo-1.v1, map: { id: $data.id } }, await: { success: orders.undone-1.v1 } } + - id: step-187 + send: { command: orders.do-2.v1, map: { id: $data.id } } + await: + success: orders.done-2.v1 + - id: step-188 + send: { command: orders.do-3.v1, map: { id: $data.id } } + await: + success: orders.done-3.v1 + failure: + - rejected: orders.refused + retry: { max: 2 } + then: fail + - id: step-189 + send: { command: orders.do-4.v1, map: { id: $data.id } } + await: + success: orders.done-4.v1 + - id: step-190 + send: { command: orders.do-0.v1, map: { id: $data.id } } + await: + success: orders.done-0.v1 + timeout: { after: PT5M, then: manual } + - id: step-191 + send: { command: orders.do-1.v1, map: { id: $data.id } } + await: + success: orders.done-1.v1 + - id: step-192 + send: { command: orders.do-2.v1, map: { id: $data.id } } + await: + success: orders.done-2.v1 + failure: + - rejected: orders.refused + retry: { max: 2 } + then: fail + compensate: { send: { command: orders.undo-2.v1, map: { id: $data.id } }, await: { success: orders.undone-2.v1 } } + - id: step-193 + send: { command: orders.do-3.v1, map: { id: $data.id } } + await: + success: orders.done-3.v1 + - id: step-194 + send: { command: orders.do-4.v1, map: { id: $data.id } } + await: + success: orders.done-4.v1 + - id: step-195 + send: { command: orders.do-0.v1, map: { id: $data.id } } + await: + success: orders.done-0.v1 + - id: step-196 + send: { command: orders.do-1.v1, map: { id: $data.id } } + await: + success: orders.done-1.v1 + failure: + - rejected: orders.refused + retry: { max: 2 } + then: fail + - id: step-197 + send: { command: orders.do-2.v1, map: { id: $data.id } } + await: + success: orders.done-2.v1 + - id: step-198 + send: { command: orders.do-3.v1, map: { id: $data.id } } + await: + success: orders.done-3.v1 + compensate: { send: { command: orders.undo-3.v1, map: { id: $data.id } }, await: { success: orders.undone-3.v1 } } + - id: step-199 + send: { command: orders.do-4.v1, map: { id: $data.id } } + await: + success: orders.done-4.v1 + - id: step-200 + send: { command: orders.do-0.v1, map: { id: $data.id } } + await: + success: orders.done-0.v1 + failure: + - rejected: orders.refused + retry: { max: 2 } + then: fail + timeout: { after: PT5M, then: manual } diff --git a/web/app/e2e/workspace/orders/workflows/order-fulfilment.sfflow.yaml b/web/app/e2e/workspace/orders/workflows/order-fulfilment.sfflow.yaml new file mode 100644 index 00000000..7fd7d7b9 --- /dev/null +++ b/web/app/e2e/workspace/orders/workflows/order-fulfilment.sfflow.yaml @@ -0,0 +1,77 @@ +sourceflow.workflow: 1 +name: order-fulfilment +version: 1 +owner: orders # generated into the orders service +description: Reserve stock, take payment, ship. + +start: + on: orders.order-placed.v1 # local domain event of the owner + correlate: data.orderId # instance id +data: # instance data, typed from schemas + orderId: { from: start.data.orderId } + amount: { from: start.data.total } + lines: { from: start.data.lines } + +steps: + - id: reserve-stock + send: { command: inventory.reserve-stock.v1, map: { orderId: $data.orderId, lines: $data.lines } } + await: + success: inventory.stock-reserved.v1 + failure: + - rejected: inventory.out_of_stock + then: fail # compensate completed steps (none yet), then Compensated + timeout: { after: PT5M, retry: { max: 2 }, then: fail } + compensate: + send: { command: inventory.release-stock.v1, map: { orderId: $data.orderId } } + await: { success: inventory.stock-released.v1 } + retry: { max: 5, backoff: exponential, initial: PT30S, cap: PT10M } + timeout: { after: PT15M } + + - id: charge-payment + send: { command: payments.charge.v1, map: { orderId: $data.orderId, amount: $data.amount } } + await: + success: + on: payments.payment-captured.v1 + capture: { paymentId: event.data.paymentId } + failure: + - rejected: payments.declined + retry: { max: 3, backoff: fixed, initial: PT10M } # business retry + then: fail + - rejected: payments.fraud_suspected + then: fail + timeout: { after: PT2M, retry: { max: 2 }, then: fail } + compensate: + send: { command: payments.refund.v1, map: { paymentId: $data.paymentId, amount: $data.amount } } + await: { success: payments.refunded.v1 } + retry: { max: 5, backoff: exponential, initial: PT1M } + timeout: { after: PT30M } + + - id: review-large-order + when: "$data.amount > 5000" # CESQL guard; skipped when false + await: + success: orders.order-approved.v1 + failure: + - on: orders.order-rejected-by-review.v1 + then: fail + timeout: { after: P1D, then: manual } + + - id: create-shipment + pivot: true # point of no return + send: { command: shipping.create-shipment.v1, map: { orderId: $data.orderId, lines: $data.lines } } + await: + success: shipping.shipment-created.v1 + failure: + - rejected: shipping.address_invalid + then: { goto: await-address-fix } # forward recovery after pivot + timeout: { after: PT1H, retry: { max: 3, backoff: exponential, initial: PT5M }, then: manual } + next: complete + + - id: await-address-fix + await: { success: orders.address-corrected.v1 } + timeout: { after: P2D, then: manual } + next: create-shipment + +on: + completed: { send: { command: orders.mark-fulfilled.v1, map: { orderId: $data.orderId } } } + compensated: { send: { command: orders.cancel-order.v1, map: { orderId: $data.orderId, reason: $failure.code } } } + manual: { alert: true } # metric + structured log + dead-letter-style record diff --git a/web/app/e2e/workspace/orders/workflows/unknown-type.sfflow.yaml b/web/app/e2e/workspace/orders/workflows/unknown-type.sfflow.yaml new file mode 100644 index 00000000..44132f46 --- /dev/null +++ b/web/app/e2e/workspace/orders/workflows/unknown-type.sfflow.yaml @@ -0,0 +1,12 @@ +sourceflow.workflow: 1 +name: approve-order +version: 1 +owner: orders +start: { on: orders.order-placed.v1, correlate: data.orderId } +data: + orderId: { from: start.data.orderId } +steps: + - id: approve + send: { command: orders.approve-the-order.v1, map: { orderId: $data.orderId } } + await: { success: orders.reject-order.v1 } + timeout: { after: PT1H, then: manual } diff --git a/web/app/e2e/workspace/sourceflow.domain.yaml b/web/app/e2e/workspace/sourceflow.domain.yaml new file mode 100644 index 00000000..b1b2e76e --- /dev/null +++ b/web/app/e2e/workspace/sourceflow.domain.yaml @@ -0,0 +1,13 @@ +# The Studio end-to-end workspace (STU-E2E): the golden suite's commerce domain, with two orders workflows. +domain: commerce +description: Order to delivery +services: + - name: orders + manifest: ../../../../tests/Golden/domain/orders.manifest.json + workflows: orders/workflows + - name: inventory + manifest: ../../../../tests/Golden/domain/inventory.manifest.json + - name: payments + manifest: ../../../../tests/Golden/domain/payments.manifest.json + - name: shipping + manifest: ../../../../tests/Golden/domain/shipping.manifest.json diff --git a/web/app/index.html b/web/app/index.html new file mode 100644 index 00000000..29b070fe --- /dev/null +++ b/web/app/index.html @@ -0,0 +1,15 @@ + + + + + + + + + SourceFlow Studio + + +
+ + + diff --git a/web/app/package.json b/web/app/package.json new file mode 100644 index 00000000..51ea896f --- /dev/null +++ b/web/app/package.json @@ -0,0 +1,52 @@ +{ + "name": "@sourceflow/studio", + "version": "0.1.0", + "private": true, + "description": "SourceFlow Studio: the workflow designer SPA (doc 15 §6, ADR-025), and `npx @sourceflow/studio build` for a read-only static site.", + "license": "MIT", + "type": "module", + "bin": { + "sourceflow-studio": "./bin/studio.mjs" + }, + "files": [ + "bin", + "dist", + "framework" + ], + "scripts": { + "dev": "vite", + "build": "vite build", + "typecheck": "tsc --noEmit -p .", + "test": "vitest run", + "e2e": "playwright test -c e2e/playwright.config.ts" + }, + "dependencies": { + "@radix-ui/react-dialog": "1.3.1", + "@sourceflow/core-client": "*", + "@tanstack/react-query": "5.105.0", + "@xyflow/react": "12.12.0", + "elkjs": "0.12.1", + "monaco-editor": "0.57.0", + "monaco-yaml": "5.5.1", + "react": "19.1.10", + "react-dom": "19.1.10", + "react-router": "7.18.5", + "yaml": "2.9.1", + "zustand": "5.0.16" + }, + "devDependencies": { + "@axe-core/playwright": "4.14.0", + "@playwright/test": "1.64.1", + "@testing-library/dom": "10.4.2", + "@testing-library/react": "16.3.3", + "@testing-library/user-event": "14.6.8", + "@types/node": "22.20.5", + "@types/react": "19.3.0", + "@types/react-dom": "19.3.0", + "@vitejs/plugin-react": "6.1.2", + "jsdom": "29.1.1", + "typescript": "6.0.3", + "vite": "8.3.5", + "vitest": "5.0.5" + } +} diff --git a/web/app/src/App.tsx b/web/app/src/App.tsx new file mode 100644 index 00000000..a457314d --- /dev/null +++ b/web/app/src/App.tsx @@ -0,0 +1,128 @@ +import { useEffect, useRef, useState } from 'react'; +import { Route, Routes, useLocation, useNavigate } from 'react-router'; +import { DiagnosticsPanel } from './components/DiagnosticsPanel.tsx'; +import { Explorer } from './components/Explorer.tsx'; +import { KeyboardMap } from './components/KeyboardMap.tsx'; +import { ThemeSwitch } from './components/ThemeSwitch.tsx'; +import { commandFor } from './keys.ts'; +import { NotFound } from './routes/NotFound.tsx'; +import { Overview } from './routes/Overview.tsx'; +import { ServiceView } from './routes/ServiceView.tsx'; +import { WorkflowView } from './routes/WorkflowView.tsx'; +import { useValidation, useWorkflowText, useWorkspace } from './services.tsx'; +import { textOf, useEditor } from './edit/editorStore.ts'; +import { useStudio } from './store.ts'; +import { applyTheme, prefersDark, resolveTheme } from './theme.ts'; +import { ownerOf, sortDiagnostics, workflowPath } from './workspace.ts'; + +/** The Studio shell (WP-S.8): header, workspace explorer, the routed view, and the diagnostics panel. */ +export function App() { + const workspace = useWorkspace(); + const location = useLocation(); + const navigate = useNavigate(); + const path = location.pathname.startsWith('/workflows/') ? workflowPath(location.pathname.slice('/workflows/'.length)) : undefined; + const text = useWorkflowText(path); + // The open workflow's live text (unsaved edits included) is what the core validates. + const live = useEditor((s) => (s.path === path && path !== undefined ? textOf(s) : undefined)) ?? text.data; + const validation = useValidation(live, workspace.data); + + const theme = useStudio((s) => s.theme); + const [systemDark, setSystemDark] = useState(prefersDark); + const resolved = resolveTheme(theme, systemDark); + useEffect(() => applyTheme(resolved), [resolved]); + useEffect(() => { + const query = typeof window.matchMedia === 'function' ? window.matchMedia('(prefers-color-scheme: dark)') : undefined; + const listener = (event: MediaQueryListEvent) => setSystemDark(event.matches); + query?.addEventListener('change', listener); + return () => query?.removeEventListener('change', listener); + }, []); + + const explorer = useRef(null); + const editor = useRef(null); + const diagnosticsPanel = useRef(null); + useEffect(() => { + const onKey = (event: KeyboardEvent) => { + const command = commandFor(event); + if (command === undefined) { + return; + } + + event.preventDefault(); + const state = useStudio.getState(); + switch (command) { + case 'keyboardMap': state.setKeyboardMapOpen(true); break; + case 'focusExplorer': explorer.current?.focus(); break; + case 'focusEditor': editor.current?.focus(); break; + case 'focusDiagnostics': diagnosticsPanel.current?.focus(); break; + case 'nextDiagnostic': state.moveDiagnostic(1); break; + case 'previousDiagnostic': state.moveDiagnostic(-1); break; + case 'toggleTheme': state.toggleTheme(resolved); break; + case 'overview': void navigate('/'); break; + case 'save': window.dispatchEvent(new Event('sourceflow:save')); break; + case 'undo': useEditor.getState().undo(); break; + case 'redo': useEditor.getState().redo(); break; + } + }; + window.addEventListener('keydown', onKey); + return () => window.removeEventListener('keydown', onKey); + }, [navigate, resolved]); + + const selectedIndex = useStudio((s) => s.selectedDiagnostic); + const sorted = validation.data === undefined ? undefined : sortDiagnostics(validation.data.diagnostics); + + if (workspace.isError) { + return ( +
+

SourceFlow Studio

+

The workspace could not be loaded: {(workspace.error as Error).message}

+
+ ); + } + + if (workspace.data === undefined) { + return

Loading the workspace…

; + } + + const data = workspace.data; + const status = path === undefined ? 'Open a workflow to see its diagnostics.' + : text.isError ? 'The workflow could not be read.' + : validation.isError ? 'The Studio core failed: ' + (validation.error as Error).message + : validation.data === undefined ? 'Validating…' : undefined; + return ( +
+
+ SourceFlow Studio + {data.domain} + {data.readOnly ? Read-only : null} + + + +
+ +
+ + } /> + } /> + s.workflowFiles.includes(path)) ? ( + + ) : ( + + )} + /> + } /> + +
+
+ +
+ +
+ ); +} diff --git a/web/app/src/a11y/contrast.ts b/web/app/src/a11y/contrast.ts new file mode 100644 index 00000000..c5398257 --- /dev/null +++ b/web/app/src/a11y/contrast.ts @@ -0,0 +1,66 @@ +// WCAG 2.1 contrast (STU-A11Y-04): relative luminance and contrast ratios of sRGB colours, shared by the tests that check +// the theme tokens and the export palettes, and by the browser check of the rendered views. + +/** An sRGB colour with 0–255 channels and an alpha of 0–1. */ +export interface Rgba { + r: number; + g: number; + b: number; + a: number; +} + +/** Parses #rgb, #rrggbb, rgb(…), rgba(…) and color(srgb …); undefined for anything else. */ +export function parseColor(text: string): Rgba | undefined { + const value = text.trim().toLowerCase(); + let match = /^#([0-9a-f]{3}|[0-9a-f]{6})$/.exec(value); + if (match?.[1] !== undefined) { + const digits = match[1]; + const hex = digits.length === 3 ? [...digits].map((c) => c + c).join('') : digits; + return { r: parseInt(hex.slice(0, 2), 16), g: parseInt(hex.slice(2, 4), 16), b: parseInt(hex.slice(4, 6), 16), a: 1 }; + } + + match = /^rgba?\(\s*([\d.]+)[,\s]+([\d.]+)[,\s]+([\d.]+)(?:\s*[,/]\s*([\d.]+%?))?\s*\)$/.exec(value); + if (match) { + return { r: Number(match[1]), g: Number(match[2]), b: Number(match[3]), a: alpha(match[4]) }; + } + + match = /^color\(srgb\s+([\d.]+)\s+([\d.]+)\s+([\d.]+)(?:\s*\/\s*([\d.]+%?))?\s*\)$/.exec(value); + if (match) { + return { r: Number(match[1]) * 255, g: Number(match[2]) * 255, b: Number(match[3]) * 255, a: alpha(match[4]) }; + } + + return undefined; +} + +function alpha(text: string | undefined): number { + if (text === undefined) { + return 1; + } + + return text.endsWith('%') ? Number(text.slice(0, -1)) / 100 : Number(text); +} + +/** drawn over an opaque . */ +export function over(top: Rgba, bottom: Rgba): Rgba { + const a = top.a; + return { r: top.r * a + bottom.r * (1 - a), g: top.g * a + bottom.g * (1 - a), b: top.b * a + bottom.b * (1 - a), a: 1 }; +} + +/** The WCAG relative luminance. */ +export function luminance({ r, g, b }: Rgba): number { + const channel = (c: number) => { + const s = c / 255; + return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4; + }; + return 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b); +} + +/** The WCAG contrast ratio of two opaque colours, 1 to 21. */ +export function contrast(a: Rgba, b: Rgba): number { + const [la, lb] = [luminance(a), luminance(b)]; + return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05); +} + +/** WCAG 2.1 AA: 4.5:1 for text (1.4.3), 3:1 for the parts of controls and graphics people must see (1.4.11). */ +export const TEXT = 4.5; +export const GRAPHIC = 3; diff --git a/web/app/src/api.ts b/web/app/src/api.ts new file mode 100644 index 00000000..1c3e7201 --- /dev/null +++ b/web/app/src/api.ts @@ -0,0 +1,151 @@ +// The Studio local host's REST API (dotnet sourceflow studio, WP-S.8). Paths are relative to the workspace file. + +export interface ServiceDto { + name: string; + /** The manifest path or URL as written in sourceflow.domain.yaml. */ + manifest: string; + /** The manifest JSON text, as the core takes it. */ + manifestJson: string; + /** The service's workflows folder, when it owns workflows. */ + workflows?: string; + /** The service's project, when Studio can re-export its manifest. */ + project?: string; + /** The service's test project folder, where Studio writes the specs of its workflows. */ + tests?: string; + /** The service's module type, which the specs register. */ + module?: string; + workflowFiles: string[]; +} + +/** What to generate specs for: one of the service's workflow files and the paths (none: the minimal cover). */ +export interface SpecsRequest { + workflow: string; + paths?: readonly string[]; + allPaths?: boolean; + /** Generate without writing: the preview. */ + dryRun?: boolean; +} + +export interface SpecsResult { + /** The file, relative to the workspace. */ + path: string; + tests: number; + bytes: number; + written: boolean; + /** The generated C#, for a dry run. */ + text?: string; +} + +export interface WorkspaceDto { + domain: string; + description?: string; + file: string; + readOnly: boolean; + /** A static site (`npx @sourceflow/studio build`): read-only, with no local host behind it. */ + staticSite?: boolean; + services: ServiceDto[]; +} + +/** A request the host refused or failed. */ +export class ApiError extends Error { + readonly status: number; + + constructor(status: number, message: string) { + super(message); + this.name = 'ApiError'; + this.status = status; + } +} + +export interface WorkspaceApi { + workspace(): Promise; + readFile(path: string): Promise; + writeFile(path: string, content: string): Promise; + exportManifest(service: string): Promise; + /** Generates (and unless `dryRun`, writes) the specs of a workflow into its owner's test project. */ + specs(service: string, request: SpecsRequest): Promise; +} + +/** The API of the host that served this page (`base` defaults to the page's origin). */ +export function hostApi(base = '', fetcher: typeof fetch = (input, init) => fetch(input, init)): WorkspaceApi { + async function request(path: string, init?: RequestInit): Promise { + const response = await fetcher(base + path, init); + if (!response.ok) { + let message = `${response.status} ${response.statusText}`; + try { + const body = (await response.json()) as { error?: string }; + message = body.error ?? message; + } catch { + // not JSON + } + + throw new ApiError(response.status, message); + } + + return response; + } + + const file = (path: string) => '/api/files?path=' + encodeURIComponent(path); + return { + async workspace() { + return (await (await request('/api/workspace')).json()) as WorkspaceDto; + }, + async readFile(path) { + return (await request(file(path))).text(); + }, + async writeFile(path, content) { + await request(file(path), { method: 'PUT', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ content }) }); + }, + async exportManifest(service) { + await request('/api/services/' + encodeURIComponent(service) + '/manifest/export', { method: 'POST' }); + }, + async specs(service, body) { + const response = await request('/api/services/' + encodeURIComponent(service) + '/specs', { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify(body), + }); + return (await response.json()) as SpecsResult; + }, + }; +} + +/** Where `npx @sourceflow/studio build` puts the workspace snapshot, next to index.html. */ +export const STATIC_DATA = { workspace: 'data/workspace.json', files: 'data/files.json' } as const; + +/** + * The API of a static site: the workspace and its files as the build wrote them, read-only. `base` is the site's folder + * (index.html's), so the site works from any path. + */ +export function staticApi(base: string, fetcher: typeof fetch = (input, init) => fetch(input, init)): WorkspaceApi { + async function json(path: string): Promise { + const response = await fetcher(new URL(path, base).href); + if (!response.ok) { + throw new ApiError(response.status, `This static site has no ${path} (${response.status}): build it again with npx @sourceflow/studio build.`); + } + + return (await response.json()) as T; + } + + let files: Promise> | undefined; + const refuse = async (): Promise => { + throw new ApiError(403, 'This is a read-only static site: open the workspace with dotnet sourceflow studio to change it.'); + }; + return { + async workspace() { + return { ...(await json(STATIC_DATA.workspace)), readOnly: true, staticSite: true }; + }, + async readFile(path) { + files ??= json>(STATIC_DATA.files); + const text = (await files)[path]; + if (text === undefined) { + throw new ApiError(404, `No file '${path}' in this static site.`); + } + + return text; + }, + writeFile: refuse, + exportManifest: refuse, + specs: refuse, + }; +} diff --git a/web/app/src/components/DiagnosticsPanel.tsx b/web/app/src/components/DiagnosticsPanel.tsx new file mode 100644 index 00000000..bffca4be --- /dev/null +++ b/web/app/src/components/DiagnosticsPanel.tsx @@ -0,0 +1,51 @@ +import type { Diagnostic } from '@sourceflow/core-client'; +import { forwardRef, useEffect } from 'react'; +import { useStudio } from '../store.ts'; +import { countDiagnostics, sortDiagnostics } from '../workspace.ts'; + +interface Props { + diagnostics: readonly Diagnostic[] | undefined; + /** Shown instead of the list (no workflow open, still validating, or the core failed). */ + status?: string; +} + +/** + * The diagnostics of the open workflow (WF-S*, WF-V*), errors first. Severity is a word and an icon, never colour + * alone (WFD-NFR-4); F8 / Shift+F8 move the selection. + */ +export const DiagnosticsPanel = forwardRef(function DiagnosticsPanel({ diagnostics, status }, ref) { + const sorted = diagnostics === undefined ? [] : sortDiagnostics(diagnostics); + const selected = useStudio((s) => s.selectedDiagnostic); + const select = useStudio((s) => s.selectDiagnostic); + const setCount = useStudio((s) => s.setDiagnostics); + useEffect(() => setCount(sorted.length), [sorted.length, setCount]); + const counts = countDiagnostics(sorted); + + return ( +
+

+ Diagnostics + {diagnostics !== undefined ? {counts.errors} error{counts.errors === 1 ? '' : 's'}, {counts.warnings} warning{counts.warnings === 1 ? '' : 's'} : null} +

+ {status !== undefined ? ( +

{status}

+ ) : sorted.length === 0 ? ( +

No problems.

+ ) : ( +
    + {sorted.map((d, index) => ( +
  1. + +
  2. + ))} +
+ )} +
+ ); +}); diff --git a/web/app/src/components/Explorer.tsx b/web/app/src/components/Explorer.tsx new file mode 100644 index 00000000..5676650c --- /dev/null +++ b/web/app/src/components/Explorer.tsx @@ -0,0 +1,38 @@ +import { forwardRef } from 'react'; +import { NavLink } from 'react-router'; +import type { WorkspaceDto } from '../api.ts'; +import { explorerTree } from '../workspace.ts'; + +/** The workspace explorer: the domain's services and the workflows each one owns (doc 15 §4). */ +export const Explorer = forwardRef(function Explorer({ workspace }, ref) { + const tree = explorerTree(workspace); + return ( + + ); +}); diff --git a/web/app/src/components/KeyboardMap.tsx b/web/app/src/components/KeyboardMap.tsx new file mode 100644 index 00000000..f4c3cc61 --- /dev/null +++ b/web/app/src/components/KeyboardMap.tsx @@ -0,0 +1,38 @@ +import * as Dialog from '@radix-ui/react-dialog'; +import { SHORTCUTS } from '../keys.ts'; +import { useStudio } from '../store.ts'; + +/** The keyboard map (`?`): every shortcut, in an accessible modal dialog. */ +export function KeyboardMap() { + const open = useStudio((s) => s.keyboardMapOpen); + const setOpen = useStudio((s) => s.setKeyboardMapOpen); + return ( + + + + + Keyboard map + + + + + + + + + {SHORTCUTS.map((shortcut) => ( + + + + + ))} + +
KeysAction
+ {shortcut.keys} + {shortcut.description}
+ Close +
+
+
+ ); +} diff --git a/web/app/src/components/Tabs.tsx b/web/app/src/components/Tabs.tsx new file mode 100644 index 00000000..7318fef9 --- /dev/null +++ b/web/app/src/components/Tabs.tsx @@ -0,0 +1,44 @@ +import { useId, useRef, type KeyboardEvent, type ReactNode } from 'react'; + +export interface Tab { + id: string; + label: string; + content: () => ReactNode; +} + +/** Accessible tabs (WAI-ARIA tabs pattern): arrow keys, Home and End move between tabs; only the selected panel renders. */ +export function Tabs({ tabs, selected, onSelect, label }: { tabs: readonly Tab[]; selected: string; onSelect: (id: string) => void; label: string }) { + const base = useId(); + const refs = useRef(new Map()); + const index = Math.max(0, tabs.findIndex((t) => t.id === selected)); + const current = tabs[index]!; + + const onKeyDown = (event: KeyboardEvent) => { + const moves: Record = { ArrowRight: index + 1, ArrowLeft: index - 1, Home: 0, End: tabs.length - 1 }; + const target = moves[event.key]; + if (target === undefined) { + return; + } + + event.preventDefault(); + const next = tabs[(target + tabs.length) % tabs.length]!; + onSelect(next.id); + refs.current.get(next.id)?.focus(); + }; + + return ( +
+
+ {tabs.map((tab) => ( + + ))} +
+
+ {current.content()} +
+
+ ); +} diff --git a/web/app/src/components/ThemeSwitch.tsx b/web/app/src/components/ThemeSwitch.tsx new file mode 100644 index 00000000..2c97153f --- /dev/null +++ b/web/app/src/components/ThemeSwitch.tsx @@ -0,0 +1,25 @@ +import { useStudio } from '../store.ts'; +import type { ThemePreference } from '../theme.ts'; + +const CHOICES: Array<{ value: ThemePreference; label: string }> = [ + { value: 'system', label: 'System' }, + { value: 'light', label: 'Light' }, + { value: 'dark', label: 'Dark' }, +]; + +/** Light, dark or the system's theme (a labelled radio group). */ +export function ThemeSwitch() { + const theme = useStudio((s) => s.theme); + const setTheme = useStudio((s) => s.setTheme); + return ( +
+ Theme + {CHOICES.map((choice) => ( + + ))} +
+ ); +} diff --git a/web/app/src/edit/CodeEditor.tsx b/web/app/src/edit/CodeEditor.tsx new file mode 100644 index 00000000..9ecc6ea6 --- /dev/null +++ b/web/app/src/edit/CodeEditor.tsx @@ -0,0 +1,38 @@ +import type { Diagnostic } from '@sourceflow/core-client'; +import { useEffect, useRef, type ComponentType } from 'react'; + +/** The code editor beside the canvas: Monaco in the app (MonacoEditor.tsx), a plain textarea in tests and as a fallback. */ +export interface CodeEditorProps { + path: string; + value: string; + onChange: (value: string) => void; + diagnostics: readonly Diagnostic[]; + readOnly: boolean; + label: string; + reveal: { line: number; nonce: number } | undefined; +} + +export type CodeEditorComponent = ComponentType; + +/** A textarea editor: the same contract as Monaco, for tests and when Monaco can't load. */ +export function TextareaEditor({ value, onChange, readOnly, label, reveal, diagnostics }: CodeEditorProps) { + const area = useRef(null); + useEffect(() => { + const element = area.current; + if (element === null || reveal === undefined) { + return; + } + + const lines = element.value.split('\n'); + const start = lines.slice(0, reveal.line - 1).reduce((sum, line) => sum + line.length + 1, 0); + element.focus(); + element.setSelectionRange(start, start + (lines[reveal.line - 1]?.length ?? 0)); + element.dataset.cursorLine = String(reveal.line); + }, [reveal]); + return ( +
+