feat: complete API-driven projects with infrastructure and business acceptance

examples/userService/internal/servicecontext/context.go

@@ -0,0 +1,122 @@
+package servicecontext
+
+import (
+	"context"
+	"errors"
+	"example.com/userService/internal/middleware"
+	userrepo "example.com/userService/internal/repository/user"
+	"example.com/userService/internal/settings"
+	"git.yuntuo.hk/k2safe/go-omni/database"
+	"git.yuntuo.hk/k2safe/go-omni/health"
+	"git.yuntuo.hk/k2safe/go-omni/httpx"
+	"git.yuntuo.hk/k2safe/go-omni/logx"
+	"git.yuntuo.hk/k2safe/go-omni/storage"
+	"github.com/go-sql-driver/mysql"
+	"net/http"
+	"sync"
+	"time"
+)
+
+// Context owns infrastructure, while Logger is borrowed from main.
+// Add business repositories here; HTTP contracts do not define database tables.
+type Context struct {
+	Users       userrepo.UnitOfWork
+	Logger      *logx.Logger
+	Health      *health.Checker
+	Middlewares map[string]httpx.Middleware
+	DB          *database.DB
+
+	Files        storage.Store
+	Uploads      *storage.Uploader
+	Downloads    storage.Presigner
+	UploadLinks  storage.UploadPresigner
+	FileHTTP     http.Handler
+	storageClose func() error
+
+	closeMu   sync.Mutex
+	closed    bool
+	closeOnce sync.Once
+	closeErr  error
+}
+
+// Pass the settings loaded by main. The optional form supports lightweight
+// tests without infrastructure; selected adapters still require valid settings.
+func New(ctx context.Context, logger *logx.Logger, configs ...settings.Config) (result *Context, err error) {
+	if ctx == nil {
+		ctx = context.Background()
+	}
+	if err = ctx.Err(); err != nil {
+		return nil, err
+	}
+	if len(configs) > 1 {
+		return nil, errors.New("expected at most one configuration")
+	}
+	cfg := settings.Default()
+	if len(configs) == 1 {
+		cfg = configs[0]
+	}
+	_ = cfg
+	checker, err := health.New()
+	if err != nil {
+		return nil, err
+	}
+	c := &Context{Logger: logger, Health: checker, Middlewares: middleware.Defaults()}
+	defer func() {
+		if err != nil {
+			err = errors.Join(err, c.Close())
+		}
+	}()
+
+	if err = cfg.Validate(); err != nil {
+		return nil, err
+	}
+	dsn, parseErr := mysql.ParseDSN(cfg.Database.DSN)
+	if parseErr != nil || dsn.DBName == "" {
+		return nil, errors.New("GO_OMNI_DB_DSN must contain a valid MySQL database name")
+	}
+	dsn.ParseTime = true
+	dsn.Loc = time.UTC
+	cfg.Database.DSN = dsn.FormatDSN()
+	c.DB, err = database.Open(ctx, cfg.Database)
+	if err != nil {
+		return nil, err
+	}
+	if err = checker.Add(health.Probe{Name: "database", Timeout: cfg.Database.PingTimeout, Check: c.DB.Health}); err != nil {
+		return nil, err
+	}
+
+	if err = c.InitStorage(ctx, cfg.Storage); err != nil {
+		return nil, err
+	}
+	c.Users = userrepo.NewStore(c.DB)
+	checkCtx, cancel := context.WithTimeout(ctx, cfg.Database.PingTimeout)
+	defer cancel()
+	if err = userrepo.NewStore(c.DB).CheckSchema(checkCtx); err != nil {
+		return nil, errors.New("user schema is missing or incompatible; apply migrations first")
+	}
+	authHook, authErr := middleware.NewAuthFromEnv()
+	if authErr != nil {
+		return nil, authErr
+	}
+	c.Middlewares["Auth"] = authHook
+	return c, nil
+}
+
+// Close is idempotent, including startup failure and graceful shutdown.
+func (c *Context) Close() error {
+	if c == nil {
+		return nil
+	}
+	c.closeMu.Lock()
+	defer c.closeMu.Unlock()
+	c.closed = true
+	c.closeOnce.Do(func() {
+		if c.storageClose != nil {
+			c.closeErr = errors.Join(c.closeErr, c.storageClose())
+		}
+		if c.DB != nil {
+			c.closeErr = errors.Join(c.closeErr, c.DB.Close())
+		}
+	})
+	return c.closeErr
+}

examples/userService/internal/servicecontext/context_test.go

@@ -0,0 +1,81 @@
+package servicecontext
+
+import (
+	"context"
+	"io"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"example.com/userService/internal/settings"
+	"git.yuntuo.hk/k2safe/go-omni/database"
+	"git.yuntuo.hk/k2safe/go-omni/logx"
+)
+
+func TestStartupFailureAndIdempotentCleanup(t *testing.T) {
+	if os.Getenv("USER_SERVICE_TEST_DATABASE") != "1" {
+		t.Skip("isolated MySQL required")
+	}
+	t.Setenv("USER_SERVICE_API_TOKEN", "test-012345678901234567890123456789")
+	t.Setenv("GO_OMNI_STORAGE_SIGNING_KEY", "test-012345678901234567890123456789")
+	cfg, err := settings.Load("../../etc/config.yaml")
+	if err != nil {
+		t.Fatal(err)
+	}
+	observer, err := database.Open(context.Background(), cfg.Database)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer observer.Close()
+	count := func() int {
+		var n int
+		if err := observer.QueryRow("SELECT COUNT(*) FROM information_schema.processlist WHERE USER=SUBSTRING_INDEX(CURRENT_USER(),'@',1) AND DB=DATABASE()").Scan(&n); err != nil {
+			t.Fatal(err)
+		}
+		return n
+	}
+	baseline := count()
+	cfg.Server.Log.File = ""
+	cfg.Server.Log.Writer = io.Discard
+	cfg.Server.Log.Rotation = logx.RotationConfig{}
+	logger, err := logx.New(cfg.Server.Log)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer logger.Close()
+	root := t.TempDir()
+	file := filepath.Join(root, "notADirectory")
+	if err = os.WriteFile(file, []byte("x"), 0600); err != nil {
+		t.Fatal(err)
+	}
+	cfg.Storage.Root = file
+	if c, err := New(context.Background(), logger, cfg); err == nil {
+		c.Close()
+		t.Fatal("invalid storage root accepted")
+	}
+	deadline := time.Now().Add(3 * time.Second)
+	for count() != baseline {
+		if time.Now().After(deadline) {
+			t.Fatal("failed startup leaked MySQL connection")
+		}
+		time.Sleep(10 * time.Millisecond)
+	}
+	cfg.Storage.Root = filepath.Join(root, "files")
+	c, err := New(context.Background(), logger, cfg)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err = c.Close(); err != nil {
+		t.Fatal(err)
+	}
+	if err = c.Close(); err != nil {
+		t.Fatal(err)
+	}
+	if err = c.DB.Ping(); err == nil {
+		t.Fatal("closed application retained database")
+	}
+	if err = c.InitStorage(context.Background(), cfg.Storage); err == nil {
+		t.Fatal("closed dependencies reopened storage")
+	}
+}

examples/userService/internal/servicecontext/storage.go

@@ -0,0 +1,49 @@
+package servicecontext
+
+import (
+	"context"
+	"errors"
+
+	"git.yuntuo.hk/k2safe/go-omni/storage/local"
+
+	"example.com/userService/internal/settings"
+	"git.yuntuo.hk/k2safe/go-omni/storage"
+)
+
+// InitStorage is called once, before serving requests. The composition root
+// owns provider clients; business services receive only capability interfaces.
+func (c *Context) InitStorage(ctx context.Context, cfg settings.StorageConfig) error {
+	if c == nil || ctx == nil {
+		return errors.New("storage initialization requires context")
+	}
+	c.closeMu.Lock()
+	defer c.closeMu.Unlock()
+	if c.closed {
+		return errors.New("service dependencies are closed")
+	}
+	if err := ctx.Err(); err != nil {
+		return err
+	}
+	if c.Files != nil {
+		return errors.New("storage already initialized")
+	}
+	if err := cfg.Validate(); err != nil {
+		return err
+	}
+
+	files, err := local.New(cfg.Root, cfg.MaxBytes)
+	if err != nil {
+		return err
+	}
+	signer, err := storage.NewUploadSigner(files, cfg.PublicURL, []byte(cfg.SigningKey), cfg.Policy())
+	if err != nil {
+		return err
+	}
+	uploader, err := storage.NewUploader(files, cfg.Policy())
+	if err != nil {
+		return err
+	}
+	c.Files, c.Uploads, c.Downloads, c.UploadLinks, c.FileHTTP = files, uploader, signer, signer, signer
+
+	return nil
+}