HTTP Service Mechanism

Monibuca provides comprehensive HTTP service support, including RESTful API, WebSocket, HTTP-FLV, and other protocols. This document details the implementation mechanism and usage of the HTTP service.

HTTP Configuration

1. Configuration Priority

• Plugin HTTP configuration takes precedence over global HTTP configuration
• If a plugin doesn't have HTTP configuration, global HTTP configuration is used

2. Configuration Items

# Global configuration example
global:
  http:
    listenaddr: :8080  # Listen address and port
    listentlsaddr: :8081 # TLS listen address and port
    certfile: ""       # SSL certificate file path
    keyfile: ""        # SSL key file path
    cors: true        # Whether to allow CORS
    username: ""      # Basic auth username
    password: ""      # Basic auth password

# Plugin configuration example (takes precedence over global config)
plugin_name:
  http:
    listenaddr: :8081
    cors: false
    username: "admin"
    password: "123456"

Service Processing Flow

1. Request Processing Order

When the HTTP server receives a request, it processes it in the following order:

1. First attempts to forward to the corresponding gRPC service
2. If no corresponding gRPC service is found, looks for plugin-registered HTTP handlers
3. If nothing is found, returns a 404 error

2. Handler Registration Methods

Plugins can register HTTP handlers in two ways:

1. Reflection Registration: The system automatically obtains plugin handling methods through reflection

   • Method names must start with uppercase to be reflected (Go language rule)
   • Usually use API_ as method name prefix (recommended but not mandatory)
   • Method signature must be func(w http.ResponseWriter, r *http.Request)
   • URL path auto-generation rules:
     • Underscores _ in method names are converted to slashes /
     • Example: API_relay_ method maps to /API/relay/* path
   • If a method name ends with underscore, it indicates a wildcard path that matches any subsequent path

2. Manual Registration: Plugin implements IRegisterHandler interface for manual registration

   • Lowercase methods can't be reflected, must be registered manually
   • Manual registration can use path parameters (like :id)
   • More flexible routing rule configuration

Example code:

// Reflection registration example
type YourPlugin struct {
    // ...
}

// Uppercase start, can be reflected
// Automatically maps to /API/relay/*
func (p *YourPlugin) API_relay_(w http.ResponseWriter, r *http.Request) {
    // Handle wildcard path requests
}

// Lowercase start, can't be reflected, needs manual registration
func (p *YourPlugin) handleUserRequest(w http.ResponseWriter, r *http.Request) {
    // Handle parameterized requests
}

// Manual registration example
func (p *YourPlugin) RegisterHandler() {
    // Can use path parameters
    engine.GET("/api/user/:id", p.handleUserRequest)
}

Middleware Mechanism

1. Adding Middleware

Plugins can add global middleware using the AddMiddleware method to handle all HTTP requests. Middleware executes in the order it was added.

Example code:

func (p *YourPlugin) OnInit() {
    // Add authentication middleware
    p.GetCommonConf().AddMiddleware(func(next http.HandlerFunc) http.HandlerFunc {
        return func(w http.ResponseWriter, r *http.Request) {
            // Execute before request handling
            if !authenticate(r) {
                http.Error(w, "Unauthorized", http.StatusUnauthorized)
                return
            }
            // Call next handler
            next(w, r)
            // Execute after request handling
        }
    })
}

2. Middleware Use Cases

• Authentication and Authorization
• Request Logging
• CORS Handling
• Request Rate Limiting
• Response Header Setting
• Error Handling
• Performance Monitoring

Special Protocol Support

1. HTTP-FLV

• Supports HTTP-FLV live stream distribution
• Automatically generates FLV headers
• Supports GOP caching
• Supports WebSocket-FLV

2. HTTP-MP4

• Supports HTTP-MP4 stream distribution
• Supports fMP4 file distribution

3. HLS

• Supports HLS protocol
• Supports MPEG-TS encapsulation

4. WebSocket

• Supports custom message protocols
• Supports ws-flv
• Supports ws-mp4