Playbook: debug a failing call between services

The question, in the user's words: "The POST to /api/shipments from our main service is failing. Which code makes the call, which service is meant to answer it, and why does Niro think so?"

What you get at the end: the calling method, the service folder and method that handle the route, and what in the repository ties the address to that folder. Then, for a call that two services could answer, how to settle which one.

Words used on this page: a route is a web address a service answers, such as POST /api/shipments; a handler is the method that answers it; an outbound call is a call your code makes to another service's route.

The steps

1. Find the call

niro ask find_outbound_http_calls path_pattern=/api/shipments

Found 2 outbound HTTP calls matching '/api/shipments'.
1. POST /api/shipments -> com.example.shop.shipping.ShippingMain.a_f_Ng3hlN
   caller: ApacheHttpClient5Calls.createShipment
   source: .../java-mono/main/src/main/java/com/example/shop/main/http/ApacheHttpClient5Calls.java
2. GET /api/shipments/{param} -> com.example.shop.shipping.ShippingMain.shipment_Np2ojN
   caller: ApacheHttpClient5Calls.shipment
confidence: complete - this is the COMPLETE list.

Each line already says where the call lands. a_f_... is a function written in place: here a lambda, (req, res) -> res.status(201).send().

2. Who answers it?

niro ask find_handler fqn=ApacheHttpClient5Calls.createShipment

Found 1 handler for 'ApacheHttpClient5Calls.createShipment'.
confidence: complete | has_more: false — this is the complete list.
1. ShippingMain.a_f [helidon-se]
   source: services/helidon-se/src/main/java/com/example/shop/shipping/ShippingMain.java

3. Why that service?

The caller dials http://shipping-api:8109/api/shipments. Nothing in the Java code says that shipping-api is the helidon-se folder. The deploy file does:

# docker-compose.yml
  shipping-api:
    build: ./services/helidon-se
    ports: ["8109:8109"]

Niro reads deploy files like this one to give each folder its address, then joins the call to the route. See Configure a folder to set an address by hand.

4. The whole map, when you do not know where to start

niro ask get_service_topology

18 link(s) between parts of this project:
  main -> helidon-se  (2 route(s))
      GET /api/shipments/{param}
      POST /api/shipments
  main -> javalin  (3 route(s))
      GET /api/stock/{param}   (not confirmed)
      ...

5. When two services declare the same route

"(not confirmed)" means the call was matched by its path alone, and more than one service declares that path. The engine lists every such call and the command that settles it:

niro route-rule unconnected

1 call(s) joined only as candidates: more than one route could be meant ...
  java-mono/main GET /api/stock/{param}: 2 services declare it (java-mono/services/javalin, java-mono/services/sparkjava)
      niro-local route-rule add '/api/stock/{param}' --from java-mono/main --to java-mono/services/javalin
5 address(es) dialled that no service here answers on:
  http://gift-cards-api:8113: 1 call(s) from java-mono/main; no service here declares their paths
  ...

Before the rule, StockRetrofitApi.stock was listed twice, once for each service, both "(one of several routes with this path, not confirmed)". After niro route-rule add ... and niro build, it is listed once, to the service named:

Before:  4. GET /api/stock/{param} -> ...stockspark.StockSparkApp.a_f_N657yN  (one of several routes with this path, not confirmed)
         5. GET /api/stock/{param} -> ...stock.StockApp.a_f_Nes1yN  (one of several routes with this path, not confirmed)
After:   3. GET /api/stock/{param} -> com.example.shop.stock.StockApp.a_f_Nes1yN

"No service here answers" usually means the service lives in another repository that is not indexed, or its address is wrong. Check the address with niro base-url in the service's folder.

Why the answer is deterministic

The link between a call and a handler comes from three things Niro read: the call's method and path, the route a framework declares, and the address of each folder. The same files always give the same links. Where the path alone matched and two routes fit, the answer says "not confirmed" and keeps it out of the risk counts, rather than guessing.

What grep would do instead

Cost

What these steps cost depends on your code and your question. How Niro counts the size of its answers, and how to measure the cost on your own tasks, is in Tokens, speed and accuracy.

Playbook: debug config and environment (addresses that come from configuration), Playbook: learn a new codebase.