Extensions

Explore Forge's powerful extension system and available extensions

Extensions

Forge's extension system provides a powerful way to add functionality to your application. Extensions are first-party, trusted components that integrate seamlessly with the framework and provide enterprise-grade features.

Extension System Overview

Extensions in Forge are:

  • First-party: Built and maintained by the Forge team
  • Trusted: Full access to framework internals
  • Integrated: Seamless integration with DI, health checks, and observability
  • Production-ready: Battle-tested in production environments

Extension Interface

All extensions implement the Extension interface:

type Extension interface {
    // Basic information
    Name() string
    Version() string
    Description() string
    
    // Lifecycle management
    Register(app App) error
    Start(ctx context.Context) error
    Stop(ctx context.Context) error
    Health(ctx context.Context) error
    
    // Dependencies
    Dependencies() []string
}

Available Extensions

Core Extensions

Auth Extension

import "github.com/xraph/forge/extensions/auth"

app.RegisterExtension(auth.NewExtension(auth.WithJWTProvider(jwtConfig)))

Cache Extension

import "github.com/xraph/forge/extensions/cache"

app.RegisterExtension(cache.NewExtension(cache.WithDriver("redis")))

Database Extension

import "github.com/xraph/forge/extensions/database"

app.RegisterExtension(database.NewExtension(database.WithDriver("postgres")))

Storage Extension

import "github.com/xraph/forge/extensions/storage"

app.RegisterExtension(storage.NewExtension(storage.WithDriver("s3")))

AI Extensions

AI Extension

import "github.com/xraph/forge/extensions/ai"

app.RegisterExtension(ai.NewExtension(ai.WithLLMProvider("openai")))

MCP Extension

import "github.com/xraph/forge/extensions/mcp"

app.RegisterExtension(mcp.NewExtension(mcp.WithServer("localhost:8080")))

Infrastructure Extensions

Events Extension

import "github.com/xraph/forge/extensions/events"

app.RegisterExtension(events.NewExtension(events.WithBroker("kafka")))

Queue Extension

import "github.com/xraph/forge/extensions/queue"

app.RegisterExtension(queue.NewExtension(queue.WithDriver("redis")))

Search Extension

import "github.com/xraph/forge/extensions/search"

app.RegisterExtension(search.NewExtension(search.WithDriver("elasticsearch")))

Consensus Extension

import "github.com/xraph/forge/extensions/consensus"

app.RegisterExtension(consensus.NewExtension(consensus.WithRaft()))

Communication Extensions

GraphQL Extension

import "github.com/xraph/forge/extensions/graphql"

app.RegisterExtension(graphql.NewExtension(graphql.WithEndpoint("/graphql")))

gRPC Extension

import "github.com/xraph/forge/extensions/grpc"

app.RegisterExtension(grpc.NewExtension(grpc.WithAddress(":50051")))

WebRTC Extension

import "github.com/xraph/forge/extensions/webrtc"

app.RegisterExtension(webrtc.NewExtension(webrtc.WithSignalingServer()))

Streaming Extension

import "github.com/xraph/forge/extensions/streaming"

app.RegisterExtension(streaming.NewExtension(streaming.WithHLS()))

Extension Lifecycle

Registration Phase

func (ext *MyExtension) Register(app App) error {
    // Register services with DI container
    app.RegisterService("myService", func(container Container) (interface{}, error) {
        return &MyService{}, nil
    })
    
    // Register health checks
    app.HealthManager().Register("myExtension", ext.healthCheck)
    
    // Register routes
    app.Router().GET("/my-endpoint", ext.handleRequest)
    
    return nil
}

Startup Phase

func (ext *MyExtension) Start(ctx context.Context) error {
    // Initialize resources
    if err := ext.initialize(); err != nil {
        return err
    }
    
    // Start background services
    go ext.startBackgroundService(ctx)
    
    return nil
}

Health Check Phase

func (ext *MyExtension) Health(ctx context.Context) error {
    // Check extension health
    if err := ext.checkHealth(); err != nil {
        return err
    }
    
    return nil
}

Shutdown Phase

func (ext *MyExtension) Stop(ctx context.Context) error {
    // Stop background services
    ext.stopBackgroundService()
    
    // Cleanup resources
    if err := ext.cleanup(); err != nil {
        return err
    }
    
    return nil
}

Extension Configuration

Configuration Sources

Extensions can be configured through multiple sources:

// Programmatic configuration
app.RegisterExtension(auth.NewExtension(
    auth.WithJWTProvider(jwtConfig),
    auth.WithAPIKeyProvider(apiKeyConfig),
))

// Configuration file
app.RegisterExtension(auth.NewExtension())

// Environment variables
app.RegisterExtension(auth.NewExtension())

Configuration File

# config.yaml
extensions:
  auth:
    providers:
      jwt:
        secret: ${JWT_SECRET}
        expires_in: 3600
      api_key:
        header: X-API-Key
        keys:
          - ${API_KEY_1}
          - ${API_KEY_2}
  
  database:
    driver: postgres
    host: ${DB_HOST}
    port: ${DB_PORT}
    name: ${DB_NAME}
    user: ${DB_USER}
    password: ${DB_PASSWORD}
  
  cache:
    driver: redis
    host: ${REDIS_HOST}
    port: ${REDIS_PORT}
    password: ${REDIS_PASSWORD}

Extension Development

Creating a Custom Extension

package myextension

import (
    "context"
    "github.com/xraph/forge"
)

type MyExtension struct {
    config *Config
    service *MyService
}

func NewExtension(opts ...Option) forge.Extension {
    config := &Config{}
    for _, opt := range opts {
        opt(config)
    }
    
    return &MyExtension{
        config: config,
    }
}

func (ext *MyExtension) Name() string {
    return "my-extension"
}

func (ext *MyExtension) Version() string {
    return "1.0.0"
}

func (ext *MyExtension) Description() string {
    return "My custom extension"
}

func (ext *MyExtension) Register(app forge.App) error {
    // Register services
    app.RegisterService("myService", func(container forge.Container) (interface{}, error) {
        return &MyService{config: ext.config}, nil
    })
    
    return nil
}

func (ext *MyExtension) Start(ctx context.Context) error {
    // Start the extension
    return nil
}

func (ext *MyExtension) Stop(ctx context.Context) error {
    // Stop the extension
    return nil
}

func (ext *MyExtension) Health(ctx context.Context) error {
    // Check health
    return nil
}

func (ext *MyExtension) Dependencies() []string {
    return []string{"database", "cache"}
}

Extension Options

type Option func(*Config)

func WithDriver(driver string) Option {
    return func(c *Config) {
        c.Driver = driver
    }
}

func WithHost(host string) Option {
    return func(c *Config) {
        c.Host = host
    }
}

func WithPort(port int) Option {
    return func(c *Config) {
        c.Port = port
    }
}

Extension Testing

Unit Testing

func TestMyExtension(t *testing.T) {
    app := forge.NewTestApp(forge.TestAppConfig{
        Name: "test-app",
    })
    
    // Register extension
    ext := NewExtension(WithDriver("test"))
    err := app.RegisterExtension(ext)
    require.NoError(t, err)
    
    // Test extension
    err = ext.Start(context.Background())
    require.NoError(t, err)
    
    // Test health
    err = ext.Health(context.Background())
    require.NoError(t, err)
    
    // Test stop
    err = ext.Stop(context.Background())
    require.NoError(t, err)
}

Integration Testing

func TestMyExtensionIntegration(t *testing.T) {
    app := forge.NewTestApp(forge.TestAppConfig{
        Name: "test-app",
    })
    
    // Register extension
    ext := NewExtension(WithDriver("test"))
    err := app.RegisterExtension(ext)
    require.NoError(t, err)
    
    // Start application
    go func() {
        app.Run()
    }()
    defer app.Stop(context.Background())
    
    // Test extension endpoints
    resp, err := http.Get("http://localhost:8080/my-endpoint")
    require.NoError(t, err)
    defer resp.Body.Close()
    
    assert.Equal(t, 200, resp.StatusCode)
}

Extension Best Practices

Design Principles

  1. Single Responsibility: Each extension should have a single, well-defined purpose
  2. Interface-Based: Use interfaces for better testability
  3. Configuration: Support multiple configuration sources
  4. Error Handling: Handle errors gracefully
  5. Observability: Include metrics, logging, and health checks
  6. Testing: Write comprehensive tests
  7. Documentation: Document extension usage and configuration

Performance Considerations

  1. Lazy Loading: Initialize resources only when needed
  2. Connection Pooling: Use connection pooling for external services
  3. Caching: Implement appropriate caching strategies
  4. Resource Management: Properly manage resources and cleanup
  5. Concurrency: Design for concurrent access

Security Considerations

  1. Input Validation: Validate all inputs
  2. Authentication: Integrate with authentication system
  3. Authorization: Implement proper authorization
  4. Secrets Management: Handle secrets securely
  5. Audit Logging: Log security-relevant events

Extension Registry

Built-in Extensions

ExtensionDescriptionStatus
authAuthentication and authorization✅ Complete
cacheCaching with multiple backends✅ Complete
databaseDatabase access and ORM✅ Complete
storageFile storage with multiple backends✅ Complete
aiAI and LLM integration✅ Complete
mcpModel Context Protocol✅ Complete
eventsEvent-driven architecture✅ Complete
queueMessage queuing✅ Complete
searchFull-text search✅ Complete
consensusDistributed consensus✅ Complete
graphqlGraphQL server✅ Complete
grpcgRPC services✅ Complete
webrtcWebRTC communication✅ Complete
streamingMedia streaming✅ Complete
hlsHTTP Live Streaming✅ Complete
kafkaApache Kafka integration✅ Complete
mqttMQTT broker✅ Complete
orpcOpenRPC support✅ Complete
dashboardWeb dashboard✅ Complete

Extension Status

  • ✅ Complete: Production-ready with full functionality
  • 🔄 In Progress: Under active development
  • 📋 Planned: Planned for future releases

Getting Started with Extensions

Quick Start

package main

import (
    "github.com/xraph/forge"
    "github.com/xraph/forge/extensions/auth"
    "github.com/xraph/forge/extensions/database"
    "github.com/xraph/forge/extensions/cache"
)

func main() {
    app := forge.NewApp(forge.DefaultAppConfig())
    
    // Register extensions
    app.RegisterExtension(auth.NewExtension())
    app.RegisterExtension(database.NewExtension())
    app.RegisterExtension(cache.NewExtension())
    
    // Run application
    app.Run()
}

Configuration

# config.yaml
extensions:
  auth:
    providers:
      jwt:
        secret: ${JWT_SECRET}
  
  database:
    driver: postgres
    url: ${DATABASE_URL}
  
  cache:
    driver: redis
    url: ${REDIS_URL}

For more information about specific extensions, see the individual extension documentation pages.

How is this guide?

Last updated on

Observability

Comprehensive observability with logging, metrics, tracing, and health checks

Introduction

Comprehensive HTTP routing system with advanced features

On this page

Extensions
Extension System Overview
Extension Interface
Available Extensions
Core Extensions
AI Extensions
Infrastructure Extensions
Communication Extensions
Extension Lifecycle
Registration Phase
Startup Phase
Health Check Phase
Shutdown Phase
Extension Configuration
Configuration Sources
Configuration File
Extension Development
Creating a Custom Extension
Extension Options
Extension Testing
Unit Testing
Integration Testing
Extension Best Practices
Design Principles
Performance Considerations
Security Considerations
Extension Registry
Built-in Extensions
Extension Status
Getting Started with Extensions
Quick Start
Configuration