queil / gmox

.NET-friendly gRPC mock server

Gmox

.NET-friendly gRPC mock server inspired by gripmock powered by Saturn and F#. It comes both as a dotnet tool and a dotnet template depending on the use case.

Gmox exposes two endpoints:

• gRPC (port 4770) serving endpoint
• HTTP (port 4771) control endpoint (for dynamic stubbing)
  • GET / - lists configured stubs
  • POST /add - adds stub configuration
  • POST /test - test if the provided data matches any stub
  • POST /clear - deletes all the stub configurations
  • POST /quit - gracefully terminates the server

Quick start

Install the tool:

dotnet tool install --global Queil.Gmox.DotNet.Cli

Run the server:

# assuming cd = root of this repo
# adding two services and the stubs dir contains stubs for both of them
gmox serve --proto tests/resources/protos/org/books/list/svc_list.proto tests/resources/protos/org/books/add/svc_add.proto --root tests/resources/protos --stub-dir tests/resources/stubs

You can also use Gmox as a dotnet template.

FAQ

• Does is support running/stubbing multiple services (and from multiple protos)? ✔️

  Yes, in the dotnet cli mode you can specify multiple proto files after the --proto param as long as they're in a common root or self-contained.

• How to override ports?

  Dotnet tool mode

  Via cmdline parameters: --serve-port and --control-port

  Dotnet template mode

  • via env vars: GMOX__PORTS__SERVE and GMOX__PORTS__CONTROL
  • via cmdline parameters: --gmox:ports:serve= and --gmox:ports:control=
  • via any other method supported by IConfiguration (Microsoft.Extensions.Configuration)

Stubbing configuration

Stub configuration consists of a fully-qualified method name (like grpc.health.v1.Health/Check), a rule that matches incoming requests data, and a corresponding response data attached to it.

There are two ways of configuring stubs (which work both in the dotnet tool and the dotnet template):

Static JSON files

Static files should contain valid JSON arrays of stub configurations, have the .json extension, and they should be located in the directory:

• in dotnet cli mode - given by the --stub-dir command line parameter
• in dotnet template mode - defined in App.fs as StubPreloadDir

Dynamic REST API configuration

Single stub configurations (not arrays) can be POSTed to the /add endpoint at port 4771 like:

curl -X POST http://localhost:4771/add -d '{ "method": "grpc.health.v1.Health/Check", "match": { "exact": {} }, "return": { "data": { "status": "NOT_SERVING" } } }'

Stub configuration JSON explained

Given the server receives a call to the grpc.health.v1.Health/Check method and the message is {} (empty) then it returns {"status": "SERVING"}.

{
  "method": "grpc.health.v1.Health/Check",
  "match": {
    "exact": {}
  }, 
  "return": {
    "data": {
      "status": "SERVING"
    }
  }
}

Stubs can be configured using the following rules:

• exact - matches if the request is exactly the same as the stub input
• partial - matches if the stub input data is a sub-tree of the request data
• regex - like partial but values in requests can be matched with a regular expression

Whenever a gRPC call is received the request data is evaluated against the available stub configurations. Multiple stubs can be configured for a gRPC method and they're evaluated from the most (exact) to the least (regex) specific. The first match wins.

Usage

ℹ️ All of the below modes support both static and dynamic stubbing.

Dotnet CLI tool

Gmox as a dotnet CLI tool is useful in development scenarios when you want to quickly create a mock server from protos.

Installation: dotnet tool install --global Queil.Gmox.DotNet.Cli

Usage:

Run gmox:

# assuming cd = root of this repo
gmox serve --proto tests/resources/protos/org/books/list/svc_list.proto tests/resources/protos/org/books/add/svc_add.proto --root tests/resources/protos --stub-dir tests/resources/stubs

You can play with the mock using grpcui if needed: grpcui -plaintext localhost:4770

Dotnet Template

Gmox as a dotnet template is useful when you want to create a mock server for a particular service, equip it with a curated set of default rules, and/or it runs in an environment where you have no access to protos.

The template makes following assumptions out-of-the-box:

• references the NuGet package provided as a parameter
• auto-registers all the services from the assembly marked with a type (fully-qualified) passed as a parameter

Installation: dotnet new --install Queil.Gmox.Template

Usage: dotnet new gmox -h

Docker image

Both the CLI tool and a server generated from the template may be packaged as Docker image and used in scenarios where having .NET SDK is not desirable.

TODO

• Unit tests!

• Docs!

  • Add examples for API endpoints

• Support dynamic stubbing:

  • exact
  • partial
  • regexp

• Handle errors:

  • /add - if input JSON is not a valid request for the specified service method
  • /add - if user tries configure a stub for a non-existent service method

• Support the following source of service schemas:

  1. NuGet package (compile-time - as a dotnet project template, useful when we have no access to protos)
  2. Protos (runtime - as a dotnet tool, useful on local dev when we do have protos and iterate quickly)

• Support recording received calls and expose via the control API

• Support requesting JSON-formatted request/responses so they can make creating stubs easier

• Support preloading stubs form JSON

• Support specifying port numbers

• Support returning errors

• CI: make push stage only run after the whole test matrix passes

Development

Testing Queil.Gmox.Template

DIR=./src/Queil.Gmox.Template/template && dotnet new --install $DIR
# then in another dir
dotnet new gmox -nu Your.NuGet.Package -amt Your.NuGet.Package.Assembly.Type

Once the template is installed it can be refreshed by:

dotnet new --debug:rebuildcache

gmox's Issues

Error within stubs.json on startup stops further valid stubs from being loaded

In the case of an error on startup partway through parsing the static stubs json processing of the file stops

For example, in the case of a static stub being defined for a proto method which isn't loaded everything after that definition is absent when checking localhost:4771/

Example error on startup:

      An error occurred starting the application
      System.AggregateException: One or more errors occurred. (Method proto.blocklist.grpc.gateway.GatewayService/RemoveFromBlocklist is not available for stubbing. 
 ---> System.Collections.Generic.KeyNotFoundException: 
 ---> System.Collections.Generic.KeyNotFoundException: An index satisfying the predicate was not found in the collection.
         at Microsoft.FSharp.Collections.SeqModule.Find[T](FSharpFunc`2 predicate, IEnumerable`1 source) in D:\a\_work\1\s\src\fsharp\FSharp.Core\seq.fs:line 677
         at [email protected](String methodToFind)

Does this support running multiple protos?

From the readme it seems like this can only server up a single proto with a set of responses? Is this correct? And if yes is there an ETA on being able to support many protos and repsonses?

Ability to change port when running Gmox for dotnet tool mode

I have the requirement to run multiple Gmox services at the same time so it would be helpful to be able to either specify the port or for them to be randomly allocated.