extension

package module
v1.8.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 5, 2026 License: MIT Imports: 22 Imported by: 0

Documentation

Overview

Package extension provides the Forge extension for Trove object storage.

It integrates Trove with the Forge application framework, providing:

  • Grove ORM models and store layer for metadata persistence
  • Automatic database migrations
  • REST API handlers for object, bucket, upload, CAS, and VFS operations
  • Configuration via YAML or functional options
  • DI integration (provides *trove.Trove to the container)
  • Auto-discovery of ecosystem services (Chronicle, Vault, Dispatch, Warden)

Usage: 

app := forge.New()
app.Use(extension.New(
    extension.WithGroveDatabase("default"),
))

Index

Constants

View Source 
const (
	// ExtensionName is the extension identifier.
	ExtensionName = "trove"

	// ExtensionVersion is the current extension version.
	ExtensionVersion = "0.1.0"

	// ExtensionDescription describes the extension.
	ExtensionDescription = "Object storage engine with middleware, CAS, VFS, and streaming"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type Config 

type Config struct {
	// StorageDriver is the DSN for the storage backend (e.g., "file:///data", "s3://bucket").
	StorageDriver string `json:"storage_driver" yaml:"storage_driver" mapstructure:"storage_driver"`

	// BasePath is the HTTP route prefix (default: "/trove").
	BasePath string `json:"base_path" yaml:"base_path" mapstructure:"base_path"`

	// DisableRoutes skips HTTP handler registration.
	DisableRoutes bool `json:"disable_routes" yaml:"disable_routes" mapstructure:"disable_routes"`

	// DisableMigrate skips automatic database migration.
	DisableMigrate bool `json:"disable_migrate" yaml:"disable_migrate" mapstructure:"disable_migrate"`

	// GroveDatabase is the named Grove DB to resolve from DI (default: "").
	GroveDatabase string `json:"grove_database" yaml:"grove_database" mapstructure:"grove_database"`

	// DefaultBucket is the default storage bucket.
	DefaultBucket string `json:"default_bucket" yaml:"default_bucket" mapstructure:"default_bucket"`

	// EnableCAS enables content-addressable storage.
	EnableCAS bool `json:"enable_cas" yaml:"enable_cas" mapstructure:"enable_cas"`

	// EnableEncryption auto-configures encryption middleware.
	EnableEncryption bool `json:"enable_encryption" yaml:"enable_encryption" mapstructure:"enable_encryption"`

	// EnableCompression auto-configures compression middleware.
	EnableCompression bool `json:"enable_compression" yaml:"enable_compression" mapstructure:"enable_compression"`

	// Stores defines named file store connections for multi-store mode.
	// When set, each entry creates a separate trove.Trove registered in DI.
	Stores []FileStoreConfig `json:"stores" yaml:"stores" mapstructure:"stores"`

	// Default is the name of the default store when using multi-store mode.
	// If empty, the first entry in Stores is the default.
	Default string `json:"default" yaml:"default" mapstructure:"default"`

	// DashboardContentPath is where the dashboard's content route mounts.
	// It sits under the dashboard's own base path so the proxy that
	// forwards the dashboard forwards this too.
	DashboardContentPath string `json:"dashboard_content_path" yaml:"dashboard_content_path" mapstructure:"dashboard_content_path"`

	// DashboardMaxUploadBytes is the largest upload the dashboard accepts.
	// Every Trove middleware buffers a whole object in memory, which is why
	// the default is 64 MiB.
	DashboardMaxUploadBytes int64 `json:"dashboard_max_upload_bytes" yaml:"dashboard_max_upload_bytes" mapstructure:"dashboard_max_upload_bytes"`

	// DashboardContentSecret signs content tickets, at least 32 bytes. When
	// empty, a random key is generated at start, which works only while
	// every request reaches the same instance.
	DashboardContentSecret string `json:"dashboard_content_secret" yaml:"dashboard_content_secret" mapstructure:"dashboard_content_secret"`

	// RequireConfig causes Register() to fail if YAML config is missing.
	RequireConfig bool `json:"-" yaml:"-"`
}

Config holds extension configuration.

func DefaultConfig 

func DefaultConfig() Config

DefaultConfig returns sensible defaults.

func (Config) ToTroveOptions 

func (c Config) ToTroveOptions() []trove.Option

ToTroveOptions converts config values to trove.Option slice.

func (*Config) Validate 

func (c *Config) Validate() error

Validate checks that the configuration is usable.

type ExtOption 

type ExtOption func(*Extension)

ExtOption configures the extension.

func WithBasePath 

func WithBasePath(path string) ExtOption

WithBasePath sets the HTTP route prefix.

func WithConfig 

func WithConfig(cfg Config) ExtOption

WithConfig sets the full configuration.

func WithDefaultFileStore 

func WithDefaultFileStore(name string) ExtOption

WithDefaultFileStore sets which named store is the default. The default is used for backward-compatible Trove() access and unnamed DI injection.

func WithDisableMigrate 

func WithDisableMigrate() ExtOption

WithDisableMigrate skips automatic database migration.

func WithDisableRoutes 

func WithDisableRoutes() ExtOption

WithDisableRoutes skips HTTP handler registration.

func WithFileStore 

func WithFileStore(name string, drv driver.Driver) ExtOption

WithFileStore adds a named file store with a pre-configured driver. Multiple calls create multiple named stores.

Example: 

ext := extension.New(
    extension.WithFileStore("primary", s3Driver),
    extension.WithFileStore("archive", localDriver),
    extension.WithDefaultFileStore("primary"),
)

func WithFileStoreDSN 

func WithFileStoreDSN(name, dsn string) ExtOption

WithFileStoreDSN adds a named file store using a DSN. The driver will be resolved from the driver registry during Register().

Example: 

ext := extension.New(
    extension.WithFileStoreDSN("primary", "s3://us-east-1/my-bucket"),
    extension.WithFileStoreDSN("archive", "file:///data/archive"),
)

func WithGroveDatabase 

func WithGroveDatabase(name string) ExtOption

WithGroveDatabase sets the named Grove DB to resolve from DI.

func WithStore 

func WithStore(s store.Store) ExtOption

WithStore provides a pre-built store (skips Grove DB resolution).

func WithTroveOption 

func WithTroveOption(opt trove.Option) ExtOption

WithTroveOption adds a trove.Option applied during initialization.

func WithTroveOptionFor 

func WithTroveOptionFor(storeName string, opt trove.Option) ExtOption

WithTroveOptionFor adds a trove.Option scoped to a specific named store.

type Extension 

type Extension struct {
	*forge.BaseExtension
	// contains filtered or unexported fields
}

Extension implements the Forge extension lifecycle for Trove.

func New 

func New(opts ...ExtOption) *Extension

New creates a new Trove extension.

func (*Extension) Health 

func (e *Extension) Health(ctx context.Context) error

Health checks the health of the Trove extension.

func (*Extension) Init 

func (e *Extension) Init(fapp forge.App) error

Init initializes the Trove extension: resolves DB, runs migrations, creates the Trove instance, and registers routes. In a Forge environment this is called during Register (single-store mode). For standalone use, call it manually after loadConfiguration.

func (*Extension) Manager 

func (e *Extension) Manager() *TroveManager

Manager returns the TroveManager for multi-store mode. Returns nil in single-store mode.

func (*Extension) Register 

func (e *Extension) Register(fapp forge.App) error

Register is called when the extension is registered with the Forge app.

func (*Extension) RegisterContractContributor 

func (e *Extension) RegisterContractContributor(
	disp *dispatcher.Dispatcher,
	reg dashcontract.Registry,
	wreg dashcontract.WardenRegistry,
) error

RegisterContractContributor registers the trove contract contributor, which is what the React dashboard reads.

func (*Extension) Start 

func (e *Extension) Start(_ context.Context) error

Start starts the Trove extension.

func (*Extension) Stop 

func (e *Extension) Stop(ctx context.Context) error

Stop gracefully shuts down the Trove extension.

func (*Extension) Store 

func (e *Extension) Store() store.Store

Store returns the underlying metadata store (default in multi-store mode).

func (*Extension) Trove 

func (e *Extension) Trove() *trove.Trove

Trove returns the underlying Trove instance (default in multi-store mode).

type FileStoreConfig 

type FileStoreConfig struct {
	// Name is the unique identifier for this store.
	Name string `json:"name" yaml:"name" mapstructure:"name"`

	// StorageDriver is the DSN for the storage backend
	// (e.g., "mem://", "file:///data", "s3://region/bucket").
	StorageDriver string `json:"storage_driver" yaml:"storage_driver" mapstructure:"storage_driver"`

	// GroveDatabase is the named Grove DB for this store's metadata.
	GroveDatabase string `json:"grove_database" yaml:"grove_database" mapstructure:"grove_database"`

	// DefaultBucket is the default bucket for this store.
	DefaultBucket string `json:"default_bucket" yaml:"default_bucket" mapstructure:"default_bucket"`

	// EnableCAS enables content-addressable storage for this store.
	EnableCAS bool `json:"enable_cas" yaml:"enable_cas" mapstructure:"enable_cas"`

	// EnableEncryption auto-configures encryption middleware for this store.
	EnableEncryption bool `json:"enable_encryption" yaml:"enable_encryption" mapstructure:"enable_encryption"`

	// EnableCompression auto-configures compression middleware for this store.
	EnableCompression bool `json:"enable_compression" yaml:"enable_compression" mapstructure:"enable_compression"`
}

FileStoreConfig defines a single named file store.

type TroveManager 

type TroveManager struct {
	// contains filtered or unexported fields
}

TroveManager manages multiple named trove.Trove instances. It provides named access, a default store, and bulk close.

func NewTroveManager 

func NewTroveManager() *TroveManager

NewTroveManager creates an empty TroveManager.

func (*TroveManager) Add 

func (m *TroveManager) Add(name string, t *trove.Trove, s store.Store)

Add registers a named Trove instance and its metadata store. The first instance added becomes the default unless SetDefault is called.

func (*TroveManager) All 

func (m *TroveManager) All() map[string]*trove.Trove

All returns a shallow copy of the name-to-Trove map.

func (*TroveManager) Close 

func (m *TroveManager) Close(ctx context.Context) error

Close closes all registered Trove instances and returns the first error encountered.

func (*TroveManager) Default 

func (m *TroveManager) Default() (*trove.Trove, error)

Default returns the default Trove instance.

func (*TroveManager) DefaultName 

func (m *TroveManager) DefaultName() string

DefaultName returns the name of the default store.

func (*TroveManager) DefaultStore 

func (m *TroveManager) DefaultStore() (store.Store, error)

DefaultStore returns the default metadata store.

func (*TroveManager) Get 

func (m *TroveManager) Get(name string) (*trove.Trove, error)

Get returns the Trove instance registered under name.

func (*TroveManager) GetStore 

func (m *TroveManager) GetStore(name string) (store.Store, error)

GetStore returns the metadata store registered under name.

func (*TroveManager) Len 

func (m *TroveManager) Len() int

Len returns the number of registered stores.

func (*TroveManager) SetDefault 

func (m *TroveManager) SetDefault(name string) error

SetDefault sets the default store by name. Returns an error if the name is not registered.

Source Files

View all Source files

Directories

Path Synopsis
Package contract wires Trove into the Forge dashboard's contract path.
 Package contract wires Trove into the Forge dashboard's contract path.
Package handler provides HTTP handlers for Trove REST API.
 Package handler provides HTTP handlers for Trove REST API.
Package hooks provides ecosystem integration hooks for Trove.
 Package hooks provides ecosystem integration hooks for Trove.
Package migrate provides Grove modular migrations for Trove tables.
 Package migrate provides Grove modular migrations for Trove tables.
Package store defines the aggregate persistence interface for Trove metadata.
 Package store defines the aggregate persistence interface for Trove metadata.
memory
Package memory provides an in-memory implementation of store.Store for testing.
 Package memory provides an in-memory implementation of store.Store for testing.
mongo
Package mongo implements the Trove store interface using MongoDB via Grove ORM.
 Package mongo implements the Trove store interface using MongoDB via Grove ORM.
postgres
Package postgres implements the Trove store interface using grove ORM (PostgreSQL).
 Package postgres implements the Trove store interface using grove ORM (PostgreSQL).
sqlite
Package sqlite implements the Trove store interface using grove ORM (SQLite).
 Package sqlite implements the Trove store interface using grove ORM (SQLite).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.