HTTP Server Configuration

Table of Contents

1. Introduction
2. Project Structure
3. Core Components
4. Architecture Overview
5. Detailed Component Analysis
6. Dependency Analysis
7. Performance Considerations
8. Troubleshooting Guide
9. Conclusion

Introduction

This document provides a comprehensive guide for HTTP server configuration in the SPARROW project. The system is built on Go language and Gin Web framework, providing complete HTTP server configuration, CORS cross-origin support, security authentication mechanisms, and performance optimization configuration.

The system adopts modular design, manages various parameters of HTTP server through configuration-driven approach, including listening address, port number, timeout settings and other network configuration parameters. At the same time, integrates multiple security authentication mechanisms, such as JWT authentication, RBAC permission control and RSA client authentication.

Project Structure

The HTTP server configuration of SPARROW project is distributed in the following key directories:

Core Components

Server Configuration Structure

The system's core configuration structure consists of three main parts:

ServerConfig - Server Basic Configuration

• Host: Network address to listen on, default value is "0.0.0.0"
• Port: Listening port number, default value is 8080

CORSConfig - Cross-Origin Resource Sharing Configuration

• AllowOrigins: List of allowed origins, default "*" (allow all origins)
• AllowMethods: Allowed HTTP methods, default includes GET, POST, PUT, DELETE, OPTIONS
• AllowHeaders: Allowed request headers, default includes Origin, Content-Type, Accept, Authorization
• AllowCredentials: Whether to allow credentials, default true
• MaxAgeHours: Preflight request cache duration, default 1 hour

Complete Configuration Structure

The system integrates all configuration items through Config structure, including application configuration, server configuration, CORS configuration, logging configuration, database configuration, etc.

Configuration Loading Process

The configuration system is implemented using Viper library, supports multiple configuration file formats and environment variable override:

Architecture Overview

The overall architecture of HTTP server adopts layered design, each layer has clear responsibilities:

Detailed Component Analysis

HTTP Server Startup Process

The system manages the complete lifecycle of HTTP server through App structure:

Server Parameter Configuration

The key parameter configuration of HTTP server is as follows:

• Listening Address: Composed of Host and Port in configuration
• Read Timeout: 10 seconds
• Write Timeout: 10 seconds
• Maximum Request Header Size: 1MB (1 << 20 bytes)

Health Check Endpoint

The system provides built-in health check functionality:

CORS Configuration

The system provides flexible CORS configuration options, supports fine-grained cross-origin control:

CORS Configuration Details

Configuration Item	Default Value	Description
allow_origins	["*"]	List of allowed access origins
allow_methods	["GET","POST","PUT","DELETE","OPTIONS"]	Allowed HTTP methods
allow_headers	["Origin","Content-Type","Accept","Authorization"]	Allowed request headers
allow_credentials	true	Whether to allow credentials
max_age_hours	1	Preflight request cache duration (hours)

CORS Middleware Integration

Although CORS middleware usage is currently commented out in code, configuration structure fully supports CORS functionality. Can be enabled through the following way:

// Enable CORS middleware
app.Engine.Use(cors.New(cors.Config{
    AllowOrigins:     cfg.CORS.AllowOrigins,
    AllowMethods:     cfg.CORS.AllowMethods,
    AllowHeaders:     cfg.CORS.AllowHeaders,
    AllowCredentials: cfg.CORS.AllowCredentials,
    MaxAge:           time.Duration(cfg.CORS.MaxAgeHours) * time.Hour,
}))

Security Authentication Configuration

The system integrates multiple security authentication mechanisms, provides multi-level security protection:

JWT Authentication Middleware

JWT authentication middleware provides token-based authentication:

RBAC Permission Middleware

Casbin-based RBAC (Role-Based Access Control) permission middleware:

• Username Extraction: Obtained from context set by JWT middleware
• Resource Identification: Uses request URL path as resource identifier
• Operation Identification: Uses HTTP method as operation type
• Permission Check: Calls Casbin to execute permission verification

RSA Client Authentication

Provides RSA PSS signature-based client authentication:

Dependency Analysis

The system's dependency relationships present clear hierarchical structure:

Performance Considerations

Network Configuration Optimization

The system provides the following performance optimization configurations at HTTP server level:

Timeout Settings

• ReadTimeout: 10 seconds - Controls timeout for reading request body
• WriteTimeout: 10 seconds - Controls timeout for writing response
• MaxHeaderBytes: 1MB - Limits maximum size of request headers

Connection Management

• Keep-Alive: Gin engine supports HTTP/1.1 Keep-Alive by default
• Connection Reuse: Supports response compression through Gzip compression middleware

Buffer Configuration

The system controls request header buffer size through MaxHeaderBytes parameter, prevents memory abuse:

Optimization Recommendations

Based on existing configuration, the following optimization schemes can be considered:

1. Adjust Timeout According to Load

   • High latency network: Appropriately increase ReadTimeout and WriteTimeout
   • Large file upload: Increase MaxHeaderBytes and corresponding timeout settings

2. Enable Gzip Compression

   app.Engine.Use(gzip.Gzip(gzip.DefaultCompression))

3. Connection Pool Optimization

   • Database connection pool: Adjust according to concurrency requirements
   • Redis connection pool: Configure appropriate maximum connection count

Troubleshooting Guide

Common Configuration Issues

Port Conflict

Symptom: Server startup fails, shows port already in use Solution:

• Check Port value in configuration
• Confirm target port is not occupied by other services
• Modify server.port value in configuration file

CORS Configuration Issues

Symptom: Cross-origin requests blocked by browser Solution:

• Check if allow_origins configuration contains correct origins
• Verify allow_methods and allow_headers settings
• Confirm preflight request cache time setting is reasonable

Authentication Failure

Symptom: JWT authentication or RSA authentication returns 401 error Solution:

• Verify JWT secret key configuration
• Check RSA public key configuration and client signature
• Confirm timestamp and nonce validity

Server Startup Issues

Configuration Loading Failure

Symptom: Application prompts configuration loading error during startup Troubleshooting Steps:

1. Check configuration file format (YAML/JSON/TOML, etc.)
2. Verify environment variable naming rules
3. Confirm required configuration items exist

Graceful Shutdown Issues

Symptom: Server cannot shutdown normally Solution:

• Check subprocess graceful shutdown implementation
• Confirm signal handling mechanism works properly
• Verify resource cleanup logic

Conclusion

The HTTP server configuration of SPARROW project demonstrates best practices for modern web applications. The system provides solid foundation for building scalable enterprise applications through modular configuration design, flexible security authentication mechanisms, and comprehensive performance optimization strategies.

Main features include:

• Configuration Driven: Flexible configuration management through Viper
• Security First: Integrated multiple authentication mechanisms, provides multi-level security protection
• Performance Optimized: Reasonable timeout settings and buffer configuration
• Easy to Maintain: Clear code structure and detailed documentation

Recommend adjusting configuration parameters according to specific requirements in production environment, and regularly review security settings to adapt to constantly changing security threat environment.