From 29a6fd6c29d404b082ae3665a6f8de98b12ecc21 Mon Sep 17 00:00:00 2001 From: "Alessandro (Ale) Segala" <43508+ItalyPaleAle@users.noreply.github.com> Date: Mon, 24 Aug 2026 15:03:31 -0700 Subject: [PATCH] feat: show admin UI warning for SQLite on networked filesystem (#1713) Co-authored-by: Elias Schneider --- backend/go.mod | 2 +- backend/go.sum | 2 + backend/internal/bootstrap/db_bootstrap.go | 7 ++ .../internal/bootstrap/router_bootstrap.go | 2 +- .../internal/bootstrap/services_bootstrap.go | 8 ++- backend/internal/common/env_config.go | 24 ++++++- backend/internal/common/env_config_test.go | 43 ++++++++++++ .../internal/controller/version_controller.go | 60 ---------------- backend/internal/environment/handler.go | 70 +++++++++++++++++++ backend/internal/environment/module.go | 38 ++++++++++ .../service.go} | 22 ++++-- backend/internal/environment/service_test.go | 36 ++++++++++ frontend/messages/en.json | 1 + .../src/lib/components/ui/alert/alert.svelte | 6 +- frontend/src/lib/services/storage-service.ts | 8 +++ frontend/src/routes/settings/+layout.svelte | 15 +++- frontend/src/routes/settings/+layout.ts | 25 +++---- 17 files changed, 278 insertions(+), 91 deletions(-) delete mode 100644 backend/internal/controller/version_controller.go create mode 100644 backend/internal/environment/handler.go create mode 100644 backend/internal/environment/module.go rename backend/internal/{service/version_service.go => environment/service.go} (71%) create mode 100644 backend/internal/environment/service_test.go create mode 100644 frontend/src/lib/services/storage-service.ts diff --git a/backend/go.mod b/backend/go.mod index 42fb6771..6c8d6166 100644 --- a/backend/go.mod +++ b/backend/go.mod @@ -25,7 +25,7 @@ require ( github.com/google/uuid v1.6.0 github.com/italypaleale/francis v0.1.0-beta.23 github.com/italypaleale/go-kit v1.0.0 - github.com/italypaleale/go-sql-utils v0.3.5 + github.com/italypaleale/go-sql-utils v0.3.6 github.com/jackc/pgx/v5 v5.10.0 github.com/jinzhu/copier v0.4.0 github.com/joho/godotenv v1.5.1 diff --git a/backend/go.sum b/backend/go.sum index a0d53aff..c9db4757 100644 --- a/backend/go.sum +++ b/backend/go.sum @@ -247,6 +247,8 @@ github.com/italypaleale/go-kit v1.0.0 h1:c+SaYHTaoZzTgbPXhSbNVdNRkNdNhE0YljBWWoP github.com/italypaleale/go-kit v1.0.0/go.mod h1:wg4UsIbsbtDiVqUjJdo/tO9lXo0OXBuwPOpSJ+u+1jI= github.com/italypaleale/go-sql-utils v0.3.5 h1:kkrhIo1tVJvcsjRc1kePWE9Cqdm26+Et5XZYSNmv764= github.com/italypaleale/go-sql-utils v0.3.5/go.mod h1:STWS4qGjiGKt2tf9OdRUlf025FhKZvUA31siUOnejj0= +github.com/italypaleale/go-sql-utils v0.3.6 h1:ND14osePZFhn717qqI+nuH2blxKLTcYqWYSAG9anVDg= +github.com/italypaleale/go-sql-utils v0.3.6/go.mod h1:STWS4qGjiGKt2tf9OdRUlf025FhKZvUA31siUOnejj0= github.com/jackc/pgerrcode v0.0.0-20250907135507-afb5586c32a6 h1:D/V0gu4zQ3cL2WKeVNVM4r2gLxGGf6McLwgXzRTo2RQ= github.com/jackc/pgerrcode v0.0.0-20250907135507-afb5586c32a6/go.mod h1:a/s9Lp5W7n/DD0VrVoyJ00FbP2ytTPDVOivvn2bMlds= github.com/jackc/pgpassfile v1.0.0 h1:/6Hmqy13Ss2zCq62VdNG8tM1wchn8zjSGOBJ6icpsIM= diff --git a/backend/internal/bootstrap/db_bootstrap.go b/backend/internal/bootstrap/db_bootstrap.go index 01db6306..22bbd2e2 100644 --- a/backend/internal/bootstrap/db_bootstrap.go +++ b/backend/internal/bootstrap/db_bootstrap.go @@ -27,6 +27,10 @@ import ( sqliteutil "github.com/pocket-id/pocket-id/backend/internal/utils/sqlite" ) +// Records whether the SQLite database was found on a networked filesystem +// It's always false when using Postgres +var sqliteOnNetworkedFilesystem bool + func NewDatabase(ctx context.Context) (db *gorm.DB, pg *pgxpool.Pool, err error) { db, pg, err = ConnectDatabase(ctx) if err != nil { @@ -68,6 +72,9 @@ func ConnectDatabase(ctx context.Context) (db *gorm.DB, pg *pgxpool.Pool, err er return nil, nil, err } + // Detect whether the database lives on a networked filesystem to show a warning in the admin UI + sqliteOnNetworkedFilesystem = connector.IsNetworked() + // We open the connection ourselves, rather than letting Gorm do it, so it goes through the instrumented driver // It also caps in-memory databases to a single connection, which they need to see the whole data sqliteDB, err := sqliteinstrument.Open(connector, sqlInstrumentOptions()) diff --git a/backend/internal/bootstrap/router_bootstrap.go b/backend/internal/bootstrap/router_bootstrap.go index 07c5d354..ff1ef34c 100644 --- a/backend/internal/bootstrap/router_bootstrap.go +++ b/backend/internal/bootstrap/router_bootstrap.go @@ -176,7 +176,7 @@ func registerRoutes(r *gin.Engine, db *gorm.DB, svc *services, rateLimitServices controller.NewUserGroupController(apiGroup, authMiddleware, svc.appConfigService, svc.userGroupService) svc.apiModule.RegisterRoutes(apiGroup, authMiddleware.Add()) controller.NewCustomClaimController(apiGroup, authMiddleware, svc.customClaimService) - controller.NewVersionController(apiGroup, authMiddleware, svc.versionService) + svc.environmentModule.RegisterRoutes(apiGroup, authMiddleware.WithAdminNotRequired().Add()) svc.scimSyncModule.RegisterRoutes(apiGroup, authMiddleware.Add()) svc.userSignUpModule.RegisterRoutes(apiGroup, authMiddleware.Add(), diff --git a/backend/internal/bootstrap/services_bootstrap.go b/backend/internal/bootstrap/services_bootstrap.go index 5c653c47..241b9ea6 100644 --- a/backend/internal/bootstrap/services_bootstrap.go +++ b/backend/internal/bootstrap/services_bootstrap.go @@ -14,6 +14,7 @@ import ( "github.com/pocket-id/pocket-id/backend/internal/devicelogin" "github.com/pocket-id/pocket-id/backend/internal/email" "github.com/pocket-id/pocket-id/backend/internal/emailverification" + "github.com/pocket-id/pocket-id/backend/internal/environment" "github.com/pocket-id/pocket-id/backend/internal/geolite" "github.com/pocket-id/pocket-id/backend/internal/ldapsync" "github.com/pocket-id/pocket-id/backend/internal/oidc" @@ -37,7 +38,6 @@ type services struct { customClaimService *service.CustomClaimService oidcService *service.OidcService userGroupService *service.UserGroupService - versionService *service.VersionService fileStorage storage.FileStorage apiKeyModule *apikey.Module @@ -51,6 +51,7 @@ type services struct { oneTimeAccessModule *onetimeaccess.Module emailVerificationModule *emailverification.Module apiModule *api.Module + environmentModule *environment.Module actors *local.Host } @@ -247,7 +248,10 @@ func initServices( return nil, fmt.Errorf("failed to create email verification module: %w", err) } - svc.versionService = service.NewVersionService(httpClient) + svc.environmentModule = environment.New(environment.Dependencies{ + HTTPClient: httpClient, + SQLiteOnNetworkedFilesystem: sqliteOnNetworkedFilesystem, + }) return svc, nil } diff --git a/backend/internal/common/env_config.go b/backend/internal/common/env_config.go index 82691d31..ce51557b 100644 --- a/backend/internal/common/env_config.go +++ b/backend/internal/common/env_config.go @@ -16,15 +16,20 @@ import ( _ "github.com/joho/godotenv/autoload" ) -type AppEnv string -type DbProvider string -type TrustProxyConfig []string +type ( + AppEnv string + DbProvider string + TrustProxyConfig []string + DismissSQLiteStorageWarningConfig bool +) const ( // TracerName should be passed to otel.Tracer, trace.SpanFromContext when creating custom spans. TracerName = "github.com/pocket-id/pocket-id/backend/tracing" // MeterName should be passed to otel.Meter when create custom metrics. MeterName = "github.com/pocket-id/pocket-id/backend/metrics" + // dismissSQLiteStorageWarningPhrase is the exact phrase DISMISS_SQLITE_STORAGE_WARNING must be set to to suppress the warning (matched case-insensitive) + dismissSQLiteStorageWarningPhrase = "i accept the risks" ) const ( @@ -99,6 +104,10 @@ type EnvConfigSchema struct { // LogQueryArgs includes the values of SQL query parameters in traces and in the query logs printed when LogLevel is "debug" // Note that these may can contain sensitive data LogQueryArgs bool `env:"LOG_QUERY_ARGS"` + + // This is true when DISMISS_SQLITE_STORAGE_WARNING is the exact confirmation phrase set in the constant above + // Note: this is omitted from the general list of environment variables in the docs, and documented only in the SQLite-specific section + DismissSQLiteStorageWarning DismissSQLiteStorageWarningConfig `env:"DISMISS_SQLITE_STORAGE_WARNING"` } var EnvConfig = defaultConfig() @@ -422,6 +431,15 @@ func (a AppEnv) IsTest() bool { return a == AppEnvTest } +func (config *DismissSQLiteStorageWarningConfig) UnmarshalText(text []byte) error { + // Make lowercase, then replace all - and _ with spaces + value := strings.ToLower(strings.TrimSpace(string(text))) + value = strings.ReplaceAll(value, "_", " ") + value = strings.ReplaceAll(value, "-", " ") + *config = DismissSQLiteStorageWarningConfig(value == dismissSQLiteStorageWarningPhrase) + return nil +} + func (config *TrustProxyConfig) UnmarshalText(text []byte) error { value := strings.TrimSpace(string(text)) diff --git a/backend/internal/common/env_config_test.go b/backend/internal/common/env_config_test.go index c7c170a6..85d1cac5 100644 --- a/backend/internal/common/env_config_test.go +++ b/backend/internal/common/env_config_test.go @@ -337,6 +337,49 @@ func TestParseEnvConfig(t *testing.T) { assert.ErrorContains(t, err, "TLS_CERT_FILE not found") }) + t.Run("should not dismiss the SQLite storage warning by default", func(t *testing.T) { + EnvConfig = defaultConfig() + t.Setenv("DB_CONNECTION_STRING", "file:test.db") + t.Setenv("APP_URL", "http://localhost:3000") + + err := parseAndValidateEnvConfig(t) + require.NoError(t, err) + assert.False(t, bool(EnvConfig.DismissSQLiteStorageWarning)) + }) + + t.Run("should not dismiss the SQLite storage warning with an unrelated value", func(t *testing.T) { + EnvConfig = defaultConfig() + t.Setenv("DB_CONNECTION_STRING", "file:test.db") + t.Setenv("APP_URL", "http://localhost:3000") + t.Setenv("DISMISS_SQLITE_STORAGE_WARNING", "true") + + err := parseAndValidateEnvConfig(t) + require.NoError(t, err) + assert.False(t, bool(EnvConfig.DismissSQLiteStorageWarning)) + }) + + t.Run("should dismiss the SQLite storage warning with the confirmation phrase", func(t *testing.T) { + EnvConfig = defaultConfig() + t.Setenv("DB_CONNECTION_STRING", "file:test.db") + t.Setenv("APP_URL", "http://localhost:3000") + t.Setenv("DISMISS_SQLITE_STORAGE_WARNING", " I Accept The Risks ") + + err := parseAndValidateEnvConfig(t) + require.NoError(t, err) + assert.True(t, bool(EnvConfig.DismissSQLiteStorageWarning)) + }) + + t.Run("should dismiss the SQLite storage warning with the confirmation phrase with dashes", func(t *testing.T) { + EnvConfig = defaultConfig() + t.Setenv("DB_CONNECTION_STRING", "file:test.db") + t.Setenv("APP_URL", "http://localhost:3000") + t.Setenv("DISMISS_SQLITE_STORAGE_WARNING", " I-Accept_The_Risks ") + + err := parseAndValidateEnvConfig(t) + require.NoError(t, err) + assert.True(t, bool(EnvConfig.DismissSQLiteStorageWarning)) + }) + t.Run("should fail when TLS key file does not exist", func(t *testing.T) { EnvConfig = defaultConfig() t.Setenv("DB_CONNECTION_STRING", "file:test.db") diff --git a/backend/internal/controller/version_controller.go b/backend/internal/controller/version_controller.go deleted file mode 100644 index a4c7b757..00000000 --- a/backend/internal/controller/version_controller.go +++ /dev/null @@ -1,60 +0,0 @@ -package controller - -import ( - "net/http" - "time" - - "github.com/gin-gonic/gin" - "github.com/pocket-id/pocket-id/backend/internal/common" - _ "github.com/pocket-id/pocket-id/backend/internal/dto" - "github.com/pocket-id/pocket-id/backend/internal/httpserver" - "github.com/pocket-id/pocket-id/backend/internal/middleware" - "github.com/pocket-id/pocket-id/backend/internal/service" - "github.com/pocket-id/pocket-id/backend/internal/utils" -) - -// NewVersionController registers version-related routes. -func NewVersionController(group *gin.RouterGroup, authMiddleware *middleware.AuthMiddleware, versionService *service.VersionService) { - vc := &VersionController{versionService: versionService} - group.GET("/version/latest", httpserver.Handle(vc.getLatestVersionHandler)) - group.GET("/version/current", authMiddleware.WithAdminNotRequired().Add(), httpserver.Handle(vc.getCurrentVersionHandler)) -} - -type VersionController struct { - versionService *service.VersionService -} - -// getLatestVersionHandler godoc -// @Summary Get latest available version of Pocket ID -// @Tags Version -// @Produce json -// @Success 200 {object} map[string]string "Latest version information" -// @Failure default {object} dto.ErrorDto "Error" -// @Router /api/version/latest [get] -func (vc *VersionController) getLatestVersionHandler(c *gin.Context) error { - tag, err := vc.versionService.GetLatestVersion(c.Request.Context()) - if err != nil { - return err - } - - utils.SetCacheControlHeader(c, 5*time.Minute, 15*time.Minute) - - c.JSON(http.StatusOK, gin.H{ - "latestVersion": tag, - }) - return nil -} - -// getCurrentVersionHandler godoc -// @Summary Get current deployed version of Pocket ID -// @Tags Version -// @Produce json -// @Success 200 {object} map[string]string "Current version information" -// @Failure default {object} dto.ErrorDto "Error" -// @Router /api/version/current [get] -func (vc *VersionController) getCurrentVersionHandler(c *gin.Context) error { - c.JSON(http.StatusOK, gin.H{ - "currentVersion": common.Version, - }) - return nil -} diff --git a/backend/internal/environment/handler.go b/backend/internal/environment/handler.go new file mode 100644 index 00000000..6900ab39 --- /dev/null +++ b/backend/internal/environment/handler.go @@ -0,0 +1,70 @@ +package environment + +import ( + "net/http" + "time" + + "github.com/gin-gonic/gin" + + "github.com/pocket-id/pocket-id/backend/internal/common" + _ "github.com/pocket-id/pocket-id/backend/internal/dto" + "github.com/pocket-id/pocket-id/backend/internal/utils" +) + +type handler struct { + service *Service +} + +func newHandler(service *Service) *handler { + return &handler{service: service} +} + +// getLatestVersion godoc +// @Summary Get latest available version of Pocket ID +// @Tags Version +// @Produce json +// @Success 200 {object} map[string]string "Latest version information" +// @Failure default {object} dto.ErrorDto "Error" +// @Router /api/version/latest [get] +func (h *handler) getLatestVersion(c *gin.Context) error { + tag, err := h.service.GetLatestVersion(c.Request.Context()) + if err != nil { + return err + } + + utils.SetCacheControlHeader(c, 5*time.Minute, 15*time.Minute) + + c.JSON(http.StatusOK, gin.H{ + "latestVersion": tag, + }) + return nil +} + +// getCurrentVersion godoc +// @Summary Get current deployed version of Pocket ID +// @Tags Version +// @Produce json +// @Success 200 {object} map[string]string "Current version information" +// @Failure default {object} dto.ErrorDto "Error" +// @Router /api/version/current [get] +func (h *handler) getCurrentVersion(c *gin.Context) error { + c.JSON(http.StatusOK, gin.H{ + "currentVersion": common.Version, + }) + return nil +} + +// getSqliteStorageWarning godoc +// @Summary Get whether the SQLite storage warning should be shown +// @Description Reports whether Pocket ID found its SQLite database on a networked filesystem, which is unsupported and can lead to database corruption +// @Tags Storage +// @Produce json +// @Success 200 {object} map[string]bool "SQLite storage warning state" +// @Failure default {object} dto.ErrorDto "Error" +// @Router /api/storage/sqlite-warning [get] +func (h *handler) getSqliteStorageWarning(c *gin.Context) error { + c.JSON(http.StatusOK, gin.H{ + "showWarning": h.service.ShowSQLiteStorageWarning(), + }) + return nil +} diff --git a/backend/internal/environment/module.go b/backend/internal/environment/module.go new file mode 100644 index 00000000..363d0b6c --- /dev/null +++ b/backend/internal/environment/module.go @@ -0,0 +1,38 @@ +package environment + +import ( + "net/http" + + "github.com/gin-gonic/gin" + + "github.com/pocket-id/pocket-id/backend/internal/httpserver" +) + +type Dependencies struct { + HTTPClient *http.Client + + // SQLiteOnNetworkedFilesystem is true when the SQLite database was found on a networked filesystem + // It's always false when using Postgres + SQLiteOnNetworkedFilesystem bool +} + +// Module exposes read-only facts about the environment Pocket ID runs in, such as its version and where its database is stored +type Module struct { + service *Service + handler *handler +} + +func New(deps Dependencies) *Module { + service := newService(deps) + return &Module{ + service: service, + handler: newHandler(service), + } +} + +// RegisterRoutes mounts the environment endpoints +func (m *Module) RegisterRoutes(apiGroup *gin.RouterGroup, auth gin.HandlerFunc) { + apiGroup.GET("/version/latest", httpserver.Handle(m.handler.getLatestVersion)) + apiGroup.GET("/version/current", auth, httpserver.Handle(m.handler.getCurrentVersion)) + apiGroup.GET("/storage/sqlite-warning", auth, httpserver.Handle(m.handler.getSqliteStorageWarning)) +} diff --git a/backend/internal/service/version_service.go b/backend/internal/environment/service.go similarity index 71% rename from backend/internal/service/version_service.go rename to backend/internal/environment/service.go index bb58b7bc..83823682 100644 --- a/backend/internal/service/version_service.go +++ b/backend/internal/environment/service.go @@ -1,4 +1,4 @@ -package service +package environment import ( "context" @@ -19,19 +19,22 @@ const ( versionCheckURL = "https://api.github.com/repos/pocket-id/pocket-id/releases/latest" ) -type VersionService struct { +type Service struct { httpClient *http.Client cache *utils.Cache[string] + + sqliteOnNetworkedFilesystem bool } -func NewVersionService(httpClient *http.Client) *VersionService { - return &VersionService{ - httpClient: httpClient, - cache: utils.New[string](versionTTL), +func newService(deps Dependencies) *Service { + return &Service{ + httpClient: deps.HTTPClient, + cache: utils.New[string](versionTTL), + sqliteOnNetworkedFilesystem: deps.SQLiteOnNetworkedFilesystem, } } -func (s *VersionService) GetLatestVersion(ctx context.Context) (string, error) { +func (s *Service) GetLatestVersion(ctx context.Context) (string, error) { if common.EnvConfig.VersionCheckDisabled { return "", nil } @@ -76,3 +79,8 @@ func (s *VersionService) GetLatestVersion(ctx context.Context) (string, error) { return version, err } + +// ShowSQLiteStorageWarning reports whether admins should be warned that the SQLite database is on a networked filesystem +func (s *Service) ShowSQLiteStorageWarning() bool { + return s.sqliteOnNetworkedFilesystem && !bool(common.EnvConfig.DismissSQLiteStorageWarning) +} diff --git a/backend/internal/environment/service_test.go b/backend/internal/environment/service_test.go new file mode 100644 index 00000000..6ba9b010 --- /dev/null +++ b/backend/internal/environment/service_test.go @@ -0,0 +1,36 @@ +package environment + +import ( + "testing" + + "github.com/stretchr/testify/assert" + + "github.com/pocket-id/pocket-id/backend/internal/common" +) + +func TestShowSQLiteStorageWarning(t *testing.T) { + tests := []struct { + name string + sqliteOnNetworkedFilesystem bool + dismissed bool + want bool + }{ + {name: "warns when the database is on a networked filesystem", sqliteOnNetworkedFilesystem: true, want: true}, + {name: "does not warn when the database is on a local filesystem", sqliteOnNetworkedFilesystem: false, want: false}, + {name: "does not warn when the warning has been dismissed", sqliteOnNetworkedFilesystem: true, dismissed: true, want: false}, + {name: "does not warn when dismissed and the database is on a local filesystem", sqliteOnNetworkedFilesystem: false, dismissed: true, want: false}, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + prevConfig := common.EnvConfig + t.Cleanup(func() { + common.EnvConfig = prevConfig + }) + common.EnvConfig.DismissSQLiteStorageWarning = common.DismissSQLiteStorageWarningConfig(tt.dismissed) + + svc := newService(Dependencies{SQLiteOnNetworkedFilesystem: tt.sqliteOnNetworkedFilesystem}) + assert.Equal(t, tt.want, svc.ShowSQLiteStorageWarning()) + }) + } +} diff --git a/frontend/messages/en.json b/frontend/messages/en.json index 1274a414..35bb6d0d 100644 --- a/frontend/messages/en.json +++ b/frontend/messages/en.json @@ -99,6 +99,7 @@ "application_configuration": "Application Configuration", "settings": "Settings", "update_pocket_id": "Update Pocket ID", + "sqlite_storage_warning": "We detected that your SQLite database is stored on a network-attached drive like NFS, SMB, or FUSE. This is unsupported and can lead to your database getting corrupted. {#link href=|https://pocket-id.org/docs/configuration/environment-variables#sqlite|}See docs.{/link}", "powered_by": "Powered by", "see_your_recent_account_activities": "See your account activities within the configured retention period.", "time": "Time", diff --git a/frontend/src/lib/components/ui/alert/alert.svelte b/frontend/src/lib/components/ui/alert/alert.svelte index 350cb294..e5f867d3 100644 --- a/frontend/src/lib/components/ui/alert/alert.svelte +++ b/frontend/src/lib/components/ui/alert/alert.svelte @@ -1,5 +1,5 @@