README
¶
Channel Services API
Warning
THIS IS A WORK IN PROGRESS. The API is not stable and may change at any time. DO NOT USE IN PRODUCTION.
Requirements
- Go >= 1.22 (for compiling)
- PostgreSQL >= 11.0 (for running)
- Valkey (opensource redis)
Configuration
The API can be configured using either a YAML configuration file or environment variables. Environment variables take precedence over the configuration file.
Configuration File
- Copy
config.yml.exampletoconfig.yml:
cp config.yml.example config.yml
- Edit
config.ymlto configure your settings. The configuration file supports all settings shown in the example file.
Environment Variables
All configuration options can be set using environment variables. The environment variables follow this pattern:
CSERVICE_<SECTION>_<KEY>
For example:
# Server configuration
export CSERVICE_SERVICE_HOST=localhost
export CSERVICE_SERVICE_PORT=8080
export CSERVICE_SERVICE_API_PREFIX=api
# Database configuration
export CSERVICE_DATABASE_HOST=localhost
export CSERVICE_DATABASE_PORT=5432
export CSERVICE_DATABASE_USERNAME=cservice
export CSERVICE_DATABASE_PASSWORD=cservice
export CSERVICE_DATABASE_NAME=cservice
# Redis configuration
export CSERVICE_REDIS_HOST=localhost
export CSERVICE_REDIS_PORT=6379
export CSERVICE_REDIS_PASSWORD=
export CSERVICE_REDIS_DATABASE=0
JWT Configuration
For JWT authentication, you need to generate RSA key pairs:
# Generate access token keys
openssl genrsa -out access_jwt.key 4096
openssl rsa -in access_jwt.key -pubout -out access_jwt.pub
# Generate refresh token keys
openssl genrsa -out refresh_jwt.key 4096
openssl rsa -in refresh_jwt.key -pubout -out refresh_jwt.pub
Configure the JWT settings in config.yml:
jwt:
signing_method: "RS256"
signing_key: /path/to/access_jwt.key
public_key: /path/to/access_jwt.pub
refresh_signing_key: /path/to/refresh_jwt.key
refresh_public_key: /path/to/refresh_jwt.pub
Or using environment variables:
export CSERVICE_SERVICE_JWT_SIGNING_METHOD=RS256
export CSERVICE_SERVICE_JWT_SIGNING_KEY=/path/to/access_jwt.key
export CSERVICE_SERVICE_JWT_PUBLIC_KEY=/path/to/access_jwt.pub
export CSERVICE_SERVICE_JWT_REFRESH_SIGNING_KEY=/path/to/refresh_jwt.key
export CSERVICE_SERVICE_JWT_REFRESH_PUBLIC_KEY=/path/to/refresh_jwt.pub
The JWKS can be downloaded from <site>/.well-known/jwks.json.
NOTE: The JWKS is only available when using RS256.
Development Setup
Prerequisites
- Install Go 1.22 or newer
- Install PostgreSQL 11.0 or newer
- Install Valkey (Redis)
- Install required Go tools:
go install github.com/golang-migrate/migrate/v4/cmd/migrate@latest
go install github.com/sqlc-dev/sqlc/cmd/sqlc@v1.28.0
go install github.com/air-verse/air@latest
Database Setup
-
Setup PostgreSQL and create a database.
-
Run migrations:
DB_URL="postgres://cservice:cservice@localhost:5432/cservice?sslmode=disable" make migrate
Alternatively, prepare the configuration YAML file, and run:
bin/cservice-api -config </path/to/config.yaml>
Database Development
This project uses sqlc to generate Go code from SQL queries.
Creating New Migrations
The database schema is defined in db/migrations/*.sql. Do NOT modify existing migration files if a schema change is
necessary. Instead, create new migration files:
migrate create -ext sql -dir db/migrations <migration_name>
This will create two new migration files in db/migrations with the current timestamp for migrating up and down.
Edit these files to add your SQL statements.
Generating Database Code
To generate the Go code from the migrations and SQL queries:
make generate-sqlc
After generating the code, you may need to update the service.go file in models to match the interface defined in
models/querier.go.
Generating Test Mocks
After changing SQL queries or schema, update the database mocks for unit tests:
make generate-mocks
Running the Service
Development Mode with Live Reload
make watch
Production Mode
make build
bin/cservice-api -config </path/to/config.yml>
Testing
Unit Tests
make test
Integration Tests
make integration-test
Linting
make lint
API Documentation
The API documentation is available at /docs when the service is running. It provides a Swagger UI interface for
exploring and testing the API endpoints.
Contributing
- Fork the repository
- Create your feature branch
- Make your changes
- Run tests and linting
- Submit a pull request
License
This project is licensed under the MIT License - see the LICENSE file for details.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
cservice-api
command
|
|
|
Package controllers provides the controllers for the API
|
Package controllers provides the controllers for the API |
|
admin
Package admin defines the admin controllers.
|
Package admin defines the admin controllers. |
|
Package db defines the database types and functions.
|
Package db defines the database types and functions. |
|
types/flags
Package flags contains all the bitmask based flags used in the database.
|
Package flags contains all the bitmask based flags used in the database. |
|
internal
|
|
|
auth/oath/totp
Package totp provides a time-based one-time password (TOTP) implementation.
|
Package totp provides a time-based one-time password (TOTP) implementation. |
|
auth/password
Package password provides password hashing and validation.
|
Package password provides password hashing and validation. |
|
auth/reset
Package reset provides password reset token management functionality
|
Package reset provides password reset token management functionality |
|
checks
Package checks contains functions intended for Is, Has, etc.
|
Package checks contains functions intended for Is, Has, etc. |
|
config
Package config provides configuration management
|
Package config provides configuration management |
|
cron
Package cron provides cron job scheduling using the robfig/cron library
|
Package cron provides cron job scheduling using the robfig/cron library |
|
docs
Package docs Code generated by swaggo/swag.
|
Package docs Code generated by swaggo/swag. |
|
errors
Package errors provides consistent error handling and response formatting for the API
|
Package errors provides consistent error handling and response formatting for the API |
|
globals
Package globals contains global variables and functions
|
Package globals contains global variables and functions |
|
helper
Package helper provides helper functions for channel registration validation
|
Package helper provides helper functions for channel registration validation |
|
jwks
Package jwks provides functions for generating a JWKS
|
Package jwks provides functions for generating a JWKS |
|
mail
Package mail provides a mail service
|
Package mail provides a mail service |
|
metrics
Package metrics provides authentication-specific metrics collection
|
Package metrics provides authentication-specific metrics collection |
|
ratelimit
Package ratelimit provides rate limiting functionality using Redis
|
Package ratelimit provides rate limiting functionality using Redis |
|
telemetry
Package telemetry provides OpenTelemetry initialization and management
|
Package telemetry provides OpenTelemetry initialization and management |
|
testutils
Package testutils provides shared unit test functions
|
Package testutils provides shared unit test functions |
|
tracing
Package tracing provides business-specific distributed tracing utilities
|
Package tracing provides business-specific distributed tracing utilities |
|
Package middlewares provides HTTP middleware for business metrics collection
|
Package middlewares provides HTTP middleware for business metrics collection |
|
Package models contains the database models
|
Package models contains the database models |
|
Package routes defines the routes for the echo server.
|
Package routes defines the routes for the echo server. |