Send and receive SMS messages using your Android phone programmatically via a simple HTTP API
feat(api): add Turso/libSQL backend for heartbeat repositories (#886)
Acho Arnold17da946349db
diff --git a/.github/workflows/api.yml b/.github/workflows/api.ymlindex beb99182..e8044d5c 100644--- a/.github/workflows/api.yml+++ b/.github/workflows/api.yml@@ -37,6 +37,21 @@ jobs:- name: Wait for services to be healthyworking-directory: ./testsrun: |+ echo "Waiting for sqld to be healthy..."+ for i in $(seq 1 20); do+ if curl -sf http://localhost:8090/health >/dev/null 2>&1; then+ echo "sqld is healthy!"+ break+ fi+ if [ $i -eq 20 ]; then+ echo "sqld failed to become healthy"+ docker compose logs sqld+ exit 1+ fi+ echo "sqld attempt $i/20 - waiting 3s..."+ sleep 3+ done+echo "Waiting for API to be healthy..."for i in $(seq 1 40); doif docker compose exec api curl -sf http://localhost:8000/health >/dev/null 2>&1; thendiff --git a/api/go.mod b/api/go.modindex 0c6ccd0b..d77c0bf6 100644--- a/api/go.mod+++ b/api/go.mod@@ -44,6 +44,7 @@ require (github.com/stretchr/testify v1.11.1github.com/swaggo/swag v1.16.6github.com/thedevsaddam/govalidator v1.9.10+ github.com/tursodatabase/libsql-client-go v0.0.0-20260514053736-a9a8fadfe885github.com/uptrace/uptrace-go v1.43.0github.com/xuri/excelize/v2 v2.10.1go.opentelemetry.io/otel v1.43.0@@ -93,11 +94,13 @@ require (github.com/PuerkitoBio/goquery v1.12.0 // indirectgithub.com/andybalholm/brotli v1.2.1 // indirectgithub.com/andybalholm/cascadia v1.3.3 // indirect+ github.com/antlr4-go/antlr/v4 v4.13.0 // indirectgithub.com/cenkalti/backoff/v5 v5.0.3 // indirectgithub.com/cespare/xxhash/v2 v2.3.0 // indirectgithub.com/clipperhouse/displaywidth v0.11.0 // indirectgithub.com/clipperhouse/uax29/v2 v2.7.0 // indirectgithub.com/cncf/xds/go v0.0.0-20260202195803-dba9d589def2 // indirect+ github.com/coder/websocket v1.8.12 // indirectgithub.com/envoyproxy/go-control-plane/envoy v1.37.0 // indirectgithub.com/envoyproxy/protoc-gen-validate v1.3.3 // indirectgithub.com/fatih/color v1.19.0 // indirect@@ -183,6 +186,7 @@ require (go.uber.org/zap v1.28.0 // indirectgo.yaml.in/yaml/v3 v3.0.4 // indirectgolang.org/x/crypto v0.50.0 // indirect+ golang.org/x/exp v0.0.0-20240325151524-a685a6edb6d8 // indirectgolang.org/x/mod v0.35.0 // indirectgolang.org/x/net v0.53.0 // indirectgolang.org/x/oauth2 v0.36.0 // indirectdiff --git a/api/go.sum b/api/go.sumindex 5af5496f..0710b094 100644--- a/api/go.sum+++ b/api/go.sum@@ -66,6 +66,8 @@ github.com/andybalholm/brotli v1.2.1 h1:R+f5xP285VArJDRgowrfb9DqL18yVK0gKAW/F+eTgithub.com/andybalholm/brotli v1.2.1/go.mod h1:rzTDkvFWvIrjDXZHkuS16NPggd91W3kUSvPlQ1pLaKY=github.com/andybalholm/cascadia v1.3.3 h1:AG2YHrzJIm4BZ19iwJ/DAua6Btl3IwJX+VI4kktS1LM=github.com/andybalholm/cascadia v1.3.3/go.mod h1:xNd9bqTn98Ln4DwST8/nG+H0yuB8Hmgu1YHNnWw0GeA=+github.com/antlr4-go/antlr/v4 v4.13.0 h1:lxCg3LAv+EUK6t1i0y1V6/SLeUi0eKEKdhQAlS8TVTI=+github.com/antlr4-go/antlr/v4 v4.13.0/go.mod h1:pfChB/xh/Unjila75QW7+VU4TSnWnnk9UTnmpPaOR2g=github.com/avast/retry-go/v5 v5.0.0 h1:kf1Qc2UsTZ4qq8elDymqfbISvkyMuhgRxuJqX2NHP7k=github.com/avast/retry-go/v5 v5.0.0/go.mod h1://d+usmKWio1agtZfS1H/ltTqwtIfBnRq9zEwjc3eH8=github.com/bsm/ginkgo/v2 v2.12.0 h1:Ny8MWAHyOepLGlLKYmXG4IEkioBysk6GpaRTLC8zwWs=@@ -88,6 +90,8 @@ github.com/cncf/xds/go v0.0.0-20260202195803-dba9d589def2 h1:aBangftG7EVZoUb69Osgithub.com/cncf/xds/go v0.0.0-20260202195803-dba9d589def2/go.mod h1:qwXFYgsP6T7XnJtbKlf1HP8AjxZZyzxMmc+Lq5GjlU4=github.com/cockroachdb/cockroach-go/v2 v2.4.3 h1:LJO3K3jC5WXvMePRQSJE1NsIGoFGcEx1LW83W6RAlhw=github.com/cockroachdb/cockroach-go/v2 v2.4.3/go.mod h1:9U179XbCx4qFWtNhc7BiWLPfuyMVQ7qdAhfrwLz1vH0=+github.com/coder/websocket v1.8.12 h1:5bUXkEPPIbewrnkU8LTCLVaxi4N4J8ahufH2vlo4NAo=+github.com/coder/websocket v1.8.12/go.mod h1:LNVeNrXQZfe5qhS9ALED3uA+l5pPqvwXg3CKoDBB2gs=github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1VwoXQT9A3Wy9MM3WgvqSxFWenqJduM=@@ -320,6 +324,8 @@ github.com/thedevsaddam/govalidator v1.9.10 h1:m3dLRbSZ5Hts3VUWYe+vxLMG+FdyQuWOjgithub.com/thedevsaddam/govalidator v1.9.10/go.mod h1:Ilx8u7cg5g3LXbSS943cx5kczyNuUn7LH/cK5MYuE90=github.com/tiendc/go-deepcopy v1.7.2 h1:Ut2yYR7W9tWjTQitganoIue4UGxZwCcJy3orjrrIj44=github.com/tiendc/go-deepcopy v1.7.2/go.mod h1:4bKjNC2r7boYOkD2IOuZpYjmlDdzjbpTRyCx+goBCJQ=+github.com/tursodatabase/libsql-client-go v0.0.0-20260514053736-a9a8fadfe885 h1:YssVXwM/9nUAjGNmUWdgvb05JVcsaBrDn5yr+MaJTn0=+github.com/tursodatabase/libsql-client-go v0.0.0-20260514053736-a9a8fadfe885/go.mod h1:08inkKyguB6CGGssc/JzhmQWwBgFQBgjlYFjxjRh7nU=github.com/uptrace/uptrace-go v1.43.0 h1:5QuCdyFJdWUEXx6Fr6sYfezdgO6n6lnkOvUTLlyQO7U=github.com/uptrace/uptrace-go v1.43.0/go.mod h1:ehDTIdtBSolg4Z0CCvg1C8yR6VX1YFDqBcg2KmsXWn0=github.com/valyala/bytebufferpool v1.0.0 h1:GqA5TC/0021Y/b9FG4Oi9Mr3q7XYx6KllzawFIhcdPw=@@ -410,6 +416,8 @@ golang.org/x/crypto v0.23.0/go.mod h1:CKFgDieR+mRhux2Lsu27y0fO304Db0wZe70UKqHu0vgolang.org/x/crypto v0.31.0/go.mod h1:kDsLvtWBEx7MV9tJOj9bnXsPbxwJQ6csT/x4KIN4Ssk=golang.org/x/crypto v0.50.0 h1:zO47/JPrL6vsNkINmLoo/PH1gcxpls50DNogFvB5ZGI=golang.org/x/crypto v0.50.0/go.mod h1:3muZ7vA7PBCE6xgPX7nkzzjiUq87kRItoJQM1Yo8S+Q=+golang.org/x/exp v0.0.0-20240325151524-a685a6edb6d8 h1:aAcj0Da7eBAtrTp03QXWvm88pSyOt+UgdZw2BFZ+lEw=+golang.org/x/exp v0.0.0-20240325151524-a685a6edb6d8/go.mod h1:CQ1k9gNrJ50XIzaKCRR2hssIjF07kZFEiieALBM/ARQ=golang.org/x/image v0.25.0 h1:Y6uW6rH1y5y/LK1J8BPWZtr6yZ7hrsy6hFrXjgsc2fQ=golang.org/x/image v0.25.0/go.mod h1:tCAmOEGthTtkalusGp1g3xa2gke8J6c2N565dTyl9Rs=golang.org/x/mod v0.6.0-dev.0.20220419223038-86c51ed26bb4/go.mod h1:jJ57K6gSWd91VN4djpZkiMVwK6gcyfeH4XE8wZrZaV4=diff --git a/api/pkg/di/container.go b/api/pkg/di/container.goindex 2ecfa04d..ce6a82e2 100644--- a/api/pkg/di/container.go+++ b/api/pkg/di/container.go@@ -3,6 +3,7 @@ package diimport ("context""crypto/tls"+ "database/sql""fmt""net/http""os"@@ -82,6 +83,7 @@ type Container struct {projectID stringdb *gorm.DBdedicatedDB *gorm.DB+ tursoDB *sql.DBversion stringapp *fiber.AppeventDispatcher *services.EventDispatcher@@ -269,19 +271,16 @@ func (container *Container) DedicatedDB() (db *gorm.DB) {container.logger.Fatal(err)}- sqlDB, err := db.DB()- if err != nil {- container.logger.Fatal(stacktrace.Propagate(err, "cannot get sql.DB from GORM"))- }-- sqlDB.SetMaxOpenConns(1)- sqlDB.SetMaxIdleConns(0)- sqlDB.SetConnMaxLifetime(10 * time.Second)-if err = db.Use(tracing.NewPlugin()); err != nil {container.logger.Fatal(stacktrace.Propagate(err, "cannot use GORM tracing plugin"))}+ container.dedicatedDB = db+ if os.Getenv("DATABASE_MIGRATION_SKIP") != "" {+ container.logger.Debug(fmt.Sprintf("skipping migrations for [%T]", db))+ return container.dedicatedDB+ }+container.logger.Debug(fmt.Sprintf("Running migrations for dedicated [%T]", db))if err = db.AutoMigrate(&entities.Heartbeat{}); err != nil {container.logger.Fatal(stacktrace.Propagate(err, fmt.Sprintf("cannot migrate %T", &entities.Heartbeat{})))@@ -291,10 +290,43 @@ func (container *Container) DedicatedDB() (db *gorm.DB) {container.logger.Fatal(stacktrace.Propagate(err, fmt.Sprintf("cannot migrate %T", &entities.HeartbeatMonitor{})))}- container.dedicatedDB = dbreturn container.dedicatedDB}+// TursoDB creates a *sql.DB connection to a Turso/libSQL database+func (container *Container) TursoDB() *sql.DB {+ if container.tursoDB != nil {+ return container.tursoDB+ }++ container.logger.Debug("creating Turso *sql.DB connection")++ db, err := repositories.NewTursoDB(os.Getenv("TURSO_DATABASE_DSN"))+ if err != nil {+ container.logger.Fatal(err)+ }++ container.tursoDB = db+ return container.tursoDB+}++// HedgingFailureCounter creates an OTel counter for hedging secondary write failures+func (container *Container) HedgingFailureCounter() otelMetric.Int64Counter {+ meter := otel.GetMeterProvider().Meter(+ container.projectID,+ otelMetric.WithInstrumentationVersion(otel.Version()),+ )+ counter, err := meter.Int64Counter(+ "hedging.secondary.write.failures",+ otelMetric.WithUnit("1"),+ otelMetric.WithDescription("Number of failed secondary writes in hedging repositories"),+ )+ if err != nil {+ container.logger.Fatal(stacktrace.Propagate(err, "cannot create hedging failure counter"))+ }+ return counter+}+// DBWithoutMigration creates an instance of gorm.DB if it has not been created alreadyfunc (container *Container) DBWithoutMigration() (db *gorm.DB) {if container.db != nil {@@ -889,12 +921,31 @@ func (container *Container) MessageThreadRepository() (repository repositories.M// HeartbeatMonitorRepository creates a new instance of repositories.HeartbeatMonitorRepositoryfunc (container *Container) HeartbeatMonitorRepository() (repository repositories.HeartbeatMonitorRepository) {- container.logger.Debug("creating GORM repositories.HeartbeatMonitorRepository")- return repositories.NewGormHeartbeatMonitorRepository(- container.Logger(),- container.Tracer(),- container.DedicatedDB(),- )+ switch os.Getenv("HEARTBEAT_DB_BACKEND") {+ case "turso":+ container.logger.Debug("creating libSQL repositories.HeartbeatMonitorRepository")+ return repositories.NewLibsqlHeartbeatMonitorRepository(+ container.Logger(),+ container.Tracer(),+ container.TursoDB(),+ )+ case "hedging":+ container.logger.Debug("creating hedging repositories.HeartbeatMonitorRepository")+ return repositories.NewHedgingHeartbeatMonitorRepository(+ container.Logger(),+ container.Tracer(),+ repositories.NewGormHeartbeatMonitorRepository(container.Logger(), container.Tracer(), container.DedicatedDB()),+ repositories.NewLibsqlHeartbeatMonitorRepository(container.Logger(), container.Tracer(), container.TursoDB()),+ container.HedgingFailureCounter(),+ )+ default:+ container.logger.Debug("creating GORM repositories.HeartbeatMonitorRepository")+ return repositories.NewGormHeartbeatMonitorRepository(+ container.Logger(),+ container.Tracer(),+ container.DedicatedDB(),+ )+ }}// HeartbeatService creates a new instance of services.HeartbeatService@@ -1708,12 +1759,31 @@ func (container *Container) RegisterSwaggerRoutes() {// HeartbeatRepository registers a new instance of repositories.HeartbeatRepositoryfunc (container *Container) HeartbeatRepository() repositories.HeartbeatRepository {- container.logger.Debug("creating GORM repositories.HeartbeatRepository")- return repositories.NewGormHeartbeatRepository(- container.Logger(),- container.Tracer(),- container.DedicatedDB(),- )+ switch os.Getenv("HEARTBEAT_DB_BACKEND") {+ case "turso":+ container.logger.Debug("creating libSQL repositories.HeartbeatRepository")+ return repositories.NewLibsqlHeartbeatRepository(+ container.Logger(),+ container.Tracer(),+ container.TursoDB(),+ )+ case "hedging":+ container.logger.Debug("creating hedging repositories.HeartbeatRepository")+ return repositories.NewHedgingHeartbeatRepository(+ container.Logger(),+ container.Tracer(),+ repositories.NewGormHeartbeatRepository(container.Logger(), container.Tracer(), container.DedicatedDB()),+ repositories.NewLibsqlHeartbeatRepository(container.Logger(), container.Tracer(), container.TursoDB()),+ container.HedgingFailureCounter(),+ )+ default:+ container.logger.Debug("creating GORM repositories.HeartbeatRepository")+ return repositories.NewGormHeartbeatRepository(+ container.Logger(),+ container.Tracer(),+ container.DedicatedDB(),+ )+ }}// UserRepository registers a new instance of repositories.UserRepositorydiff --git a/api/pkg/repositories/hedging_heartbeat_monitor_repository.go b/api/pkg/repositories/hedging_heartbeat_monitor_repository.gonew file mode 100644index 00000000..3304230c--- /dev/null+++ b/api/pkg/repositories/hedging_heartbeat_monitor_repository.go@@ -0,0 +1,128 @@+package repositories++import (+ "context"+ "fmt"++ "github.com/google/uuid"+ otelMetric "go.opentelemetry.io/otel/metric"++ "github.com/NdoleStudio/httpsms/pkg/entities"+ "github.com/NdoleStudio/httpsms/pkg/telemetry"+ "github.com/palantir/stacktrace"+)++// hedgingHeartbeatMonitorRepository writes to both primary and secondary repositories.+// Reads only hit primary. Secondary writes are fail-open.+type hedgingHeartbeatMonitorRepository struct {+ logger telemetry.Logger+ tracer telemetry.Tracer+ primary HeartbeatMonitorRepository+ secondary HeartbeatMonitorRepository+ failureCounter otelMetric.Int64Counter+}++// NewHedgingHeartbeatMonitorRepository creates a hedging HeartbeatMonitorRepository+func NewHedgingHeartbeatMonitorRepository(+ logger telemetry.Logger,+ tracer telemetry.Tracer,+ primary HeartbeatMonitorRepository,+ secondary HeartbeatMonitorRepository,+ failureCounter otelMetric.Int64Counter,+) HeartbeatMonitorRepository {+ return &hedgingHeartbeatMonitorRepository{+ logger: logger.WithService(fmt.Sprintf("%T", &hedgingHeartbeatMonitorRepository{})),+ tracer: tracer,+ primary: primary,+ secondary: secondary,+ failureCounter: failureCounter,+ }+}++func (repository *hedgingHeartbeatMonitorRepository) Store(ctx context.Context, monitor *entities.HeartbeatMonitor) error {+ ctx, span := repository.tracer.Start(ctx)+ defer span.End()++ if err := repository.primary.Store(ctx, monitor); err != nil {+ return err+ }++ if err := repository.secondary.Store(ctx, monitor); err != nil {+ repository.logger.Error(stacktrace.Propagate(err, fmt.Sprintf("hedging: secondary write failed for monitor [%s]", monitor.ID)))+ repository.failureCounter.Add(ctx, 1)+ }++ return nil+}++func (repository *hedgingHeartbeatMonitorRepository) Load(ctx context.Context, userID entities.UserID, phoneNumber string) (*entities.HeartbeatMonitor, error) {+ return repository.primary.Load(ctx, userID, phoneNumber)+}++func (repository *hedgingHeartbeatMonitorRepository) Exists(ctx context.Context, userID entities.UserID, monitorID uuid.UUID) (bool, error) {+ return repository.primary.Exists(ctx, userID, monitorID)+}++func (repository *hedgingHeartbeatMonitorRepository) UpdateQueueID(ctx context.Context, monitorID uuid.UUID, queueID string) error {+ ctx, span := repository.tracer.Start(ctx)+ defer span.End()++ if err := repository.primary.UpdateQueueID(ctx, monitorID, queueID); err != nil {+ return err+ }++ if err := repository.secondary.UpdateQueueID(ctx, monitorID, queueID); err != nil {+ repository.logger.Error(stacktrace.Propagate(err, fmt.Sprintf("hedging: secondary UpdateQueueID failed for monitor [%s]", monitorID)))+ repository.failureCounter.Add(ctx, 1)+ }++ return nil+}++func (repository *hedgingHeartbeatMonitorRepository) Delete(ctx context.Context, userID entities.UserID, phoneNumber string) error {+ ctx, span := repository.tracer.Start(ctx)+ defer span.End()++ if err := repository.primary.Delete(ctx, userID, phoneNumber); err != nil {+ return err+ }++ if err := repository.secondary.Delete(ctx, userID, phoneNumber); err != nil {+ repository.logger.Error(stacktrace.Propagate(err, fmt.Sprintf("hedging: secondary delete failed for monitor with owner [%s]", phoneNumber)))+ repository.failureCounter.Add(ctx, 1)+ }++ return nil+}++func (repository *hedgingHeartbeatMonitorRepository) UpdatePhoneOnline(ctx context.Context, userID entities.UserID, monitorID uuid.UUID, online bool) error {+ ctx, span := repository.tracer.Start(ctx)+ defer span.End()++ if err := repository.primary.UpdatePhoneOnline(ctx, userID, monitorID, online); err != nil {+ return err+ }++ if err := repository.secondary.UpdatePhoneOnline(ctx, userID, monitorID, online); err != nil {+ repository.logger.Error(stacktrace.Propagate(err, fmt.Sprintf("hedging: secondary UpdatePhoneOnline failed for monitor [%s]", monitorID)))+ repository.failureCounter.Add(ctx, 1)+ }++ return nil+}++func (repository *hedgingHeartbeatMonitorRepository) DeleteAllForUser(ctx context.Context, userID entities.UserID) error {+ ctx, span := repository.tracer.Start(ctx)+ defer span.End()++ if err := repository.primary.DeleteAllForUser(ctx, userID); err != nil {+ return err+ }++ if err := repository.secondary.DeleteAllForUser(ctx, userID); err != nil {+ repository.logger.Error(stacktrace.Propagate(err, fmt.Sprintf("hedging: secondary delete all failed for user [%s]", userID)))+ repository.failureCounter.Add(ctx, 1)+ }++ return nil+}diff --git a/api/pkg/repositories/hedging_heartbeat_repository.go b/api/pkg/repositories/hedging_heartbeat_repository.gonew file mode 100644index 00000000..07346264--- /dev/null+++ b/api/pkg/repositories/hedging_heartbeat_repository.go@@ -0,0 +1,79 @@+package repositories++import (+ "context"+ "fmt"++ otelMetric "go.opentelemetry.io/otel/metric"++ "github.com/NdoleStudio/httpsms/pkg/entities"+ "github.com/NdoleStudio/httpsms/pkg/telemetry"+ "github.com/palantir/stacktrace"+)++// hedgingHeartbeatRepository writes to both primary and secondary repositories.+// Reads only hit primary. Secondary writes are fail-open.+type hedgingHeartbeatRepository struct {+ logger telemetry.Logger+ tracer telemetry.Tracer+ primary HeartbeatRepository+ secondary HeartbeatRepository+ failureCounter otelMetric.Int64Counter+}++// NewHedgingHeartbeatRepository creates a hedging HeartbeatRepository+func NewHedgingHeartbeatRepository(+ logger telemetry.Logger,+ tracer telemetry.Tracer,+ primary HeartbeatRepository,+ secondary HeartbeatRepository,+ failureCounter otelMetric.Int64Counter,+) HeartbeatRepository {+ return &hedgingHeartbeatRepository{+ logger: logger.WithService(fmt.Sprintf("%T", &hedgingHeartbeatRepository{})),+ tracer: tracer,+ primary: primary,+ secondary: secondary,+ failureCounter: failureCounter,+ }+}++func (repository *hedgingHeartbeatRepository) Store(ctx context.Context, heartbeat *entities.Heartbeat) error {+ ctx, span := repository.tracer.Start(ctx)+ defer span.End()++ if err := repository.primary.Store(ctx, heartbeat); err != nil {+ return err+ }++ if err := repository.secondary.Store(ctx, heartbeat); err != nil {+ repository.logger.Error(stacktrace.Propagate(err, fmt.Sprintf("hedging: secondary write failed for heartbeat [%s]", heartbeat.ID)))+ repository.failureCounter.Add(ctx, 1)+ }++ return nil+}++func (repository *hedgingHeartbeatRepository) Index(ctx context.Context, userID entities.UserID, owner string, params IndexParams) (*[]entities.Heartbeat, error) {+ return repository.primary.Index(ctx, userID, owner, params)+}++func (repository *hedgingHeartbeatRepository) Last(ctx context.Context, userID entities.UserID, owner string) (*entities.Heartbeat, error) {+ return repository.primary.Last(ctx, userID, owner)+}++func (repository *hedgingHeartbeatRepository) DeleteAllForUser(ctx context.Context, userID entities.UserID) error {+ ctx, span := repository.tracer.Start(ctx)+ defer span.End()++ if err := repository.primary.DeleteAllForUser(ctx, userID); err != nil {+ return err+ }++ if err := repository.secondary.DeleteAllForUser(ctx, userID); err != nil {+ repository.logger.Error(stacktrace.Propagate(err, fmt.Sprintf("hedging: secondary delete failed for user [%s]", userID)))+ repository.failureCounter.Add(ctx, 1)+ }++ return nil+}diff --git a/api/pkg/repositories/libsql.go b/api/pkg/repositories/libsql.gonew file mode 100644index 00000000..66ee8c0e--- /dev/null+++ b/api/pkg/repositories/libsql.go@@ -0,0 +1,67 @@+package repositories++import (+ "database/sql"+ "fmt"++ _ "github.com/tursodatabase/libsql-client-go/libsql" // libSQL database driver++ "github.com/palantir/stacktrace"+)++const (+ tableHeartbeats = "heartbeats"+ tableHeartbeatMonitors = "heartbeat_monitors"+)++// NewTursoDB creates a new *sql.DB connection to a Turso database and auto-creates tables+func NewTursoDB(dsn string) (*sql.DB, error) {+ db, err := sql.Open("libsql", dsn)+ if err != nil {+ return nil, stacktrace.Propagate(err, fmt.Sprintf("cannot open turso database with DSN [%s]", dsn))+ }++ if err = db.Ping(); err != nil {+ return nil, stacktrace.Propagate(err, fmt.Sprintf("cannot ping turso database with DSN [%s]", dsn))+ }++ if err = createTursoTables(db); err != nil {+ return nil, stacktrace.Propagate(err, "cannot create turso tables")+ }++ return db, nil+}++func createTursoTables(db *sql.DB) error {+ statements := []string{+ `CREATE TABLE IF NOT EXISTS ` + tableHeartbeats + ` (+ id TEXT PRIMARY KEY,+ owner TEXT NOT NULL,+ version TEXT NOT NULL,+ charging INTEGER NOT NULL DEFAULT 0,+ user_id TEXT NOT NULL,+ timestamp DATETIME NOT NULL+ )`,+ `CREATE INDEX IF NOT EXISTS idx_heartbeats_owner_timestamp ON ` + tableHeartbeats + `(owner, timestamp)`,+ `CREATE INDEX IF NOT EXISTS idx_heartbeats_user_id ON ` + tableHeartbeats + `(user_id)`,+ `CREATE TABLE IF NOT EXISTS ` + tableHeartbeatMonitors + ` (+ id TEXT PRIMARY KEY,+ phone_id TEXT NOT NULL,+ user_id TEXT NOT NULL,+ queue_id TEXT NOT NULL DEFAULT '',+ owner TEXT NOT NULL,+ phone_online INTEGER NOT NULL DEFAULT 1,+ created_at DATETIME NOT NULL,+ updated_at DATETIME NOT NULL+ )`,+ `CREATE INDEX IF NOT EXISTS idx_heartbeat_monitors_user_owner ON ` + tableHeartbeatMonitors + `(user_id, owner)`,+ }++ for _, stmt := range statements {+ if _, err := db.Exec(stmt); err != nil {+ return stacktrace.Propagate(err, fmt.Sprintf("cannot execute statement: %s", stmt))+ }+ }++ return nil+}diff --git a/api/pkg/repositories/libsql_heartbeat_monitor_repository.go b/api/pkg/repositories/libsql_heartbeat_monitor_repository.gonew file mode 100644index 00000000..0cb594af--- /dev/null+++ b/api/pkg/repositories/libsql_heartbeat_monitor_repository.go@@ -0,0 +1,199 @@+package repositories++import (+ "context"+ "database/sql"+ "fmt"+ "time"++ "github.com/google/uuid"++ "github.com/NdoleStudio/httpsms/pkg/entities"+ "github.com/NdoleStudio/httpsms/pkg/telemetry"+ "github.com/palantir/stacktrace"+)++// libsqlHeartbeatMonitorRepository is responsible for persisting entities.HeartbeatMonitor in Turso/libSQL+type libsqlHeartbeatMonitorRepository struct {+ logger telemetry.Logger+ tracer telemetry.Tracer+ db *sql.DB+}++// NewLibsqlHeartbeatMonitorRepository creates the libSQL version of the HeartbeatMonitorRepository+func NewLibsqlHeartbeatMonitorRepository(+ logger telemetry.Logger,+ tracer telemetry.Tracer,+ db *sql.DB,+) HeartbeatMonitorRepository {+ return &libsqlHeartbeatMonitorRepository{+ logger: logger.WithService(fmt.Sprintf("%T", &libsqlHeartbeatMonitorRepository{})),+ tracer: tracer,+ db: db,+ }+}++func (repository *libsqlHeartbeatMonitorRepository) Store(ctx context.Context, monitor *entities.HeartbeatMonitor) error {+ ctx, span := repository.tracer.Start(ctx)+ defer span.End()++ ctx, cancel := context.WithTimeout(ctx, dbOperationDuration)+ defer cancel()++ _, err := repository.db.ExecContext(ctx,+ "INSERT INTO "+tableHeartbeatMonitors+" (id, phone_id, user_id, queue_id, owner, phone_online, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)",+ monitor.ID.String(),+ monitor.PhoneID.String(),+ string(monitor.UserID),+ monitor.QueueID,+ monitor.Owner,+ boolToInt(monitor.PhoneOnline),+ monitor.CreatedAt.UTC(),+ monitor.UpdatedAt.UTC(),+ )+ if err != nil {+ msg := fmt.Sprintf("cannot save heartbeat monitor with ID [%s]", monitor.ID)+ return repository.tracer.WrapErrorSpan(span, stacktrace.Propagate(err, msg))+ }++ return nil+}++func (repository *libsqlHeartbeatMonitorRepository) Load(ctx context.Context, userID entities.UserID, phoneNumber string) (*entities.HeartbeatMonitor, error) {+ ctx, span := repository.tracer.Start(ctx)+ defer span.End()++ ctx, cancel := context.WithTimeout(ctx, dbOperationDuration)+ defer cancel()++ row := repository.db.QueryRowContext(ctx,+ "SELECT id, phone_id, user_id, queue_id, owner, phone_online, created_at, updated_at FROM "+tableHeartbeatMonitors+" WHERE user_id = ? AND owner = ? LIMIT 1",+ string(userID), phoneNumber,+ )++ monitor, err := repository.scanHeartbeatMonitorRow(row)+ if err == sql.ErrNoRows {+ msg := fmt.Sprintf("heartbeat monitor with userID [%s] and owner [%s] does not exist", userID, phoneNumber)+ return nil, repository.tracer.WrapErrorSpan(span, stacktrace.PropagateWithCode(err, ErrCodeNotFound, msg))+ }+ if err != nil {+ msg := fmt.Sprintf("cannot load heartbeat monitor with userID [%s] and owner [%s]", userID, phoneNumber)+ return nil, repository.tracer.WrapErrorSpan(span, stacktrace.Propagate(err, msg))+ }++ return monitor, nil+}++func (repository *libsqlHeartbeatMonitorRepository) Exists(ctx context.Context, userID entities.UserID, monitorID uuid.UUID) (bool, error) {+ ctx, span := repository.tracer.Start(ctx)+ defer span.End()++ ctx, cancel := context.WithTimeout(ctx, dbOperationDuration)+ defer cancel()++ var count int+ err := repository.db.QueryRowContext(ctx,+ "SELECT COUNT(*) FROM "+tableHeartbeatMonitors+" WHERE user_id = ? AND id = ?",+ string(userID), monitorID.String(),+ ).Scan(&count)+ if err != nil {+ msg := fmt.Sprintf("cannot check if heartbeat monitor exists with userID [%s] and monitor ID [%s]", userID, monitorID)+ return false, repository.tracer.WrapErrorSpan(span, stacktrace.Propagate(err, msg))+ }++ return count > 0, nil+}++func (repository *libsqlHeartbeatMonitorRepository) UpdateQueueID(ctx context.Context, monitorID uuid.UUID, queueID string) error {+ ctx, span := repository.tracer.Start(ctx)+ defer span.End()++ ctx, cancel := context.WithTimeout(ctx, dbOperationDuration)+ defer cancel()++ _, err := repository.db.ExecContext(ctx,+ "UPDATE "+tableHeartbeatMonitors+" SET queue_id = ?, updated_at = ? WHERE id = ?",+ queueID, time.Now().UTC(), monitorID.String(),+ )+ if err != nil {+ msg := fmt.Sprintf("cannot update heartbeat monitor ID [%s]", monitorID)+ return repository.tracer.WrapErrorSpan(span, stacktrace.Propagate(err, msg))+ }++ return nil+}++func (repository *libsqlHeartbeatMonitorRepository) Delete(ctx context.Context, userID entities.UserID, phoneNumber string) error {+ ctx, span := repository.tracer.Start(ctx)+ defer span.End()++ ctx, cancel := context.WithTimeout(ctx, dbOperationDuration)+ defer cancel()++ _, err := repository.db.ExecContext(ctx,+ "DELETE FROM "+tableHeartbeatMonitors+" WHERE user_id = ? AND owner = ?",+ string(userID), phoneNumber,+ )+ if err != nil {+ msg := fmt.Sprintf("cannot delete heartbeat monitor with owner [%s] and userID [%s]", phoneNumber, userID)+ return repository.tracer.WrapErrorSpan(span, stacktrace.Propagate(err, msg))+ }++ return nil+}++func (repository *libsqlHeartbeatMonitorRepository) UpdatePhoneOnline(ctx context.Context, userID entities.UserID, monitorID uuid.UUID, online bool) error {+ ctx, span := repository.tracer.Start(ctx)+ defer span.End()++ ctx, cancel := context.WithTimeout(ctx, dbOperationDuration)+ defer cancel()++ _, err := repository.db.ExecContext(ctx,+ "UPDATE "+tableHeartbeatMonitors+" SET phone_online = ?, updated_at = ? WHERE id = ? AND user_id = ?",+ boolToInt(online), time.Now().UTC(), monitorID.String(), string(userID),+ )+ if err != nil {+ msg := fmt.Sprintf("cannot update heartbeat monitor ID [%s] for user [%s]", monitorID, userID)+ return repository.tracer.WrapErrorSpan(span, stacktrace.Propagate(err, msg))+ }++ return nil+}++func (repository *libsqlHeartbeatMonitorRepository) DeleteAllForUser(ctx context.Context, userID entities.UserID) error {+ ctx, span := repository.tracer.Start(ctx)+ defer span.End()++ ctx, cancel := context.WithTimeout(ctx, dbOperationDuration)+ defer cancel()++ _, err := repository.db.ExecContext(ctx, "DELETE FROM "+tableHeartbeatMonitors+" WHERE user_id = ?", string(userID))+ if err != nil {+ msg := fmt.Sprintf("cannot delete all [%T] for user with ID [%s]", &entities.HeartbeatMonitor{}, userID)+ return repository.tracer.WrapErrorSpan(span, stacktrace.Propagate(err, msg))+ }++ return nil+}++func (repository *libsqlHeartbeatMonitorRepository) scanHeartbeatMonitorRow(row *sql.Row) (*entities.HeartbeatMonitor, error) {+ monitor := new(entities.HeartbeatMonitor)+ var id, phoneID, userID string+ var phoneOnline int+ err := row.Scan(&id, &phoneID, &userID, &monitor.QueueID, &monitor.Owner, &phoneOnline, &monitor.CreatedAt, &monitor.UpdatedAt)+ if err != nil {+ return nil, err+ }+ monitor.ID, err = uuid.Parse(id)+ if err != nil {+ return nil, stacktrace.Propagate(err, fmt.Sprintf("cannot parse heartbeat monitor ID [%s]", id))+ }+ monitor.PhoneID, err = uuid.Parse(phoneID)+ if err != nil {+ return nil, stacktrace.Propagate(err, fmt.Sprintf("cannot parse heartbeat monitor phone ID [%s]", phoneID))+ }+ monitor.UserID = entities.UserID(userID)+ monitor.PhoneOnline = phoneOnline != 0+ return monitor, nil+}diff --git a/api/pkg/repositories/libsql_heartbeat_repository.go b/api/pkg/repositories/libsql_heartbeat_repository.gonew file mode 100644index 00000000..42fdf911--- /dev/null+++ b/api/pkg/repositories/libsql_heartbeat_repository.go@@ -0,0 +1,186 @@+package repositories++import (+ "context"+ "database/sql"+ "fmt"++ "github.com/google/uuid"++ "github.com/NdoleStudio/httpsms/pkg/entities"+ "github.com/NdoleStudio/httpsms/pkg/telemetry"+ "github.com/palantir/stacktrace"+)++// libsqlHeartbeatRepository is responsible for persisting entities.Heartbeat in Turso/libSQL+type libsqlHeartbeatRepository struct {+ logger telemetry.Logger+ tracer telemetry.Tracer+ db *sql.DB+}++// NewLibsqlHeartbeatRepository creates the libSQL version of the HeartbeatRepository+func NewLibsqlHeartbeatRepository(+ logger telemetry.Logger,+ tracer telemetry.Tracer,+ db *sql.DB,+) HeartbeatRepository {+ return &libsqlHeartbeatRepository{+ logger: logger.WithService(fmt.Sprintf("%T", &libsqlHeartbeatRepository{})),+ tracer: tracer,+ db: db,+ }+}++func (repository *libsqlHeartbeatRepository) Store(ctx context.Context, heartbeat *entities.Heartbeat) error {+ ctx, span, _ := repository.tracer.StartWithLogger(ctx, repository.logger)+ defer span.End()++ ctx, cancel := context.WithTimeout(ctx, dbOperationDuration)+ defer cancel()++ _, err := repository.db.ExecContext(ctx,+ "INSERT INTO "+tableHeartbeats+" (id, owner, version, charging, user_id, timestamp) VALUES (?, ?, ?, ?, ?, ?)",+ heartbeat.ID.String(),+ heartbeat.Owner,+ heartbeat.Version,+ boolToInt(heartbeat.Charging),+ string(heartbeat.UserID),+ heartbeat.Timestamp.UTC(),+ )+ if err != nil {+ msg := fmt.Sprintf("cannot save heartbeat with ID [%s]", heartbeat.ID)+ return repository.tracer.WrapErrorSpan(span, stacktrace.Propagate(err, msg))+ }++ return nil+}++func (repository *libsqlHeartbeatRepository) Index(ctx context.Context, userID entities.UserID, owner string, params IndexParams) (*[]entities.Heartbeat, error) {+ ctx, span := repository.tracer.Start(ctx)+ defer span.End()++ ctx, cancel := context.WithTimeout(ctx, dbOperationDuration)+ defer cancel()++ var rows *sql.Rows+ var err error++ if len(params.Query) > 0 {+ queryPattern := "%" + params.Query + "%"+ rows, err = repository.db.QueryContext(ctx,+ "SELECT id, owner, version, charging, user_id, timestamp FROM "+tableHeartbeats+" WHERE user_id = ? AND owner = ? AND version LIKE ? ORDER BY timestamp DESC LIMIT ? OFFSET ?",+ string(userID), owner, queryPattern, params.Limit, params.Skip,+ )+ } else {+ rows, err = repository.db.QueryContext(ctx,+ "SELECT id, owner, version, charging, user_id, timestamp FROM "+tableHeartbeats+" WHERE user_id = ? AND owner = ? ORDER BY timestamp DESC LIMIT ? OFFSET ?",+ string(userID), owner, params.Limit, params.Skip,+ )+ }+ if err != nil {+ msg := fmt.Sprintf("cannot fetch heartbeats with owner [%s] and params [%+#v]", owner, params)+ return nil, repository.tracer.WrapErrorSpan(span, stacktrace.Propagate(err, msg))+ }+ defer rows.Close()++ heartbeats := make([]entities.Heartbeat, 0)+ for rows.Next() {+ heartbeat, scanErr := repository.scanHeartbeat(rows)+ if scanErr != nil {+ msg := fmt.Sprintf("cannot scan heartbeat row for owner [%s]", owner)+ return nil, repository.tracer.WrapErrorSpan(span, stacktrace.Propagate(scanErr, msg))+ }+ heartbeats = append(heartbeats, *heartbeat)+ }+ if rowsErr := rows.Err(); rowsErr != nil {+ msg := fmt.Sprintf("error iterating heartbeat rows for owner [%s]", owner)+ return nil, repository.tracer.WrapErrorSpan(span, stacktrace.Propagate(rowsErr, msg))+ }++ return &heartbeats, nil+}++func (repository *libsqlHeartbeatRepository) Last(ctx context.Context, userID entities.UserID, owner string) (*entities.Heartbeat, error) {+ ctx, span := repository.tracer.Start(ctx)+ defer span.End()++ ctx, cancel := context.WithTimeout(ctx, dbOperationDuration)+ defer cancel()++ row := repository.db.QueryRowContext(ctx,+ "SELECT id, owner, version, charging, user_id, timestamp FROM "+tableHeartbeats+" WHERE user_id = ? AND owner = ? ORDER BY timestamp DESC LIMIT 1",+ string(userID), owner,+ )++ heartbeat, err := repository.scanHeartbeatRow(row)+ if err == sql.ErrNoRows {+ msg := fmt.Sprintf("heartbeat with userID [%s] and owner [%s] does not exist", userID, owner)+ return nil, repository.tracer.WrapErrorSpan(span, stacktrace.PropagateWithCode(err, ErrCodeNotFound, msg))+ }+ if err != nil {+ msg := fmt.Sprintf("cannot load heartbeat with userID [%s] and owner [%s]", userID, owner)+ return nil, repository.tracer.WrapErrorSpan(span, stacktrace.Propagate(err, msg))+ }++ return heartbeat, nil+}++func (repository *libsqlHeartbeatRepository) DeleteAllForUser(ctx context.Context, userID entities.UserID) error {+ ctx, span := repository.tracer.Start(ctx)+ defer span.End()++ ctx, cancel := context.WithTimeout(ctx, dbOperationDuration)+ defer cancel()++ _, err := repository.db.ExecContext(ctx, "DELETE FROM "+tableHeartbeats+" WHERE user_id = ?", string(userID))+ if err != nil {+ msg := fmt.Sprintf("cannot delete all [%T] for user with ID [%s]", &entities.Heartbeat{}, userID)+ return repository.tracer.WrapErrorSpan(span, stacktrace.Propagate(err, msg))+ }++ return nil+}++func (repository *libsqlHeartbeatRepository) scanHeartbeat(rows *sql.Rows) (*entities.Heartbeat, error) {+ heartbeat := new(entities.Heartbeat)+ var id string+ var charging int+ var userID string+ err := rows.Scan(&id, &heartbeat.Owner, &heartbeat.Version, &charging, &userID, &heartbeat.Timestamp)+ if err != nil {+ return nil, err+ }+ heartbeat.ID, err = uuid.Parse(id)+ if err != nil {+ return nil, stacktrace.Propagate(err, fmt.Sprintf("cannot parse heartbeat ID [%s]", id))+ }+ heartbeat.Charging = charging != 0+ heartbeat.UserID = entities.UserID(userID)+ return heartbeat, nil+}++func (repository *libsqlHeartbeatRepository) scanHeartbeatRow(row *sql.Row) (*entities.Heartbeat, error) {+ heartbeat := new(entities.Heartbeat)+ var id string+ var charging int+ var userID string+ err := row.Scan(&id, &heartbeat.Owner, &heartbeat.Version, &charging, &userID, &heartbeat.Timestamp)+ if err != nil {+ return nil, err+ }+ heartbeat.ID, err = uuid.Parse(id)+ if err != nil {+ return nil, stacktrace.Propagate(err, fmt.Sprintf("cannot parse heartbeat ID [%s]", id))+ }+ heartbeat.Charging = charging != 0+ heartbeat.UserID = entities.UserID(userID)+ return heartbeat, nil+}++func boolToInt(b bool) int {+ if b {+ return 1+ }+ return 0+}diff --git a/docs/superpowers/plans/2026-05-15-hedging-repository.md b/docs/superpowers/plans/2026-05-15-hedging-repository.mdnew file mode 100644index 00000000..e3b838fa--- /dev/null+++ b/docs/superpowers/plans/2026-05-15-hedging-repository.md@@ -0,0 +1,265 @@+# Hedging Repository Implementation Plan++> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.++> **Status:** All tasks implemented. This plan was written retroactively to document and verify the implementation.++**Goal:** Create composite hedging repositories that dual-write to GORM (primary) and Turso (secondary) with fail-open semantics on secondary failures.++**Architecture:** Two new repository files implement the existing `HeartbeatRepository` and `HeartbeatMonitorRepository` interfaces by delegating reads to primary only and writes to both. Secondary write failures are logged and counted via an OTel metric but never propagated. Activated via `HEARTBEAT_DB_BACKEND=hedging`.++**Tech Stack:** Go, OpenTelemetry metrics (`go.opentelemetry.io/otel/metric`), existing repository interfaces++**Spec:** `docs/superpowers/specs/2026-05-15-hedging-repository-design.md`++---++### Task 1: Create hedging heartbeat repository ✅++**Files:**++- Created: `api/pkg/repositories/hedging_heartbeat_repository.go`++- [ ] **Step 1: Create the hedging heartbeat repository file**++```go+package repositories++import (+ "context"+ "fmt"++ otelMetric "go.opentelemetry.io/otel/metric"++ "github.com/NdoleStudio/httpsms/pkg/entities"+ "github.com/NdoleStudio/httpsms/pkg/telemetry"+ "github.com/palantir/stacktrace"+)++type hedgingHeartbeatRepository struct {+ logger telemetry.Logger+ tracer telemetry.Tracer+ primary HeartbeatRepository+ secondary HeartbeatRepository+ failureCounter otelMetric.Int64Counter+}++func NewHedgingHeartbeatRepository(+ logger telemetry.Logger,+ tracer telemetry.Tracer,+ primary HeartbeatRepository,+ secondary HeartbeatRepository,+ failureCounter otelMetric.Int64Counter,+) HeartbeatRepository {+ return &hedgingHeartbeatRepository{+ logger: logger.WithService(fmt.Sprintf("%T", &hedgingHeartbeatRepository{})),+ tracer: tracer,+ primary: primary,+ secondary: secondary,+ failureCounter: failureCounter,+ }+}+```++Implement 4 methods:++- `Store` — write to primary, then secondary (fail-open with log + metric)+- `Index` — delegate to primary only+- `Last` — delegate to primary only+- `DeleteAllForUser` — write to primary, then secondary (fail-open with log + metric)++Write methods follow this pattern:++```go+func (r *hedgingHeartbeatRepository) Store(ctx context.Context, heartbeat *entities.Heartbeat) error {+ ctx, span := r.tracer.Start(ctx)+ defer span.End()++ if err := r.primary.Store(ctx, heartbeat); err != nil {+ return err+ }++ if err := r.secondary.Store(ctx, heartbeat); err != nil {+ r.logger.Error(stacktrace.Propagate(err, fmt.Sprintf("hedging: secondary write failed for heartbeat [%s]", heartbeat.ID)))+ r.failureCounter.Add(ctx, 1)+ }++ return nil+}+```++Read methods simply delegate:++```go+func (r *hedgingHeartbeatRepository) Index(ctx context.Context, userID entities.UserID, owner string, params IndexParams) (*[]entities.Heartbeat, error) {+ return r.primary.Index(ctx, userID, owner, params)+}+```++- [ ] **Step 2: Verify build**++Run: `cd api && go build ./...`+Expected: exit code 0++- [ ] **Step 3: Commit**++```bash+git add api/pkg/repositories/hedging_heartbeat_repository.go+git commit -m "feat(api): add hedging heartbeat repository"+```++---++### Task 2: Create hedging heartbeat monitor repository ✅++**Files:**++- Created: `api/pkg/repositories/hedging_heartbeat_monitor_repository.go`++- [ ] **Step 1: Create the hedging heartbeat monitor repository file**++Same struct pattern as Task 1 but wrapping `HeartbeatMonitorRepository` interface.++Implement 7 methods:++| Method | Behavior |+| ------------------- | ---------------------- |+| `Store` | Write both (fail-open) |+| `Load` | Primary only |+| `Exists` | Primary only |+| `UpdateQueueID` | Write both (fail-open) |+| `Delete` | Write both (fail-open) |+| `UpdatePhoneOnline` | Write both (fail-open) |+| `DeleteAllForUser` | Write both (fail-open) |++All write methods follow the same fail-open pattern: primary must succeed, secondary logs + increments counter on failure.++- [ ] **Step 2: Verify build**++Run: `cd api && go build ./...`+Expected: exit code 0++- [ ] **Step 3: Commit**++```bash+git add api/pkg/repositories/hedging_heartbeat_monitor_repository.go+git commit -m "feat(api): add hedging heartbeat monitor repository"+```++---++### Task 3: Add HedgingFailureCounter to DI container ✅++**Files:**++- Modified: `api/pkg/di/container.go` (added `HedgingFailureCounter()` method after `TursoDB()`, ~line 320)++- [ ] **Step 1: Add the HedgingFailureCounter method**++```go+func (container *Container) HedgingFailureCounter() otelMetric.Int64Counter {+ meter := otel.GetMeterProvider().Meter(+ container.projectID,+ otelMetric.WithInstrumentationVersion(otel.Version()),+ )+ counter, err := meter.Int64Counter(+ "hedging.secondary.write.failures",+ otelMetric.WithUnit("1"),+ otelMetric.WithDescription("Number of failed secondary writes in hedging repositories"),+ )+ if err != nil {+ container.logger.Fatal(stacktrace.Propagate(err, "cannot create hedging failure counter"))+ }+ return counter+}+```++- [ ] **Step 2: Verify build**++Run: `cd api && go build ./...`+Expected: exit code 0++---++### Task 4: Wire hedging mode in DI container ✅++**Files:**++- Modified: `api/pkg/di/container.go`++ - `HeartbeatRepository()` (~line 1768)+ - `HeartbeatMonitorRepository()` (~line 930)++- [ ] **Step 1: Change both methods from if/else to switch**++Replace the existing `if os.Getenv("HEARTBEAT_DB_BACKEND") == "turso"` with a switch:++```go+func (container *Container) HeartbeatRepository() repositories.HeartbeatRepository {+ switch os.Getenv("HEARTBEAT_DB_BACKEND") {+ case "turso":+ // existing libSQL path+ case "hedging":+ return repositories.NewHedgingHeartbeatRepository(+ container.Logger(),+ container.Tracer(),+ repositories.NewGormHeartbeatRepository(container.Logger(), container.Tracer(), container.DedicatedDB()),+ repositories.NewLibsqlHeartbeatRepository(container.Logger(), container.Tracer(), container.TursoDB()),+ container.HedgingFailureCounter(),+ )+ default:+ // existing GORM path+ }+}+```++Same pattern for `HeartbeatMonitorRepository()`.++- [ ] **Step 2: Verify build**++Run: `cd api && go build ./...`+Expected: exit code 0++- [ ] **Step 3: Run pre-commit hooks**++Run: `cd api && gofumpt -w pkg/repositories/hedging_heartbeat_repository.go pkg/repositories/hedging_heartbeat_monitor_repository.go pkg/di/container.go`+Expected: exit code 0++- [ ] **Step 4: Final commit**++```bash+git add api/pkg/di/container.go+git commit -m "feat(api): wire hedging mode in DI container (HEARTBEAT_DB_BACKEND=hedging)"+```++---++### Task 5: Final verification++- [ ] **Step 1: Full build**++Run: `cd api && go build ./...`+Expected: exit code 0++- [ ] **Step 2: Run tests**++Run: `cd api && go test ./...`+Expected: all tests pass++- [ ] **Step 3: go vet (no new warnings)**++Run: `cd api && go vet ./... 2>&1 | Select-String "hedging"`+Expected: only pre-existing `non-constant format string` warnings (same category as all other repos)++- [ ] **Step 4: Pre-commit hooks pass**++Run: `git add -A && git commit --dry-run`+Expected: all hooks pass (go-fumpt, go-lint, go-imports, go-mod-tidy)++- [ ] **Step 5: Verify three modes work (code review)**++Check that the DI container correctly handles all three values:++- Default (unset) → GORM only+- `turso` → libSQL only+- `hedging` → GORM primary + libSQL secondarydiff --git a/docs/superpowers/specs/2026-05-15-hedging-repository-design.md b/docs/superpowers/specs/2026-05-15-hedging-repository-design.mdnew file mode 100644index 00000000..2afc6ace--- /dev/null+++ b/docs/superpowers/specs/2026-05-15-hedging-repository-design.md@@ -0,0 +1,164 @@+# Hedging Repository for Heartbeat & Monitor++**Date:** 2026-05-15+**Status:** Approved++## Overview++Create composite "hedging" repositories for `HeartbeatRepository` and `HeartbeatMonitorRepository` that write to both GORM (primary) and Turso (secondary). Reads only hit the primary. Secondary writes are fail-open — errors are logged and a metric is emitted, but the operation succeeds from the caller's perspective.++## Motivation++Gradually migrate heartbeat data to Turso by dual-writing. The GORM/PostgreSQL backend remains the source of truth while Turso builds up a complete dataset. If Turso has issues, the system is unaffected.++## Configuration++Activated via `HEARTBEAT_DB_BACKEND=hedging`. The three modes are now:++| Value | Behavior |+| ----------------- | ---------------------------------------------------------------------- |+| _(unset/default)_ | GORM/PostgreSQL only |+| `turso` | Turso/libSQL only |+| `hedging` | GORM primary (reads+writes) + Turso secondary (writes only, fail-open) |++## Architecture++### New Files++| File | Purpose |+| -------------------------------------------------------------- | -------------------------------------- |+| `api/pkg/repositories/hedging_heartbeat_repository.go` | Composite `HeartbeatRepository` |+| `api/pkg/repositories/hedging_heartbeat_monitor_repository.go` | Composite `HeartbeatMonitorRepository` |++### Modified Files++| File | Change |+| ------------------------- | ------------------------------------------------------------------ |+| `api/pkg/di/container.go` | Add `hedging` case to switch, add `HedgingFailureCounter()` method |++## Method Delegation++### HeartbeatRepository++| Method | Primary (GORM) | Secondary (Turso) |+| ------------------ | -------------- | -------------------- |+| `Store` | ✅ write | ✅ write (fail-open) |+| `Index` | ✅ read | ❌ skip |+| `Last` | ✅ read | ❌ skip |+| `DeleteAllForUser` | ✅ write | ✅ write (fail-open) |++### HeartbeatMonitorRepository++| Method | Primary (GORM) | Secondary (Turso) |+| ------------------- | -------------- | -------------------- |+| `Store` | ✅ write | ✅ write (fail-open) |+| `Load` | ✅ read | ❌ skip |+| `Exists` | ✅ read | ❌ skip |+| `UpdateQueueID` | ✅ write | ✅ write (fail-open) |+| `Delete` | ✅ write | ✅ write (fail-open) |+| `UpdatePhoneOnline` | ✅ write | ✅ write (fail-open) |+| `DeleteAllForUser` | ✅ write | ✅ write (fail-open) |++## Struct Design++```go+type hedgingHeartbeatRepository struct {+ logger telemetry.Logger+ tracer telemetry.Tracer+ primary HeartbeatRepository+ secondary HeartbeatRepository+ failureCounter otelMetric.Int64Counter+}++type hedgingHeartbeatMonitorRepository struct {+ logger telemetry.Logger+ tracer telemetry.Tracer+ primary HeartbeatMonitorRepository+ secondary HeartbeatMonitorRepository+ failureCounter otelMetric.Int64Counter+}+```++## Error Handling (Fail-Open Pattern)++```go+func (r *hedgingHeartbeatRepository) Store(ctx context.Context, heartbeat *entities.Heartbeat) error {+ ctx, span := r.tracer.Start(ctx)+ defer span.End()++ // Primary: must succeed+ if err := r.primary.Store(ctx, heartbeat); err != nil {+ return err+ }++ // Secondary: fail-open (log + metric)+ if err := r.secondary.Store(ctx, heartbeat); err != nil {+ r.logger.Error(stacktrace.Propagate(err, fmt.Sprintf(+ "hedging: secondary write failed for heartbeat [%s]", heartbeat.ID,+ )))+ r.failureCounter.Add(ctx, 1)+ }++ return nil+}+```++**Rules:**++- Primary error → return immediately, no secondary attempt+- Secondary error → log at ERROR level, increment `failureCounter`, return nil+- Read methods → delegate directly to primary, no secondary involvement+- Each method has its own tracing span via `tracer.Start(ctx)`++## Observability++**Metric:**++- Name: `hedging.secondary.write.failures`+- Unit: `1` (count)+- Description: `Number of failed secondary writes in hedging repositories`+- Created once in DI container, shared by both hedging repos++**Logging:** Each secondary failure logs at ERROR with the method context (entity ID, user ID, etc.)++## DI Container Changes++```go+func (container *Container) HeartbeatRepository() repositories.HeartbeatRepository {+ switch os.Getenv("HEARTBEAT_DB_BACKEND") {+ case "turso":+ return repositories.NewLibsqlHeartbeatRepository(...)+ case "hedging":+ return repositories.NewHedgingHeartbeatRepository(+ container.Logger(),+ container.Tracer(),+ repositories.NewGormHeartbeatRepository(container.Logger(), container.Tracer(), container.DedicatedDB()),+ repositories.NewLibsqlHeartbeatRepository(container.Logger(), container.Tracer(), container.TursoDB()),+ container.HedgingFailureCounter(),+ )+ default:+ return repositories.NewGormHeartbeatRepository(...)+ }+}++func (container *Container) HedgingFailureCounter() otelMetric.Int64Counter {+ meter := otel.GetMeterProvider().Meter(container.projectID)+ counter, err := meter.Int64Counter("hedging.secondary.write.failures",+ otelMetric.WithUnit("1"),+ otelMetric.WithDescription("Number of failed secondary writes in hedging repositories"),+ )+ if err != nil {+ container.logger.Fatal(...)+ }+ return counter+}+```++Same switch pattern for `HeartbeatMonitorRepository()`.++## Safety++- Default behavior (no env var) is unchanged — pure GORM/PostgreSQL+- `turso` mode remains available for pure Turso usage+- `hedging` mode never fails due to Turso issues — secondary is fully fail-open+- Service layer requires no changes — same interfacesdiff --git a/docs/superpowers/specs/2026-05-15-turso-heartbeat-backend-design.md b/docs/superpowers/specs/2026-05-15-turso-heartbeat-backend-design.mdnew file mode 100644index 00000000..b501650f--- /dev/null+++ b/docs/superpowers/specs/2026-05-15-turso-heartbeat-backend-design.md@@ -0,0 +1,162 @@+# Turso/libSQL Backend for Heartbeat & Monitor Repositories++**Date:** 2026-05-15+**Status:** Approved++## Overview++Add a libSQL/Turso alternative implementation for `HeartbeatRepository` and `HeartbeatMonitorRepository`, switchable via the `HEARTBEAT_DB_BACKEND` environment variable. When set to `turso`, the API connects to a cloud-hosted Turso database instead of the dedicated PostgreSQL instance.++## Motivation++Move heartbeat storage to a dedicated Turso database for cost efficiency and edge performance, while keeping the existing PostgreSQL path as the default fallback.++## Configuration++| Env Var | Purpose | Example |+| ---------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------- |+| `HEARTBEAT_DB_BACKEND` | Selects backend (`turso` = libSQL, anything else = PostgreSQL) | `turso` |+| `TURSO_DATABASE_DSN` | Turso database DSN (URL with authToken query param) | `libsql://httpsms-ndolestudio.aws-us-east-1.turso.io?authToken=eyJ...` |++When `HEARTBEAT_DB_BACKEND` is not set or is any value other than `turso`, the existing GORM/PostgreSQL path is used unchanged.++## Architecture++### Approach++Direct `database/sql` with the Turso Go remote driver (`github.com/tursodatabase/libsql-client-go`). No ORM — raw SQL queries for a simple 2-table schema. This is the pure-Go HTTP driver for remote Turso Cloud access (no CGo required).++### New Files++| File | Purpose |+| ------------------------------------------------------------- | -------------------------------------------------------- |+| `api/pkg/repositories/libsql.go` | Connection factory, table auto-creation, shared helpers |+| `api/pkg/repositories/libsql_heartbeat_repository.go` | `HeartbeatRepository` implementation using libSQL |+| `api/pkg/repositories/libsql_heartbeat_monitor_repository.go` | `HeartbeatMonitorRepository` implementation using libSQL |++### Modified Files++| File | Change |+| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |+| `api/pkg/di/container.go` | Add `tursoDB *sql.DB` field, `TursoDB()` method, conditional wiring in `HeartbeatRepository()` and `HeartbeatMonitorRepository()` |+| `api/go.mod` | Add `github.com/tursodatabase/libsql-client-go` dependency |++## Database Schema++```sql+CREATE TABLE IF NOT EXISTS heartbeats (+ id TEXT PRIMARY KEY,+ owner TEXT NOT NULL,+ version TEXT NOT NULL,+ charging INTEGER NOT NULL DEFAULT 0,+ user_id TEXT NOT NULL,+ timestamp DATETIME NOT NULL+);+CREATE INDEX IF NOT EXISTS idx_heartbeats_owner_timestamp ON heartbeats(owner, timestamp);+CREATE INDEX IF NOT EXISTS idx_heartbeats_user_id ON heartbeats(user_id);++CREATE TABLE IF NOT EXISTS heartbeat_monitors (+ id TEXT PRIMARY KEY,+ phone_id TEXT NOT NULL,+ user_id TEXT NOT NULL,+ queue_id TEXT NOT NULL DEFAULT '',+ owner TEXT NOT NULL,+ phone_online INTEGER NOT NULL DEFAULT 1,+ created_at DATETIME NOT NULL,+ updated_at DATETIME NOT NULL+);+CREATE INDEX IF NOT EXISTS idx_heartbeat_monitors_user_owner ON heartbeat_monitors(user_id, owner);+```++**Type mappings from PostgreSQL:**++- UUID → TEXT+- BOOLEAN → INTEGER (0/1)+- TIMESTAMP → DATETIME (ISO 8601 text)++## Repository Implementations++### `libsql.go` (shared)++- `NewTursoDB(url, authToken string) (*sql.DB, error)` — opens connection with libSQL driver, executes CREATE TABLE/INDEX statements+- Returns `*sql.DB` for use by both repository implementations++### `libsql_heartbeat_repository.go`++Implements `HeartbeatRepository`:++| Method | SQL |+| ------------------ | ------------------------------------------------------------------------------------------------------------------------ |+| `Store` | `INSERT INTO heartbeats (id, owner, version, charging, user_id, timestamp) VALUES (?, ?, ?, ?, ?, ?)` |+| `Index` | `SELECT ... WHERE user_id = ? AND owner = ? ORDER BY timestamp DESC LIMIT ? OFFSET ?` (optional `version LIKE ?` filter) |+| `Last` | `SELECT ... WHERE user_id = ? AND owner = ? ORDER BY timestamp DESC LIMIT 1` |+| `DeleteAllForUser` | `DELETE FROM heartbeats WHERE user_id = ?` |++### `libsql_heartbeat_monitor_repository.go`++Implements `HeartbeatMonitorRepository`:++| Method | SQL |+| ------------------- | --------------------------------------------------------------------------- |+| `Store` | INSERT all fields |+| `Load` | SELECT by user_id + owner |+| `Exists` | `SELECT COUNT(*) FROM ... WHERE user_id = ? AND id = ?` (returns count > 0) |+| `UpdateQueueID` | UPDATE queue_id + updated_at WHERE id = ? |+| `Delete` | DELETE WHERE user_id = ? AND owner = ? |+| `UpdatePhoneOnline` | UPDATE phone_online + updated_at WHERE id = ? AND user_id = ? |+| `DeleteAllForUser` | DELETE WHERE user_id = ? |++### Error Handling++- `sql.ErrNoRows` → wrap with `stacktrace.PropagateWithCode(err, ErrCodeNotFound, msg)` to match GORM behavior expected by the service layer+- All other errors → wrap with `stacktrace.Propagate(err, msg)`++### Observability++Every method follows the existing tracing pattern:++```go+ctx, span := repository.tracer.Start(ctx)+defer span.End()+```++## DI Container Changes++```go+// New field on Container struct+tursoDB *sql.DB++// New method+func (container *Container) TursoDB() *sql.DB {+ if container.tursoDB != nil {+ return container.tursoDB+ }+ db, err := repositories.NewTursoDB(os.Getenv("TURSO_DATABASE_DSN"))+ if err != nil {+ container.logger.Fatal(err)+ }+ container.tursoDB = db+ return container.tursoDB+}++// Modified methods+func (container *Container) HeartbeatRepository() repositories.HeartbeatRepository {+ if os.Getenv("HEARTBEAT_DB_BACKEND") == "turso" {+ return repositories.NewLibsqlHeartbeatRepository(container.Logger(), container.Tracer(), container.TursoDB())+ }+ return repositories.NewGormHeartbeatRepository(container.Logger(), container.Tracer(), container.DedicatedDB())+}++func (container *Container) HeartbeatMonitorRepository() repositories.HeartbeatMonitorRepository {+ if os.Getenv("HEARTBEAT_DB_BACKEND") == "turso" {+ return repositories.NewLibsqlHeartbeatMonitorRepository(container.Logger(), container.Tracer(), container.TursoDB())+ }+ return repositories.NewGormHeartbeatMonitorRepository(container.Logger(), container.Tracer(), container.DedicatedDB())+}+```++## Safety++- When `HEARTBEAT_DB_BACKEND != "turso"`, `TursoDB()` is never called — no Turso connection is opened+- The existing PostgreSQL path remains the default and is completely unaffected+- Both implementations satisfy the same interface — the service layer requires no changesdiff --git a/tests/.env.test b/tests/.env.testindex a95703f0..909902ae 100644--- a/tests/.env.test+++ b/tests/.env.test@@ -28,3 +28,5 @@ PUSHER_CLUSTER=GCS_BUCKET_NAME=UPTRACE_DSN=CLOUDFLARE_TURNSTILE_SECRET_KEY=+HEARTBEAT_DB_BACKEND=hedging+TURSO_DATABASE_DSN=http://sqld:8080diff --git a/tests/docker-compose.yml b/tests/docker-compose.ymlindex a4d6b9dc..1e111b78 100644--- a/tests/docker-compose.yml+++ b/tests/docker-compose.yml@@ -25,6 +25,11 @@ services:timeout: 5sretries: 10+ sqld:+ image: ghcr.io/tursodatabase/libsql-server:latest+ ports:+ - "8090:8080"+wiremock:image: wiremock/wiremock:3xports:@@ -53,6 +58,8 @@ services:condition: service_healthywiremock:condition: service_healthy+ sqld:+ condition: service_startedenv_file:- .env.testenvironment:diff --git a/tests/integration_test.go b/tests/integration_test.goindex 5aae58ff..12776aac 100644--- a/tests/integration_test.go+++ b/tests/integration_test.go@@ -346,3 +346,59 @@ func TestSendSMS_OutstandingFlow(t *testing.T) {assertWebhookJWT(t, req.Request, signingKey)}}++func TestHeartbeat_StoreAndIndex(t *testing.T) {+ ctx := context.Background()+ phone := setupPhone(ctx, t, 60)++ // Store a heartbeat via phone API key (retry to allow async phone-API-key association)+ storePayload := map[string]interface{}{+ "phone_numbers": []string{phone.PhoneNumber},+ "charging": true,+ }++ url := apiBaseURL + "/v1/heartbeats"+ var respBody []byte+ var statusCode int+ deadline := time.Now().Add(15 * time.Second)+ for time.Now().Before(deadline) {+ body, err := json.Marshal(storePayload)+ require.NoError(t, err)++ req, err := http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(body))+ require.NoError(t, err)+ req.Header.Set("Content-Type", "application/json")+ req.Header.Set("x-api-key", phone.PhoneAPIKey)++ resp, err := http.DefaultClient.Do(req)+ require.NoError(t, err)++ respBody, err = io.ReadAll(resp.Body)+ resp.Body.Close()+ require.NoError(t, err)++ statusCode = resp.StatusCode+ if statusCode == http.StatusCreated {+ break+ }+ time.Sleep(500 * time.Millisecond)+ }+ require.Equal(t, http.StatusCreated, statusCode, "store heartbeat failed: %s", string(respBody))++ // Read heartbeats back via user API key+ client := newAPIClient()+ heartbeats, indexResp, err := client.Heartbeats.Index(ctx, &httpsms.HeartbeatIndexParams{+ Owner: phone.PhoneNumber,+ Limit: 1,+ })+ require.NoError(t, err)+ require.Equal(t, http.StatusOK, indexResp.HTTPResponse.StatusCode)++ require.NotNil(t, heartbeats)+ require.GreaterOrEqual(t, len(heartbeats.Data), 1, "expected at least 1 heartbeat")++ hb := heartbeats.Data[0]+ assert.Equal(t, phone.PhoneNumber, hb.Owner)+ assert.True(t, hb.Charging)+ assert.False(t, hb.Timestamp.IsZero(), "timestamp should not be zero")+}