Falcon Logo

Falcon

Documentation

Learn how to install, configure, and deploy your Go framework.

Getting StartedGitHub

Introduction

Falcon is a minimal and fast Go framework for building HTTP services. It provides a clear API, predictable performance, and a smooth developer experience.

Installation

Install Falcon using:

bash
go get github.com/ascendingheavens/falcon

Getting Started

Create a new main.go and start a Falcon server:

go
package main

import (
  "net/http"
  framework "github.com/AscendingHeavens/falcon"
)

func main() {
  app := framework.New()

  app.GET("/", func(c framework.Context) error {
    return c.String(http.StatusOK, "Hello, World!")
  })

  app.Start(":8080")
}

Server Setup

The Server struct initializes Falcon with middleware, routes, and a database connection.

go
type Server struct {
  Router *falcon.Server
  db     db.DB
  config config.Config
}

func NewServer(cfg config.Config) (*Server, error) {
  server := &Server{
    config: cfg,
    db:     db.NewInMemoryUserDB(),
  }

  server.SetupRouter()
  return server, nil
}

Routing

Define routes and map them to handler methods. Example from SetupRouter:

go
func (server *Server) SetupRouter() {
  router := falcon.New()
  router.Use(middleware.CORS())
  router.Use(middleware.Logger())

  router.GET("/hello", func(c *falcon.Context) *falcon.Response {
    return c.JSON(true, "Works", map[string]any{
      "message": "Hello, World!",
    }, http.StatusOK)
  })

  // Users
  router.GET("/users", server.FetchAllUsers)
  router.POST("/users", server.CreateUser)
  router.GET("/users/:id", server.FetchUser)
  router.PUT("/users/:id", server.UpdateUser)
  router.DELETE("/users/:id", server.DeleteUser)

  // Blob Example
  router.GET("/blob", server.Blob)

  server.Router = router
}

Blob Route

Falcon can also serve binary files (like images). Example /blob route:

go
func (server *Server) Blob(ctx *falcon.Context) *falcon.Response {
  data, err := os.ReadFile("falcon.png")
  if err != nil {
    return ctx.ErrorJSON("Could not load image", err.Error(), http.StatusInternalServerError)
  }
  return ctx.Blob(http.StatusOK, data, "image/png")
}

User CRUD

Falcon makes it easy to implement REST-style CRUD endpoints.

Create User

go
func (server *Server) CreateUser(ctx *falcon.Context) *falcon.Response {
  var request db.User
  if err := ctx.Bind(&request); err != nil {
    return ctx.ErrorJSON("Invalid request body", nil, http.StatusBadRequest)
  }
  user, err := server.db.CreateUser(request)
  if err != nil {
    return ctx.ErrorJSON("Could not create user", nil, http.StatusInternalServerError)
  }
  return ctx.JSON(true, "User created successfully!", user, http.StatusCreated)
}

Fetch User

go
func (server *Server) FetchUser(ctx *falcon.Context) *falcon.Response {
  id := ctx.Param("id")
  intId, _ := strconv.Atoi(id)
  user, _ := server.db.GetUser(intId)
  return ctx.JSON(true, "User fetched successfully", user, http.StatusOK)
}

Update User

go
func (server *Server) UpdateUser(ctx *falcon.Context) *falcon.Response {
  id := ctx.Param("id")
  intId, _ := strconv.Atoi(id)
  var request db.User
  ctx.Bind(&request)
  updatedUser, _ := server.db.UpdateUser(intId, request)
  return ctx.JSON(true, "User updated successfully!", updatedUser, http.StatusOK)
}

Delete User

go
func (server *Server) DeleteUser(ctx *falcon.Context) *falcon.Response {
  id := ctx.Param("id")
  intId, _ := strconv.Atoi(id)
  server.db.DeleteUser(intId)
  return ctx.JSON(true, "User deleted successfully!", nil, http.StatusOK)
}

Middleware

Use middleware for logging, authentication, and more:

go
app.Use(framework.Logger())

app.Use(func(next framework.HandlerFunc) framework.HandlerFunc {
  return func(c framework.Context) error {
    // before
    err := next(c)
    // after
    return err
  }
})

Constants

Falcon currently does not define any constants.

Variables

Falcon currently does not define any variables.

Functions

func NewTemplateRenderer

Encapsulates server.NewTemplateRenderer.

go
func NewTemplateRenderer(pattern string, devMode bool, funcs template.FuncMap) *server.TemplateRenderer
// Creates a new template renderer with optional development mode and custom functions

Types

type ConditionalMiddleware

Pairs a pattern (e.g. "/api/*") with a Middleware function.

go
type ConditionalMiddleware = middleware.ConditionalMiddleware
// Associates a URL pattern with a middleware function

type Context

Wraps the request and response writer and provides convenience methods (params, body parsing, etc.).

go
type Context = server.Context
// Provides methods for accessing request parameters, body, and writing responses

type Group

go
type Group struct {
  Prefix string
  Server *Server
  Middlewares []middleware.Middleware
}

Represents a collection of routes sharing a common prefix and middleware stack. Useful for organizing related endpoints like /api/v1/*.

type HandlerFunc

go
type HandlerFunc = server.HandlerFunc
// Function signature for route handlers: accepts *Context and returns *Response

type Middleware

go
type Middleware = middleware.Middleware
// Wraps and modifies a HandlerFunc

type Response

go
type Response = server.Response
// Unified return type from handlers, encoded as JSON

type Server

go
type Server struct {
  // internal fields
}

type TLSStarter

go
type TLSStarter interface {
  // startTLSServer method
}

type TemplateRenderer

go
type TemplateRenderer = server.TemplateRenderer
// Responsible for rendering HTML templates within Falcon

Server Methods

func New

go
func New() *Server
// Creates a new Falcon Server instance

func (*Server) GET / POST / PUT / PATCH / DELETE

go
func (s *Server) GET(path string, handler HandlerFunc)
func (s *Server) POST(path string, handler HandlerFunc)
func (s *Server) PUT(path string, handler HandlerFunc)
func (s *Server) PATCH(path string, handler HandlerFunc)
func (s *Server) DELETE(path string, handler HandlerFunc)
// Registers a route with the corresponding HTTP method

func (*Server) Group

go
func (s *Server) Group(prefix string) *Group
// Creates a route group with common prefix and middleware stack

func (*Server) Use / UseIf

go
func (s *Server) Use(mw Middleware)
func (s *Server) UseIf(pattern string, mw Middleware)
// Registers global or conditional middleware

func (*Server) ServeHTTP

go
func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)
// Implements http.Handler, executes the route handler, writes Response

func (*Server) Start / StartTLS / StartAutoTLS / StartAutoTLSWithStarter

go
func (s *Server) Start(addr string)
func (s *Server) StartTLS(addr, certFile, keyFile string)
func (s *Server) StartAutoTLS(domain string)
func (s *Server) StartAutoTLSWithStarter(domain string, starter TLSStarter)
// Starts the server with optional TLS or automatic Let's Encrypt support