gostarter

README

gostarter

• Batteries included, offers cron jobs, backups and more.
• Configurable, either full on setup, or just basic tables, or even build from scratch.
• Infrastructure independent, works with both monolith and microservice architecture.
• Compatible with SQLite and PostgreSQL.

What is gostarter?

gostarter is a package aiming to provide useful components to create a monolith backend server. That said, gostarter can also be configured to act as just a Restful API server or a sidecar application if you are adopting a microservice architecture.

Why not PocketBase (or other alternatives)?

PocketBase

PocketBase assumes you to use the record and collection operations instead of messing with raw SQL queries, which works very well for many cases. That said, you may still want to go around the API and extend the app for your use case from time to time. If this happens again and again, starting from scratch could be a better option.

If you also find the API of PocketBase a bit limiting, you can also explore the option of adopting this package, as it provides many commonly used components, while still offer enough flexibility for different kinds of applications.

All these aside, make sure to check out PocketBase before looking at gostarter, as it is still a more actively maintained and more mature product.

Supabase

As for BaaS, Supabase is one of the very popular options. It is a much more complete solution compared to this Golang package. If you are building a prototype with possibility to serve millions of concurrent users, Supabase is a much more mature and suitable platform to develop your product.

That being said, you may realize the downside of Supabase when you try to self-host it on your machine. You have to clone the entire repository to install and update the whole infrastructure, making it hard to version control your backend. Also, the whole stack consume a lot of resources if you are just building a simple application. These and other caveats make self-hosting very far from an ideal solution for small to medium scale products, or internal applications.

When not to use gostarter?

If you are building a backend with millions of concurrent users, avoid using this package in production workflow without any thorough stress test.

When you are developing prototype or facing requirements that change very frequently, as other options also provide interface for frontend to connect with the backend. This package only provides handy utilities to serve a Restful API, the frontend has to connect to the server by itself.

gostarter is very, very far from perfect, and is just a personal project with very limited resources, so please be aware of the shortcomings before using it.

Documentation

Index

• func Debug(msg string)
• func Debugf(format string, args ...any)
• func Error(msg string)
• func Errorf(format string, args ...any)
• func GetBool(key string, defaultValue bool) (bool, error)
• func GetInt(key string, defaultValue int) (int, error)
• func GetString(key string, defaultValue string) (string, error)
• func Info(msg string)
• func Infof(format string, args ...any)
• func MustGetBool(key string, defaultValue bool) bool
• func MustGetInt(key string, defaultValue int) int
• func MustGetString(key string, defaultValue string) string
• func MustSetConstantsWithPrefix()
• func MustSetConstantsWithoutPrefix()
• func NewDBFromEnv() (*sqlx.DB, error)
• func SetCustomLoggerFromEnv() error
• func Warn(msg string)
• func Warnf(format string, args ...any)
• type Handler
• type Job
  • func DefaultSchedulerJobFromEnv(schedulerService *cron.SchedulerService) []Job
  • func SQLiteBackupJob(schedulerService *cron.SchedulerService) Job
  • func SessionCleanupJob(schedulerService *cron.SchedulerService) Job
• type Option
  • func WithApiHandler(subpath string, handlerList ...Handler) Option
  • func WithAppMigrations(appMigrationFS embed.FS) Option
  • func WithCustomCookieGenerator(cookieGenerator *common.CookieGenerator) Option
  • func WithCustomHashingManager(hashingManager *crypto.HashingManager) Option
  • func WithCustomIDGenerator(idGenerator func() string) Option
  • func WithCustomResponseHandler(responseHandler *common.ResponseHandler) Option
  • func WithCustomValidationManager(validationManager *validation.ValidationManager) Option
  • func WithDefaultApiHandler(handlerList ...Handler) Option
  • func WithDefaultMiddleware() Option
  • func WithDefaultScheduler(jobList ...Job) Option
  • func WithGostarterMigration() Option
  • func WithGracefulShutdownTimeout(timeout time.Duration) Option
  • func WithHttpServer() Option
  • func WithMiddleware(middlewareList ...middleware.Middleware) Option
  • func WithPort(port string) Option
  • func WithScheduler(jobList ...Job) Option
  • func WithStaticSite(path string, siteFs fs.FS) Option
• type Scheduler
  • func NewScheduler() (*Scheduler, error)
  • func (s *Scheduler) AddJob(job Job) error
  • func (s *Scheduler) Shutdown(ctx context.Context) error
  • func (s *Scheduler) Start()
• type Server
  • func NewServer(db *sqlx.DB, options ...Option) (*Server, error)
  • func (s *Server) Start() error
  • func (s *Server) StartWithGracefulShutdown()
  • func (s *Server) Stop(ctx context.Context) error

Functions

func Debug

func Debug(msg string)

func Debugf

func Debugf(format string, args ...any)

func Error

func Error(msg string)

func Errorf

func Errorf(format string, args ...any)

func GetBool

func GetBool(key string, defaultValue bool) (bool, error)

func GetInt

func GetInt(key string, defaultValue int) (int, error)

func GetString

func GetString(key string, defaultValue string) (string, error)

func Info

func Info(msg string)

func Infof

func Infof(format string, args ...any)

func MustGetBool

func MustGetBool(key string, defaultValue bool) bool

func MustGetInt

func MustGetInt(key string, defaultValue int) int

func MustGetString

func MustGetString(key string, defaultValue string) string

func MustSetConstantsWithPrefix

func MustSetConstantsWithPrefix()

func MustSetConstantsWithoutPrefix

func MustSetConstantsWithoutPrefix()

func NewDBFromEnv

func NewDBFromEnv() (*sqlx.DB, error)

NewDBFromEnv creates a new database connection based on the environment variables defined in the env package. It returns a pointer to sqlx.DB and an error if any occurs during the connection process.

func SetCustomLoggerFromEnv

func SetCustomLoggerFromEnv() error

SetCustomLoggerFromEnv sets a custom logger based on the log level defined in the environment variables. It uses the slog package to create a new logger with a custom handler that formats log messages with a timestamp, log level, and message. The log level is set based on the value of env.LogLevel.

func Warn

func Warn(msg string)

func Warnf

func Warnf(format string, args ...any)

Types

type Handler

type Handler interface {
	RegisterRoutes(*http.ServeMux)
}

type Job

type Job struct {
	CronSchedule string
	WithSeconds  bool
	Task         func(context.Context)
}

func DefaultSchedulerJobFromEnv

func DefaultSchedulerJobFromEnv(schedulerService *cron.SchedulerService) []Job

func SQLiteBackupJob

func SQLiteBackupJob(schedulerService *cron.SchedulerService) Job

func SessionCleanupJob

func SessionCleanupJob(schedulerService *cron.SchedulerService) Job

type Option

type Option func(*Server) error

func WithApiHandler

func WithApiHandler(subpath string, handlerList ...Handler) Option

func WithAppMigrations

func WithAppMigrations(appMigrationFS embed.FS) Option

func WithCustomCookieGenerator

func WithCustomCookieGenerator(cookieGenerator *common.CookieGenerator) Option

func WithCustomHashingManager

func WithCustomHashingManager(hashingManager *crypto.HashingManager) Option

func WithCustomIDGenerator

func WithCustomIDGenerator(idGenerator func() string) Option

func WithCustomResponseHandler

func WithCustomResponseHandler(responseHandler *common.ResponseHandler) Option

func WithCustomValidationManager

func WithCustomValidationManager(validationManager *validation.ValidationManager) Option

func WithDefaultApiHandler

func WithDefaultApiHandler(handlerList ...Handler) Option

func WithDefaultMiddleware

func WithDefaultMiddleware() Option

func WithDefaultScheduler

func WithDefaultScheduler(jobList ...Job) Option

func WithGostarterMigration

func WithGostarterMigration() Option

func WithGracefulShutdownTimeout

func WithGracefulShutdownTimeout(timeout time.Duration) Option

func WithHttpServer

func WithHttpServer() Option

func WithMiddleware

func WithMiddleware(middlewareList ...middleware.Middleware) Option

func WithPort

func WithPort(port string) Option

func WithScheduler

func WithScheduler(jobList ...Job) Option

func WithStaticSite

func WithStaticSite(path string, siteFs fs.FS) Option

type Scheduler

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

func NewScheduler

func NewScheduler() (*Scheduler, error)

func (*Scheduler) AddJob

func (s *Scheduler) AddJob(job Job) error

func (*Scheduler) Shutdown

func (s *Scheduler) Shutdown(ctx context.Context) error

func (*Scheduler) Start

func (s *Scheduler) Start()

type Server

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

func NewServer

func NewServer(db *sqlx.DB, options ...Option) (*Server, error)

func (*Server) Start

func (s *Server) Start() error

func (*Server) StartWithGracefulShutdown

func (s *Server) StartWithGracefulShutdown()

func (*Server) Stop

func (s *Server) Stop(ctx context.Context) error