Protos - Citadelas

Protocol Buffers definitions and generated code for Citadelas microservices architecture. Contains gRPC service definitions and message types shared across all services.

🏗️ Overview

This repository provides:

• gRPC service definitions for all microservices
• Message type definitions for inter-service communication
• Automated code generation via GitHub Actions
• Versioned releases with semantic versioning
• Multi-language support (currently Go, extensible to other languages)

📦 Services

SSO Service

Authentication and authorization service definitions:

• Login - User authentication with credentials
• Register - New user registration
• RefreshToken - JWT token refresh mechanism
• IsAdmin - Admin role verification

Task Service

Task management service definitions:

• CreateTask - Create new task
• GetTask - Retrieve task by ID
• UpdateTask - Update existing task
• DeleteTask - Delete task
• UpdateStatus - Change task status
• ListUserTasks - Get all user tasks

🚀 Usage

For Go Services

1. Import the generated Go module

import (
    ssov1 "github.com/Citadelas/protos/golang/sso"
    taskv1 "github.com/Citadelas/protos/golang/task"
)

2. Use in gRPC client

// SSO client
conn, err := grpc.Dial("sso-service:44043", grpc.WithInsecure())
if err != nil {
    log.Fatal(err)
}
defer conn.Close()

client := ssov1.NewAuthClient(conn)
response, err := client.Login(context.Background(), &ssov1.LoginRequest{
    Email:    "user@example.com",
    Password: "password",
    AppId:    1,
})

3. Implement gRPC server

type authServer struct {
    ssov1.UnimplementedAuthServer
}

func (s *authServer) Login(ctx context.Context, req *ssov1.LoginRequest) (*ssov1.LoginResponse, error) {
    // Implementation
}

func main() {
    lis, _ := net.Listen("tcp", ":44043")
    s := grpc.NewServer()
    ssov1.RegisterAuthServer(s, &authServer{})
    s.Serve(lis)
}

For Other Languages

Protocol buffer files are available in the repository root:

• sso/sso.proto - SSO service definitions
• task/task.proto - Task service definitions

Generate code for your language using protoc:

# Python
protoc --python_out=. --grpc_python_out=. sso/sso.proto

# JavaScript
protoc --js_out=import_style=commonjs:. --grpc-web_out=import_style=commonjs,mode=grpcwebtext:. sso/sso.proto

# Java
protoc --java_out=. --grpc-java_out=. sso/sso.proto

🔄 Versioning and Releases

Semantic Versioning

This repository follows semantic versioning:

• MAJOR.MINOR.PATCH (e.g., v1.2.3)
• MAJOR: Breaking changes to protobuf definitions
• MINOR: New services or methods (backward compatible)
• PATCH: Bug fixes and documentation updates

Automated Releases

GitHub Actions automatically:

1. Generates Go code when proto files change
2. Creates new releases with version tags
3. Updates Go module with new generated code
4. Maintains backward compatibility checks

Using Specific Versions

// In go.mod
require github.com/Citadelas/protos v1.0.18

// Import specific version
import ssov1 "github.com/Citadelas/protos/golang/sso"

🏗️ Project Structure

protos/
├── .github/
│   └── workflows/
│       └── protoc.yaml        # Automated code generation
├── golang/                    # Generated Go code
│   ├── sso/                  # SSO service generated files
│   └── task/                 # Task service generated files
├── sso/
│   └── sso.proto             # SSO service definitions
├── task/
│   └── task.proto            # Task service definitions
├── go.mod                    # Go module definition
├── go.sum                    # Go module checksums
└── README.md

🛠️ Development

Prerequisites

• Protocol Buffers compiler (protoc)
• Go 1.24+
• protoc-gen-go plugin
• protoc-gen-go-grpc plugin

Install protoc tools

# Install protoc
# On macOS
brew install protobuf

# On Ubuntu/Debian
apt install -y protobuf-compiler

# Install Go plugins
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest

Adding New Service

1. Create proto file

mkdir -p newservice
cat > newservice/newservice.proto << EOF
syntax = "proto3";

package newservice;
option go_package = "github.com/Citadelas/protos/golang/newservice";

service NewService {
    rpc DoSomething(DoSomethingRequest) returns (DoSomethingResponse);
}

message DoSomethingRequest {
    string input = 1;
}

message DoSomethingResponse {
    string output = 1;
}
EOF

2. Update GitHub Actions workflow Add new service to .github/workflows/protoc.yaml:

- name: Generate Go code
  run: |
    # ... existing services ...
    protoc --go_out=. --go-grpc_out=. newservice/newservice.proto

3. Commit and push

git add .
git commit -m "feat: add NewService proto definitions"
git push origin main

The GitHub Actions will automatically generate Go code and create a new release.

Modifying Existing Services

1. Make backward-compatible changes

   • Add new fields with higher field numbers
   • Add new methods to services
   • Use reserved for removed fields

2. Example: Adding field to existing message

message TaskRequest {
    string id = 1;
    string title = 2;
    string description = 3;
    // New field (backward compatible)
    string priority = 4;
}

3. Breaking changes require major version bump:
   • Removing fields
   • Changing field types
   • Renaming services or methods

Local Development

Generate code locally for testing:

# Generate all Go code
make generate

# Or manually
protoc --go_out=. --go-grpc_out=. sso/sso.proto
protoc --go_out=. --go-grpc_out=. task/task.proto

📋 API Reference

Common Types

// Task priorities
enum Priority {
    LOW = 0;
    MEDIUM = 1;
    HIGH = 2;
}

// Task statuses  
enum Status {
    BACKLOG = 0;
    NEW = 1;
    IN_PROGRESS = 2;
    DONE = 3;
}

// Standard timestamp
import "google/protobuf/timestamp.proto";
google.protobuf.Timestamp created_at = 1;

SSO Service Methods

Method	Description	Request	Response
Login	Authenticate user	LoginRequest	LoginResponse
Register	Register new user	RegisterRequest	RegisterResponse
RefreshToken	Refresh JWT token	RefreshTokenRequest	RefreshTokenResponse
IsAdmin	Check admin status	IsAdminRequest	IsAdminResponse

Task Service Methods

Method	Description	Request	Response
CreateTask	Create new task	CreateTaskRequest	CreateTaskResponse
GetTask	Get task by ID	GetTaskRequest	GetTaskResponse
UpdateTask	Update task	UpdateTaskRequest	UpdateTaskResponse
DeleteTask	Delete task	DeleteTaskRequest	DeleteTaskResponse
UpdateStatus	Update task status	UpdateStatusRequest	UpdateStatusResponse
ListUserTasks	Get user tasks	ListUserTasksRequest	ListUserTasksResponse

🔧 Configuration

GitHub Actions Workflow

The repository uses automated code generation:

name: Generate Protocol Buffers
on:
  push:
    branches: [main]
    paths: ['**/*.proto']

jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Go
        uses: actions/setup-go@v3
        with:
          go-version: '1.24'
      - name: Install protoc
        run: |
          sudo apt-get update
          sudo apt-get install -y protobuf-compiler
          go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
          go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
      - name: Generate code
        run: |
          protoc --go_out=. --go-grpc_out=. sso/sso.proto
          protoc --go_out=. --go-grpc_out=. task/task.proto
      - name: Commit generated code
        run: |
          git config --local user.email "action@github.com"
          git config --local user.name "GitHub Action"
          git add .
          git commit -m "chore: regenerate Go code for ${{ github.sha }}"
          git push

🧪 Testing

Validate Proto Files

# Check syntax
protoc --descriptor_set_out=/dev/null sso/sso.proto
protoc --descriptor_set_out=/dev/null task/task.proto

# Lint with buf (optional)
buf lint

Test Generated Code

# Test Go module
go mod tidy
go build ./golang/...

📝 License

Distributed under the MIT License. See LICENSE for more information.

🔗 Related Services

• API Gateway - HTTP/REST API gateway
• SSO Service - Authentication service
• Task Service - Task management service

---

Maintainer: muerewa
Organization: Citadelas