api-gateway/.docs/development.md

Development

Prerequisites

• Go 1.25.5 or later
• Git

Setup

1. Clone the repository:

git clone git.secnex.io/secnex/gateway.git
cd gateway

2. Install dependencies:

cd app
go mod download

Project Structure

gateway/
├── app/                    # Application source code
│   ├── main.go             # Entry point
│   ├── config/             # Configuration management
│   ├── server/             # Core server components
│   ├── middlewares/        # HTTP middleware
│   ├── handlers/           # Request handlers
│   └── res/                # Response utilities
├── .docs/                  # Documentation
├── gateway.yaml            # Configuration file
├── Dockerfile              # Docker image definition
├── docker-compose.yml      # Docker Compose configuration
└── .gitignore              # Git ignore rules

Running Locally

cd app
go run main.go

Testing

# Run all tests
go test ./...

# Run tests with coverage
go test -cover ./...

# Run tests for specific package
go test ./config
go test ./server
go test ./middlewares

Building

# Build binary
cd app
go build -o gateway main.go

# Build for Linux
GOOS=linux go build -o gateway-linux main.go

# Build for macOS (ARM64)
GOOS=darwin GOARCH=arm64 go build -o gateway-darwin-arm64 main.go

Code Style

• Follow standard Go conventions
• Use gofmt for formatting
• Keep functions focused and small
• Add comments for exported types and functions
• Use meaningful variable names

Adding Features

Adding a New Middleware

Create a new file in app/middlewares/:

package middlewares

import "net/http"

func MyMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // Your logic here
        next.ServeHTTP(w, r)
    })
}

Then apply it in server/routes.go:

if route.Security.CustomMiddleware.Enabled {
    handlers[route.Path] = middlewares.MyMiddleware(handlers[route.Path])
}

Adding a New Configuration Field

1. Update config/types.go to add the field to the struct
2. Update gateway.yaml with the new configuration
3. Update configuration documentation in .docs/configuration.md

Adding a New Handler

Add your handler in app/handlers/route.go:

package handlers

import "net/http"

func MyCustomHandler(w http.ResponseWriter, r *http.Request) {
    // Your logic here
}

Documentation

When making changes to the codebase, update the relevant documentation:

• Architecture changes → .docs/architecture.md
• Configuration changes → .docs/configuration.md
• New features or usage changes → .docs/usage.md
• Deployment changes → .docs/deployment.md

Debugging

Enable Debug Logging

Debug logging is enabled by default in main.go:

masterlog.SetLevel(masterlog.LevelDebug)

Using Delve

# Install Delve
go install github.com/go-delve/delve/cmd/dlv@latest

# Debug main.go
cd app
dlv debug main.go

Internal Module

The project uses an internal Go module:

git.secnex.io/secnex/gateway

When importing packages within the project, use this path:

import "git.secnex.io/secnex/gateway/config"

Release Process

1. Update version in documentation
2. Tag the release:

git tag -a v1.0.0 -m "Release v1.0.0"
git push origin v1.0.0

3. Build Docker image:

docker build -t git.secnex.io/secnex/api-gateway:v1.0.0 .