{"id":41075866,"url":"https://github.com/lastbackend/toolkit","last_synced_at":"2026-01-22T13:22:12.463Z","repository":{"id":209497507,"uuid":"418439228","full_name":"lastbackend/toolkit","owner":"lastbackend","description":"Toolkit is a framework for distributed systems","archived":false,"fork":false,"pushed_at":"2025-06-23T13:31:22.000Z","size":600,"stargazers_count":31,"open_issues_count":2,"forks_count":3,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-06-23T14:36:52.247Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lastbackend.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","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}},"created_at":"2021-10-18T09:52:35.000Z","updated_at":"2025-06-23T13:31:26.000Z","dependencies_parsed_at":"2024-04-04T13:45:08.682Z","dependency_job_id":"77883c77-c783-4771-96fd-677b0344598e","html_url":"https://github.com/lastbackend/toolkit","commit_stats":null,"previous_names":["lastbackend/toolkit"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/lastbackend/toolkit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lastbackend%2Ftoolkit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lastbackend%2Ftoolkit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lastbackend%2Ftoolkit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lastbackend%2Ftoolkit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lastbackend","download_url":"https://codeload.github.com/lastbackend/toolkit/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lastbackend%2Ftoolkit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28663784,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-22T01:17:37.254Z","status":"online","status_checked_at":"2026-01-22T02:00:07.137Z","response_time":144,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":[],"created_at":"2026-01-22T13:22:11.205Z","updated_at":"2026-01-22T13:22:12.455Z","avatar_url":"https://github.com/lastbackend.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# LastBackend Toolkit\n\n[![License](https://img.shields.io/:license-apache-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![GoDev](https://img.shields.io/badge/go.dev-reference-007d9c?logo=go\u0026logoColor=white\u0026style=flat-square)](https://pkg.go.dev/github.com/lastbackend/toolkit?tab=doc)\n[![Go Report Card](https://goreportcard.com/badge/github.com/lastbackend/toolkit)](https://goreportcard.com/report/github.com/lastbackend/toolkit)\n[![Discord](https://dcbadge.vercel.app/api/server/WhK9ujvem9)](https://discord.gg/WhK9ujvem9)\n\n**A comprehensive Go framework for building production-ready microservices with automatic code generation, multi-protocol support, and modular plugin architecture.**\n\nLastBackend Toolkit eliminates microservice boilerplate through protobuf-first development, enabling developers to focus on business logic while the framework handles infrastructure concerns.\n\n---\n\n## ✨ Key Features\n\n- 🔧 **Protobuf-First Development** - Define services in `.proto` files, get everything else generated\n- 🌐 **Multi-Protocol Support** - gRPC, HTTP REST, WebSocket from single definition  \n- 🔌 **Rich Plugin Ecosystem** - PostgreSQL, Redis, RabbitMQ, and [more plugins](https://github.com/lastbackend/toolkit-plugins)\n- 🏗️ **Automatic Code Generation** - Service interfaces, clients, mocks, and infrastructure\n- 💉 **Dependency Injection** - Built on Uber FX with automatic plugin registration\n- ⚙️ **Environment Configuration** - Hierarchical configuration with validation\n- 🧪 **Testing Ready** - Generated mocks and testing utilities\n- 📊 **Production Features** - Metrics, tracing, health checks, graceful shutdown\n\n## 🚀 Quick Start\n\n### Installation\n\n```bash\n# Install the toolkit CLI\ngo install github.com/lastbackend/toolkit/cli@latest\n\n# Install protoc plugins\ngo install google.golang.org/protobuf/cmd/protoc-gen-go@latest\ngo install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest\ngo install github.com/envoyproxy/protoc-gen-validate@latest\ngo install github.com/lastbackend/toolkit/protoc-gen-toolkit@latest\n```\n\n### Create Your First Service\n\n```bash\n# Generate a new microservice with PostgreSQL and Redis\ntoolkit init service github.com/yourorg/user-service --postgres-gorm --redis\n\ncd user-service\n\n# Initialize and generate code\nmake init proto update tidy\n\n# Run the service\ngo run main.go\n```\n\n### Define Your Service\n\n**`apis/user-service.proto`:**\n```protobuf\nsyntax = \"proto3\";\npackage userservice;\n\noption go_package = \"github.com/yourorg/user-service/gen;servicepb\";\n\nimport \"github.com/lastbackend/toolkit/protoc-gen-toolkit/toolkit/options/annotations.proto\";\nimport \"google/api/annotations.proto\";\nimport \"validate/validate.proto\";\n\n// Database plugin\noption (toolkit.plugins) = {\n  prefix: \"pgsql\"\n  plugin: \"postgres_gorm\"\n};\n\n// Cache plugin  \noption (toolkit.plugins) = {\n  prefix: \"cache\"\n  plugin: \"redis\"\n};\n\nservice UserService {\n  option (toolkit.runtime) = {\n    servers: [GRPC, HTTP]  // Multi-protocol support\n  };\n  \n  rpc CreateUser(CreateUserRequest) returns (CreateUserResponse) {\n    option (google.api.http) = {\n      post: \"/users\"\n      body: \"*\"\n    };\n  };\n  \n  rpc GetUser(GetUserRequest) returns (GetUserResponse) {\n    option (google.api.http) = {\n      get: \"/users/{user_id}\"\n    };\n  };\n}\n\nmessage CreateUserRequest {\n  string name = 1 [(validate.rules).string.min_len = 1];\n  string email = 2 [(validate.rules).string.pattern = \"^[^@]+@[^@]+\\\\.[^@]+$\"];\n}\n\nmessage CreateUserResponse {\n  string user_id = 1;\n  string status = 2;\n}\n\nmessage GetUserRequest {\n  string user_id = 1 [(validate.rules).string.uuid = true];\n}\n\nmessage GetUserResponse {\n  string user_id = 1;\n  string name = 2;\n  string email = 3;\n  google.protobuf.Timestamp created_at = 4;\n}\n```\n\n### Generated Code Usage\n\nThe toolkit generates everything you need:\n\n**`main.go`:**\n```go\npackage main\n\nimport (\n    \"context\"\n    servicepb \"github.com/yourorg/user-service/gen\"\n    \"github.com/yourorg/user-service/internal/server\"\n    \"github.com/lastbackend/toolkit/pkg/runtime\"\n)\n\nfunc main() {\n    // Service with automatic plugin initialization\n    app, err := servicepb.NewUserServiceService(\"user-service\",\n        runtime.WithVersion(\"1.0.0\"),\n        runtime.WithEnvPrefix(\"USER_SERVICE\"),\n    )\n    if err != nil {\n        panic(err)\n    }\n\n    // Register your business logic\n    app.Server().GRPC().SetService(server.NewUserServer)\n\n    // Start with gRPC and HTTP servers\n    if err := app.Start(context.Background()); err != nil {\n        panic(err)\n    }\n}\n```\n\n**`internal/server/server.go`:**\n```go\npackage server\n\nimport (\n    \"context\"\n    servicepb \"github.com/yourorg/user-service/gen\"\n)\n\ntype UserServer struct {\n    servicepb.UserServiceRpcServer\n    \n    app    toolkit.Service\n    pgsql  servicepb.PgsqlPlugin  // Auto-injected PostgreSQL\n    cache  servicepb.CachePlugin  // Auto-injected Redis\n}\n\n// Constructor with automatic dependency injection\nfunc NewUserServer(\n    app toolkit.Service,\n    pgsql servicepb.PgsqlPlugin,\n    cache servicepb.CachePlugin,\n) servicepb.UserServiceRpcServer {\n    return \u0026UserServer{app: app, pgsql: pgsql, cache: cache}\n}\n\nfunc (s *UserServer) CreateUser(ctx context.Context, req *CreateUserRequest) (*CreateUserResponse, error) {\n    // Use plugins directly - they're ready to go\n    user := \u0026User{Name: req.Name, Email: req.Email}\n    \n    // Save to PostgreSQL\n    if err := s.pgsql.DB().WithContext(ctx).Create(user).Error; err != nil {\n        return nil, err\n    }\n    \n    // Cache the user\n    s.cache.Client().Set(ctx, fmt.Sprintf(\"user:%s\", user.ID), user, time.Hour)\n    \n    return \u0026CreateUserResponse{\n        UserId: user.ID,\n        Status: \"created\",\n    }, nil\n}\n```\n\n### Configuration via Environment Variables\n\n```bash\n# Service configuration\nUSER_SERVICE_APP_NAME=user-service\nUSER_SERVICE_ENVIRONMENT=production\n\n# PostgreSQL plugin configuration (auto-parsed)\nUSER_SERVICE_PGSQL_HOST=localhost\nUSER_SERVICE_PGSQL_PORT=5432\nUSER_SERVICE_PGSQL_USERNAME=user\nUSER_SERVICE_PGSQL_PASSWORD=secret\nUSER_SERVICE_PGSQL_DATABASE=users_db\n\n# Redis plugin configuration (auto-parsed)\nUSER_SERVICE_CACHE_HOST=localhost\nUSER_SERVICE_CACHE_PORT=6379\nUSER_SERVICE_CACHE_PASSWORD=redispass\n```\n\n## 📚 Documentation\n\n- **[Getting Started](docs/getting-started.md)** - Detailed setup and first steps\n- **[Architecture Guide](docs/architecture.md)** - Framework concepts and design\n- **[Plugin System](docs/plugins/)** - Available plugins and development guide\n- **[Configuration](docs/configuration.md)** - Environment-based configuration\n- **[Testing](docs/testing.md)** - Testing strategies and generated mocks\n- **[Deployment](docs/deployment.md)** - Production deployment guide\n\n### For AI Agents\n- **[AI Instructions](.ai/INSTRUCTIONS.md)** - Complete guide for AI code generation\n- **[Usage Patterns](.ai/toolkit-usage.md)** - Common patterns and examples\n- **[Troubleshooting](.ai/troubleshooting.md)** - Common issues and solutions\n\n## 🔌 Plugin Ecosystem\n\nLastBackend Toolkit includes a rich set of plugins from [`toolkit-plugins`](https://github.com/lastbackend/toolkit-plugins):\n\n| Plugin | Purpose | Interface |\n|--------|---------|-----------|\n| **postgres_gorm** | PostgreSQL with GORM | `Plugin.DB() *gorm.DB` |\n| **postgres_pg** | PostgreSQL with go-pg | `Plugin.DB() *pg.DB` |\n| **redis** | Redis cache/pub-sub | `Plugin.Client() redis.Cmdable` |\n| **rabbitmq** | Message queue | `Plugin.Publish/Subscribe` |\n| **centrifuge** | Real-time messaging | `Plugin.Node() *centrifuge.Node` |\n| **sentry** | Error monitoring | Error tracking integration |\n\n### Using Plugins\n\n```protobuf\n// Declare plugins in your .proto file\noption (toolkit.plugins) = {\n  prefix: \"pgsql\"\n  plugin: \"postgres_gorm\"\n};\n\noption (toolkit.plugins) = {\n  prefix: \"cache\"  \n  plugin: \"redis\"\n};\n```\n\nPlugins are automatically:\n- ✅ Initialized with environment configuration\n- ✅ Registered for dependency injection\n- ✅ Managed through lifecycle hooks\n- ✅ Available as typed interfaces in your code\n\n## 🏗️ Examples\n\nExplore real-world examples in the [`examples/`](examples/) directory:\n\n- **[Basic Service](examples/helloworld/)** - Simple gRPC service\n- **[Full Microservice](examples/service/)** - Complete service with plugins\n- **[HTTP Gateway](examples/gateway/)** - HTTP-to-gRPC proxy\n- **[WebSocket Service](examples/wss/)** - Real-time WebSocket service\n\n## 🔄 Multi-Protocol Support\n\nDefine once, serve everywhere:\n\n```protobuf\nservice UserService {\n  option (toolkit.runtime) = {\n    servers: [GRPC, HTTP, WEBSOCKET]  // All protocols from one definition\n  };\n  \n  rpc GetUser(GetUserRequest) returns (GetUserResponse) {\n    // Available as gRPC call\n    option (google.api.http) = {\n      get: \"/users/{user_id}\"  // Also as HTTP GET\n    };\n  };\n  \n  rpc StreamUsers(StreamRequest) returns (StreamResponse) {\n    option (toolkit.route).websocket = true;  // And WebSocket\n  };\n}\n```\n\nYour service automatically provides:\n- 🔧 **gRPC** - High-performance RPC\n- 🌐 **HTTP REST** - Web-friendly APIs  \n- ⚡ **WebSocket** - Real-time communication\n- 🔀 **Proxying** - HTTP-to-gRPC and WebSocket-to-gRPC\n\n## 🧪 Testing Support\n\nGenerated testing utilities:\n\n```go\n// Generated mocks for all interfaces\nmockPlugin := new(tests.MockPgsqlPlugin)\nmockPlugin.On(\"DB\").Return(mockDB)\n\n// Generated client for integration tests\nclient := servicepb.NewUserServiceClient(conn)\nresp, err := client.GetUser(ctx, \u0026GetUserRequest{UserId: \"123\"})\n```\n\n## 🏢 Production Ready\n\nBuilt-in production features:\n- 📊 **Metrics** - Prometheus integration\n- 🔍 **Tracing** - Distributed tracing support  \n- 🏥 **Health Checks** - Kubernetes-ready health endpoints\n- 🛡️ **Graceful Shutdown** - Clean resource cleanup\n- ⚙️ **Configuration Validation** - Environment variable validation\n- 📝 **Structured Logging** - Contextual logging throughout\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see:\n- [Contributing Guidelines](CONTRIBUTING.md)\n- [Code of Conduct](CODE_OF_CONDUCT.md)\n- [Development Setup](docs/development.md)\n\n### Development\n\n```bash\n# Clone the repository\ngit clone https://github.com/lastbackend/toolkit.git\ncd toolkit\n\n# Install dependencies\nmake init\n\n# Run tests\nmake test\n\n# Generate examples\nmake examples\n```\n\n## 📄 License\n\nThis project is licensed under the Apache 2.0 License - see the [LICENSE](LICENSE) file for details.\n\n## 🌟 Why LastBackend Toolkit?\n\n**Before:**\n```go\n// Hundreds of lines of boilerplate\nserver := grpc.NewServer()\nmux := http.NewServeMux()\ndb, _ := gorm.Open(postgres.Open(dsn))\nredis := redis.NewClient(\u0026redis.Options{})\n// ... setup middleware, routing, health checks, etc.\n```\n\n**After:**\n```protobuf\n// Just describe what you want\noption (toolkit.plugins) = {\n  prefix: \"pgsql\" \n  plugin: \"postgres_gorm\"\n};\n\nservice UserService {\n  option (toolkit.runtime) = {\n    servers: [GRPC, HTTP]\n  };\n  // ... your business logic\n}\n```\n\n**Focus on what matters:** Your business logic, not infrastructure setup.\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**[Get Started](docs/getting-started.md)** • **[Examples](examples/)** • **[Discord](https://discord.gg/WhK9ujvem9)** • **[Documentation](docs/)**\n\nMade with ❤️ by the [LastBackend](https://github.com/lastbackend) team\n\n\u003c/div\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flastbackend%2Ftoolkit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flastbackend%2Ftoolkit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flastbackend%2Ftoolkit/lists"}