Forward requests without mocks to a different "fallback" server

[OliverJAsh]

We are considering migrating from MockServer to mockttp and one of the requirements we have is to forward requests without mocks to a different "fallback" server.

When the mock server receives a request, if there is no mock defined for this request, we would like to forward the request on to another server.

In MockServer this is possible using the following CLI flags:

        -proxyRemotePort <port>                 Optionally enables port forwarding mode.
                                                When specified all requests received will
                                                be forwarded to the specified port, unless
                                                they match an expectation.

        -proxyRemoteHost <hostname>             Specified the host to forward all proxy
                                                requests to when port forwarding mode has
                                                been enabled using the proxyRemotePort
                                                option.  This setting is ignored unless
                                                proxyRemotePort has been specified. If no
                                                value is provided for proxyRemoteHost when
                                                proxyRemotePort has been specified,
                                                proxyRemoteHost will default to "localhost".

Is this possible with mockttp, or is it something you would consider adding?

I read some stuff about proxies in the mockttp docs but as far as I can tell this is a different type of proxy.

[pimterry]

You can absolutely proxy traffic through Mockttp, either by using the Mockttp server as a real proxy server, or by transparently proxying direct requests elsewhere.

There's a few different ways to do it, but in general it's configured by defining a specific rule that matches some traffic and proxies it in some way. There's no concept of a fallback rule here (although it might be a sensible addition...) but instead you do this by defining the proxy rule as your last rule, so all your other rules will match first, and it's only used if they don't.

That's the theory. In practice that it usually looks something like this:

const mockServer = require("mockttp").getLocal();

await mockServer.get('/abc').always().thenReply(200); // A real request you want to mock
await mockServer.anyRequest().thenForwardTo('localhost:9000'); // Forward everything else
await mockServer.start();

That's it! The docs for that method are here. You can also pass options for advanced tricks, like adding callbacks that run and potentially transform each forwarded requests and/or response, e.g. so that you can log them.

Note the always() though. This is required, because the default behaviour when you have multiple matching rules for one request is to run the rules in order (run thenReply for request 1, then run thenForwardTo for requests 2+). Always() ensures that the first /abc rule will always take precedence over any subsequent rules for all requests that it matches.

Does that make sense? Happy to explain more if there's anything that's not clear.

[OliverJAsh]

Thanks so much for the fast response! ❤️

There's no concept of a fallback rule here (although it might be a sensible addition...) but instead you do this by defining the proxy rule as your last rule, so all your other rules will match first, and it's only used if they don't.

I was hoping to use mockttp to define mock responses inline in my tests, pseudo code:

before(() => mockServer.start());
before(() => mockServer.anyRequest().thenForwardTo('localhost:9000'));

it('my test', () => {
  await mockServer.get('/abc').always().thenReply(200); // A real request you want to mock

  /* run the test */
});

However it sounds like this wouldn't work because the "proxy rule" must come last—or do you see a way around that?

In MockServer I can define a fallback which will only be used when other "rules" don't match.

[pimterry]

Yeah, that makes sense, I'm imagining this could work with something like:

await mockServer.unmatchedRequest().thenX();

That would effectively create a rule as normal, but with lower priority than all other possible rules, and which only matches completely unmatched requests (so no .always() is required). I think to make this behave sensibly calling it more than once needs to throw an exception (i.e. you're only allowed one fallback rule, to keep things sane). And you can't include matchers like withJsonBody() or similar to match specific fallback requests here, just the thenSomething() methods to handle them.

Anyway, given that you'd just need to globally set this once at some point before your test with something like:

before(() => mockServer.unmatchedRequest().thenForwardTo('localhost:8080'));

to guarantee that every unmatched request in your tests gets forwarded. Would that work for you?

I should be able to put something together for this in the next week or so.

Or you need this urgently and you've got a minute, you're welcome to have a go yourself! I think it just requires expanding this line to encapsulate the existing implementing of sendUnmatchedRequestError into a rule (using thenCallback), store that default rule in a field, and add an unmatchedRequest() method to build a setter for that field.

[OliverJAsh]

Yeah, that makes sense, I'm imagining this could work with something like:

Would this match the unmatched request once? From what you're saying it sounds like it would match all unmatched requests, not just the first one. That's good with me but it's not unthinkable that someone would only want to match the first one 🤔

Anyway, given that you'd just need to globally set this once at some point before your test with something like:

I think that would be great!

[pimterry]

Hi @OliverJAsh, this is now available! Update to Mockttp 2.1.0 and you can now create fallback rules with unmatchedRequest(), like so:

await server.unmatchedRequest().thenReply(200, "Fallback response");
await server.get('/specific-endpoint').thenReply(404, "Mock error response");

These follow the behaviours discussed above: you can only have one, it can't use any matchers, but it will always match against any requests that would otherwise return the standard 503 unmatched request response. Other than that it should behave like any other rule. Let me know how this works for you.

[OliverJAsh]

Thank you! I'll let you know.

[pimterry]

I'm going to close this - I think it's all resolved in Mockttp 2.1.0 - but do shout if you're still having issues.