feat: add DST setup

.github/workflows/antithesis_daily.yml

@@ -0,0 +1,91 @@
+name: Antithesis Integration
+on:
+  workflow_dispatch:
+    inputs:
+      run_tests:
+        description: "Run Antithesis tests after pushing images"
+        type: boolean
+        default: true
+  # push:
+  #   branches:
+  #     - main
+  pull_request:
+    types: [opened, synchronize, reopened]
+    paths:
+      - "test/antithesis/**"
+  schedule:
+    - cron: "0 10 * * *"
+
+jobs:
+  push-antithesis-images:
+    name: Push Images to Antithesis
+    runs-on: shipfox-4vcpu-ubuntu-2404
+    env:
+      ANTITHESIS_PASSWORD: ${{ secrets.ANTITHESIS_PASSWORD }}
+      ANTITHESIS_SLACK_REPORT_RECIPIENT: ${{ secrets.ANTITHESIS_SLACK_REPORT_RECIPIENT }}
+      ANTITHESIS_REPOSITORY: ${{ secrets.ANTITHESIS_REPOSITORY }}
+      OPERATOR_TAG: "v2.10.1"
+      OPERATOR_UTILS_TAG: "v2.0.14"
+      GATEWAY_TAG: "v2.0.24"
+      # LEDGER_PREVIOUS_TAG: "v2.2.47"
+      # temporary: remove this when support for multiple image versions is added
+      LEDGER_PREVIOUS_TAG: "v2.3.0"
+      LEDGER_LATEST_TAG: "v2.3.0"
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Earthly
+        uses: earthly/actions-setup@v1
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          version: "latest"
+
+      - name: Setup Just
+        uses: extractions/setup-just@v3
+        with:
+          just-version: "1.40.0"
+
+      - name: Setup Environment
+        uses: ./.github/actions/default
+        with:
+          token: ${{ secrets.NUMARY_GITHUB_TOKEN }}
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: "NumaryBot"
+          password: ${{ secrets.NUMARY_GITHUB_TOKEN }}
+
+      - name: Login to Antithesis Docker Registry
+        run: |
+          echo '${{ secrets.ANTITHESIS_JSON_KEY }}' | docker login -u _json_key https://us-central1-docker.pkg.dev --password-stdin
+
+      - name: Build and Push Config Image
+        run: |
+          cd test/antithesis
+          just requirements-build
+
+      - name: Run Antithesis Tests
+        # if: ${{ github.event_name == 'workflow_dispatch' && inputs.run_tests == true }}
+        uses: antithesishq/antithesis-trigger-action@v0.8
+        with:
+          notebook_name: formance-k8s
+          tenant: formance
+          username: ${{ secrets.ANTITHESIS_USERNAME }}
+          password: ${{ secrets.ANTITHESIS_PASSWORD }}
+          github_token: ${{ secrets.NUMARY_GITHUB_TOKEN }}
+          # images: "workload:latest;docker.io/library/postgres:15-alpine;ghcr.io/formancehq/operator:${{ env.OPERATOR_TAG }};ghcr.io/formancehq/operator-utils:${{ env.OPERATOR_UTILS_TAG }};ghcr.io/formancehq/gateway:${{ env.GATEWAY_TAG }};ghcr.io/formancehq/ledger-instrumented:${{ env.LEDGER_PREVIOUS_TAG }};ghcr.io/formancehq/ledger-instrumented:${{ env.LEDGER_LATEST_TAG }}"
+          # temporary: remove this when support for multiple image versions is added
+          images: "workload:latest;docker.io/library/postgres:15-alpine;ghcr.io/formancehq/operator:${{ env.OPERATOR_TAG }};ghcr.io/formancehq/operator-utils:${{ env.OPERATOR_UTILS_TAG }};ghcr.io/formancehq/gateway:${{ env.GATEWAY_TAG }};ghcr.io/formancehq/ledger-instrumented:${{ env.LEDGER_LATEST_TAG }}"
+          config_image: "antithesis-config:k8s_test"
+          email_recipients: ${{ secrets.ANTITHESIS_SLACK_REPORT_RECIPIENT }}

.github/workflows/antithesis_release.yml

@@ -0,0 +1,53 @@
+name: Antithesis Integration
+on:
+  push:
+    tags:
+      - "*"
+
+jobs:
+  push-antithesis-images:
+    name: Push Images to Antithesis
+    runs-on: shipfox-4vcpu-ubuntu-2404
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Earthly
+        uses: earthly/actions-setup@v1
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          version: "latest"
+
+      - name: Setup Just
+        uses: extractions/setup-just@v3
+        with:
+          just-version: "1.40.0"
+
+      - name: Setup Environment
+        uses: ./.github/actions/default
+        with:
+          token: ${{ secrets.NUMARY_GITHUB_TOKEN }}
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: "NumaryBot"
+          password: ${{ secrets.NUMARY_GITHUB_TOKEN }}
+
+      - name: Login to Antithesis Docker Registry
+        run: |
+          echo '${{ secrets.ANTITHESIS_JSON_KEY }}' | docker login -u _json_key https://us-central1-docker.pkg.dev --password-stdin
+
+      - name: Build and Push Config Image
+        run: |
+          cd test/antithesis/image
+          earthly --push ./image+build --ANTITHESIS_REPOSITORY="${{ secrets.ANTITHESIS_REPOSITORY }}" --LEDGER_LATEST_TAG="${{ env.GITHUB_REF_NAME }}"

go.mod

@@ -11,6 +11,7 @@ replace google.golang.org/genproto v0.0.0-20200423170343-7949de9c1215 => google.
 require (
 	github.com/ThreeDotsLabs/watermill v1.4.7
 	github.com/alitto/pond v1.9.2
+	github.com/antithesishq/antithesis-sdk-go v0.4.3
 	github.com/antlr/antlr4/runtime/Go/antlr v1.4.10
 	github.com/bluele/gcache v0.0.2
 	github.com/dop251/goja v0.0.0-20250630131328-58d95d85e994

go.sum

@@ -34,6 +34,8 @@ github.com/andybalholm/brotli v1.1.1 h1:PR2pgnyFznKEugtsUo0xLdDop5SKXd5Qf5ysW+7X
 github.com/andybalholm/brotli v1.1.1/go.mod h1:05ib4cKhjx3OQYUY22hTVd34Bc8upXjOLL2rKwwZBoA=
 github.com/antithesishq/antithesis-sdk-go v0.4.3-default-no-op h1:+OSa/t11TFhqfrX0EOSqQBDJ0YlpmK0rDSiB19dg9M0=
 github.com/antithesishq/antithesis-sdk-go v0.4.3-default-no-op/go.mod h1:IUpT2DPAKh6i/YhSbt6Gl3v2yvUZjmKncl7U91fup7E=
+github.com/antithesishq/antithesis-sdk-go v0.4.3 h1:a2hGdDogClzHzFu20r1z0tzD6zwSWUipiaerAjZVP90=
+github.com/antithesishq/antithesis-sdk-go v0.4.3/go.mod h1:IUpT2DPAKh6i/YhSbt6Gl3v2yvUZjmKncl7U91fup7E=
 github.com/antlr/antlr4/runtime/Go/antlr v1.4.10 h1:yL7+Jz0jTC6yykIK/Wh74gnTJnrGr5AyrNMXuA0gves=
 github.com/antlr/antlr4/runtime/Go/antlr v1.4.10/go.mod h1:F7bn7fEU90QkQ3tnmaTx3LTKLEDqnwWODIYppRQ5hnY=
 github.com/antlr4-go/antlr/v4 v4.13.1 h1:SqQKkuVZ+zWkMMNkjy5FZe5mr5WURWnlpmOuzYWrPrQ=

internal/storage/driver/driver.go

@@ -4,13 +4,15 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"sync"
+	"time"
+
+	"github.com/antithesishq/antithesis-sdk-go/assert"
 	"github.com/formancehq/ledger/internal/storage/common"
 	systemstore "github.com/formancehq/ledger/internal/storage/system"
 	"github.com/formancehq/ledger/internal/tracing"
 	"go.opentelemetry.io/otel/trace"
 	"go.opentelemetry.io/otel/trace/noop"
-	"sync"
-	"time"
 
 	"github.com/alitto/pond"
 	"github.com/formancehq/go-libs/v3/bun/bunpaginate"
@@ -36,13 +38,31 @@ type Driver struct {
 	parallelBucketMigrations int
 }
 
-func (d *Driver) CreateLedger(ctx context.Context, l *ledger.Ledger) (*ledgerstore.Store, error) {
+/*
+CreateLedger creates a new ledger in the system and sets up all necessary database objects.
 
+The function follows these steps:
+ 1. Create a ledger record in the system store (_system.ledgers table)
+ 2. Get the bucket (database schema) for this ledger
+ 3. Check if the bucket is already initialized:
+    a. If initialized: Verify it's up to date and add ledger-specific objects to it
+    b. If not initialized: Create the bucket schema with all necessary tables
+ 4. Return a ledger store that provides an interface to interact with the ledger
+
+Note: This entire process is wrapped in a database transaction, ensuring atomicity.
+If any step fails, the entire transaction is rolled back, preventing partial state.
+*/
+func (d *Driver) CreateLedger(ctx context.Context, l *ledger.Ledger) (*ledgerstore.Store, error) {
 	var ret *ledgerstore.Store
+
+	// Run the entire ledger creation process in a transaction for atomicity
+	// This ensures that either all steps succeed or none do (preventing partial state)
 	err := d.db.RunInTx(ctx, nil, func(ctx context.Context, tx bun.Tx) error {
 		systemStore := d.systemStoreFactory.Create(tx)
 
+		// Step 1: Create the ledger record in the system store
 		if err := systemStore.CreateLedger(ctx, l); err != nil {
+			// Handle the case where the ledger already exists
 			if errors.Is(postgres.ResolveError(err), postgres.ErrConstraintsFailed{}) {
 				return systemstore.ErrLedgerAlreadyExists
 			}
@@ -54,13 +74,25 @@ func (d *Driver) CreateLedger(ctx context.Context, l *ledger.Ledger) (*ledgersto
 		if err != nil {
 			return fmt.Errorf("checking if bucket is initialized: %w", err)
 		}
+
 		if isInitialized {
 			upToDate, err := b.IsUpToDate(ctx, tx)
 			if err != nil {
 				return fmt.Errorf("checking if bucket is up to date: %w", err)
 			}
 
 			if !upToDate {
+				assert.AlwaysOrUnreachable(
+					// @todo: replace this with a proper flag detailing wether we're
+					// operating a new version of the binary or not.
+					// if we are, we are definitely expecting this to happen.
+					// if we're not, this should be unreachable.
+					false,
+					"Bucket is outdated",
+					map[string]any{
+						"bucket": l.Bucket,
+					},
+				)
 				return ErrBucketOutdated
 			}
 
@@ -73,14 +105,18 @@ func (d *Driver) CreateLedger(ctx context.Context, l *ledger.Ledger) (*ledgersto
 			}
 		}
 
+		// Step 4: Create a store for interacting with the ledger
 		ret = d.ledgerStoreFactory.Create(b, *l)
 
 		return nil
 	})
+
+	// If any error occurred during the transaction, resolve and return it
 	if err != nil {
 		return nil, postgres.ResolveError(err)
 	}
 
+	// Return the created ledger store
 	return ret, nil
 }
 

pkg/client/Earthfile

@@ -0,0 +1,8 @@
+VERSION 0.7
+
+FROM --platform=linux/amd64 golang:1.22.2
+
+client:
+  FROM scratch
+  COPY . /client
+  SAVE ARTIFACT /client client

test/antithesis/Justfile

@@ -0,0 +1,27 @@
+run-6min: requirements-build
+    curl --fail \
+        --user "formance:$ANTITHESIS_PASSWORD" \
+        -X POST https://formance.antithesis.com/api/v1/launch_experiment/formance-k8s -d '{ \
+          "params": { \
+            "custom.duration": "0.1", \
+            "antithesis.report.recipients": "'"$ANTITHESIS_SLACK_REPORT_RECIPIENT"'", \
+            "antithesis.config_image": "antithesis-config:k8s_test", \
+            "antithesis.images": "workload:latest;docker.io/library/postgres:15-alpine;ghcr.io/formancehq/operator:v2.10.1;ghcr.io/formancehq/operator-utils:v2.0.14;ghcr.io/formancehq/gateway:v2.0.24;ghcr.io/formancehq/ledger-instrumented:k8s_test" \
+          } \
+        }'
+
+run-1h: requirements-build
+    curl --fail \
+        --user "formance:$ANTITHESIS_PASSWORD" \
+        -X POST https://formance.antithesis.com/api/v1/launch_experiment/formance-k8s -d '{ \
+          "params": { \
+            "custom.duration": "1", \
+            "antithesis.report.recipients": "'"$ANTITHESIS_SLACK_REPORT_RECIPIENT"'", \
+            "antithesis.config_image": "antithesis-config:k8s_test", \
+            "antithesis.images": "workload:latest;docker.io/library/postgres:15-alpine;ghcr.io/formancehq/operator:v2.10.1;ghcr.io/formancehq/operator-utils:v2.0.14;ghcr.io/formancehq/gateway:v2.0.24;ghcr.io/formancehq/ledger-instrumented:k8s_test" \
+          } \
+        }'
+
+requirements-build:
+    just config/push
+    earthly --push ./workload+build --ANTITHESIS_REPOSITORY="$ANTITHESIS_REPOSITORY" --LEDGER_LATEST_TAG="$LEDGER_LATEST_TAG"

test/antithesis/config/.gitignore

@@ -0,0 +1 @@
+tmp

test/antithesis/config/Dockerfile.config

@@ -0,0 +1,2 @@
+FROM scratch
+COPY tmp/* /manifests/

test/antithesis/config/Justfile

@@ -0,0 +1,19 @@
+build-manifest:
+	rm -f -- tmp/resources.yaml
+	mkdir -p tmp
+	cat manifests/namespace.yaml >> tmp/resources.yaml
+	echo "---" >> tmp/resources.yaml
+	cat manifests/postgres.yaml >> tmp/resources.yaml
+	echo "---" >> tmp/resources.yaml
+	helm template regions oci://ghcr.io/formancehq/helm/regions --version 2.15.2 --namespace formance-systems >> tmp/resources.yaml
+	# helm template operator oci://ghcr.io/formancehq/helm/operator-crds --version v2.8.0 --namespace formance-systems >> tmp/resources.yaml
+	echo "---" >> tmp/resources.yaml
+	cat manifests/stack.yaml >> tmp/resources.yaml
+	echo "---" >> tmp/resources.yaml
+	yq '.spec.version = strenv(LEDGER_PREVIOUS_TAG)' manifests/ledger.yaml >> tmp/resources.yaml
+	echo "---" >> tmp/resources.yaml
+	cat manifests/workload.yaml >> tmp/resources.yaml
+
+push: build-manifest
+	docker build -f Dockerfile.config -t $ANTITHESIS_REPOSITORY/antithesis-config:k8s_test .
+	docker push $ANTITHESIS_REPOSITORY/antithesis-config:k8s_test

test/antithesis/config/manifests/ledger.yaml

@@ -0,0 +1,7 @@
+apiVersion: formance.com/v1beta1
+kind: Ledger
+metadata:
+  name: stack0-ledger
+spec:
+  stack: stack0
+  version: LEDGER_VERSION_PLACEHOLDER

test/antithesis/config/manifests/namespace.yaml

@@ -0,0 +1,4 @@
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: formance-systems

test/antithesis/config/manifests/postgres.yaml

@@ -0,0 +1,42 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: postgres
+  namespace: formance-systems
+spec:
+  selector:
+    app: postgres
+  ports:
+    - protocol: TCP
+      port: 5432
+      targetPort: 5432
+---
+apiVersion: v1
+kind: Pod
+metadata:
+  name: postgres
+  namespace: formance-systems
+  labels:
+    app: postgres
+spec:
+  containers:
+    - name: postgres
+      image: postgres:15-alpine
+      imagePullPolicy: IfNotPresent
+      args: ["-c", "max_connections=100"]
+      env:
+        - name: "POSTGRES_USER"
+          value: "ledger"
+        - name: "POSTGRES_PASSWORD"
+          value: "ledger"
+        - name: "POSTGRES_DB"
+          value: "ledger"
+        - name: "PGDATA"
+          value: /data/postgres
+      livenessProbe:
+        exec:
+          command: ["pg_isready", "-Uledger"]
+        initialDelaySeconds: 0
+        periodSeconds: 10
+        timeoutSeconds: 5
+        failureThreshold: 5