commonuseragent

README

Common User Agent Library

A secure, production-ready Go library and demo application for managing user agent strings with comprehensive security features, input validation, and a practical web-based test harness.

Features

Core Library

• Cryptographically Secure Random Selection - Uses crypto/rand instead of math/rand
• Thread-Safe Operations - All operations are protected with proper synchronization
• Comprehensive Input Validation - Validates all user agent data with strict rules
• Proper Error Handling - No panics, all errors are returned and handled gracefully
• Zero External Dependencies - Core library has no external dependencies

Demo Application

• Web-Based GUI - Interactive test harness for API testing and configuration
• SQLite Database - Tracks user agent requests with full history
• Parameterized Queries - 100% protection against SQL injection
• Environment-Based Configuration - Secure configuration via environment variables
• Rate Limiting - Built-in protection against abuse
• Input Sanitization - All inputs are validated and sanitized
• Secure Error Messages - No internal information leakage
• Docker Support - Production-ready containerization

Security Features

✅ No SQL Injection - All database queries use parameterized statements ✅ Crypto-Secure Random - Uses crypto/rand for unpredictable randomness ✅ Input Validation - Strict validation on all inputs with length limits ✅ Error Sanitization - No sensitive information in error messages ✅ Rate Limiting - Configurable request rate limits ✅ Security Headers - CSP, X-Frame-Options, X-Content-Type-Options ✅ Non-Root Container - Docker runs as unprivileged user ✅ Resource Limits - CPU and memory constraints ✅ Health Checks - Built-in health monitoring

Installation

Library Only

go get github.com/baditaflorin/commonuseragent

Full Development Environment

git clone https://github.com/baditaflorin/commonuseragent.git
cd commonuseragent
make deps
make build

Quick Start

Using the Library

package main

import (
    "fmt"
    "log"

    "github.com/baditaflorin/commonuseragent"
)

func main() {
    // Get a random desktop user agent
    ua, err := commonuseragent.GetRandomDesktopUA()
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println("Desktop UA:", ua)

    // Get a random mobile user agent
    mobileUA, err := commonuseragent.GetRandomMobileUA()
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println("Mobile UA:", mobileUA)

    // Get any random user agent
    randomUA, err := commonuseragent.GetRandomUA()
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println("Random UA:", randomUA)

    // Get all desktop user agents
    allDesktop, err := commonuseragent.GetAllDesktop()
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Total desktop agents: %d\n", len(allDesktop))
}

Running the Demo Application

# Using Make
make run-demo-dev

# Using Go directly
go run ./cmd/demo

# Using Docker
docker-compose up

# Or with custom configuration
SERVER_PORT=9000 DB_PATH=./custom.db go run ./cmd/demo

Access the web interface at: http://localhost:8080

Configuration

The demo application is configured entirely through environment variables. See .env.example for all options.

Key Configuration Variables

Variable	Default	Description
SERVER_PORT	8080	Server port
DB_PATH	./useragent.db	SQLite database path
APP_ENV	development	Environment (development, staging, production)
MAX_REQUESTS_PER_MINUTE	100	Rate limit per IP

See full configuration documentation in CONFIGURATION.md

API Endpoints

User Agent Endpoints

• GET /api/desktop - Get random desktop user agent
• GET /api/mobile - Get random mobile user agent
• GET /api/random - Get random user agent (any type)
• GET /api/all/desktop - Get all desktop user agents
• GET /api/all/mobile - Get all mobile user agents

Monitoring Endpoints

• GET /api/logs?limit=N - Get recent requests (max 1000)
• GET /api/stats - Get aggregated statistics
• GET /api/health - Health check endpoint

Example Response

{
  "success": true,
  "data": {
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36...",
    "type": "desktop"
  }
}

Development

Building

make build          # Build library
make build-demo     # Build demo application
make all            # Build everything

Testing

make test           # Run tests
make test-race      # Run tests with race detector
make test-coverage  # Run tests with coverage
make bench          # Run benchmarks

Code Quality

make fmt            # Format code
make lint           # Run linter
make security-scan  # Run security scanner
make check          # Run all checks

Docker Deployment

# Using Docker Compose (Recommended)
docker-compose up -d

# Using Docker directly
docker build -t commonuseragent:latest .
docker run -p 8080:8080 commonuseragent:latest

Security

See SECURITY.md for security best practices, vulnerability reporting, and security architecture details.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

UserAgent data comes from https://useragents.me/

This project is licensed under the MIT License - see the LICENSE file for details.

Changelog

v2.0.0 (Latest)

Breaking Changes:

• All API functions now return errors instead of panicking
• Thread-safe Manager pattern introduced

Security Improvements:

• ✅ Replaced math/rand with crypto/rand
• ✅ Added comprehensive input validation
• ✅ Implemented parameterized SQL queries
• ✅ Added error sanitization
• ✅ Thread-safety with proper locking

New Features:

• Web-based test harness and GUI
• SQLite request logging with analytics
• Environment-based configuration
• Rate limiting and security headers
• Docker support with non-root execution
• Comprehensive test suite (78%+ coverage)

See CHANGELOG.md for full version history.

Documentation

Index

• Variables
• func GetInitError() error
• func GetRandomDesktopUA() (string, error)
• func GetRandomMobileUA() (string, error)
• func GetRandomUA() (string, error)
• type Config
  • func DefaultConfig() Config
• type Manager
  • func NewManager(cfg Config) (*Manager, error)
  • func (m *Manager) GetAllDesktop() []UserAgent
  • func (m *Manager) GetAllMobile() []UserAgent
  • func (m *Manager) GetRandomDesktop() (UserAgent, error)
  • func (m *Manager) GetRandomDesktopUA() (string, error)
  • func (m *Manager) GetRandomMobile() (UserAgent, error)
  • func (m *Manager) GetRandomMobileUA() (string, error)
  • func (m *Manager) GetRandomUA() (string, error)
• type UserAgent
  • func GetAllDesktop() ([]UserAgent, error)
  • func GetAllMobile() ([]UserAgent, error)
  • func GetRandomDesktop() (UserAgent, error)
  • func GetRandomMobile() (UserAgent, error)

Variables

var (
	// ErrEmptyAgentList is returned when trying to get a random agent from an empty list
	ErrEmptyAgentList = errors.New("agent list is empty")
	// ErrInvalidData is returned when user agent data is invalid
	ErrInvalidData = errors.New("invalid user agent data")
	// ErrFileNotFound is returned when the embedded file cannot be found
	ErrFileNotFound = errors.New("embedded file not found")
)

Functions

func GetInitError

func GetInitError() error

GetInitError returns any error that occurred during initialization

func GetRandomDesktopUA

func GetRandomDesktopUA() (string, error)

GetRandomDesktopUA returns just the UA string of a random desktop user agent using the default manager

func GetRandomMobileUA

func GetRandomMobileUA() (string, error)

GetRandomMobileUA returns just the UA string of a random mobile user agent using the default manager

func GetRandomUA

func GetRandomUA() (string, error)

GetRandomUA returns a random user agent string from either desktop or mobile using the default manager

Types

type Config

type Config struct {
	DesktopFile string
	MobileFile  string
}

Config holds runtime configuration for the user agent library

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns the default configuration

type Manager

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

Manager handles user agent data with thread-safe operations

func NewManager

func NewManager(cfg Config) (*Manager, error)

NewManager creates a new Manager with the given configuration

func (*Manager) GetAllDesktop

func (m *Manager) GetAllDesktop() []UserAgent

GetAllDesktop returns a copy of all desktop user agents

func (*Manager) GetAllMobile

func (m *Manager) GetAllMobile() []UserAgent

GetAllMobile returns a copy of all mobile user agents

func (*Manager) GetRandomDesktop

func (m *Manager) GetRandomDesktop() (UserAgent, error)

GetRandomDesktop returns a random desktop UserAgent using weighted random selection

func (*Manager) GetRandomDesktopUA

func (m *Manager) GetRandomDesktopUA() (string, error)

GetRandomDesktopUA returns just the UA string of a random desktop user agent

func (*Manager) GetRandomMobile

func (m *Manager) GetRandomMobile() (UserAgent, error)

GetRandomMobile returns a random mobile UserAgent using weighted random selection

func (*Manager) GetRandomMobileUA

func (m *Manager) GetRandomMobileUA() (string, error)

GetRandomMobileUA returns just the UA string of a random mobile user agent

func (*Manager) GetRandomUA

func (m *Manager) GetRandomUA() (string, error)

GetRandomUA returns a random user agent string from either desktop or mobile

type UserAgent

type UserAgent struct {
	UA  string  `json:"ua"`
	Pct float64 `json:"pct"`
}

UserAgent represents a user agent string with its usage percentage

func GetAllDesktop

func GetAllDesktop() ([]UserAgent, error)

GetAllDesktop returns all desktop user agents using the default manager

func GetAllMobile

func GetAllMobile() ([]UserAgent, error)

GetAllMobile returns all mobile user agents using the default manager

func GetRandomDesktop

func GetRandomDesktop() (UserAgent, error)

GetRandomDesktop returns a random desktop UserAgent using the default manager

func GetRandomMobile

func GetRandomMobile() (UserAgent, error)

GetRandomMobile returns a random mobile UserAgent using the default manager