# apisix

## Welcome to apisix

Your guide to understanding the codebase

### Learning Path

15 units • 5 levels

#### Orchestration & APIs
- Pipelines, workflows, public interfaces • 4 units

#### API Gateway Architecture & Core Components
- Architecture · 4
- API Gateway Architecture and Configuration • Architecture · 6

#### Deployment and Operations
- Deployment
- Testing Fundamentals • Testing · 8

#### Core Logic & Data
- Business rules, schemas, models • 3 units

#### Plugin System and Extensions
- Architecture · 2

#### Security and Access Control
- Security · 10

#### Traffic Management
- Workflow · 1

#### Interaction & Integration
- UI components, external connectors • 2 units
- Protocol Support and Proxying • API · 3
- Service Integration and Discovery • Integration · 10

#### Cross-Cutting Concerns
- Auth, logging, config, testing • 2 units

#### Observability and Monitoring
- Infrastructure · 2

#### Advanced Testing and Reliability
- Testing · 5

#### Edge Cases & Resilience
- Error handling, fault tolerance • 1 units

#### Additional Data Model Patterns
- Data Model · 8

## Test Your Knowledge

Test your deep understanding of the codebase

### Your Challenge

Implement a custom plugin that adds intelligent request retry logic with exponential backoff for upstream service failures. Your plugin should intercept failed upstream requests (5xx errors or timeouts), automatically retry them with increasing delays, and expose metrics about retry attempts and success rates. The plugin should be configurable per route, allowing operators to specify max retry attempts, initial delay, and backoff multiplier.

### Starting Points

- `apisix/include/apisix/model/pubsub.proto:1-124`
  - Study the protobuf message structure to understand how APISIX models data structures for communication between components

- `.devcontainer/docker-compose.yml:1-38`
  - Examine the service architecture and dependencies - you'll need to understand how APISIX connects to upstream services and potentially add test services

- `benchmark/run.sh:1-140`
  - Review how performance testing is structured - you'll want to benchmark your retry logic to ensure it doesn't significantly impact latency

- `ci/check_changelog_prs.ts:1-120`
  - Understand the project's contribution standards - you'll need to document your plugin appropriately

### Success Criteria

- Plugin successfully retries failed upstream requests (5xx errors) up to the configured maximum
- Exponential backoff is correctly implemented - verify delays increase exponentially between retries
- Plugin exposes Prometheus metrics showing retry attempts, successes, and failures
- Configuration schema allows per-route customization of `max_retries`, `initial_delay_ms`, and `backoff_multiplier`
- Plugin does not retry on 4xx client errors (only 5xx server errors and timeouts)
- Existing APISIX tests pass and new test cases demonstrate retry behavior with a mock failing upstream
- Documentation includes plugin configuration examples and explains when retries are triggered

### Hints

- **Hint 1:** Understanding APISIX plugin architecture conceptual
- **Hint 2:** Handling upstream failures code location
- **Hint 3:** State management for retries implementation
- **Hint 4:** Metrics and observability implementation
- **Hint 5:** Testing your plugin implementation

**Prerequisites:**
- Lua programming basics
- HTTP status codes and error handling
- Exponential backoff algorithms
- Prometheus metrics concepts
- API Gateway plugin architecture