{"id":37213415,"url":"https://github.com/soundphilosopher/basic-grpc-service-go","last_synced_at":"2026-01-15T00:37:29.951Z","repository":{"id":313172624,"uuid":"1031983258","full_name":"soundphilosopher/basic-grpc-service-go","owner":"soundphilosopher","description":"Basic gRPC service written in go","archived":false,"fork":false,"pushed_at":"2025-12-11T14:06:10.000Z","size":59,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-12T17:53:29.580Z","etag":null,"topics":["cloudevents","go","grpc","learning","protobuf"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/soundphilosopher.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-04T16:13:56.000Z","updated_at":"2025-12-11T14:06:14.000Z","dependencies_parsed_at":"2025-09-04T11:19:08.129Z","dependency_job_id":"6d8eefcd-6b7d-4162-b370-cbf2dc204429","html_url":"https://github.com/soundphilosopher/basic-grpc-service-go","commit_stats":null,"previous_names":["soundphilosopher/basic-grpc-service-go"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/soundphilosopher/basic-grpc-service-go","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soundphilosopher%2Fbasic-grpc-service-go","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soundphilosopher%2Fbasic-grpc-service-go/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soundphilosopher%2Fbasic-grpc-service-go/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soundphilosopher%2Fbasic-grpc-service-go/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/soundphilosopher","download_url":"https://codeload.github.com/soundphilosopher/basic-grpc-service-go/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soundphilosopher%2Fbasic-grpc-service-go/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28439828,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-15T00:34:46.850Z","status":"ssl_error","status_checked_at":"2026-01-15T00:34:46.551Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cloudevents","go","grpc","learning","protobuf"],"created_at":"2026-01-15T00:37:29.141Z","updated_at":"2026-01-15T00:37:29.930Z","avatar_url":"https://github.com/soundphilosopher.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🚀 Basic gRPC Service\n\n[![Go Version](https://img.shields.io/github/go-mod/go-version/soundphilosopher/basic-grpc-service-go)](https://golang.org/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Go Report Card](https://goreportcard.com/badge/github.com/soundphilosopher/basic-grpc-service-go)](https://goreportcard.com/report/github.com/soundphilosopher/basic-grpc-service-go)\n[![ConnectRPC](https://img.shields.io/badge/ConnectRPC-v1.18.1-blue.svg)](https://connectrpc.com/)\n[![HTTP/3](https://img.shields.io/badge/HTTP%2F3-supported-green.svg)](https://tools.ietf.org/html/rfc9114)\n\nA modern, high-performance gRPC service built with Go, featuring ConnectRPC, dual HTTP/2 and HTTP/3 support, and comprehensive observability.\n\n## ✨ Features\n\n- **Modern gRPC**: Built with [ConnectRPC](https://connectrpc.com/) for better developer experience\n- **Dual Protocol Support**: HTTP/2 and HTTP/3 on the same port\n- **CloudEvents Integration**: All responses wrapped in CloudEvents for better event-driven architecture\n- **TLS Security**: Local development certificates with mkcert\n- **Health Checks**: Built-in gRPC health checking\n- **Service Reflection**: Automatic service discovery and introspection\n- **Streaming Support**: Bidirectional streaming capabilities\n- **Background Processing**: Asynchronous task processing with state management\n- **Fan-out/Fan-in Pattern**: Demonstrates concurrent service calls and response aggregation\n- **Docker Support**: Multi-stage Docker build for optimized container deployment\n- **Configurable Address**: Command-line flag support for server address configuration\n\n## 🛠️ Tech Stack\n\n- **Language**: Go 1.24+\n- **RPC Framework**: ConnectRPC\n- **Protocol Buffers**: buf CLI for code generation\n- **TLS**: mkcert for local certificate management\n- **HTTP/3**: QUIC protocol support\n- **State Management**: Custom in-memory state manager\n- **Observability**: Structured logging and health monitoring\n- **Containerization**: Docker with Alpine Linux base\n\n## 📋 Prerequisites\n\nBefore running this service, make sure you have:\n\n- Go 1.21 or later\n- [buf CLI](https://buf.build/docs/installation)\n- [mkcert](https://github.com/FiloSottile/mkcert) for local TLS certificates\n- Docker (optional, for containerized deployment)\n\n## 🚀 Quick Start\n\n### Option 1: Native Go Development\n\n#### 1. Clone and Setup\n\n```bash\ngit clone https://github.com/soundphilosopher/basic-grpc-service-go\ncd basic-grpc-service-go\n```\n\n#### 2. Generate TLS Certificates\n\n```bash\n# Install mkcert (if not already installed)\n# On macOS: brew install mkcert\n# On Linux: see mkcert installation docs\n\n# Create local CA\nmkcert -install\n\n# Generate certificates for localhost\nmkdir -p certs\nmkcert -key-file certs/local.key -cert-file certs/local.crt localhost 127.0.0.1 0.0.0.0 ::1\n```\n\n#### 3. Generate Protocol Buffer Code\n\n```bash\nbuf generate\n```\n\n#### 4. Install Dependencies\n\n```bash\ngo mod tidy\n```\n\n#### 5. Run the Service\n\n```bash\n# Run with default address (127.0.0.1:8443)\ngo run main.go\n\n# Run with custom address\ngo run main.go -server-addr \"0.0.0.0:9090\"\n```\n\n### Option 2: Docker Deployment\n\n#### 1. Generate TLS Certificates\n\n```bash\n# Create certificates directory\nmkdir -p certs\n\n# Generate certificates for localhost and Docker environments\nmkcert -key-file certs/local.key -cert-file certs/local.crt localhost 127.0.0.1 0.0.0.0 ::1\n```\n\n#### 2. Build Docker Image\n\n```bash\n# Build the Docker image\ndocker build -f docker/Dockerfile -t basic-grpc-service:0.1.0 .\n```\n\n#### 3. Run Docker Container\n\n```bash\n# Run with default address (127.0.0.1:8443)\ndocker run -d \\\n  --name grpc-service \\\n  -p 8443:8443/tcp \\\n  -p 8443:8443/udp \\\n  -v $(pwd)/certs:/app/certs:ro \\\n  basic-grpc-service:0.1.0\n\n# Run with custom address (bind to all interfaces)\ndocker run -d \\\n  --name grpc-service \\\n  -p 9090:9090/tcp \\\n  -p 9090:9090/udp \\\n  -v $(pwd)/certs:/app/certs:ro \\\n  basic-grpc-service:0.1.0 grpc-server -server-addr \"0.0.0.0:9090\"\n```\n\n#### 4. Verify Container Status\n\n```bash\n# Check container logs\ndocker logs grpc-service\n\n# Test the service\ncurl -k --http2 -X POST https://localhost:8443/basic.v1.BasicService/Hello \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"message\":\"World\"}'\n```\n\nThe service will start with both HTTP/2 and HTTP/3 support.\n\n## ⚙️ Configuration\n\n### Command Line Flags\n\n- **`-server-addr`**: Server bind address (default: `127.0.0.1:8443`)\n\n```bash\n# Examples\n./grpc-server -server-addr \"0.0.0.0:8080\"    # Bind to all interfaces on port 8080\n./grpc-server -server-addr \"localhost:9443\"   # Bind to localhost on port 9443\n./grpc-server -h                               # Show help with available flags\n```\n\n## 🏗️ Project Structure\n\n```text\n├── certs/              # TLS certificates\n├── docker/             # Docker configuration\n│   └── Dockerfile     # Multi-stage Docker build\n├── examples/           # Usage examples and demos\n├── internal/           # Private application code\n│   ├── talk/          # Conversation logic\n│   └── utils/         # Utility functions\n├── proto/             # Protocol buffer definitions\n│   ├── basic/         # Service definitions\n│   └── io/            # CloudEvents definitions\n├── sdk/               # Generated gRPC code\n├── buf.gen.yaml       # Buf code generation config\n├── buf.yaml           # Buf project config\n├── go.mod             # Go dependencies\n└── main.go            # Application entry point\n```\n\n## 🔧 Development\n\n### Regenerate Protocol Buffers\n\n```bash\nbuf generate --clean\n```\n\n### Update Dependencies\n\n```bash\ngo mod tidy\ngo mod verify\n```\n\n### Format and Lint\n\n```bash\ngo fmt ./...\ngo vet ./...\n```\n\n### Docker Development\n\n```bash\n# Rebuild Docker image\ndocker build -f docker/Dockerfile -t basic-grpc-service:0.1.0 .\n\n# Run in development mode with live logs\ndocker run --rm \\\n  -p 8443:8443/tcp \\\n  -p 8443:8443/udp \\\n  -v $(pwd)/certs:/app/certs:ro \\\n  basic-grpc-service:0.1.0\n\n# Clean up containers and images\ndocker rm -f grpc-service\ndocker rmi basic-grpc-service\n```\n\n## 🚦 Health Monitoring\n\nThe service includes comprehensive health checking:\n\n- **Health Check Endpoint**: Standard gRPC health checking\n- **Service Reflection**: Automatic API documentation\n- **TLS Status**: Secure connections monitoring\n- **State Management**: Background task status tracking\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.\n\n## 🆘 Troubleshooting\n\n### Certificate Issues\nIf you encounter TLS certificate errors:\n```bash\n# Regenerate certificates\nrm -rf certs/\nmkdir certs\nmkcert -key-file certs/local.key -cert-file certs/local.crt localhost 127.0.0.1 0.0.0.0 ::1\n```\n\n### Port Configuration\nChange the server address using the command-line flag:\n```bash\n# Native Go\ngo run main.go -server-addr \"127.0.0.1:9000\"\n\n# Docker\ndocker run -p 9000:9000/tcp -p 9000:9000/udp \\\n  -v $(pwd)/certs:/app/certs:ro \\\n  basic-grpc-service -server-addr \"0.0.0.0:9000\"\n```\n\n### Docker Issues\n\n**Container won't start:**\n```bash\n# Check logs\ndocker logs grpc-service\n\n# Verify certificates are mounted\ndocker run --rm -v $(pwd)/certs:/app/certs:ro alpine ls -la /app/certs\n```\n\n**Port binding conflicts:**\n```bash\n# Use different ports\ndocker run -p 9090:8443/tcp -p 9090:8443/udp basic-grpc-service\n```\n\n### Protocol Buffer Generation Fails\nEnsure buf CLI is properly installed and run:\n```bash\nbuf mod update\nbuf generate\n```\n\n## 🐳 Docker Details\n\nThe Docker image uses a multi-stage build:\n\n1. **Build Stage**: Uses `golang:1.24-alpine3.22` to compile the Go application\n2. **Runtime Stage**: Uses minimal `alpine:3.22` for a small, secure final image\n\n**Benefits:**\n- Small image size (~15MB final image)\n- Security-focused with minimal attack surface\n- Optimized for production deployment\n- Efficient layer caching for fast rebuilds\n\n## 🔗 Useful Links\n\n- [ConnectRPC Documentation](https://connectrpc.com/docs/)\n- [Protocol Buffers Guide](https://protobuf.dev/)\n- [buf CLI Reference](https://buf.build/docs/)\n- [gRPC Health Checking](https://github.com/grpc/grpc/blob/master/doc/health-checking.md)\n- [HTTP/3 Specification](https://tools.ietf.org/html/rfc9114)\n- [Docker Multi-stage Builds](https://docs.docker.com/build/building/multi-stage/)\n\n---\n\n**Built with ❤️ and Go\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoundphilosopher%2Fbasic-grpc-service-go","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsoundphilosopher%2Fbasic-grpc-service-go","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoundphilosopher%2Fbasic-grpc-service-go/lists"}