Go-Lynx

The Plug-and-Play Go Microservices Framework

Architecture Position

Lynx should be read as a plugin orchestration framework first.

• Core: plugin orchestration, lifecycle ordering, shared runtime, event plumbing
• Optional shell: boot, app startup wiring, control-plane-facing helpers
• Compatibility surface: singleton access, root-package runtime wrappers, global event helpers

The preferred path for new code is explicit app/runtime ownership. Compatibility helpers remain available, but they are no longer the design center.

📊 Event System

Lynx provides a unified event system for inter-plugin communication:

Event Types

Lynx supports various event types:

// Add event listener
listener := &MyEventListener{}
runtime.AddListener(listener, nil)

// Add plugin-specific listener
runtime.AddPluginListener("my-plugin", listener, nil)

// Emit events
runtime.EmitPluginEvent("my-plugin", "started", map[string]any{
    "timestamp": time.Now().Unix(),
})

Event Filtering

Lynx supports event filtering to process only relevant events:

event_filters:
  - type: "started"
    plugin: "http"
  - type: "stopped"
    plugin: "grpc"

📈 Monitoring and Observability

Lynx provides comprehensive monitoring and observability features:

Metrics

Lynx integrates with Prometheus for metrics collection:

metrics:
  enabled: true
  endpoint: "/metrics"
  namespace: "lynx"
  subsystem: "http"
  labels:
    - "service"
    - "instance"

Tracing

Lynx integrates with OpenTelemetry for distributed tracing:

tracing:
  enabled: true
  provider: "otlp"
  endpoint: "localhost:4317"
  service_name: "demo"
  sample_rate: 0.1

Logging

Lynx provides structured logging with Zap:

logging:
  level: "info"
  format: "json"
  output: "stdout"
  caller: true
  stacktrace: true

Health Checks

Lynx includes health checks for monitoring service health:

health:
  enabled: true
  endpoint: "/health"
  checks:
    - name: "database"
      timeout: 5s
    - name: "redis"
      timeout: 2s

🚀 Production-Ready Features

Lynx includes several production-ready features:

Graceful Shutdown

Lynx supports graceful shutdown to ensure all requests are processed before shutting down:

graceful_shutdown:
  timeout: 30s
  wait_for_ongoing_requests: true
  max_wait_time: 60s

Rate Limiting

Lynx includes rate limiting to prevent abuse:

rate_limit:
  enabled: true
  rate_per_second: 100
  burst_limit: 200

Retry Policies

Lynx supports retry policies for handling transient failures:

retry:
  enabled: true
  max_attempts: 3
  initial_interval: 100ms
  max_interval: 1s
  multiplier: 2.0

Dead Letter Queues

Lynx supports dead letter queues for handling failed messages:

dead_letter_queue:
  enabled: true
  max_retries: 3
  destination: "dlq-topic"

---

Translations: English | 简体中文

🚀 What is Lynx?

Lynx is an open-source plugin orchestration framework for Go applications built on top of Kratos. Its center of gravity is plugin lifecycle management, dependency-aware startup order, unified runtime ownership, and framework stability rather than in-process platform magic.

🎯 Why Choose Lynx?

• ⚡ Fast Startup Path: Start with a small core and add plugins deliberately
• 🔌 Plugin-Oriented: Modular architecture centered on orchestration and lifecycle
• 🛡️ Stability First: Production-focused resource ownership and shutdown behavior
• 📈 Cloud-Native Friendly: Designed to work with restart- and rollout-based deployment models
• 🔄 Clear Boundaries: Leaves rollout and in-process mutation concerns to external tooling when appropriate

---

🏗️ Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                 Shell / Application Layer                     │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐           │
│  │ LynxApp     │  │ Boot        │  │ Control     │           │
│  │             │  │             │  │ Plane       │           │
│  └─────────────┘  └─────────────┘  └─────────────┘           │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                  Plugin Management Layer                       │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐           │
│  │ Plugin      │  │ Lifecycle   │  │ Plugin      │           │
│  │ Manager     │  │ / Ops       │  │ Factory     │           │
│  └─────────────┘  └─────────────┘  └─────────────┘           │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Runtime Layer                               │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐           │
│  │ Runtime     │  │ Unified     │  │ Compat      │           │
│  │ Interface   │  │ Runtime     │  │ Wrappers    │           │
│  └─────────────┘  └─────────────┘  └─────────────┘           │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                Resource Management Layer                       │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐           │
│  │ Private     │  │ Shared      │  │ Resource    │           │
│  │ Resources   │  │ Resources   │  │ Info        │           │
│  └─────────────┘  └─────────────┘  └─────────────┘           │
└─────────────────────────────────────────────────────────────────┘

---

✨ Key Features

🔍 Service Discovery & Registration

• Automatic Service Registration: Seamlessly register your services
• Smart Service Discovery: Dynamic service discovery with health checks
• Multi-Version Support: Deploy multiple service versions simultaneously
• Load Balancing: Intelligent traffic distribution

🔐 Security & Communication

• Encrypted Intranet Communication: End-to-end encryption for service communication
• Authentication & Authorization: Built-in security mechanisms
• TLS Support: Secure transport layer communication

🚦 Traffic Management

• Rate Limiting: Prevent service overload with intelligent throttling
• Circuit Breaker: Automatic fault tolerance and recovery
• Traffic Routing: Intelligent routing with blue-green and canary deployments
• Fallback Mechanisms: Graceful degradation during failures

💾 Distributed Transactions

• ACID Compliance: Ensure data consistency across services
• Automatic Rollback: Handle transaction failures gracefully
• Performance Optimized: Minimal overhead for distributed transactions

🔌 Plugin Architecture

• Hot-Pluggable: Add or remove features without code changes
• Extensible: Easy integration of third-party tools
• Modular Design: Clean separation of concerns

---

🛠️ Built With

Lynx leverages battle-tested open-source technologies:

Component	Technology	Purpose
Service Discovery	Polaris	Service registration and discovery
Distributed Transactions	Seata	ACID transactions across services
Framework Core	Kratos	High-performance Go service framework
Language	Go	Fast, reliable, and concurrent

---

🚀 Quick Start

1. Install Lynx CLI

go install github.com/go-lynx/lynx/cmd/lynx@latest

2. Create Your Project

# Create a single project
lynx new my-service

# Create multiple projects at once
lynx new service1 service2 service3

3. Write Your Code

package main

import (
    "github.com/go-lynx/lynx/app"
    "github.com/go-lynx/lynx/app/boot"
)

func main() {
    // That's it! Lynx handles everything else
    boot.LynxApplication(wireApp).Run()
}

4. Configure Your Services

# config.yml
lynx:
  polaris:
    namespace: "default"
    weight: 100
  http:
    addr: ":8080"
    timeout: "10s"
  grpc:
    addr: ":9090"
    timeout: "5s"

🔐 Security

Lynx provides comprehensive security features to protect your microservices:

TLS Configuration

Lynx supports TLS for secure communication between services:

tls:
  source_type: local_file  # Options: local_file, memory, etc.
  auth_type: mutual        # Options: no_client_cert, request_client_cert, require_any_client_cert, etc.
  min_version: TLS1.2      # Minimum TLS version
  cert_file: /path/to/cert.pem
  key_file: /path/to/key.pem
  ca_file: /path/to/ca.pem

Authentication

Lynx supports various authentication mechanisms:

• TLS Mutual Authentication: Client and server authenticate each other using certificates
• OAuth2: Support for OAuth2 authentication flows
• API Keys: Simple API key authentication
• JWT: JSON Web Token authentication

Authorization

Lynx provides flexible authorization mechanisms:

• Role-Based Access Control (RBAC): Control access based on roles
• Attribute-Based Access Control (ABAC): Fine-grained access control based on attributes
• Policy Enforcement: Enforce access policies at the service level

⚠️ Error Handling

Lynx provides a comprehensive error handling framework:

Error Types

Lynx defines common error types for consistent error handling:

// Common errors
var (
    ErrCacheMiss  = errors.New("cache: key not found")
    ErrCacheSet   = errors.New("cache: failed to set value")
    ErrInvalidTTL = errors.New("cache: invalid TTL")
)

Error Recovery

Lynx includes an error recovery manager for handling and recovering from errors:

// ErrorRecoveryManager provides centralized error handling and recovery
type ErrorRecoveryManager struct {
    // Error tracking
    errorCounts     map[string]int64
    errorHistory    []ErrorRecord
    recoveryHistory []RecoveryRecord

    // Circuit breakers for different error types
    circuitBreakers map[string]*CircuitBreaker

    // Recovery strategies
    recoveryStrategies map[string]RecoveryStrategy
    
    // ... other fields
}

Circuit Breakers

Lynx includes circuit breakers to prevent cascading failures:

circuit_breaker:
  enabled: true
  threshold: 5        # Number of errors before opening the circuit
  timeout: 30s        # Time to keep the circuit open
  half_open_timeout: 5s  # Time to wait in half-open state

---

📊 Performance & Scalability

• ⚡ High Performance: Optimized for low latency and high throughput
• 📈 Horizontal Scaling: Easy scaling across multiple instances
• 🔄 Zero Downtime: Rolling updates and graceful shutdowns
• 📊 Monitoring: Built-in metrics and observability

---

🧰 CLI Logging & I18n

Lynx CLI provides a unified, level-based logger and internationalized messages.

Logging

• Env vars
  • LYNX_LOG_LEVEL: one of error|warn|info|debug (default: info)
  • LYNX_QUIET: suppress non-error outputs when set to 1/true
  • LYNX_VERBOSE: enable verbose mode when set to 1/true
• Flags (override env for current command)
  • --log-level <level>
  • --quiet / -q
  • --verbose / -v

Examples:

# quiet mode
LYNX_QUIET=1 lynx new demo

# debug logs for one run
lynx --log-level=debug new demo

Internationalization (i18n)

• Env var: LYNX_LANG with zh or en.
• All user-facing messages respect this setting.

Examples:

LYNX_LANG=en lynx new demo
LYNX_LANG=zh lynx new demo

🧭 CLI Commands

📋 lynx new - Create New Projects

Common flags for lynx new:

• --repo-url, -r: layout repository URL (env: LYNX_LAYOUT_REPO)
• --branch, -b: branch name for layout repo
• --ref: commit/tag/branch to checkout; takes precedence over --branch
• --module, -m: go module path for the new project (e.g. github.com/acme/foo)
• --force, -f: overwrite existing directory without prompt
• --post-tidy: run go mod tidy after generation
• --timeout, -t: creation timeout (e.g. 60s)
• --concurrency, -c: max concurrent project creations

Examples:

# use a specific tag
lynx new demo --ref v1.2.3

# set module and run mod tidy automatically
lynx new demo -m github.com/acme/demo --post-tidy

# create multiple projects with concurrency 4
lynx new svc-a svc-b svc-c svc-d -c 4

🔍 lynx doctor - Diagnose Environment & Project Health

The lynx doctor command performs comprehensive health checks on your development environment and Lynx project.

What It Checks

Environment Checks:

• ✅ Go installation and version (minimum Go 1.20+)
• ✅ Go environment variables (GOPATH, GO111MODULE, GOPROXY)
• ✅ Git repository status and uncommitted changes

Tool Checks:

• ✅ Protocol Buffers compiler (protoc) installation
• ✅ Wire dependency injection tool availability
• ✅ Required development tools for Lynx projects

Project Structure:

• ✅ Validates expected directory structure (app/, boot/, plugins/, etc.)
• ✅ Checks go.mod file existence and validity
• ✅ Verifies Makefile and expected targets

Configuration:

• ✅ Scans and validates YAML/YML configuration files
• ✅ Checks configuration syntax and structure

Output Formats

• Text (default): Human-readable with colors and icons
• JSON: Machine-readable for CI/CD integration
• Markdown: Documentation-friendly format

Command Options

# Run all diagnostic checks
lynx doctor

# Output in JSON format (for CI/CD)
lynx doctor --format json

# Output in Markdown format
lynx doctor --format markdown > health-report.md

# Check specific category only
lynx doctor --category env      # Environment only
lynx doctor --category tools    # Tools only
lynx doctor --category project  # Project structure only
lynx doctor --category config   # Configuration only

# Auto-fix issues when possible
lynx doctor --fix

# Show detailed diagnostic information
lynx doctor --verbose

Auto-Fix Capabilities

The --fix flag can automatically resolve:

• Missing development tools (installs via make init or go install)
• go.mod issues (runs go mod tidy)
• Other fixable configuration problems

Health Status Indicators

• 💚 Healthy: All checks passed
• 💛 Degraded: Some warnings detected but functional
• 🔴 Critical: Errors found that need attention

Example Output

🔍 Lynx Doctor - Diagnostic Report
==================================================

📊 System Information:
  • OS/Arch: darwin/arm64
  • Go Version: go1.24.4
  • Lynx Version: v2.0.0

🔎 Diagnostic Checks:
--------------------------------------------------
✅ Go Version: Go 1.24 installed
✅ Project Structure: All expected directories found
⚠️ Wire Dependency Injection: Not installed
   💡 Fix available (use --fix to apply)

📈 Summary:
  Total Checks: 9
  ✅ Passed: 7
  ⚠️ Warnings: 2

💛 Overall Health: Degraded

🚀 lynx run - Quick Development Server

The lynx run command provides a convenient way to build and run your Lynx project with optional file-watch auto-restart for rapid development.

Features

• Automatic Build & Run: Compiles and executes your project in one command
• File-Watch Auto-Restart: Automatically rebuilds and restarts on file changes during development (with --watch flag)
• Process Management: Graceful shutdown and restart handling
• Smart Detection: Automatically finds main package in project structure
• Environment Control: Pass custom environment variables and arguments

Command Options

lynx run [path] [flags]

Flags:

• --watch, -w: Enable file-watch auto-restart for development
• --build-args: Additional arguments for go build
• --run-args: Arguments to pass to the running application
• --verbose, -v: Enable verbose output
• --env, -e: Environment variables (KEY=VALUE)
• --port, -p: Override the application port
• --skip-build: Skip build and run existing binary

Example Usage

# Run project in current directory
lynx run

# Run with file-watch auto-restart
lynx run --watch

# Run specific project directory
lynx run ./my-service

# Pass custom build flags
lynx run --build-args="-ldflags=-s -w"

# Pass runtime configuration
lynx run --run-args="--config=./configs"

# Set environment variables
lynx run -e PORT=8080 -e ENV=development

# Run existing binary without rebuild
lynx run --skip-build

Hot Reload Details

When using --watch mode, the following files trigger rebuilds:

• Go source files (.go)
• Go module files (go.mod, go.sum)
• Configuration files (.yaml, .yml, .json, .toml)
• Environment files (.env)
• Protocol buffer files (.proto)

Ignored paths:

• .git, .idea, vendor, node_modules
• Build directories (bin, dist, tmp)
• Test files (*_test.go)

🎯 Use Cases

🏢 Enterprise Applications

• Microservices Migration: Legacy system modernization
• Cloud-Native Applications: Kubernetes and container-native deployments
• High-Traffic Services: E-commerce and financial applications

🚀 Startups & Scale-ups

• Rapid Development: Quick time-to-market with minimal setup
• Cost Optimization: Efficient resource utilization
• Team Productivity: Focus on business logic, not infrastructure

---

🤝 Contributing

We welcome contributions to Lynx! Here's how you can help:

1. Report Issues: Found a bug? Please open an issue.
2. Suggest Features: Have an idea? Start a discussion.
3. Submit Pull Requests: Submit PRs for bug fixes or new features.
4. Improve Documentation: Help improve documentation or add examples.
5. Spread the Word: Star the repository and share it with others.

Please read our Contributing Guide for detailed instructions on development setup, coding conventions, testing, and the pull request process.

---

📚 Documentation

• 📖 User Guide
• 🔧 API Reference
• 🎯 Examples
• 🚀 Quick Start

---

📄 License

Lynx is licensed under the Apache License 2.0.

⭐ Star History

---