{"id":20543562,"url":"https://github.com/bavix/gripmock","last_synced_at":"2026-04-25T22:01:01.817Z","repository":{"id":189063326,"uuid":"679188193","full_name":"bavix/gripmock","owner":"bavix","description":"The fastest and most reliable gRPC mock server for testing and development","archived":false,"fork":false,"pushed_at":"2026-04-17T21:17:25.000Z","size":19826,"stargazers_count":62,"open_issues_count":0,"forks_count":8,"subscribers_count":3,"default_branch":"master","last_synced_at":"2026-04-17T22:40:10.187Z","etag":null,"topics":["gripmock","grpc-mock","grpc-mock-server","grpc-mocking","mock","mock-server","mockserver","service"],"latest_commit_sha":null,"homepage":"https://bavix.github.io/gripmock/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"tokopedia/gripmock","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bavix.png","metadata":{"files":{"readme":"README.md","changelog":"changelog.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","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},"funding":{"buy_me_a_coffee":"babichev"}},"created_at":"2023-08-16T09:37:44.000Z","updated_at":"2026-04-17T21:17:29.000Z","dependencies_parsed_at":"2026-02-18T00:01:01.764Z","dependency_job_id":"de27ee9d-5d86-4b0f-85e9-802a51606efb","html_url":"https://github.com/bavix/gripmock","commit_stats":{"total_commits":698,"total_committers":20,"mean_commits":34.9,"dds":"0.47851002865329517","last_synced_commit":"722ba8a6210e7a59c6230874b13d61eff1009b30"},"previous_names":["bavix/gripmock"],"tags_count":121,"template":false,"template_full_name":null,"purl":"pkg:github/bavix/gripmock","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bavix%2Fgripmock","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bavix%2Fgripmock/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bavix%2Fgripmock/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bavix%2Fgripmock/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bavix","download_url":"https://codeload.github.com/bavix/gripmock/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bavix%2Fgripmock/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32278249,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-25T18:29:39.964Z","status":"ssl_error","status_checked_at":"2026-04-25T18:29:32.149Z","response_time":59,"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":["gripmock","grpc-mock","grpc-mock-server","grpc-mocking","mock","mock-server","mockserver","service"],"created_at":"2024-11-16T01:38:47.848Z","updated_at":"2026-04-25T22:01:01.810Z","avatar_url":"https://github.com/bavix.png","language":"Go","funding_links":["https://buymeacoffee.com/babichev"],"categories":[],"sub_categories":[],"readme":"![GripMock](https://github.com/bavix/gripmock/assets/5111255/d1fc10ef-2149-4302-8e24-aef4fdfe043c)\n\n[![Coverage Status](https://coveralls.io/repos/github/bavix/gripmock/badge.svg?branch=master)](https://coveralls.io/github/bavix/gripmock?branch=master)\n[![Go Report Card](https://goreportcard.com/badge/github.com/bavix/gripmock/v3)](https://goreportcard.com/report/github.com/bavix/gripmock/v3)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n# GripMock 🚀\n\n**Languages:** English | [简体中文](README.zh-CN.md)\n\n**The fastest and most reliable gRPC mock server** for testing and development.\n\nGripMock creates a mock server from your `.proto` files or compiled `.pb` descriptors, making gRPC testing simple and efficient. Perfect for end-to-end testing, development environments, and CI/CD pipelines.\n\n![greeter](https://raw.githubusercontent.com/bavix/.github/master/svgs/gripmock-greeter.gif)\n\n## ✨ Features\n\n- **Native Runtime** - Single in-process engine without runtime gRPC code generation\n- **Descriptor Sources** - Load API from `.proto`, compiled `.pb`, BSR modules, or gRPC reflection\n- **Dynamic `.pb` Service Loading** - Load compiled protobuf descriptors at runtime via API without restarts\n- **Hot Stub Management** - Create, update, and remove stubs via API/UI without server restarts\n- **Flexible Matching** - `equals`, `contains`, `matches`, headers, priority, and match limits\n- **Array-Aware Matching** - Optional array-order flexibility to reduce brittle test assertions\n- **Dynamic Templates** - Build responses from request payload, headers, and stream context\n- **Complete gRPC Coverage** - Unary, server streaming, client streaming, and bidirectional streaming\n- **Error, Details, and Delay Simulation** - Return realistic gRPC status codes, details (`Any`), and response timing\n- **TLS and mTLS Support** - Run secure gRPC/HTTP test environments with native TLS options\n- **Advanced Protobuf Type Support** - Handle well-known and extended protobuf types (`google.protobuf.*`, `google.type.*`)\n- **YAML/JSON + Schema** - Author stubs in either format with JSON Schema IDE validation\n- **Plugin Ecosystem** - Extend functions with Go plugins and matching builder image tags\n- **Built-in Faker Templates** - Generate realistic fake person/contact/geo/network data directly in templates (`faker.*`)\n- **OpenTelemetry Tracing** - OTLP tracing for gRPC and HTTP paths (`otelgrpc` + `otelhttp`)\n- **Prometheus Metrics (`/metrics`)** - Runtime/process metrics (`go_*`, `process_*`) plus GripMock metrics\n- **Operational APIs** - Health endpoints, descriptors API, stubs API, and web dashboard\n- **Embedded SDK (Experimental)** - Run GripMock inside Go tests/services with verification helpers\n- **MCP API (Experimental)** - Streamable MCP endpoint for agent and tool integrations\n- **Upstream Modes (Experimental)** - `proxy`, `replay`, `capture` modes for gradual migration from live upstream services to local mocks\n\n## 📚 Documentation\n\n**[Full Documentation](https://bavix.github.io/gripmock)** - Complete guide with examples\n\n- **Descriptor API (`/api/descriptors`)**: runtime loading of compiled proto descriptors (`.pb`) with validated curl workflow: [docs](https://bavix.github.io/gripmock/guide/api/descriptors)\n- **Upstream Modes (Experimental)**: `proxy`, `replay`, `capture` with practical rollout guidance: [docs](https://bavix.github.io/gripmock/guide/modes)\n- **Embedded SDK (Experimental)**: in-process testing with stubs, verification, `sdk.By(fullMethod)` helpers, and context-aware remote checks: [docs](https://bavix.github.io/gripmock/guide/embedded-sdk)\n- **Faker Reference**: built-in faker key-by-key catalog with examples: [docs](https://bavix.github.io/gripmock/guide/stubs/faker)\n- **OpenTelemetry + Metrics**: tracing env vars and `/metrics` behavior: [docs](https://bavix.github.io/gripmock/guide/introduction/advanced-usage)\n- **GitHub Actions (CI/CD)**: official workflow action to download, start, wait for readiness, and stop GripMock automatically: [docs](https://bavix.github.io/gripmock/guide/ci-cd/github-actions)\n\n## 🧬 Project Evolution\n\nGripMock started as a fork of [tokopedia/gripmock](https://github.com/tokopedia/gripmock), and then evolved into an independent, fully rewritten project.\n\nToday GripMock is an independent runtime focused on practical testing workflows:\n\n- Native in-process architecture (no runtime code generation)\n- Flexible descriptor sources and runtime operations (hot stubs + descriptors API)\n- Production-style testing features (streaming, templates, upstream modes, plugins, SDK, MCP)\n\nFor architecture details and benchmark methodology, see: [Performance Comparison](https://bavix.github.io/gripmock/guide/introduction/performance-comparison)\n\n## 🖥️ Web Interface\n\n![gripmock-ui](https://raw.githubusercontent.com/bavix/.github/master/svgs/gripmock-ui.gif)\n\nAccess the web dashboard at `http://localhost:4771/` to manage your stubs visually.\n\n## 🚀 Quick Start\n\n### Installation\n\nChoose your preferred installation method:\n\n#### Homebrew (Recommended)\n```bash\nbrew tap gripmock/tap\nbrew install --cask gripmock\n```\n\n#### Shell Script\n```bash\ncurl -s https://raw.githubusercontent.com/bavix/gripmock/refs/heads/master/setup.sh | sh -s\n```\n\n#### PowerShell (Windows)\n```powershell\nirm https://raw.githubusercontent.com/bavix/gripmock/refs/heads/master/setup.ps1 | iex\n```\n\n#### Docker\n```bash\ndocker pull bavix/gripmock\n```\n\nFor plugin builds, use the paired builder image:\n\n```bash\ndocker pull bavix/gripmock:v3.7.1-builder\n```\n\n#### Go Install\n```bash\ngo install github.com/bavix/gripmock/v3@latest\n```\n\n### Basic Usage\n\n**Start with a `.proto` file:**\n```bash\ngripmock service.proto\n```\n\n**Add static stubs:**\n```bash\ngripmock --stub stubs/ service.proto\n```\n\n**Load API directly from Buf Schema Registry (BSR):**\n```bash\ngripmock --stub third_party/bsr/eliza buf.build/connectrpc/eliza\n```\n\n**Load API from live gRPC server reflection:**\n```bash\ngripmock grpc://localhost:50051\ngripmock grpcs://api.company.local:443\n```\n\nWith options:\n```bash\ngripmock grpc://localhost:50051?timeout=10s\ngripmock grpcs://10.0.0.5:8443?serverName=api.company.local\ngripmock grpc://localhost:50051?bearer=\u003ctoken\u003e\n```\n\n**Use upstream modes over reflection (Experimental):**\n```bash\n# Pure reverse proxy through GripMock\ngripmock grpc+proxy://localhost:50051\n\n# Local stubs first, then upstream fallback on matcher miss\ngripmock grpc+replay://localhost:50051\n\n# Replay + record upstream misses into GripMock stubs\ngripmock grpc+capture://localhost:50051\n```\n\nFor private BSR modules:\n```bash\nBSR_BUF_TOKEN=\u003ctoken\u003e gripmock --stub stubs/ buf.build/acme/private-api\n```\n\nFor self-hosted BSR:\n```bash\nBSR_SELF_BASE_URL=https://bsr.company.local \\\nBSR_SELF_TOKEN=\u003ctoken\u003e \\\ngripmock --stub stubs/ bsr.company.local/team/payments\n```\n\n**Using Docker:**\n```bash\ndocker run -p 4770:4770 -p 4771:4771 \\\n  -v $(pwd)/stubs:/stubs \\\n  -v $(pwd)/proto:/proto \\\n  bavix/gripmock --stub=/stubs /proto/service.proto\n```\n\n- **Port 4770**: gRPC server\n- **Port 4771**: Web UI and REST API\n\n### Observability (v3.10.0)\n\n```bash\nOTEL_ENABLED=true \\\nOTEL_EXPORTER_OTLP_ENDPOINT=localhost:4317 \\\nOTEL_EXPORTER_OTLP_INSECURE=true \\\ngripmock --stub stubs/ service.proto\n```\n\n- `GET /metrics` is always available\n- Tracing export is enabled only when `OTEL_ENABLED=true`\n\n## 🤖 GitHub Actions (CI/CD)\n\nUse the official action [`bavix/gripmock-action`](https://github.com/bavix/gripmock-action) to run GripMock in CI pipelines.\n\n```yaml\nname: test\n\non: [push, pull_request]\n\njobs:\n  e2e:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v5\n\n      - name: Start GripMock\n        uses: bavix/gripmock-action@v1\n        with:\n          source: proto/service.proto\n          stub: stubs\n\n      - name: Run tests\n        run: go test ./...\n```\n\nWhat the action does:\n\n- Downloads GripMock from GitHub Releases (`latest` or pinned `version`)\n- Starts GripMock in background and waits for readiness (`/api/health/readiness`)\n- Exposes addresses via outputs (`grpc-addr`, `http-addr`) for test steps\n- Stops GripMock automatically in the post step\n\nMore examples and full inputs/outputs: [GitHub Actions guide](https://bavix.github.io/gripmock/guide/ci-cd/github-actions).\n\n## 📖 Examples\n\nCheck out our comprehensive examples in the [`examples`](https://github.com/bavix/gripmock/tree/master/examples) folder:\n\n- **Streaming** - Server, client, and bidirectional streaming\n- **File Uploads** - Test chunked file uploads\n- **Real-time Chat** - Bidirectional communication\n- **Data Feeds** - Continuous data streaming\n- **Authentication** - Header-based auth testing\n- **Performance** - High-throughput scenarios\n\n### Greeter: dynamic stub demo\n\nStub (universal):\n\n```yaml\n# yaml-language-server: $schema=https://bavix.github.io/gripmock/schema/stub.json\n# examples/projects/greeter/stub_say_hello.yaml\n- service: helloworld.Greeter\n  method: SayHello\n  input:\n    matches:\n      name: \".+\"\n  output:\n    data:\n      message: \"Hello, {{.Request.name}}!\"  # dynamic template lives in output\n```\n\nNotes:\n- Put dynamic templates only in `output` (e.g., `data`, `headers`, `stream`).\n- Keep `input` matching static (no `{{ ... }}` in `equals`/`contains`/`matches`).\n\n```bash\n# Start server\ngo run main.go examples/projects/greeter/service.proto --stub examples/projects/greeter\n\n# Call via grpcurl\ngrpcurl -plaintext -d '{\"name\":\"Alex\"}' localhost:4770 helloworld.Greeter/SayHello\n```\n\nExpected response:\n\n```json\n{\n  \"message\": \"Hello, Alex!\"\n}\n```\n\n## 🔧 Stubbing\n\n### Basic Stub Example\n\n```yaml\nservice: Greeter\nmethod: SayHello\ninput:\n  equals:\n    name: \"gripmock\"\noutput:\n  data:\n    message: \"Hello GripMock!\"\n```\n\n### Advanced Features\n\n**Priority System:**\n```yaml\n- service: UserService\n  method: GetUser\n  priority: 100  # Higher priority\n  input:\n    equals:\n      id: \"admin\"\n  output:\n    data:\n      role: \"administrator\"\n\n- service: UserService\n  method: GetUser\n  priority: 1    # Lower priority (fallback)\n  input:\n    contains:\n      id: \"user\"\n  output:\n    data:\n      role: \"user\"\n```\n\n**Streaming Support:**\n```yaml\nservice: TrackService\nmethod: StreamData\ninput:\n  equals:\n    sensor_id: \"GPS001\"\noutput:\n  stream:\n    - position: {\"lat\": 40.7128, \"lng\": -74.0060}\n      timestamp: \"2024-01-01T12:00:00Z\"\n    - position: {\"lat\": 40.7130, \"lng\": -74.0062}\n      timestamp: \"2024-01-01T12:00:05Z\"\n```\n\n### Dynamic Templates\n\nGripMock supports dynamic templates in the `output` section using Go's `text/template` syntax.\n\n- Access request fields: `{{.Request.field}}`\n- Access headers: `{{.Headers.header_name}}`\n- Client streaming context: `{{.Requests}}` (slice of received messages), `{{len .Requests}}`, `{{(index .Requests 0).field}}`\n- Bidirectional streaming: `{{.MessageIndex}}` gives the current message index (0-based)\n- Math helpers: `sum`, `avg`, `mul`, `min`, `max`, `add`, `sub`, `div`\n- Utility: `json`, `split`, `join`, `upper`, `lower`, `title`, `sprintf`, `int`, `int64`, `float`, `round`, `floor`, `ceil`\n- Built-in faker: `faker.Person.*`, `faker.Contact.*`, `faker.Geo.*`, `faker.Network.*`, `faker.Identity.*`\n\nImportant rules:\n- Do not use dynamic templates inside `input.equals`, `input.contains`, or `input.matches` (matching must be static)\n- For server streaming, if both `output.stream` and `output.error`/`output.code` are set, messages are sent first and then the error is returned. If `output.stream` is empty, the error is returned immediately\n\n**Header Matching:**\n```yaml\nservice: AuthService\nmethod: ValidateToken\nheaders:\n  equals:\n    authorization: \"Bearer valid-token\"\ninput:\n  equals:\n    token: \"abc123\"\noutput:\n  data:\n    valid: true\n    user_id: \"user123\"\n```\n\n## 🔍 Input Matching\n\nGripMock supports three powerful matching strategies:\n\n### 1. Exact Match (`equals`)\n```yaml\ninput:\n  equals:\n    name: \"gripmock\"\n    age: 25\n    active: true\n```\n\n### 2. Partial Match (`contains`)\n```yaml\ninput:\n  contains:\n    name: \"grip\"  # Matches \"gripmock\", \"gripster\", etc.\n```\n\n### 3. Regex Match (`matches`)\n```yaml\ninput:\n  matches:\n    email: \"^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\\\.[a-zA-Z]{2,}$\"\n    phone: \"^\\\\+?[1-9]\\\\d{1,14}$\"\n```\n\n## 🛠️ API\n\n### REST API Endpoints\n\n- `GET /api/stubs` - List all stubs\n- `POST /api/descriptors` - Load protobuf descriptor set (`FileDescriptorSet`) at runtime\n- `POST /api/stubs` - Add new stub\n- `POST /api/stubs/search` - Find matching stub\n- `DELETE /api/stubs` - Clear all stubs\n- `GET /api/health/liveness` - Health check\n- `GET /api/health/readiness` - Readiness check\n\n### Example API Usage\n\n```bash\n# Add a stub\ncurl -X POST http://localhost:4771/api/stubs \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"service\": \"Greeter\",\n    \"method\": \"SayHello\",\n    \"input\": {\"equals\": {\"name\": \"world\"}},\n    \"output\": {\"data\": {\"message\": \"Hello World!\"}}\n  }'\n\n# Search for matching stub\ncurl -X POST http://localhost:4771/api/stubs/search \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"service\": \"Greeter\",\n    \"method\": \"SayHello\",\n    \"data\": {\"name\": \"world\"}\n  }'\n```\n\n## 📋 JSON Schema Support\n\nAdd schema validation to your stub files for IDE support:\n\n**JSON files:**\n```json\n{\n  \"$schema\": \"https://bavix.github.io/gripmock/schema/stub.json\",\n  \"service\": \"MyService\",\n  \"method\": \"MyMethod\"\n}\n```\n\n**YAML files:**\n```yaml\n# yaml-language-server: $schema=https://bavix.github.io/gripmock/schema/stub.json\nservice: MyService\nmethod: MyMethod\n```\n\n## 🌐 BSR Integration\n\nGripMock supports simplified integration with Buf Schema Registry:\n\n### Configuration\n\n```bash\n# Public BSR (default)\nBSR_BUF_BASE_URL=https://buf.build\nBSR_BUF_TOKEN=\u003ctoken\u003e\n\n# Self-hosted BSR\nBSR_SELF_BASE_URL=https://bsr.company.local\nBSR_SELF_TOKEN=\u003ctoken\u003e\n```\n\n### Usage\n\n```bash\n# Public module\ngripmock buf.build/connectrpc/eliza\n\n# Self-hosted module  \ngripmock bsr.company.local/team/payments:main\n\n# With stubs\ngripmock --stub stubs/ bsr.company.local/team/payments\n```\n\n### Routing\n\nGripMock automatically routes modules:\n- `buf.build/owner/repo` → uses Buf profile\n- `bsr.company.local/owner/repo` → uses Self profile\n\nFor details see [BSR Documentation](https://bavix.github.io/gripmock/guide/sources/bsr).\n\n## 🔎 gRPC Reflection Source\n\nGripMock supports descriptor loading from gRPC reflection using endpoint schemes:\n\n- `grpc://host:port` (insecure)\n- `grpcs://host:port` (TLS)\n\nSupported query parameters:\n\n- `timeout` (default `5s`)\n- `bearer` (Authorization token)\n- `serverName` (TLS SNI override)\n\nExamples:\n\n```bash\ngripmock grpc://localhost:50051\ngripmock grpcs://api.company.local:443\ngripmock grpcs://10.0.0.5:8443?serverName=api.company.local\n```\n\nFull guide: [gRPC Reflection Source](https://bavix.github.io/gripmock/guide/sources/grpc-reflection).\n\n## 🔁 Upstream Modes (Experimental)\n\n⚠️ **EXPERIMENTAL FEATURE**: Upstream modes may change without notice.\n\nUpstream modes work on top of reflection sources and define runtime behavior:\n\n- `proxy` - pure reverse proxy\n- `replay` - local-first + upstream fallback\n- `capture` - replay + automatic stub recording from upstream\n\nMode guides:\n\n- [Upstream Modes Overview](https://bavix.github.io/gripmock/guide/modes)\n- [Proxy Mode](https://bavix.github.io/gripmock/guide/modes/proxy)\n- [Replay Mode](https://bavix.github.io/gripmock/guide/modes/replay)\n- [Capture Mode](https://bavix.github.io/gripmock/guide/modes/capture)\n\n## 📊 Benchmark Charts\n\n![Image size benchmark](docs/public/bench/image-size.svg)\n![Startup readiness benchmark](docs/public/bench/startup-ready.svg)\n![Latency percentiles benchmark](docs/public/bench/latency-percentiles.svg)\n![Throughput benchmark](docs/public/bench/throughput-rps.svg)\n\n## 🔗 Useful Resources\n\n- 📖 **[Documentation](https://bavix.github.io/gripmock)** - Complete guides and examples\n- 🧪 **[Testing gRPC with Testcontainers](https://medium.com/skyro-tech/testing-grpc-client-with-mock-server-and-testcontainers-f51cb8a6be9a)** - Article by [@AndrewIISM](https://github.com/AndrewIISM)\n- 📋 **[JSON Schema](https://bavix.github.io/gripmock/schema/stub.json)** - Stub validation schema\n- 🔗 **[OpenAPI](https://bavix.github.io/gripmock-openapi/)** - REST API documentation\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n## 📄 License\n\nThis project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.\n\n---\n\n**Made with ❤️ by the GripMock community**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbavix%2Fgripmock","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbavix%2Fgripmock","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbavix%2Fgripmock/lists"}