vibe

README

Vibe

Vibe is a lightweight, flexible Go web framework designed for building modern web applications and APIs with minimal boilerplate. Built on top of Go's standard net/http library, Vibe provides a thin layer of convenience without sacrificing performance or compatibility.

Features

• Built on standard library: Leverages Go's net/http package for maximum compatibility and performance
• Simple and intuitive API: Build web applications with a clean, expressive syntax
• Middleware support: Add global or route-specific middleware for cross-cutting concerns
• JSON handling: Built-in utilities for working with JSON requests and responses
• Error handling: Comprehensive error handling with helpful response utilities
• Flexible routing: HTTP method-based routing with path parameters
• CORS support: Built-in middleware for handling Cross-Origin Resource Sharing
• Route groups: Organize routes with common prefixes and middleware

Why Vibe?

Vibe takes a pragmatic approach by building on Go's battle-tested net/http package rather than reinventing the wheel. This means:

• No magic: Clear, predictable behavior that follows Go idioms
• Easy to learn: If you know net/http, you'll feel right at home
• Excellent performance: Minimal overhead compared to raw net/http
• Compatibility: Works with existing net/http middleware and handlers
• Future-proof: Benefits from improvements to the standard library

Installation

go get github.com/sribucoding/vibe

Quick Start

package main

import (
    "net/http"
    "github.com/sribucoding/vibe"
    "github.com/sribucoding/vibe/respond"
)

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

    // Create an API group with version prefix
    api := router.Group("/api/v1")

    // Add routes to the group
    api.Get("/users", func(w http.ResponseWriter, r *http.Request) error {
        return respond.JSON(w, http.StatusOK, map[string]string{"message": "List of users"})
    })

    // Nested groups for more organization
    admin := api.Group("/admin")
    admin.Get("/stats", func(w http.ResponseWriter, r *http.Request) error {
        return respond.JSON(w, http.StatusOK, map[string]string{"status": "ok"})
    })

    http.ListenAndServe(":8080", router)
}

Documentation

For detailed documentation and examples, please visit the GoDoc page .

Examples

Check out the examples directory for complete working examples:

• Todo API : A simple todo list API demonstrating basic CRUD operations

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch ( git checkout -b feature/amazing-feature )
3. Commit your changes ( git commit -m 'Add some amazing feature' )
4. Push to the branch ( git push origin feature/amazing-feature )
5. Open a Pull Request Please make sure your code follows the project's coding standards and includes appropriate tests.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Code of Conduct

Please read our Code of Conduct to keep our community approachable and respectable.

Security

If you discover a security vulnerability within Vibe, please send an email to sribucoding@gmail.com instead of using the issue tracker.

Acknowledgments

• The Go community for inspiration and best practices
• All contributors who have helped shape this project

Future Improvements

• Request validation: Add built-in request validation with custom error messages
• WebSocket support: Real-time communication capabilities
• Rate limiting middleware: Protect APIs from abuse
• Authentication middleware: Common auth patterns (JWT, OAuth)
• Swagger/OpenAPI integration: Automatic API documentation
• Hot reload: Development mode with automatic reloading

Documentation

Overview

Package vibe provides a lightweight, flexible web framework for building modern web applications and APIs in Go with minimal boilerplate.

Vibe focuses on simplicity and expressiveness, offering features like middleware support, flexible routing, and built-in utilities for common web development tasks.

Basic usage example:

package main

import (
    "net/http"
    "github.com/sribucoding/vibe"
    "github.com/sribucoding/vibe/respond"
)

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

    router.Get("/hello", func(w http.ResponseWriter, r *http.Request) error {
        return respond.JSON(w, http.StatusOK, map[string]string{
            "message": "Hello, World!",
        })
    })

    http.ListenAndServe(":8080", router)
}

Index

• type Group
  • func (g *Group) Delete(pattern string, handler middleware.HandlerFunc, mws ...middleware.Middleware)
  • func (g *Group) Get(pattern string, handler middleware.HandlerFunc, mws ...middleware.Middleware)
  • func (g *Group) Group(prefix string, mws ...middleware.Middleware) *Group
  • func (g *Group) Head(pattern string, handler middleware.HandlerFunc, mws ...middleware.Middleware)
  • func (g *Group) Options(pattern string, handler middleware.HandlerFunc, mws ...middleware.Middleware)
  • func (g *Group) Patch(pattern string, handler middleware.HandlerFunc, mws ...middleware.Middleware)
  • func (g *Group) Post(pattern string, handler middleware.HandlerFunc, mws ...middleware.Middleware)
  • func (g *Group) Put(pattern string, handler middleware.HandlerFunc, mws ...middleware.Middleware)
  • func (g *Group) Use(mw middleware.Middleware) *Group
• type HandlerFunc
• type Middleware
• type Router
  • func New(options ...RouterOption) *Router
  • func (r *Router) Delete(pattern string, handler middleware.HandlerFunc, mws ...middleware.Middleware)
  • func (r *Router) Get(pattern string, handler middleware.HandlerFunc, mws ...middleware.Middleware)
  • func (r *Router) Group(prefix string, mws ...middleware.Middleware) *Group
  • func (r *Router) Head(pattern string, handler middleware.HandlerFunc, mws ...middleware.Middleware)
  • func (r *Router) JSON(w http.ResponseWriter, data interface{}) error
  • func (r *Router) NotFound(handler middleware.HandlerFunc)
  • func (r *Router) Options(pattern string, handler middleware.HandlerFunc, mws ...middleware.Middleware)
  • func (r *Router) Patch(pattern string, handler middleware.HandlerFunc, mws ...middleware.Middleware)
  • func (r *Router) Post(pattern string, handler middleware.HandlerFunc, mws ...middleware.Middleware)
  • func (r *Router) Put(pattern string, handler middleware.HandlerFunc, mws ...middleware.Middleware)
  • func (r *Router) ServeHTTP(w http.ResponseWriter, req *http.Request)
  • func (r *Router) Use(mw middleware.Middleware)
• type RouterOption
  • func WithoutRecovery() RouterOption

Types

type Group

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

Group represents a group of routes with a common prefix and middleware. It allows for organizing routes into logical groups.

func (*Group) Delete

func (g *Group) Delete(pattern string, handler middleware.HandlerFunc, mws ...middleware.Middleware)

Delete registers a DELETE route in the group. The pattern is relative to the group's prefix.

func (*Group) Get

func (g *Group) Get(pattern string, handler middleware.HandlerFunc, mws ...middleware.Middleware)

Get registers a GET route in the group. The pattern is relative to the group's prefix.

func (*Group) Group

func (g *Group) Group(prefix string, mws ...middleware.Middleware) *Group

Group creates a sub-group with the given prefix. The prefix is relative to the parent group's prefix. This allows for nested route organization.

Example:

api := router.Group("/api/v1")
admin := api.Group("/admin")
admin.Get("/stats", getStats)  // Route: /api/v1/admin/stats

func (*Group) Head

func (g *Group) Head(pattern string, handler middleware.HandlerFunc, mws ...middleware.Middleware)

Head registers a HEAD route in the group. The pattern is relative to the group's prefix.

func (*Group) Options

func (g *Group) Options(pattern string, handler middleware.HandlerFunc, mws ...middleware.Middleware)

Options registers an OPTIONS route in the group. The pattern is relative to the group's prefix.

func (*Group) Patch

func (g *Group) Patch(pattern string, handler middleware.HandlerFunc, mws ...middleware.Middleware)

Patch registers a PATCH route in the group. The pattern is relative to the group's prefix.

func (*Group) Post

func (g *Group) Post(pattern string, handler middleware.HandlerFunc, mws ...middleware.Middleware)

Post registers a POST route in the group. The pattern is relative to the group's prefix.

func (*Group) Put

func (g *Group) Put(pattern string, handler middleware.HandlerFunc, mws ...middleware.Middleware)

Put registers a PUT route in the group. The pattern is relative to the group's prefix.

func (*Group) Use

func (g *Group) Use(mw middleware.Middleware) *Group

Use adds middleware to the group. The middleware will be applied to all routes in the group. Returns the group for method chaining.

type HandlerFunc

type HandlerFunc func(w http.ResponseWriter, r *http.Request) error

HandlerFunc defines the signature for route handlers. It returns an error if processing fails, which will be handled by the router.

type Middleware

type Middleware func(HandlerFunc) HandlerFunc

Middleware defines a function to wrap a HandlerFunc. Middleware can perform pre-processing before calling the next handler, and post-processing after the next handler returns.

type Router

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

Router wraps the standard library ServeMux and adds middleware and method-specific route registration. It provides a more expressive API for defining routes and applying middleware.

func New

func New(options ...RouterOption) *Router

New creates a new Router instance with default configuration. By default, it includes a recovery middleware to handle panics. Options can be provided to customize the router's behavior.

Example:

// Default router with recovery middleware
router := vibe.New()

// Router without recovery middleware
router := vibe.New(vibe.WithoutRecovery())

func (*Router) Delete

func (r *Router) Delete(pattern string, handler middleware.HandlerFunc, mws ...middleware.Middleware)

Delete registers a DELETE route. The pattern supports path parameters in the format "/{param}".

func (*Router) Get

func (r *Router) Get(pattern string, handler middleware.HandlerFunc, mws ...middleware.Middleware)

Get registers a GET route. The pattern supports path parameters in the format "/{param}".

func (*Router) Group

func (r *Router) Group(prefix string, mws ...middleware.Middleware) *Group

Group creates a new route group with the given prefix. All routes registered on the group will have the specified path prefix. Additional middleware can be applied to all routes in the group.

Example:

api := router.Group("/api/v1")
api.Get("/users", listUsers)

func (*Router) Head

func (r *Router) Head(pattern string, handler middleware.HandlerFunc, mws ...middleware.Middleware)

Head registers a HEAD route. The pattern supports path parameters in the format "/{param}".

func (*Router) JSON

func (r *Router) JSON(w http.ResponseWriter, data interface{}) error

JSON sets the Content-Type to "application/json" and encodes the data as JSON. It's a convenience method for returning JSON responses.

func (*Router) NotFound

func (r *Router) NotFound(handler middleware.HandlerFunc)

NotFound sets a custom handler for 404 Not Found responses. This allows customizing the behavior when no route matches the request.

Example:

router.NotFound(func(w http.ResponseWriter, r *http.Request) error {
    return respond.JSON(w, http.StatusNotFound, map[string]string{
        "error": "Resource not found",
        "path": r.URL.Path,
    })
})

func (*Router) Options

func (r *Router) Options(pattern string, handler middleware.HandlerFunc, mws ...middleware.Middleware)

Options registers an OPTIONS route. The pattern supports path parameters in the format "/{param}".

func (*Router) Patch

func (r *Router) Patch(pattern string, handler middleware.HandlerFunc, mws ...middleware.Middleware)

Patch registers a PATCH route. The pattern supports path parameters in the format "/{param}".

func (*Router) Post

func (r *Router) Post(pattern string, handler middleware.HandlerFunc, mws ...middleware.Middleware)

Post registers a POST route. The pattern supports path parameters in the format "/{param}".

func (*Router) Put

func (r *Router) Put(pattern string, handler middleware.HandlerFunc, mws ...middleware.Middleware)

Put registers a PUT route. The pattern supports path parameters in the format "/{param}".

func (*Router) ServeHTTP

func (r *Router) ServeHTTP(w http.ResponseWriter, req *http.Request)

ServeHTTP implements the http.Handler interface. This allows the Router to be used with the standard library's http.ListenAndServe.

func (*Router) Use

func (r *Router) Use(mw middleware.Middleware)

Use adds a global middleware to the router. Global middlewares are applied to all routes.

type RouterOption

type RouterOption func(*Router)

RouterOption defines a function to configure Router options. It follows the functional options pattern for flexible configuration.

func WithoutRecovery

func WithoutRecovery() RouterOption

WithoutRecovery disables the default recovery middleware. By default, the router includes a recovery middleware to handle panics.