DOCSEARCHbyAlgolia
Submit Docs

Flamingo Web Framework Documentation

repository·master·Indexed 20 days ago

https://github.com/i-love-flamingo/flamingo

A modular, production-ready web framework for Go designed for pluggable and maintainable projects using dependency injection. Features include a flexible authentication system with brokers and identities, a two-tier caching architecture with HTTPFrontend, structured templating via Gotemplate, and built-in modules for healthchecks, locale management, and static asset serving.

Tokens
27.9K
Snippets
87
Records
129
Agent score
69%

What's inside Flamingo

  2. Compare Flamingo with other Go frameworks

    master

    Flamingo is designed for building pluggable and maintainable web applications, distinguishing itself from other Go frameworks (like Gin, Gobuffalo, Beego, and Revel) through several core architectural concepts.

    Key differentiators where Flamingo provides unique or advanced support include:

    • Modular Architecture: Strong support for a Module concept and Configuration Areas.
    • Advanced Routing: Supports both Reverse Routing and Prefix Routing.
    • Dependency Injection: Includes advanced DI features like MapBinding, MultiBinding, and Overrides.
    • Observability: Built-in support for Tracing and Metrics.
    • API Capabilities: Native support for GraphQL and a generic Authentication concept.
    • Application Lifecycle: Includes Event Handling and a robust Session management system.
    • Resilience: Integrated support for Resilience and Caching.

  3. Core features of Flamingo Framework

    master

    Flamingo is a modular web framework for Go with the following core capabilities:

    • Dependency Injection: Powered by Dingo.
    • Modular Architecture: Uses a module concept for building pluggable applications.
    • Routing: Flexible routing with support for prefix routes and reverse routing.
    • Web Abstractions: Web controller concept with request/response abstraction and form handling.
    • Templating: Supports multiple engines including gotemplates and pugtemplates.
    • Configuration: Uses cue with support for multiple config areas and contexts.
    • Security: Includes authentication concepts and security middleware.
    • Operational Readiness: Built-in logging, (distributed) tracing, metrics, and healthchecks.
    • Session Management: Uses Gorilla by default.
    • CLI: Commands are implemented using Cobra.
    • Other: Event handling, localization support, and GraphQL support.

  4. Use the Fake Auth Module for local development

    master

    The Fake Auth Module provides a way to simulate a login service without requiring a real Identity Provider (IDP). It allows you to define configurable user credentials and provides a customizable login form.

    When configuring the module, you must provide a unique broker ID for each instance.

  5. General usage of Opencensus in Flamingo

    master

    Opencensus in Flamingo allows for data collection (metrics and traces) that can be processed by tools like Prometheus or Jaeger.

    By default, the framework automatically collects:

    • Metrics for routers and prefixrouters (rendering times).
    • Traces for request handling.

    Once the module is activated, the metrics endpoint is available via the systemendpoint at http://localhost:13210/metrics.

  7. Understand the configuration loading priority

    master

    When the same configuration key is defined in multiple places, Flamingo uses the value from the last loaded source. The priority order (from lowest to highest) is:

    1. Files in config/ directory (config.yml, routes.yml, context files, _local.yml files).
    2. Files specified in the CONTEXTFILE environment variable.
    3. Values provided via the --flamingo-config CLI flag.

  8. Implement a custom session backend

    master

    You can provide a custom session store by implementing the gorilla.sessions.Store interface. There are two ways to integrate it:

    1. Replace flamingo.SessionModule: Replace the default module and bind your implementation to the session.Store interface via dingo.
    2. Provide a flamingo.CustomSessionBackend: If you cannot replace the default module (e.g., because other modules depend on it), implement the flamingo.CustomSessionBackend interface and bind it using: injector.Bind(new(flamingo.CustomSessionBackend)).To(new(CustomStoreBackend))

    To provide a health check for your custom backend, bind it to the session key using .To or .ToInstance for healthcheck.Status.

    injector.BindMap(new(healthcheck.Status), "session").To(new(db.Health))

  9. Trigger authentication with WebAuthenticator

    master

    If a WebIdentifier also implements the authenticator interface, it becomes a WebAuthenticator. This allows the framework to trigger the authentication flow, which can involve:

    • Redirecting the user to an external page.
    • Setting specific HTTP headers.
    • Presenting a login form.

  10. About the Flamingo root command

    master

    The Flamingo root command is a *cobra.Command annotated with flamingo. It serves as the entry point for the Flamingo CLI and is typically used by the default Flamingo bootstrap.

    By default, a standard Flamingo project provides the following commands:

    • config: Config dump
    • help: Help about any command
    • serve: Default serve command (starts on Port 3322)

  11. Organize a Flamingo module using Ports and Adapters

    master

    Flamingo modules should be organized around a clear bounded context with minimal dependencies on other modules. The recommended directory structure follows the Ports and Adapters architecture to separate business logic from external technologies:

    • module.go: The mandatory entry point for the Flamingo module.
    • domain/: Contains technology-free domain logic and secondary ports.
    • application/: Contains the main module use cases, serving as the primary "API" for programmers.
    • interfaces/: Contains interfaces to the outside world, subdivided into:
      • controller/: Web and data controllers.
      • templatefunctions/: Custom template functions.
    • infrastructure/: Contains the implementation of secondary ports (e.g., an adapter for an external microservice).
    moduleName
│   module.go (The entry for a Flamingo module)
│   README.md (The full documentation)
│
└───domain (technology free domain logic with secondary ports)      
│   
└───application (main modules use cases / programmers "API")
│
└───interfaces (interfaces to the outside)
│   └───controller (web and data controllers)
│   └───templatefunctions (templatefunctions)
│
└───infrastructure (implementation of secondary ports)
│   └───adapterExample.go (e.g. an adapter to an external microservice)

  12. Understand Flamingo Bootstrap and Configuration Areas

    master

    The Flamingo Bootstrap manages the application lifecycle, including defining configuration areas, loading default and overriding configurations, configuring dingo dependency injection, registering handlers, and executing the root command (e.g., the serve command to start a server and router).

    Configuration Areas

    Projects can define multiple Configuration Areas, which form a tree structure.

    • Inheritance: Children in the tree inherit most configurations and modules from their parents.
    • Structure: Each area has a name, a list of modules to load, and optional child config areas.
    • Use Case: This is primarily used to manage different websites, channels, or locales. For example, when used with the prefixrouter module, the router can detect the URL prefix to select the correct configuration area.