velocity

package module
v0.10.0 Latest Latest
Warning

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

Go to latest
Published: Feb 14, 2026 License: MIT Imports: 28 Imported by: 0

README

Velocity

A Laravel-inspired web framework for Go

Velocity brings joy and elegance to Go web development, without sacrificing Go's simplicity, performance, and type safety. Build web applications with expressive APIs and the speed of Go.

Why Velocity?

For Framework Users: Get familiar conventions and developer happiness you love, with Go's performance and concurrency.

For Go Developers: Skip the boilerplate and focus on building. Velocity provides a unified, elegant interface over common web development tasks.

Key Features
  • Single Binary: Deploy anywhere with zero dependencies
  • Type Safety: Full compile-time type checking with Go's type system
  • True Concurrency: Built-in goroutines and channels for high performance
  • Driver-Based Architecture: Swap implementations via config (Redis ↔ Memory, PostgreSQL ↔ MySQL)
  • Expressive DX: Familiar conventions, expressive APIs, and developer-friendly errors

Requirements

  • Go 1.25 or higher
  • Node.js 18+ (for frontend assets)

CLI Installation

Install the Velocity CLI to create and manage projects:

# Homebrew (macOS)
brew tap velocitykode/tap
brew install velocity

# Or with Go
go install github.com/velocitykode/velocity-cli@latest

Verify installation:

velocity version

Quick Start

Create a new project:

velocity new myapp
cd myapp
velocity serve

Your app runs at http://localhost:3000

Manual Setup

Add the framework to an existing project:

go get github.com/velocitykode/velocity
package main

import (
    "github.com/velocitykode/velocity/pkg/router"
    "github.com/velocitykode/velocity/pkg/log"
)

func main() {
    r := router.New()

    r.Get("/", func(c *router.Context) error {
        return c.JSON(200, map[string]string{
            "message": "Welcome to Velocity!",
        })
    })

    log.Info("Starting server on :4000")
    r.Run(":4000")
}

Feature Status

Package Status Description
async ✅ Complete Async primitives and concurrency patterns
auth ✅ Complete Authentication and session management
broadcast ✅ Complete Real-time event broadcasting
cache ✅ Complete Multi-driver caching (memory, file, redis)
config ✅ Complete Configuration management
crypto ✅ Complete Encryption and decryption
csrf ✅ Complete CSRF protection
events ✅ Complete Event system with listeners
log ✅ Complete Structured logging with multiple drivers
mail ✅ Complete Email sending with multiple drivers
orm ✅ Complete Database ORM with relationships
queue ✅ Complete Job queue system with workers
router ✅ Complete HTTP routing with middleware
scheduler ✅ Complete Task scheduling (cron-like)
storage ✅ Complete File storage abstraction
str ✅ Complete String manipulation utilities
testing ✅ Complete Testing helpers and utilities
validation ✅ Complete Input validation
view ✅ Complete Template rendering
vite ✅ Complete Vite.js integration for frontend
websocket ✅ Complete WebSocket support

Documentation

Full documentation at velocitykode.com/docs

Community

Philosophy

Velocity is built on three principles:

  1. Developer Happiness: Code should be a joy to write and read
  2. Convention over Configuration: Sensible defaults, configure only when needed
  3. Go's Strengths: Embrace simplicity, performance, and type safety

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

License

Velocity is open-source software licensed under the MIT License.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type App

type App struct {
	// Services contains all non-router services, shared with router.Context.
	*app.Services

	// Router is separate from Services because it creates contexts that
	// reference Services — putting Router inside Services would be circular.
	Router *router.VelocityRouterV2
	// contains filtered or unexported fields
}

App represents the Velocity application container. It owns all framework subsystem instances and provides them to the consumer.

func New

func New(opts ...Option) (*App, error)

New creates a new Velocity application with all services initialized. Services are initialized in dependency order. If any required service fails to initialize, New returns an error — it never panics.

func NewTestApp added in v0.9.5

func NewTestApp(opts ...Option) (*App, error)

NewTestApp creates an App with in-memory services suitable for testing. Uses memory cache, memory queue, and console logger.

func (*App) Run

func (a *App) Run()

Run starts the application.

func (*App) Serve added in v0.9.5

func (a *App) Serve() error

Serve starts the HTTP server with signal handling and graceful shutdown.

func (*App) Shutdown added in v0.9.5

func (a *App) Shutdown(ctx context.Context) error

Shutdown gracefully shuts down all services in reverse initialization order.

func (*App) Version

func (a *App) Version() string

Version returns the framework version.

type AuthConfig added in v0.9.5

type AuthConfig = auth.Config

Type aliases — these reuse the canonical package types to avoid duplication. Consumers can use either velocity.AuthConfig or auth.Config interchangeably.

type CacheConfig added in v0.9.5

type CacheConfig struct {
	Driver        string // CACHE_DRIVER: memory, file, redis, database
	Prefix        string // CACHE_PREFIX, default "velocity_cache"
	Path          string // CACHE_PATH (for file driver)
	RedisHost     string // REDIS_HOST, default "127.0.0.1"
	RedisPort     int    // REDIS_PORT, default 6379
	RedisPassword string // REDIS_PASSWORD
	RedisDatabase int    // REDIS_DATABASE, default 0
}

CacheConfig holds cache configuration. Kept as a root type because it uses a flat structure (single driver) while cache.Config uses a multi-store map pattern.

type Config added in v0.9.5

type Config struct {
	// App
	Name  string // APP_NAME, default "Velocity"
	Env   string // APP_ENV, default "development"
	Debug bool   // APP_DEBUG, default false
	Port  string // PORT, default "4000"
	Key   string // APP_KEY (used for crypto)

	// Database
	DB DBConfig

	// Auth
	Auth AuthConfig

	// Cache
	Cache CacheConfig

	// Log
	Log LogConfig

	// Queue
	Queue QueueConfig

	// Storage
	Storage StorageConfig

	// Session
	Session SessionConfig

	// View
	View ViewConfig

	// Crypto
	Crypto CryptoConfig

	// Mail
	Mail MailConfig

	// Server timeouts
	ReadTimeout  time.Duration // SERVER_READ_TIMEOUT, default 30s
	WriteTimeout time.Duration // SERVER_WRITE_TIMEOUT, default 30s
	IdleTimeout  time.Duration // SERVER_IDLE_TIMEOUT, default 120s

}

Config holds all configuration for a Velocity application. It replaces the scattered os.Getenv() calls across packages.

func ConfigFromEnv added in v0.9.5

func ConfigFromEnv() Config

ConfigFromEnv loads configuration from environment variables and .env file.

type CryptoConfig added in v0.9.5

type CryptoConfig = crypto.Config

Type aliases — these reuse the canonical package types to avoid duplication. Consumers can use either velocity.AuthConfig or auth.Config interchangeably.

type DBConfig added in v0.9.5

type DBConfig struct {
	Connection      string        // DB_CONNECTION: sqlite, postgres, mysql
	Host            string        // DB_HOST, default "127.0.0.1"
	Port            string        // DB_PORT, default per driver
	Database        string        // DB_DATABASE
	Username        string        // DB_USERNAME
	Password        string        // DB_PASSWORD
	Charset         string        // DB_CHARSET
	Collation       string        // DB_COLLATION
	Prefix          string        // DB_PREFIX
	Schema          string        // DB_SCHEMA
	SSLMode         string        // DB_SSL_MODE
	Timezone        string        // DB_TIMEZONE
	MaxIdleConns    int           // DB_MAX_IDLE_CONNS, default 10
	MaxOpenConns    int           // DB_MAX_OPEN_CONNS, default 100
	ConnMaxLifetime time.Duration // DB_CONN_MAX_LIFETIME, default 3600s
	LogQueries      bool          // DB_LOG_QUERIES
	SlowThreshold   time.Duration // DB_SLOW_QUERY_THRESHOLD
}

DBConfig holds database configuration. Kept as a root type because it differs structurally from orm.ManagerConfig.

type DiskConfig added in v0.9.5

type DiskConfig struct {
	Driver     string // "local", "s3", "memory"
	Root       string // Root path for local driver
	URL        string // Base URL for file access
	Visibility string // Default visibility (public/private)
	// S3 fields
	Bucket   string
	Region   string
	Key      string
	Secret   string
	Endpoint string
	// Memory driver
	MaxSize int64 // Maximum memory usage in bytes
}

DiskConfig holds configuration for a single storage disk.

type GuardConfig added in v0.9.5

type GuardConfig = auth.GuardConfig

Type aliases — these reuse the canonical package types to avoid duplication. Consumers can use either velocity.AuthConfig or auth.Config interchangeably.

type JWTConfig added in v0.9.5

type JWTConfig = auth.JWTConfig

Type aliases — these reuse the canonical package types to avoid duplication. Consumers can use either velocity.AuthConfig or auth.Config interchangeably.

type LogConfig added in v0.9.5

type LogConfig = log.LogConfig

Type aliases — these reuse the canonical package types to avoid duplication. Consumers can use either velocity.AuthConfig or auth.Config interchangeably.

type MailConfig added in v0.9.5

type MailConfig = mail.MailConfig

Type aliases — these reuse the canonical package types to avoid duplication. Consumers can use either velocity.AuthConfig or auth.Config interchangeably.

type Option added in v0.9.5

type Option func(*App)

Option is a function that configures the App.

func WithConfig added in v0.9.5

func WithConfig(config Config) Option

WithConfig sets a custom configuration.

func WithIdleTimeout added in v0.9.16

func WithIdleTimeout(d time.Duration) Option

WithIdleTimeout sets the HTTP server idle timeout.

func WithPort added in v0.9.5

func WithPort(port string) Option

WithPort sets the server port.

func WithProviders added in v0.10.0

func WithProviders(providers ...app.ServiceProvider) Option

WithProviders appends service providers to the application. Providers are registered and booted in the order they are given.

func WithReadTimeout added in v0.9.16

func WithReadTimeout(d time.Duration) Option

WithReadTimeout sets the HTTP server read timeout.

func WithWriteTimeout added in v0.9.16

func WithWriteTimeout(d time.Duration) Option

WithWriteTimeout sets the HTTP server write timeout.

type ProviderConfig added in v0.9.5

type ProviderConfig = auth.ProviderConfig

Type aliases — these reuse the canonical package types to avoid duplication. Consumers can use either velocity.AuthConfig or auth.Config interchangeably.

type QueueConfig added in v0.9.5

type QueueConfig struct {
	Driver        string // QUEUE_DRIVER: memory, redis, database
	RedisHost     string // QUEUE_REDIS_HOST, default "localhost"
	RedisPort     string // QUEUE_REDIS_PORT, default "6379"
	RedisPassword string // QUEUE_REDIS_PASSWORD
	RedisDB       string // QUEUE_REDIS_DB, default "0"
}

QueueConfig holds queue configuration. Kept as a root type because it uses a flat structure while queue.QueueConfig nests Redis fields in a sub-struct.

type SessionConfig added in v0.9.5

type SessionConfig = auth.SessionConfig

Type aliases — these reuse the canonical package types to avoid duplication. Consumers can use either velocity.AuthConfig or auth.Config interchangeably.

type StorageConfig added in v0.9.5

type StorageConfig struct {
	Default string                // STORAGE_DRIVER, default "local"
	Disks   map[string]DiskConfig // Disk configurations
}

StorageConfig holds storage configuration. Kept as a root type because the DiskConfig fields differ slightly from storage.DiskConfig (Endpoint field).

type ViewConfig added in v0.9.5

type ViewConfig = view.Config

Type aliases — these reuse the canonical package types to avoid duplication. Consumers can use either velocity.AuthConfig or auth.Config interchangeably.

Directories

Path Synopsis
pkg
app
broadcast
Package broadcast provides a high-level broadcasting system for real-time communication built on top of the WebSocket package and supporting multiple drivers
Package broadcast provides a high-level broadcasting system for real-time communication built on top of the WebSocket package and supporting multiple drivers
cache/testing
Package testing provides test helpers for the cache package.
Package testing provides test helpers for the cache package.
exceptions
Package exceptions provides Laravel-style exception handling for Velocity.
Package exceptions provides Laravel-style exception handling for Velocity.
grpc
Package grpc provides a fluent API for building gRPC servers and HTTP gateways.
Package grpc provides a fluent API for building gRPC servers and HTTP gateways.
grpc/converters
Package converters provides utilities for converting between Go types and protobuf types.
Package converters provides utilities for converting between Go types and protobuf types.
grpc/grpcevents
Package grpcevents provides event types for gRPC operations.
Package grpcevents provides event types for gRPC operations.
grpc/interceptors
Package interceptors provides gRPC interceptors for Velocity applications.
Package interceptors provides gRPC interceptors for Velocity applications.
httpclient
Package httpclient provides an instrumented HTTP client for APM monitoring.
Package httpclient provides an instrumented HTTP client for APM monitoring.
log
mail/alldrivers
Package alldrivers imports all mail drivers to register them Import this package with _ to ensure all drivers are registered
Package alldrivers imports all mail drivers to register them Import this package with _ to ensure all drivers are registered
orm
router
Package router provides HTTP routing functionality for the Velocity framework.
Package router provides HTTP routing functionality for the Velocity framework.
str
trace
Package trace provides distributed tracing context helpers for APM instrumentation.
Package trace provides distributed tracing context helpers for APM instrumentation.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL