How to properly setup JS or GROOVY dispatching rules

[sgkiokas]

I have created a simple Service in Microcks which I want it to act like a proxy to redirect me when hit to an Express Server. I have tried to use the following 3 dispatchers available in the UI:

1. PROXY
2. JS
3. GROOVY

When I use the PROXY dispatcher and hit Microcks like curl -i -X POST "http://localhost:8080/rest/ExpressServer+Dispatcher/1/dispatch/paycord" -H "Content-Type: application/json" -d '{}', Microcks reports that no such dispatcher exists.

When I try the other 2 (by the way, I have enabled Postman runtime as well in the same docker-compose), nothing really happens:

1. Executing:

sgkiokas@ATH-SDV-M088-GS ~ % curl -i -X POST "http://localhost:8080/rest/ExpressServer+Dispatcher/1/dispatch/paycord" -H "Content-Type: application/json" -d '{}'
HTTP/1.1 200
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: POST, PUT, GET, OPTIONS, DELETE
Access-Control-Max-Age: 3600
Access-Control-Allow-Headers: content-length, host, content-type, user-agent, accept
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Content-Type: application/json;charset=UTF-8
Content-Length: 49
Date: Wed, 03 Dec 2025 13:54:50 GMT

{
  "status": "callback received by dispatcher"
}%

2. At the logs I see:

14:11:59.823  INFO 1 --- [andler-528] i.github.microcks.web.RestController     : Servicing mock response for service [ExpressServer+Dispatcher, 1] on uri /rest/ExpressServer+Dispatcher/1/dispatch/paycord with verb POST

3. The artifact currently is (I have tried both a Swagger and a Postman collection):

{
  "info": {
    "name": "ExpressServer Dispatcher",
    "_postman_id": "expressserver-dispatcher-001",
    "description": "version=1 - Postman collection for Microcks to mock and dispatch to Express server.",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "item": [
    {
      "name": "POST /dispatch/paycord",
      "request": {
        "method": "POST",
        "header": [
          { "key": "Content-Type", "value": "application/json" }
        ],
        "body": {
          "mode": "raw",
          "raw": "{}"
        },
        "url": {
          "raw": "{{base}}/dispatch/paycord",
          "host": ["{{base}}"],
          "path": ["dispatch", "paycord"]
        }
      },
      "response": [
        {
          "name": "Ack",
          "originalRequest": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": { "mode": "raw", "raw": "{}" },
            "url": { "raw": "{{base}}/dispatch/paycord", "host": ["{{base}}"], "path": ["dispatch", "paycord"] }
          },
          "status": "OK",
          "code": 200,
          "_postman_previewlanguage": "json",
          "body": "{\n  \"status\": \"callback received by dispatcher\"\n}"
        }
      ]
    }
  ],
  "variable": [
    { "key": "base", "value": "http://localhost:8080/rest/ExpressServer/1.0" }
  ]
}

4. My dispatcher rule is:

function dispatch(request) {
  const method = (request.method || 'POST').toUpperCase();

  if (method !== 'POST') {
    return { passthrough: true };
  }

  return {
    forward: {
      method: 'POST',
      url: 'http://express-server:5000/dispatch/paycord',
      headers: {
        'Content-Type': 'application/json',
      },
      body: '{}',
    },
  };
}

Connectivity wise, I have checked everything and the containers do talk to each other.

I am using quay.io/microcks/microcks:1.13.0 and quay.io/microcks/microcks-postman-runtime:0.7.0.

Maybe we need more examples of how to properly setup those dispatching rules at the docs?

Thanks in advance!

[lbroudoux]

Hey @sgkiokas,

We might actually lack some documentation... sorry. I'll try to give you some pointers and insights below.

PROXY dispatcher

Have you checked https://microcks.io/blog/new-proxy-features-1.9.1/?

Microcks reports that no such dispatcher exists.

Maybe the dispatcher rules have been badly specified... It should consist of just the base URL of the target endpoint. Exemple: https://backend.acme.com- so when you call http://localhost:8080/rest/ExpressServer+Dispatcher/1/dispatch/paycord on Microcks, it is actually proxied to https://backend.acme.com/dispatch/paycord.

Do not hesitate to share more logs from the Microcks container to see what's actually going wrong.

JS dispatcher

The dispatch rule should be the JavaScript snippet and you don't have to wrap it into a function or other stuff. This JavaScript snippet performs computations, adds new elements to the context, and must return the name of the Response to send back to the caller. You cannot use this dispatcher to proxy request but to fetch additional external data.

For example:

const productId = mockRequest.getParameters("productId")[0];
const data = fetch("https://acme.example.com/api/inventory?productId=" + productId);
requestContext.available = JSON.parse(data.body).available
return "product_details"

Note that as of today, the standard fetch() function is not available and the fetch() function here is a limited one we maintain in the Microcks code base.

GROOVY dispatcher

GROOVY dispatcher is basically the same as JS but with a Groovy syntax. The fetching options are more complete but the drawback is that you'll not be able to use a Groovy dispatcher in the native compiled Uber image of Microcks.

About tuning and troubleshooting

As you're using the recent 1.13.0, aren't the new observability and testing features of any help? See https://microcks.io/blog/microcks-1.13.0-release/. Inspecting the logs, you should be able to see of it's a dispatcher, dispatcher rules or script evaluation errors you're facing.

Let me know how it goes.

[sgkiokas]

Hi @lbroudoux,

Yes, I did check the blogpost and added the proxy dispatcher accordingly. As per the live traces, I'll be honest: I didn't notice them! I will give them a go and report the progress.

Thanks a lot!

[sgkiokas]

Ok, so this is what happens:

Live tracing

16:15:35.666Received REST invocation POST /dispatch/paycordin d20596ffa05fdd97 • secured request
body.content"{}"
body.size2
client.address"185.125.190.80"
http.method"POST"
query.string"empty"
uri.full"http://localhost:8080/rest/ExpressServer+Dispatcher/1/dispatch/paycord"

16:15:35.666Selected dispatcher and rules for this invocationin b7621419ef1e3400 • processInvocation
dispatcher"PROXY"
dispatcher.rules"http://express-server:5000"

16:15:35.666Unknown dispatcher type encounteredin 9f696f0a39828777 • computeDispatchCriteria
dispatch.criteria"null"
dispatcher"PROXY"
dispatcher.rules"http://express-server:5000"

16:15:35.667Response lookup completedin b7621419ef1e3400 • processInvocation
response.foundtrue
response.name"Ack"

16:15:35.667Configured response delayin b7621419ef1e3400 • processInvocation
delay.strategy"fixed"
delay.value0

16:15:35.667Proxying request to external servicein b7621419ef1e3400 • processInvocation

Checking the logs of my Express Server, it has indeed been triggered

Microcks logs

However, in the logs of the Microcks container I see

14:15:35.665  INFO 1 --- [ndler-5492] i.github.microcks.web.RestController     : Servicing mock response for service [ExpressServer+Dispatcher, 1] on uri /rest/ExpressServer+Dispatcher/1/dispatch/paycord with verb POST

14:15:35.666 ERROR 1 --- [ndler-5492] i.g.m.web.RestInvocationProcessor        : Unknown dispatcher type: PROXY

This is the part that got me confused.

[lbroudoux]

14:15:35.666 ERROR 1 --- [ndler-5492] i.g.m.web.RestInvocationProcessor : Unknown dispatcher type: PROXY

Oh I see! I think this is a bad log message that has not been refactored with the rest of the code... Sorry.

So it now works as expected?

[sgkiokas]

Yes, it does!