flamingo

README

Flamingo Framework

Flamingo is a web framework based on Go.
It is designed to build pluggable and maintainable web projects. It is production ready, field tested and has a growing ecosystem.

Quick start

See "examples/hello-world"

Initialize an empty project:

mkdir helloworld
cd helloworld
go mod init helloworld

Create your project main file:

cat main.go

package main

import (
	"flamingo.me/dingo"
	"flamingo.me/flamingo/v3"
)

func main() {
	flamingo.App([]dingo.Module{
	})
}

If you then start your project you will see a list of registered commands:

go run main.go

It will print something like:

Flamingo main

Usage:
  main [command]

Examples:
Run with -h or -help to see global debug flags

Available Commands:
  config      Config dump
  handler     Dump the Handlers and its registered methods
  help        Help about any command
  routes      Routes dump
  serve       Default serve command - starts on Port 3322

Flags:
  -h, --help   help for main

Use "main [command] --help" for more information about a command.

To start the server use the following sub command:

go run main.go serve

And open http://localhost:3322

Hello World Example:

To extend this empty flamingo project with a "Hello World" output please create a new module "helloworld" like this:

mkdir helloworld
cat helloworld/module.go

With the following code in module.go:

package helloworld

import (
        "context"
        "net/http"
        "strings"
        
        "flamingo.me/dingo"
        "flamingo.me/flamingo/v3/framework/web"
)

type Module struct{}

func (*Module) Configure(injector *dingo.Injector) {
        web.BindRoutes(injector, new(routes))
}

type routes struct{}

func (*routes) Routes(registry *web.RouterRegistry) {
        registry.Route("/", "home")
        registry.HandleAny("home", indexHandler)
}

func indexHandler(ctx context.Context, req *web.Request) web.Result {
        return &web.Response{
            Status: http.StatusOK,
            Body:   strings.NewReader("Hello World!"),
        }
}

This file now defines a very simple module, that can be used in the Flamingo bootstrap. In this case it registers a new handler that renders a simple "Hello World" message and binds the route "/" to this handler. Now please include this new module in your existing main.go file:

package main

import (
	"flamingo.me/dingo"
	"flamingo.me/flamingo/v3"
	"helloworld/helloworld"
)

func main() {
	flamingo.App([]dingo.Module{
        new(helloworld.Module),
	})
}

If you now run the server again

go run main.go serve

And open http://localhost:3322 you will see your "Hello World!" output.

Getting started

To learn more about Flamingo you can check out the full hello-world example tutorial and read the documentation under docs.flamingo.me

Getting Help

The best way to ask a question is the #flamingo channel on gophers.slack.com

If you are not yet in the Gophers slack, get your invitation here: https://invite.slack.golangbridge.org/

Other ways are:

• Ask in stackoverflow (we try to keep track of new questions)
• Write us an email: flamingo@aoe.com
• Open an issue in github for bugs and feature requests

Framework Details

Feature List

• dependency injection with Dingo
• Flexible templating engines. (gotemplates and pugtemplates)
• configuration concepts using cue with support for multiple config areas and additional config contexts
• A module concept for building modular and pluggable applications based on Dingo
• Authentication concepts and security middleware
• Flexible routing with support for prefix routes and reverse routing
• Web controller concept with request/response abstraction; form handling etc
• Operational readiness: logging, (distributed) tracing, metrics and healthchecks with separate endpoint
• Localisation support
• Commands using Cobra
• Event handling
• Sessionhandling and Management (By default uses Gorilla)

Ecosystem

• GraphQL Module (and therefore support to build SPA and PWAs on top of it)
• Caching modules providing resilience and caching for external APIs calls.
• pugtemplate template engine for server side rendering with the related frontend tooling Flamingo Carotene
• Flamingo Commerce is an active projects that offer rich and flexible features to build modern e-commerce applications.

Documentation

Index

• Constants
• Variables
• func App(modules []dingo.Module, options ...ApplicationOption)
• type Application
  • func NewApplication(modules []dingo.Module, options ...ApplicationOption) (*Application, error)
  • func (app *Application) ConfigArea() *config.Area
  • func (app *Application) Run() error
• type ApplicationOption
  • func ChildAreas(areas ...*config.Area) ApplicationOption
  • func ConfigDir(configdir string) ApplicationOption
  • func DefaultContext(name string) ApplicationOption
  • func SetEagerSingletons(enabled bool) ApplicationOption
  • func WithArgs(args ...string) ApplicationOption
  • func WithCustomLogger(logger dingo.Module) ApplicationOption
  • func WithRoutes(routesModule web.RoutesModule) ApplicationOption

Constants

const (
	// FailedShutdownExitCode is returned when application cannot accomplish graceful shutdown
	FailedShutdownExitCode = 130

	// ServerReadHeaderTimeout default timeout to read incoming request headers
	ServerReadHeaderTimeout = 10 * time.Second
)

Variables

var (
	// ErrAppRun is returned when an error occurs during app.Run()
	ErrAppRun = errors.New("app run error")
)

Functions

func App

func App(modules []dingo.Module, options ...ApplicationOption)

App is the default app-runner for flamingo

Types

type Application

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

Application contains a main flamingo application

func NewApplication

func NewApplication(modules []dingo.Module, options ...ApplicationOption) (*Application, error)

NewApplication loads a new application for running the Flamingo application with the given modules, loaded configs etc

func (*Application) ConfigArea

func (app *Application) ConfigArea() *config.Area

ConfigArea returns the initialized configuration area

func (*Application) Run

func (app *Application) Run() error

Run runs the Root Cmd and triggers the standard event

type ApplicationOption

type ApplicationOption func(config *Application)

ApplicationOption configures an Application

func ChildAreas

func ChildAreas(areas ...*config.Area) ApplicationOption

ChildAreas allows to define additional config areas for roots

func ConfigDir

func ConfigDir(configdir string) ApplicationOption

ConfigDir configuration ApplicationOption

func DefaultContext

func DefaultContext(name string) ApplicationOption

DefaultContext for flamingo to start with

func SetEagerSingletons

func SetEagerSingletons(enabled bool) ApplicationOption

SetEagerSingletons controls if eager singletons will be created

func WithArgs

func WithArgs(args ...string) ApplicationOption

WithArgs sets the initial arguments different from os.Args[1:]

func WithCustomLogger

func WithCustomLogger(logger dingo.Module) ApplicationOption

WithCustomLogger allows to use custom logger modules for flamingo app, if nothing available default will be used

func WithRoutes

func WithRoutes(routesModule web.RoutesModule) ApplicationOption

WithRoutes configures a given RoutesModule for usage in the flamingo app