cservice-api

module
v0.4.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 28, 2025 License: MIT

README

CI Codacy Badge Codacy Badge

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.example to config.yml:
cp config.yml.example config.yml
  • Edit config.yml to 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
  1. Install Go 1.22 or newer
  2. Install PostgreSQL 11.0 or newer
  3. Install Valkey (Redis)
  4. 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
  1. Setup PostgreSQL and create a database.

  2. 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

  1. Fork the repository
  2. Create your feature branch
  3. Make your changes
  4. Run tests and linting
  5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Directories

Path Synopsis
cmd
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.
db
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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL