Imported from sofastack/sofa-registry (AGENTS.md). Install upstream with npx skills add sofastack/sofa-registry. Copyright stays with the author.

AGENTS.md - AI Agent Development Guide

This file provides context for AI coding assistants (Claude Code, GitHub Copilot, Cursor, Cline, Aider, etc.)

⚠️ Critical Rules (Read First)

1. DO NOT edit generated files in target/
2. DO NOT delete backward-compatible code without discussion
3. DO NOT add new dependencies without review
4. DO NOT swallow exceptions silently
5. DO NOT create threads directly - use thread pools
6. DO NOT hardcode sensitive data
7. DO NOT skip tests with @Ignore without explanation

Project Overview

SOFARegistry is a production-grade service registry for microservices, developed by Ant Group. It features:

• AP architecture with millisecond-level push notifications
• Multi-tier architecture for horizontal scalability
• Support for massive connections and large-scale datasets

Tech Stack

Module Structure

sofa-registry/
├── client/                    # Client SDK
│   ├── api/                   # Client API interfaces
│   ├── impl/                  # Client implementation
│   ├── log/                   # Client logging
│   └── all/                   # Aggregated client artifact
├── server/
│   ├── common/
│   │   ├── model/             # Data models & Protobuf definitions
│   │   └── util/              # Common utilities
│   ├── remoting/
│   │   ├── api/               # Remoting abstractions
│   │   ├── bolt/              # SOFABolt implementation
│   │   └── http/              # HTTP/REST implementation
│   ├── server/
│   │   ├── meta/              # Meta server (cluster coordination)
│   │   ├── data/              # Data server (data storage)
│   │   ├── session/           # Session server (client connections)
│   │   ├── shared/            # Shared server components
│   │   └── integration/       # Integration entry point
│   ├── store/
│   │   ├── api/               # Storage abstractions
│   │   ├── jraft/             # JRaft-based storage
│   │   └── jdbc/              # JDBC-based storage
│   └── distribution/          # Distribution packaging
├── core/                      # Core shared code
└── test/                      # Integration tests

Architecture

┌─────────────────────────────────────────────────────────┐
│                      Clients                             │
└─────────────────────┬───────────────────────────────────┘
                      │ SOFABolt
┌─────────────────────▼───────────────────────────────────┐
│                 Session Server                           │
│  (Client connections, Pub/Sub routing)                   │
└─────────────────────┬───────────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────────┐
│                  Data Server                             │
│  (Data storage, Slot-based sharding)                     │
└─────────────────────┬───────────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────────┐
│                  Meta Server                             │
│  (Cluster coordination, Leader election)                 │
└─────────────────────────────────────────────────────────┘

Development Commands

# Build (skip tests)
mvn clean install -DskipTests

# Run unit tests
mvn test

# Run integration tests
mvn verify -Pintegration-test

# Run single test class
mvn test -Dtest=ClassName

# Generate protobuf
make proto

# Build Docker image
make image_build

Key Entry Points

Code Conventions

Naming

• Classes: PascalCase
• Methods/Variables: camelCase
• Constants: UPPER_SNAKE_CASE
• Packages: com.alipay.sofa.registry.*

Style Rules (from ruleset.xml)

• Follow Alibaba Java Coding Guidelines (P3C)
• Use braces for all control structures
• Avoid manual thread creation (use thread pools)
• Handle exceptions properly, don't swallow them

Logging

• Use com.alipay.sofa.registry.log.Logger (not SLF4J directly)
• Critical errors: CRITICAL_LOGGER.safeError(...)
• Use parameterized logging: LOGGER.info("msg: {}", value)

Testing

• Unit tests: *Test.java in src/test/java
• Integration tests: test/ module, extend BaseIntegrationTest
• Use JUnit 4 with @Test annotations

Common Tasks

Adding a new API endpoint

1. Define handler in server/server/{meta|data|session}/src/.../resource/
2. Register in corresponding *Configuration.java
3. Add tests in same module's test directory

Modifying data models

1. Edit .proto files in server/common/model/src/main/resources/proto/
2. Run make proto to regenerate Java classes
3. Update corresponding Java wrappers if needed

Adding client functionality

1. Define interface in client/api/
2. Implement in client/impl/
3. Add integration tests in test/ module

Important Patterns

Bootstrap Pattern

Each server has a *ServerBootstrap class that initializes components:

• MetaServerBootstrap
• DataServerBootstrap
• SessionServerBootstrap

Configuration Pattern

Spring configurations in *ServerConfiguration.java classes define beans and wiring.

Handler Pattern

Request handlers implement specific interfaces and are registered with remoting layer.

Prohibited Actions (IMPORTANT)

Code Modification Rules

Configuration Rules

Testing Rules

Architecture Rules

Security Rules

Files to Avoid Modifying

• Generated protobuf files in target/
• IDE-specific files (.idea/, .vscode/)

Quick Reference

Last updated: 2026-03-31