README
¶
REST in pieces
A one-file golang server using sqlite, with focus on simplicity, performance and avoiding 3-party packages as much as possible.
Content
Key Features
Authentication
- Complete authentication workflows:
- Password-based registration/login
- OAuth2 integration for social login
- Email verification with confirmation flow
- Password reset via email
- Email address change with confirmation
- JWT-based session management
Security
- Built-in security headers (CSP, CORS, etc.)
- IP blocking based on rate limiting
Core Infrastructure
- Embedded file server with gzip compression
- Discoverable API endpoints (/api/refresh-auth, /api/auth-with-oauth2, etc.)
- SQLite database interface with pure Go Zombiezen as default driver
- Alternative drivers available in separate repos (like Crawshaw)
- Cache interface with Ristretto implementation
- Router abstraction supporting standard Mux and httprouter
- Middleware-compatible handlers
Frontend Integration
- JavaScript SDK for seamless frontend-backend interaction
- Example frontend pages demonstrating all core functionality
- Built-in asset pipeline (minification + gzip bundling for HTML/CSS/JS)
- Example usage of the SDK and authentication endpoints available at restinpieces-js-sdk
Background Processing
- Job queue system for async tasks (email sending, etc.)
- Worker implementation for processing background jobs
Performance
- Optimized for high throughput (thousands of requests/second)
- Minimal external dependencies
- Production-ready builds with size optimization
Backups
- Built-in Litestream integration for continuous SQLite backups
- Supports incremental backups with minimal overhead
- See restinpieces-litestream for implementation details
Building the Project
Build
# Default build with pure Go Zombiezen SQLite driver
go build -ldflags="-s -w" -trimpath ./cmd/restinpieces/...
TODO
Documentation
¶
Index ¶
- Variables
- func New(ageKeyPath string, opts ...core.Option) (*core.App, *server.Server, error)
- func NewZombiezenPerformancePool(dbPath string) (*sqlitex.Pool, error)
- func NewZombiezenPool(dbPath string) (*sqlitex.Pool, error)
- func SetupScheduler(configProvider *config.Provider, dbAuth db.DbAuth, dbQueue db.DbQueue, ...) (*scl.Scheduler, error)
- func WithCacheRistretto() core.Option
- func WithDbZombiezen(pool *sqlitex.Pool) core.Option
- func WithPhusLogger(opts *slog.HandlerOptions) core.Option
- func WithRouterHttprouter() core.Option
- func WithRouterServeMux() core.Option
- func WithTextLogger(opts *slog.HandlerOptions) core.Option
Constants ¶
This section is empty.
Variables ¶
var DefaultLoggerOptions = &slog.HandlerOptions{ Level: slog.LevelDebug, ReplaceAttr: func(groups []string, a slog.Attr) slog.Attr { if a.Key == slog.TimeKey { return slog.Attr{} } return a }, }
DefaultLoggerOptions provides default settings for slog handlers. Level: Debug, Removes time and level attributes from output.
Functions ¶
func New ¶
New creates a new App instance and Server with the provided options and age key file path. It initializes the core application components like database, router, cache first, then loads configuration from the database using the provided age key.
func NewZombiezenPerformancePool ¶
NewZombiezenPerformancePool creates a new Zombiezen SQLite connection pool optimized for performance using explicit PRAGMA settings via the DSN string.
func NewZombiezenPool ¶
NewZombiezenPool creates a new Zombiezen SQLite connection pool with reasonable defaults compatible with restinpieces (e.g., WAL mode enabled, busy_timeout set). Use this if your application needs to share the pool with restinpieces.
func SetupScheduler ¶
func SetupScheduler(configProvider *config.Provider, dbAuth db.DbAuth, dbQueue db.DbQueue, logger *slog.Logger) (*scl.Scheduler, error)
SetupScheduler initializes the job scheduler and its handlers. dbAcme parameter removed.
func WithCacheRistretto ¶
func WithDbZombiezen ¶
WithDbZombiezen configures the App to use the Zombiezen SQLite implementation with an existing pool.
func WithPhusLogger ¶
func WithPhusLogger(opts *slog.HandlerOptions) core.Option
WithPhusLog configures slog with phuslu/log's JSON handler. Uses DefaultLoggerOptions if opts is nil.
func WithRouterHttprouter ¶
func WithRouterServeMux ¶
func WithTextLogger ¶
func WithTextLogger(opts *slog.HandlerOptions) core.Option
WithTextHandler configures slog with the standard library's text handler.
Types ¶
This section is empty.
Source Files
Directories