Handle non-root path requests

[ComputerDaddyGuy]

Hello,

For my use case, I would need java-httpbin to support handling requests on non-root paths, not only on the root path.

For example, for the /headers endpoint, we are currently forced to call http://127.0.0.1:8080/headers, whereas in my case I would need to call http://127.0.0.1:8080/some/other/path/headers (which returns 501 Not Implemented).

I thought of three possible options. Please let me know your thoughts, or if there is another option I may have missed.

Thank you!

---

Option 1: Custom HttpBinHandler

As mentioned in #15, I could indeed implement my own HttpBinHandler, but it would mostly be copy-and-paste work.

Since I would need to keep my implementation in sync with future changes in java-httpbin, this solution is neither ideal nor future-proof.

---

Option 2: Modify HttpBinHandler to support non-root paths

Modify HttpBinHandler so that it also handles non-root paths by default.

Not sure it is a valid approach as it seems to be a breaking change.

// HttpBinHandler
if (method.equals("GET") && uri.equals("/headers")) // Current implementation
if (method.equals("GET") && uri.endsWith("/headers")) // Proposed implementation: "endsWith" instead of "equals"

---

Option 3: Refactor HttpBinHandler to make it easier to extend/override

Instead of having a large if / else if / else block in a single method, perhaps a List<HttpBinRoute> could be introduced and iterated until a matching route is found.

This would make it easy to:

• Extend existing routes to adjust matching logic or behavior
• Add custom routes and behavior that are not provided by java-httpbin

It requires a bit more work, but it is also the most flexible approach. I would be glad to help 😊.

/** 
  * HttpBinHandler
  */

private List<HttpBinRoute> customRoutes = new ArrayList<>(); // mutable with some addCustomRoute(HttpBinRoute) method
private List<HttpBinRoute> defaultRoutes = /* default routes */;

private void handleHelper(Request baseRequest, HttpServletRequest request,
        HttpServletResponse servletResponse, InputStream is,
        OutputStream os) throws IOException {
    if(!handleRoutes(customRoutes, baseRequest, request, servletResponse, is, os)) { // Try first to handle request with custom routes...
        handleRoutes(defaultRoutes , baseRequest, request, servletResponse, is, os); // ... fallback to default routes otherwise
    }
}

private boolean handleRoutes(List<HttpBinRoute> routes, Request baseRequest, HttpServletRequest request,
        HttpServletResponse servletResponse, InputStream is,
        OutputStream os) throws IOException {
    // try
    for(var route : routes) {
        if(route.matches(request)) {
            route.handle(baseRequest, request, servletResponse, is, os);
            return true;
        }
    }
    // catch JSONException
    return false;
}

// ------------------------------------------------------------------------------

/** 
  * New interface
  */
public interface HttpBinRoute {

    boolean matches(Request request);

    void handle(Request baseRequest, HttpServletRequest request, 
            HttpServletResponse servletResponse, InputStream is,
            OutputStream os) throws IOException;
}

/** 
  * Default implementation from java-httpbin.
  * One implementation for each route handled by java-httpbin: HeadersRoute, GetRoute, PostRoute, IpRoute, etc.
  */
public class HeadersRoute implements HttpBinRoute {

    public boolean matches(Request request) {
        return request.getMethod().equals("GET") && request.getRequestURI().equals("/headers");
    }

    public void handle(...) throw IOException, JSONException {
        // default implementation from HttpBinHandler
    }
}

// ------------------------------------------------------------------------------

/**
  * Custom implementation that only overrides the "matches" method.
  */
public class MyCustomHeadersRoute extends HeadersRoute {

    @Override
    public boolean matches(Request request) {
        return request.getMethod().equals("GET") && request.getRequestURI().endsWith("/headers");
    }

}

var handler = new HttpBinHandler();
handler.addCustomRoute(new MyCustomHeadersRoute());
var httpBin = new HttpBin( uri, handler );
httpBin.start();

[gaul]

Please test the latest master then I'll run a 1.5.0 release.

[ComputerDaddyGuy]

Hello,
Thank you for your quick proposal 😊

Your fix is for a single prefix, set at build time.
As my use case is testing a custom reverse proxy solution, I'm calling httpbin with multiple different paths, sometime even within a single test method (I'm sorry I was not clear on that point, my bad).
Also, using @ExtendsWith(HttpBinExtension) is not very convenient for this single prefix solution.

Just for my own usecase, option 2 is the most suitable (less work, less config): use endsWith instead of equals.

Thank you!

[gaul]

Thanks for the clarification — that changes the shape of the problem, so I am reopening this.

The prefix on master is fixed when the server starts. You need several prefixes at once against one server, sometimes within a single test method. The current feature cannot do that.

Why I do not want endsWith on its own

Matching is only half of what the prefix is for. The handler also generates root-relative URLs from it, and with endsWith it would no longer know which prefix a request arrived under:

• Location for /redirect/n, /relative-redirect/n, /absolute-redirect/n, /status/3xx, /links/n, /cookies/set and /cookies/delete
• the Path of the cookies /cookies/set and /digest-auth write
• the form action in /forms/post and the Disallow line in /robots.txt

GET /proxy-a/redirect/3 would answer Location: /relative-redirect/2, pointing outside the proxy. Since a proxy rewriting paths is exactly what you are testing, that is the part that has to be right, and you would get passing matches with silently wrong redirects.

It also only helps the exact routes. /status/, /bytes/, /redirect/ and the rest match with startsWith, so endsWith does nothing for them.

What I would rather do

Make the prefix per request rather than per handler: the prefix is whatever precedes a recognized route. That gives you the matching you asked for and keeps the generated URLs correct.

// The empty prefix first, so a request at the root behaves as it does
// today; then each / boundary, shortest prefix winning.
for (int i = 0; i >= 0; i = path.indexOf('/', i + 1)) {
    String rest = path.substring(i);
    if (Route.match(rest) != null) {
        return new Split(path.substring(0, i), rest);
    }
}
return null;

Dispatch on master is now a table of routes, each handler taking an Exchange that carries the request, the response and the streams. Adding the prefix to that record and reading it where the field is read today is a small change. The url field in the JSON bodies already reports the whole original URL, so it needs nothing.

Opting in through the endpoint URI keeps it available to the executable jar as well:

new HttpBin(URI.create("http://127.0.0.1:0/*"))   // any prefix
new HttpBin(URI.create("http://127.0.0.1:0"))     // root only, as today

One server then answers /proxy-a/redirect/3 with Location: /proxy-a/relative-redirect/2 and /proxy-b/redirect/3 with /proxy-b/..., in the same test method — one extension for the whole class, whatever paths the tests use.

I do not want to make it the default. Serving these endpoints at every path that happens to end in /get turns a mistyped path in somebody else's test into a 200 instead of a 404.

Two limits I would document rather than solve:

• a prefix whose tail resembles a prefix route loses the ambiguity: /status/200/headers matches /status/ first and 404s. Fine for prefixes like /api/v1 or /proxy-a.
• the home page is reachable at <prefix>/ but not at a bare <prefix>. With no configured prefix there is nothing to tell /foo from an unknown path.

On your option 3

Most of it has landed: dispatch is a table now, so a hook for custom routes would be a few lines. It would not solve this on its own though — you would be reimplementing the prefix-aware URL generation by hand in every custom route. I would rather keep this issue to the prefix and open a separate one for the extension point if you still want it afterwards.

Does the above cover your case? If so I will implement it before 1.5.0.

[ComputerDaddyGuy]

Hi,

Your proposal seems perfect 👍
The identified limits are totally acceptable.

Thank you!