{"id":36483893,"url":"https://github.com/z5labs/humus","last_synced_at":"2026-01-12T01:07:34.315Z","repository":{"id":257190150,"uuid":"852564407","full_name":"z5labs/humus","owner":"z5labs","description":"Opiniated Go framework for building various Z5Labs projects","archived":false,"fork":false,"pushed_at":"2026-01-03T00:50:01.000Z","size":16339,"stargazers_count":1,"open_issues_count":19,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-07T23:12:09.242Z","etag":null,"topics":["go","golang","grpc","grpc-go","rest-api","restful"],"latest_commit_sha":null,"homepage":"https://z5labs.dev/humus/","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/z5labs.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":"2024-09-05T02:58:00.000Z","updated_at":"2026-01-02T21:22:32.000Z","dependencies_parsed_at":null,"dependency_job_id":"e32f3346-95bc-4e8a-999c-0317a70124e2","html_url":"https://github.com/z5labs/humus","commit_stats":null,"previous_names":["z5labs/humus"],"tags_count":28,"template":false,"template_full_name":null,"purl":"pkg:github/z5labs/humus","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/z5labs%2Fhumus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/z5labs%2Fhumus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/z5labs%2Fhumus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/z5labs%2Fhumus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/z5labs","download_url":"https://codeload.github.com/z5labs/humus/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/z5labs%2Fhumus/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28330241,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T00:36:25.062Z","status":"ssl_error","status_checked_at":"2026-01-12T00:36:15.229Z","response_time":60,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: 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":["go","golang","grpc","grpc-go","rest-api","restful"],"created_at":"2026-01-12T01:07:30.368Z","updated_at":"2026-01-12T01:07:34.310Z","avatar_url":"https://github.com/z5labs.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Humus\n\n[![Go Reference](https://pkg.go.dev/badge/github.com/z5labs/humus.svg)](https://pkg.go.dev/github.com/z5labs/humus)\n[![Go Report Card](https://goreportcard.com/badge/github.com/z5labs/humus)](https://goreportcard.com/report/github.com/z5labs/humus)\n![Coverage](https://img.shields.io/badge/Coverage-36.2%25-yellow)\n[![build](https://github.com/z5labs/humus/actions/workflows/build.yaml/badge.svg)](https://github.com/z5labs/humus/actions/workflows/build.yaml)\n\nA modular Go framework for building production-ready REST APIs, gRPC services, and batch jobs with built-in observability, health checks, and graceful shutdown.\n\nBuilt on top of [Bedrock](https://github.com/z5labs/bedrock), Humus provides standardized patterns and automatic instrumentation to help you focus on business logic while maintaining best practices.\n\n## Quick Start\n\n```go\npackage main\n\nimport (\n    \"context\"\n    \"net/http\"\n\n    \"github.com/z5labs/humus/rest\"\n    \"github.com/z5labs/humus/rest/rpc\"\n)\n\ntype HelloResponse struct {\n    Message string `json:\"message\"`\n}\n\nfunc main() {\n    rest.Run(rest.YamlSource(\"config.yaml\"), Init)\n}\n\nfunc Init(ctx context.Context, cfg rest.Config) (*rest.Api, error) {\n    api := rest.NewApi(\"Hello API\", \"1.0.0\")\n\n    handler := rpc.ProducerFunc[HelloResponse](func(ctx context.Context) (*HelloResponse, error) {\n        return \u0026HelloResponse{Message: \"Hello, World!\"}, nil\n    })\n\n    rest.Handle(http.MethodGet, rest.BasePath(\"/hello\"), rpc.ProduceJson(handler))\n    return api, nil\n}\n```\n\nYour API is now running with:\n- Automatic OpenAPI documentation at `/openapi.json`\n- Health endpoints at `/health/liveness` and `/health/readiness`\n- OpenTelemetry tracing and metrics\n- Graceful shutdown handling\n\n## Features\n\n### 🌐 REST Services\n- **OpenAPI 3.0** - Automatic spec generation from Go types\n- **Type-safe handlers** - Compile-time request/response validation\n- **Built-in authentication** - JWT, API keys, Basic auth, OAuth2\n- **Parameter validation** - Query params, headers, path params with regex support\n\n### 🔌 gRPC Services\n- **Auto-instrumentation** - OpenTelemetry interceptors built-in\n- **Health service** - Automatic gRPC health checks\n- **Service registration** - Simple, familiar gRPC patterns\n\n### ⚙️ Job/Batch Services\n- **One-off execution** - Run jobs with observability and lifecycle management\n- **Simple interface** - Just implement `Handle(ctx context.Context) error`\n\n### 📊 Observability\n- **OpenTelemetry SDK** - Traces, metrics, and logs out of the box\n- **Structured logging** - slog integration with context propagation\n- **Health monitoring** - Composable health check patterns\n\n## Installation\n\n```bash\ngo get github.com/z5labs/humus\n```\n\n## Documentation\n\n📚 **[Full Documentation](https://z5labs.dev/humus/)** - Comprehensive guides, examples, and API reference\n\n- [Getting Started](https://z5labs.dev/humus/getting-started/) - Installation and first service\n- [REST Services](https://z5labs.dev/humus/features/rest/) - Building HTTP APIs\n- [gRPC Services](https://z5labs.dev/humus/features/grpc/) - Building gRPC services\n- [Job Services](https://z5labs.dev/humus/features/job/) - Batch processing\n- [Authentication](https://z5labs.dev/humus/features/rest/authentication/) - Securing your APIs\n\n## Examples\n\nCheck out the [examples directory](./example) for complete, runnable examples:\n- [REST Petstore](./example/rest/petstore) - Full REST API example\n- [gRPC Petstore](./example/grpc/petstore) - gRPC service with health monitoring\n\n## AI Coding Agent Instructions\n\nIf you're using an AI coding agent (like GitHub Copilot, Cursor, etc.), copy the relevant instruction files from the [instructions/](./instructions/) directory to your project repository (e.g., `.github/`). These files provide your AI assistant with Humus framework best practices, project structure patterns, and common pitfalls to avoid.\n\n**Available instruction files:**\n- [humus-common.instructions.md](./instructions/humus-common.instructions.md) - Common patterns for all service types (required)\n- [humus-rest.instructions.md](./instructions/humus-rest.instructions.md) - REST API specific patterns\n- [humus-grpc.instructions.md](./instructions/humus-grpc.instructions.md) - gRPC service specific patterns\n- [humus-kafka.instructions.md](./instructions/humus-kafka.instructions.md) - Kafka queue processor specific patterns\n- [humus-job.instructions.md](./instructions/humus-job.instructions.md) - Job executor specific patterns\n\nCopy `humus-common.instructions.md` along with the file(s) specific to your application type.\n\n## Requirements\n\n- Go 1.24 or later\n\n## License\n\nReleased under the [MIT License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fz5labs%2Fhumus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fz5labs%2Fhumus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fz5labs%2Fhumus/lists"}