f986711974
Implement readiness endpoint (/api/ready) that returns:
- {"ready":true} (HTTP 200) during normal operation
- {"ready":false} (HTTP 503) during graceful shutdown
Key changes:
- Added readiness context to control readiness state
- Modified server.NewServer() to accept readiness context
- Implemented handleReadiness() with context-aware logic
- Updated cmd/server/main.go to manage readiness state
- Readiness set to false when shutdown signal received
- Updated test script to validate readiness behavior
- Added comprehensive documentation for readiness endpoint
This allows Kubernetes/service meshes to stop routing traffic
to the pod during graceful shutdown while allowing existing
requests to complete. Health endpoint continues to return
happy status during shutdown for proper orchestration.
176 lines
3.7 KiB
Markdown
176 lines
3.7 KiB
Markdown
# DanceLessonsCoach
|
|
|
|
A Go project demonstrating idiomatic package structure, CLI implementation, and JSON API with Chi router.
|
|
|
|
## Features
|
|
|
|
- Greet function with default behavior
|
|
- Command-line interface
|
|
- JSON API with versioned endpoints
|
|
- Chi router integration
|
|
- Zerolog for high-performance logging
|
|
- Viper for configuration management
|
|
- Graceful shutdown with context
|
|
- Unit tests
|
|
- Go 1.26.1 compatible
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone https://github.com/yourusername/DanceLessonsCoach.git
|
|
cd DanceLessonsCoach
|
|
|
|
# Build and run
|
|
go run ./cmd/greet
|
|
```
|
|
|
|
## Optional Configuration
|
|
|
|
The project supports configuration via YAML file, environment variables, or defaults.
|
|
Configuration priority: file > environment variables > defaults
|
|
|
|
### Configuration File
|
|
|
|
By default, the application looks for `config.yaml` in the current working directory.
|
|
|
|
Create a `config.yaml` file:
|
|
|
|
```yaml
|
|
server:
|
|
host: "0.0.0.0"
|
|
port: 8080
|
|
shutdown:
|
|
timeout: 30s
|
|
logging:
|
|
json: false # Set to true for JSON format logging
|
|
```
|
|
|
|
Then start the server:
|
|
|
|
```bash
|
|
go run ./cmd/server
|
|
```
|
|
|
|
### Custom Config File Path
|
|
|
|
To specify a custom config file path, use the `DLC_CONFIG_FILE` environment variable:
|
|
|
|
```bash
|
|
# Use a specific config file
|
|
export DLC_CONFIG_FILE="/path/to/your/config.yaml"
|
|
go run ./cmd/server
|
|
|
|
# Or in one command
|
|
DLC_CONFIG_FILE="/path/to/your/config.yaml" go run ./cmd/server
|
|
```
|
|
|
|
### Environment Variables
|
|
|
|
You can also configure via environment variables with `DLC_` prefix:
|
|
|
|
```bash
|
|
# Set configuration via environment variables
|
|
export DLC_SERVER_HOST="0.0.0.0"
|
|
export DLC_SERVER_PORT=8080
|
|
export DLC_SHUTDOWN_TIMEOUT=30s
|
|
export DLC_LOGGING_JSON=false # Set to true for JSON format logging
|
|
|
|
# Start the server
|
|
go run ./cmd/server
|
|
```
|
|
|
|
### Configuration Priority
|
|
|
|
1. **File-based configuration** (highest priority)
|
|
2. **Environment variables** (override defaults)
|
|
3. **Default values** (lowest priority)
|
|
|
|
This means if you have both a config file and environment variables, the file takes precedence.
|
|
|
|
## Usage
|
|
|
|
### CLI
|
|
|
|
```bash
|
|
# Default greeting
|
|
go run ./cmd/greet
|
|
# Output: Hello world!
|
|
|
|
# Custom greeting
|
|
go run ./cmd/greet John
|
|
# Output: Hello John!
|
|
```
|
|
|
|
### Web Server
|
|
|
|
**Using the server control script (recommended):**
|
|
|
|
```bash
|
|
# Start the server
|
|
./scripts/start-server.sh start
|
|
|
|
# Test API endpoints
|
|
./scripts/start-server.sh test
|
|
|
|
# Stop the server
|
|
./scripts/start-server.sh stop
|
|
```
|
|
|
|
**Manual server management:**
|
|
|
|
```bash
|
|
# Start the server
|
|
go run ./cmd/server
|
|
|
|
# Test API endpoints
|
|
curl http://localhost:8080/api/health
|
|
# Output: {"status":"healthy"}
|
|
|
|
curl http://localhost:8080/api/ready
|
|
# Output: {"ready":true}
|
|
|
|
curl http://localhost:8080/api/v1/greet
|
|
# Output: {"message":"Hello world!"}
|
|
|
|
curl http://localhost:8080/api/v1/greet/John
|
|
# Output: {"message":"Hello John!"}
|
|
```
|
|
|
|
## Testing
|
|
|
|
```bash
|
|
# Run all tests
|
|
go test ./...
|
|
|
|
# Run specific package tests
|
|
go test ./pkg/greet/
|
|
```
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
DanceLessonsCoach/
|
|
├── cmd/
|
|
│ ├── greet/ # CLI entry point
|
|
│ │ └── main.go
|
|
│ └── server/ # Web server entry point
|
|
│ └── main.go
|
|
├── pkg/
|
|
│ ├── config/ # Configuration management
|
|
│ │ └── config.go
|
|
│ ├── greet/ # Core greet functionality
|
|
│ │ ├── api_v1.go # API v1 handlers
|
|
│ │ ├── greet.go # Core service
|
|
│ │ └── greet_test.go # Unit tests
|
|
│ └── server/ # Server implementation
|
|
│ └── server.go
|
|
├── config.example.yaml # Configuration template
|
|
├── go.mod # Go module definition
|
|
└── README.md # Project documentation
|
|
```
|
|
|
|
## License
|
|
|
|
MIT
|