{"id":30039375,"url":"https://github.com/alitari/mockgo-server","last_synced_at":"2025-08-07T01:42:27.153Z","repository":{"id":61962918,"uuid":"516648358","full_name":"alitari/mockgo-server","owner":"alitari","description":"Lightweight and scalable server for mocking http endpoints","archived":false,"fork":false,"pushed_at":"2023-05-21T09:41:25.000Z","size":909,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-11-18T02:44:27.410Z","etag":null,"topics":["go","golang","golang-application","http","kubernetes","mock-server"],"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/alitari.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}},"created_at":"2022-07-22T07:10:36.000Z","updated_at":"2024-11-05T18:43:56.000Z","dependencies_parsed_at":"2024-06-19T19:08:50.624Z","dependency_job_id":"bdd0f38e-8750-4363-b1a6-c7eb0ba74fd9","html_url":"https://github.com/alitari/mockgo-server","commit_stats":{"total_commits":138,"total_committers":2,"mean_commits":69.0,"dds":"0.32608695652173914","last_synced_commit":"eb5fd355439f74b106b9c579573c98cdc04acb40"},"previous_names":[],"tags_count":85,"template":false,"template_full_name":null,"purl":"pkg:github/alitari/mockgo-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alitari%2Fmockgo-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alitari%2Fmockgo-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alitari%2Fmockgo-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alitari%2Fmockgo-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alitari","download_url":"https://codeload.github.com/alitari/mockgo-server/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alitari%2Fmockgo-server/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269185745,"owners_count":24374629,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-06T02:00:09.910Z","response_time":99,"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":["go","golang","golang-application","http","kubernetes","mock-server"],"created_at":"2025-08-07T01:42:24.473Z","updated_at":"2025-08-07T01:42:27.125Z","avatar_url":"https://github.com/alitari.png","language":"Go","readme":"# mockgo-server\n\n\u003cimg src=\"./assets/mockgo-icon.png\" alt=\"drawing\" width=\"200\"/\u003e\n\n[![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/6619/badge)](https://bestpractices.coreinfrastructure.org/projects/6619)\n[![Build](https://github.com/alitari/mockgo-server/workflows/Workflow/badge.svg?branch=master)](https://github.com/alitari/mockgo-server/actions?workflow=Workflow\u0026branch=master)\n[![Go Report Card](https://goreportcard.com/badge/github.com/alitari/mockgo-server/mockgo)](https://goreportcard.com/report/github.com/alitari/mockgo-server/mockgo)\n[![codecov](https://codecov.io/gh/alitari/mockgo-server/branch/master/graph/badge.svg?token=WRJ9KFCJFI)](https://codecov.io/gh/alitari/mockgo-server)\n[![Go Reference](https://pkg.go.dev/badge/github.com/alitari/mockgo-server/mockgo.svg)](https://pkg.go.dev/github.com/alitari/mockgo-server/mockgo)\n\n![Docker Image Size (latest semver)](https://img.shields.io/docker/image-size/alitari/mockgo-standalone?label=image%20mockgo-standalone)\n![Docker Image Size (latest semver)](https://img.shields.io/docker/image-size/alitari/mockgo-grpc?label=image%20mockgo-grpc)\n\n\n\n*mockgo-server* is a lightweight http server which can be used to mock http endpoints. *mockgo-server* is designed for horizontal scaling and feels at home in cloud environments like [kubernetes](https://kubernetes.io/) and [knative](https://knative.dev/). The main features are:\n\n- **Simplicity** : easy configuration with human readable yaml files with reasonable defaults\n- **Scalability** : mockgo-server is designed for horizontal scaling. Therefore it can be used in environments with high http traffic ( e.g. for performance/load tests )\n- **Flexibility** : sometimes requirements for mocking requests goes beyond static responses. With templating mechanism and state management it is possible to implement particular logic for building responses.\n\n## TL;DR\n\nSee [Examples.md](./Examples.md).\n\n## variants\n\n*mockgo-server* is built with different variants which have their own use cases. The following table gives an overview:\n\n| variant             | can scale | persistence | use this when you ...                                                                         |\n|---------------------|-----------|-------------|-----------------------------------------------------------------------------------------------|\n| `mockgo-standalone` | no        | no          | want a simple setup and you don't need to scale, usually this variant is the starting point   |\n| `mockgo-grpc`       | yes       | no          | have to deal with high incoming traffic, but you don't need durability for states and results |\n| `mockgo-redis`      | yes       | yes         | have to deal with high incoming traffic and you want a durable storage for states and results or if you want to use mockgo as serverless deployment in knative |\n\n\n## install on kubernetes\n\nKubernetes is the first class environment for *mockgo-server*. So, if you have kubernetes cluster available, you can start right away with [helm](https://helm.sh/) charts:\n\n```bash\nhelm repo add mockgo-server https://alitari.github.io/mockgo-server/\nhelm upgrade mymock mockgo-server/mockgo-server --install\n```\nsee [here](./deployments/helm/mockgo-server/README.md) for further helm configuration options.\n\n## install on knative\n\nIf you have a [knative](https://knative.dev/) cluster available, you can start right away with [kn](https://knative.dev/docs/client/install-kn/)\n\n```bash\ncat \u003c\u003cEOF \u003e kn-mock.yaml\nendpoints:\n- request:\n    path: \"/hello-kn\"\n  response:\n    statusCode: 200\n    body: \"Hello from knative\"\nEOF\nkubectl create configmap mockgo-config --from-file=kn-mock.yaml\nkn service create mockgo --image=alitari/mockgo-standalone:v1.3.0 --mount /mockdir=cm:mockgo-config --env MOCK_DIR=/mockdir --env MOCK_PORT=8080\nMOCKGO_URL=$(kn service describe mockgo -o url)\ncurl -v $MOCKGO_URL/hello-kn\n```\n\nSee [here](./knative.md) for a example with redis.\n\n\n## install on local machine\n\nDefine the environment :\n\n```bash\nMOCKGO_RELEASE_VERSION=\"v1.3.0\"\nMOCKGO_VARIANT=\"standalone\" # or \"grpc\"\nMOCKGO_OS=\"linux\" # or \"windows\"\nMOCKGO_ARCH=\"amd64\" # or \"arm64\"\nMOCKGO_NAME=mockgo-${MOCKGO_VARIANT}-${MOCKGO_OS}-${MOCKGO_ARCH}\n```\n\n### option 1: download binary excutable\n\n```bash\nwget https://github.com/alitari/mockgo-server/releases/download/$MOCKGO_RELEASE_VERSION/$MOCKGO_NAME\nchmod +x $MOCKGO_NAME\n# MOCK_DIR is the path for looking for mockfiles, per default this are files with names matching \"*-mock.*\"\nMOCK_DIR=$(pwd)/test/mocks ./$MOCKGO_NAME\n```\n\n### option 2: go install\n\n```bash\ngo install github.com/alitari/mockgo-server/mockgo-$MOCKGO_VARIANT/starter/mockgo@latest\nMOCK_DIR=$(pwd)/test/mocks mockgo\n```\n\n### option 3: run with docker\n\n```bash\nMOCK_DIR=$(pwd)/test/mocks\ndocker run -it -v $MOCK_DIR:/mocks -e MOCK_DIR=/mocks alitari/mockgo-$MOCKGO_VARIANT:$MOCKGO_RELEASE_VERSION \n```\n\n## mockfiles and endpoints\n\nA mockgo-server configuration consist of one or multiple files in yaml format, the so called *mockfiles*.\nEach *mockfile* contains one or multiple *endpoints*.\nThe *endpoint* defines criteria which qualify the endpoint to serve an incoming request. This process is called *matching*.\nThe second configuration part of an *endpoint* is the definition of the http response. \n\n```yaml\nendpoints:\n  - id: \"id\" # [OPTIONAL] unique string to identify endpoint\n    prio: 1  # [OPTIONAL] integer to define precedence of endpoints if more than one endpoint matches\n    request: # request defines the matching\n      host: \"alexkrieg.com\" # [OPTIONAL], match to http host\n      method: \"POST\" # [OPTIONAL], match to http method, default is \"GET\"\n      path: \"/mypath\" # [MANDATORY], match to http request path\n      query: # [OPTIONAL] for matching, every key value pair must be part of the http query parameters of the incoming request\n        firstQueryParam: value1\n        secondQueryParam: value2\n      headers: # [OPTIONAL] for matching, every key value pair must be part of the http header values of the incoming request\n        Content-Type: \"application/json\"\n        Myheader: myheaderValue\n      body: \"^{.*}$\" # [OPTIONAL] regular expression which match to the request body\n    response: # defines the response\n      statusCode: 204 # [OPTIONAL], http response code ( see RFC 7231), defaults to \"200\"\n      body: \"hello\" # [OPTIONAL], response body as string, templates can be used\n      bodyFilename: \"response.json\" # [OPTIONAL], refers to a file which contains the response body, templates can be used in the file\n      headers: | # [OPTIONAL],multiline string in form of key: value, templates can be used\n        Content-Type: \"application/text\"\n```\n\n## path matching\n\nThe form of a http request can be described as a sequence of *pathsegments* which are separated through a `/`. In order to achieve flexibility matching the path of an http request, there are 3 special symbols which can be used for the *pathsegment* defining the `request.path`:\n\n1. `*` every *pathsegment* on this position matches\n2. `{pathvariable}` every *pathsegment* on this position matches, the value of the *pathsegment* is available as template variable with name `pathvariable`\n3. `**` one or more arbitrary *pathsegments* match on this position\n\n### examples\n\n| `request.path`      | incoming request path | match                                                        |\n|---------------------|-----------------------|--------------------------------------------------------------|\n| `/foo/*`            | `/bar`                | ➖                                                            |\n| `/foo/*`            | `/foo`                | ➖                                                            |\n| `/foo/*`            | `/foo/bar`            | ✅                                                            |\n| `/foo/*`            | `/foo/bar/foo`        | ➖                                                            |\n| `/foo/*/bar`        | `/foo/bar`            | ➖                                                            |\n| `/foo/*/bar`        | `/foo/bar/bar`        | ✅                                                            |\n| `/foo/{foo}/bar`    | `/foo/bar/bar`        | ✅ `{{ RequestPathParams.foo }}` resolves to `bar`            |\n| `/foo/*/{bar}`      | `/foo/bar/bar/foo`    | ➖                                                            |\n| `/foo/*/{bar}`      | `/foo/bar/bar`        | ✅ `{{ RequestPathParams.bar }}` resolves to `bar`            |\n| `/foo/**`           | `/foo/`               | ➖                                                            |\n| `/foo/**`           | `/foo/bar`            | ✅                                                            |\n| `/foo/**`           | `/foo/bar/1/2/3`      | ✅                                                            |\n| `/foo/**/{bar}`     | `/foo/bar/1`          | ✅ matches but `{{ RequestPathParams.bar }}` does not resolve |\n| `/foo/**/foo/{bar}` | `/foo/bar/foo`        | ➖                                                            |\n| `/foo/**/foo/{bar}` | `/foo/bar/1/2/foo/3`  | ✅ `{{ RequestPathParams.bar }}` resolves to `3`              |\n\n## creating dynamic responses with go templates\n\nIn order to implement program logic, you can use [*go templates*](https://blog.gopheracademy.com/advent-2017/using-go-templates/) for creating dynamic responses.\nThe templating mechanism is available for the `response.body` and `response.headers` attributes and provides following additional functions for:\n\n- common template functionality through the [sprig library](https://masterminds.github.io/sprig/)\n- access to the incoming request through the `Request` variables\n- using the key-value store\n\n### access attributes of the incoming request\n\n| template variable     | type                     |\n|-----------------------|--------------------------|\n| `RequestPathParams`   | `map[string]string`      |\n| `RequestUrl`          | `string`                 |\n| `RequestPath`         | `string`                 |\n| `RequestHost`         | `string`                 |\n| `RequestBody`         | `string`                 |\n| `RequestBodyJSONData` | `map[string]interface{}` |\n\n### access the key-value store\n\nThere are 2 parameters which identifies a value in the key-value store:\n- `store` is a string which identifies the store\n- `key` is a string which identifies the value in the store\n\n| template function name | signature                                    | description                                                           |\n|------------------------|----------------------------------------------|-----------------------------------------------------------------------|\n| `kvStoreGet`           | `func(store, key string) interface{}`        | get the value from store `store`, which is stored under the key `key` |\n| `kvStorePut`           | `func(store, key string, value interface{})` | store value `value` under the key `key` in the store `store`          |\n| `kvStoreRemove`        | `func(store, key string)`                    | remove the value under the key `key` from store `store`               |\n\n## mockgo-server api\n\nThe *mockgo-server* holds multiple kinds of state: \n- current configuration (mock endpoints, logging , etc.)\n- storage of incoming requests\n- key-value store\n\nAll states can be accessed through an [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) api. \nThe api is secured with basic auth which can be configured with the environment variables `API_USERNAME` and `API_PASSWORD`.\nIn order to avoid conflicts with the mock endpoints, the api is exposed under the path prefix `/__`.\nThis can be changed with the environment variable `API_PATH_PREFIX`.\n\n### configuration api\n\n| method  | path         | description                             |\n|---------|--------------|-----------------------------------------|\n| `POST`  | `/__/reload` | reload the mock files from the mock dir |\n\n### matching api\n\nThe request storage has a limited capacity which can be configured with `MATCHES_CAPACITY`.\n\n| method   | path                            | description                                                                                          |\n|----------|---------------------------------|------------------------------------------------------------------------------------------------------|\n| `GET`    | `/__/matches/{endpointId}`      | returns all requests which matched to an endpoint                                                    |\n| `GET`    | `/__/matchesCount/{endpointId}` | returns the count of requests which matched to an endpoint, is not limited through capacity          |\n| `GET`    | `/__/mismatches`                | returns all requests which didn't match to an endpoint                                               |\n| `GET`    | `/__/mismatchesCount`           | returns the count of all requests which didn't match to an endpoint, is not limited through capacity |\n| `DELETE` | `/__/matches/{endpointId}`      | deletes storage of all requests which matched to an endpoint                                         |\n| `DELETE` | `/__/mismatches`                | deletes storage of all requests which didn't match to an endpoint                                    |\n\n### key-value store api\n\nUsing the path `/__/kvstore/{store}/{key}` you can access the key-value store with the following methods:\n\n- `PUT` stores the content of the request body under the key `key` in the store `store`\n- `GET` returns the content which is stored under the key `key` in the store `store`\n- `DELETE` removes the content which is stored under the key `key` in the store `store`\n\n## prometheus metrics\n\nThe *mockgo-server* exposes besides of the standard go metrics the following application specific counters:\n\n- `matches{\"endpoint\":\"\u003cendpointId\u003e\"}`: Number of matches of an endpoint\n- `mismatches`: Number of requests which did not match to on endpoint\n\n## using config reload feature\n\nFor local development it is useful to have a way to reload the mock files without restarting the *mockgo-server*. This can be achieved by sending a `POST` request to the reload endpoint. This functionality can be combined with a file watcher to automatically reload the mock files when they change. The script `scripts/watchmocks.sh` implements this functionality. \n\n```bash\n# watch for changes in test/main and reload the mock files\n./scripts/watchmocks.sh test/main\n```\n\n## contribute\n\nLearn how to contribute [here](./contribute.md)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falitari%2Fmockgo-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falitari%2Fmockgo-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falitari%2Fmockgo-server/lists"}