mirror of https://github.com/lukaszraczylo/traefikoidc.git synced 2026-06-05 22:44:17 +00:00

Files

T

lukaszraczylo c474bbafd6 Cleanup [dec2025] (#101 )

* Cleanup excessive comments.

* Remove leftovers hanging around from previous refactor

* Improve test coverage

2025-12-09 01:38:02 +00:00

9.3 KiB

Raw Blame History

Development Guide

Guide for local development, testing, and contributing to the Traefik OIDC middleware.

Prerequisites
Local Development Setup
Running Tests
Test Categories
CI/CD Pipeline
Code Quality
Contributing

Prerequisites

Go 1.23+ for plugin compilation
Docker & Docker Compose for local testing
OIDC Provider credentials (Google, Azure, etc.)

Required Development Tools

# golangci-lint (comprehensive linting)
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

# staticcheck (static analysis)
go install honnef.co/go/tools/cmd/staticcheck@latest

# gosec (security scanning)
go install github.com/securego/gosec/v2/cmd/gosec@latest

# govulncheck (vulnerability scanning)
go install golang.org/x/vuln/cmd/govulncheck@latest

Local Development Setup

Docker Compose Environment

The repository includes a Docker Compose setup for testing the plugin locally.

1. Host Configuration

Add to /etc/hosts:

127.0.0.1 hello.localhost
127.0.0.1 traefik.localhost

2. Plugin Configuration

The plugin is loaded using Traefik's local plugins mode:

Plugin source: Parent directory (../)
Mount path: /plugins-local/src/github.com/lukaszraczylo/traefikoidc
Configuration: experimental.localPlugins in traefik.yml

3. OIDC Provider Setup

Edit docker/dynamic.yml with your provider details:

Google:

http:
  middlewares:
    oidc-auth:
      plugin:
        traefikoidc:
          providerURL: "https://accounts.google.com"
          clientID: "your-client-id.apps.googleusercontent.com"
          clientSecret: "your-google-client-secret"
          sessionEncryptionKey: "your-32-character-encryption-key"
          callbackURL: "/oauth2/callback"
          logoutURL: "/oauth2/logout"
          scopes:
            - "openid"
            - "email"
            - "profile"

Azure AD:

http:
  middlewares:
    oidc-auth:
      plugin:
        traefikoidc:
          providerURL: "https://login.microsoftonline.com/your-tenant-id/v2.0"
          clientID: "your-azure-client-id"
          clientSecret: "your-azure-client-secret"
          sessionEncryptionKey: "your-32-character-encryption-key"
          callbackURL: "/oauth2/callback"
          scopes:
            - "openid"
            - "email"
            - "profile"

4. Start Environment

cd docker
docker-compose up -d

5. Test Plugin

Protected App: http://hello.localhost (redirects to OIDC)
Traefik Dashboard: http://traefik.localhost:8080

Development Workflow

Edit plugin code in the project root
Build and test (optional syntax check):
```
go mod tidy
go build .
go test ./...
```
Restart Traefik to reload plugin:
```
docker-compose restart traefik
```
Test changes at http://hello.localhost

Debugging

View plugin logs:

docker-compose logs -f traefik | grep traefikoidc

Check plugin loading:

docker-compose logs traefik | grep -i plugin

Verify plugin directory:

docker-compose exec traefik ls -la /plugins-local/src/github.com/lukaszraczylo/traefikoidc/

Running Tests

Quick Start

# Fast development testing (< 30 seconds)
go test ./... -short

# Standard tests with race detector
go test -race -timeout=15m ./...

# With coverage report
go test -coverprofile=coverage.out ./...
go tool cover -func=coverage.out

Test Modes

Mode	Command	Duration	Use Case
Quick	`go test ./... -short`	< 30s	During development
Extended	`RUN_EXTENDED_TESTS=1 go test ./...`	2-5 min	Before commits
Long	`RUN_LONG_TESTS=1 go test ./...`	5-15 min	Release validation
Stress	`RUN_STRESS_TESTS=1 go test ./...`	10-30 min	Performance testing

Environment Variables

# Enable specific test types
export RUN_EXTENDED_TESTS=1
export RUN_LONG_TESTS=1
export RUN_STRESS_TESTS=1

# Disable specific features
export DISABLE_LEAK_DETECTION=1

# Customize test parameters
export TEST_MAX_CONCURRENCY=10
export TEST_MAX_ITERATIONS=50
export TEST_MEMORY_THRESHOLD_MB=25.5

Test Categories

Quick Tests (Default)

Basic functionality verification
Limited iterations (1-3)
Small data sets
Essential memory leak checks

Configuration:

Max Iterations: 3
Max Concurrency: 5
Memory Threshold: 2.0 MB
Timeout: 10 seconds

Extended Tests

Comprehensive testing before commits
More iterations (5-10)
Enhanced memory leak detection

Configuration:

Max Iterations: 10
Max Concurrency: 20
Memory Threshold: 10.0 MB
Timeout: 30 seconds

Long Tests

Performance validation
High iteration counts (50-100)
Large data sets

Configuration:

Max Iterations: 100
Max Concurrency: 50
Memory Threshold: 50.0 MB
Timeout: 60 seconds

Stress Tests

Maximum load testing
Edge case validation
Extreme parameters

Configuration:

Max Iterations: 500
Max Concurrency: 100
Memory Threshold: 100.0 MB
Timeout: 120 seconds

Running Specific Test Suites

# Memory leak tests
go test -v -run='.*Leak.*' ./...

# Integration tests
go test -v -run='.*Integration.*' ./...

# Regression tests
go test -v -run='.*Regression.*' ./...

# Provider-specific tests
go test -v -run='.*Azure.*' ./...
go test -v -run='.*Google.*' ./...

Benchmarks

# Quick benchmarks
go test -bench=. -short

# Extended benchmarks
RUN_EXTENDED_TESTS=1 go test -bench=.

# Memory profiling
go test -bench=. -memprofile=mem.prof
go tool pprof mem.prof

CI/CD Pipeline

The repository uses GitHub Actions for comprehensive validation with 20+ parallel checks.

Triggered On

Pull requests to main branch
Pushes to main branch

Parallel Jobs

Code Quality (3 checks)

Format & Basic Checks - gofmt, go vet, go mod
golangci-lint - 30+ linters
Staticcheck - Advanced static analysis

Security (3 checks)

Gosec - Security vulnerability scanning
Govulncheck - Go vulnerability database
CodeQL - GitHub's semantic code analysis

Testing (9 suites)

Race Detector
Coverage (75% threshold)
Memory Leaks
Integration Tests
Regression Tests
Security Edge Cases
Session Tests
Token Tests
CSRF Tests

Provider Testing (9 providers)

Tests run in parallel for:

Google
Azure AD
Auth0
Okta
Keycloak
AWS Cognito
GitLab
GitHub
Generic OIDC

Performance & Build (3 checks)

Benchmarks
Multi-platform Build (linux/darwin x amd64/arm64)
Go Version Compatibility (Go 1.23 & 1.24)

Quality Gates

All PRs must pass:

All parallel checks
75% test coverage minimum
Zero security vulnerabilities
No race conditions
No memory leaks
All providers tested
Builds on all platforms

Code Quality

Pre-Commit Checklist

# Run before every commit
gofmt -s -w . && \
go mod tidy && \
golangci-lint run && \
go test -race -short ./... && \
echo "Ready to commit!"

Local Validation

# Format code
gofmt -s -w .

# Run linter
golangci-lint run

# Static analysis
staticcheck ./...

# Security scan
gosec ./...

# Vulnerability check
govulncheck ./...

# Tests with race detector
go test -race -timeout=15m -count=1 ./...

# Coverage report
go test -coverprofile=coverage.out ./...
go tool cover -func=coverage.out

# View coverage in browser
go tool cover -html=coverage.out

Troubleshooting

Coverage Below Threshold:

go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out  # See uncovered lines

Race Condition Found:

go test -race -v -run=TestName ./...

Linter Errors:

golangci-lint run -v
golangci-lint run --fix  # Auto-fix some issues

Provider Test Fails:

go test -v -run='.*Azure.*' ./...

Contributing