go-cloud-k8s-thing

README

🚀 go-cloud-k8s-thing

A modern Proto-first microservice for managing "Things" — built with Go, gRPC, ConnectRPC, and designed for cloud-native Kubernetes deployments.

Proto as Source of Truth: API contracts are defined in Protocol Buffers, generating both Go code and OpenAPI specs automatically. Clients can connect via REST, gRPC, or Connect protocols.

✨ Features

• 🔐 JWT Authentication — Secure endpoints with token-based auth from go-cloud-k8s-user-group
• 📡 Multi-Protocol Support — REST, gRPC, and Connect (JSON/Proto) via Vanguard transcoding
• 📋 Proto-First Design — Single source of truth for API definitions
• 🐘 PostgreSQL Backend — Robust data persistence with pgx driver
• 🐳 Container Ready — Optimized Docker images with CVE scanning via Trivy
• ☸️ Kubernetes Native — Ready for K8s deployment with health checks and metrics

---

🏗️ Architecture

graph TB
    subgraph Clients["📱 Clients"]
        REST["🌐 REST<br/>GET /goapi/v1/thing"]
        CONNECT["⚡ Connect<br/>JSON / Proto"]
        GRPC["🔌 gRPC"]
    end
    
    subgraph Server["🖥️ Echo Server"]
        VG["🔄 Vanguard Transcoder"]
        subgraph Services["Connect Services"]
            TS["ThingService"]
            TTS["TypeThingService"]
        end
    end
    
    subgraph Core["⚙️ Business Layer"]
        BS["BusinessService"]
        ST["Storage Interface"]
    end
    
    subgraph Data["💾 Data Layer"]
        PG[(PostgreSQL)]
    end
    
    REST --> VG
    CONNECT --> VG
    GRPC --> VG
    VG --> TS
    VG --> TTS
    TS --> BS
    TTS --> BS
    BS --> ST
    ST --> PG

---

📦 Proto-First API Design

The API is defined using Protocol Buffers as the single source of truth:

api/proto/thing/v1/
├── thing.proto           # ThingService definitions
└── type_thing.proto      # TypeThingService definitions

Generated Artifacts

Source	Generated	Purpose
.proto files	gen/thing/v1/*.go	Go types & gRPC stubs
.proto files	gen/thing/v1/thingv1connect/*.go	Connect handlers
.proto files	api/openapi/thing.yaml	OpenAPI 3.0 spec

Regenerate Code

./scripts/buf_generate.sh
# or
buf generate api/proto

---

🔌 API Endpoints

All endpoints are prefixed with /goapi/v1 and require JWT authentication.

Thing Resources

Method	Endpoint	Description
GET	/goapi/v1/thing	List things
POST	/goapi/v1/thing	Create a thing
GET	/goapi/v1/thing/{id}	Get thing by ID
PUT	/goapi/v1/thing/{id}	Update a thing
DELETE	/goapi/v1/thing/{id}	Delete a thing
GET	/goapi/v1/thing/search	Search things
GET	/goapi/v1/thing/count	Count things
GET	/goapi/v1/thing/geojson	Get GeoJSON

TypeThing Resources

Method	Endpoint	Description
GET	/goapi/v1/types	List type things
POST	/goapi/v1/types	Create type thing
GET	/goapi/v1/types/{id}	Get type thing by ID
PUT	/goapi/v1/types/{id}	Update type thing
DELETE	/goapi/v1/types/{id}	Delete type thing
GET	/goapi/v1/types/count	Count type things

Connect RPC Endpoints

# Connect JSON format
curl -X POST http://localhost:9090/thing.v1.ThingService/List \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"limit": 10}'

---

🚀 Quick Start

Prerequisites

• Go 1.21+
• PostgreSQL 14+
• buf (for proto generation)

Environment Variables

# Required
export PORT=9090
export DB_HOST=localhost
export DB_PORT=5432
export DB_NAME=go_cloud_k8s_thing
export DB_USER=your_user
export DB_PASSWORD=your_password
export JWT_SECRET=your_jwt_secret
export ADMIN_PASSWORD=your_admin_password

Run Locally

# Install dependencies
go mod download

# Run database migrations
# (migrations are auto-applied on startup)

# Start the server
go run ./cmd/goCloudK8sThingServer

Run Tests

make test

---

🐳 Docker

Pull from GitHub Container Registry

docker pull ghcr.io/lao-tseu-is-alive/go-cloud-k8s-thing:latest

Build Locally

docker build -t go-cloud-k8s-thing .

Find all available versions in the Packages section.

---

📚 Documentation

• 📋 Requirements — Functional and system requirements
• 🔗 OpenAPI Spec (YAML) — Generated from proto
• 🌐 Swagger UI — Interactive API docs

---

🛠️ Tech Stack

Category	Technology
Language	Go 1.21+
API Framework	Echo
RPC	ConnectRPC + Vanguard
Proto Tooling	buf
Database	PostgreSQL with pgx
Auth	JWT via cristalhq/jwt
Monitoring	Prometheus metrics
Container	Docker with multi-stage builds
Security	Trivy CVE scanning

---

📁 Project Structure

go-cloud-k8s-thing/
├── api/
│   ├── proto/thing/v1/          # 📋 Proto definitions (source of truth)
│   └── openapi/                  # 📄 Generated OpenAPI specs
├── cmd/
│   └── goCloudK8sThingServer/   # 🚀 Main application entry point
├── gen/
│   └── thing/v1/                # ⚙️ Generated Go code from protos
├── pkg/
│   └── thing/                   # 📦 Business logic
│       ├── business_service.go  # Core business operations
│       ├── connect_server.go    # Connect RPC handlers
│       ├── mappers.go           # Domain ↔ Proto conversion
│       └── storage_postgres.go  # Database operations
├── db/migrations/               # 🗃️ SQL migrations
├── scripts/                     # 🔧 Build & generation scripts
└── documentation/               # 📚 Requirements & docs

---

🔒 Security

• All CVE scans performed automatically before container builds
• JWT authentication required for all /goapi/v1/* endpoints
• SonarCloud analysis for code quality and security
• Dependabot for dependency updates

---

📄 License

MIT License — See LICENSE for details.

---

Built with ❤️ using Go, Proto, and Connect