mitre/HTTP-Proxy-Servlet: Java Reverse Proxy Setup and Constraints

Smiley's HTTP Proxy Servlet Target Use Case

Smiley's HTTP Proxy Servlet addresses a specific browser-to-service problem: a Java web application needs to reach an HTTP service hosted somewhere else without exposing that destination directly to the client. The README gives AJAX applications as the principal example. In that arrangement, the servlet acts as a reverse proxy or gateway inside the application's origin rather than as a proxy configured independently in each browser.

The intended users are Java developers working with servlet containers who need a compact forwarding layer for an internal or separately hosted HTTP endpoint. The documented Solr example maps `/solr/*` to `http://solrserver:8983/solr`. That fixed target makes the scope clearer than the term proxy can initially suggest. It is an application component with a configured upstream, not a general client proxy that can relay to arbitrary Internet destinations.

The implementation's small footprint is part of its value proposition. The README describes it as a single-source-file implementation and emphasizes that it can be embedded into an existing Java web application. It can also be secured through Java EE `web.xml` or a servlet filter such as `Spring-Security`. Those points favor teams that want to place the proxy under an application's existing security boundary.

That does not make it an API gateway with built-in policy management. The documentation does not describe built-in authentication rules, rate limits, quotas, request-size controls, caching, circuit breaking, or structured audit records. The decision therefore depends on whether basic forwarding plus servlet-level controls meet the requirement.

Request Flow Through ProxyServlet

At runtime, `ProxyServlet` receives a servlet request and uses the configured `targetUri` to identify the destination HTTP service. The servlet then relies on Apache HttpClient for the outbound exchange rather than implementing an independent HTTP transport. The README states that version 2.0 supports HttpClient 4.5 and newer versions.

Several parameters control details around that basic flow. `preserveHost` keeps the incoming `HOST` value as-is, while `forwardip` enables forwarding of the client IP. Cookie behavior can be controlled with `preserveCookies` and `preserveCookiePath`. Redirect handling is controlled by `http.protocol.handle-redirects`. These switches allow the proxy to align or deliberately alter behavior at the HTTP boundary, but the README does not present them as a complete header-security policy.

Connection management is also exposed. `http.socket.timeout`, `http.read.timeout`, and `http.connectionrequest.timeout` accept millisecond values for different phases of an HttpClient request. `http.maxConnections` sets the maximum connection number, while `useSystemProperties` selects JVM-defined networking properties. The parameter list gives administrators direct control over failure timing and connection use, but it does not document retry behavior, pooling details, or concurrency guarantees beyond those named settings.

Logging is optional through the `log` parameter, which records input and target URLs in the servlet log. URL logging can help diagnose a routing problem, although it may also make request paths part of application logs. Operators should account for that consequence before enabling it in an environment with sensitive query parameters.

Fixed and URI-Template Servlet Targets

The basic servlet configuration uses a fixed `targetUri`. This is the safer and simpler pattern when the servlet exists to expose one known service. The repository's `web.xml` example registers `org.mitre.dsmiley.httpproxy.ProxyServlet`, sets its target to the Solr server, enables logging, and maps it to `/solr/*`.

A dynamic form requires `org.mitre.dsmiley.httpproxy.URITemplateProxyServlet`. Its `targetUri` follows URI Template Level 1 syntax, allowing selected query parameters to replace named placeholders. The documented destination template is `http://{_subHost}.behindfirewall.mycompany.com:{_port}/{_path}`, with `_subHost`, `_port`, and `_path` supplied by the client. The README recommends the leading underscore to distinguish these proxy arguments from ordinary application parameters.

There is an important constraint for POST requests. Template substitutions must be present in the query string even when the client sends application data as an URL-encoded POST body. The reserved `proxyArgs` parameters cannot simply be moved into that body. This distinction can affect clients that expect all input in the request body and can complicate request signing or form design.

Dynamic host selection also changes the security review. A fixed `targetUri` keeps the destination under administrator control. A template driven by request parameters lets clients influence part of the destination. The documentation does not claim that the servlet validates an allowlist of hosts or paths. Deployment code or a surrounding security layer must impose any required restrictions.

Building and Configuring the Servlet

The README specifies Java 11 as the minimum version. To build the project from a checkout, run the Maven package command shown in the documentation. Maven writes the resulting artifact to the `target` directory using the project version in its filename.

mvn package

After a successful local build, the README says to look for `target/smiley-http-proxy-servlet-VERSION.jar`. A deployment that does not modify the code can instead consume the Maven Central artifact. The documentation's example uses version `1.12.1` and explicitly warns that the example version is not necessarily the latest. The release list identifies version 2.0 as the latest listed release.

Version 2.0 changed the servlet dependency to `jakarta.servlet-api`. Applications that still require `javax.servlet-api` can select the `javax` classifier as documented:

<dependency>
    <groupId>org.mitre.dsmiley.httpproxy</groupId>
    <artifactId>smiley-http-proxy-servlet</artifactId>
    <version>${smiley-http-proxy-servlet.version}</version>
    <classifier>javax</classifier>
</dependency>

The fixed Solr proxy is then registered through `web.xml`. This is a complete first-use mapping, not just a class import:

<servlet>
  <servlet-name>solr</servlet-name>
  <servlet-class>org.mitre.dsmiley.httpproxy.ProxyServlet</servlet-class>
  <init-param>
    <param-name>targetUri</param-name>
    <param-value>http://solrserver:8983/solr</param-value>
  </init-param>
  <init-param>
    <param-name>log</param-name>
    <param-value>true</param-value>
  </init-param>
</servlet>
<servlet-mapping>
  <servlet-name>solr</servlet-name>
  <url-pattern>/solr/*</url-pattern>
</servlet-mapping>

After deploying the servlet in its container, a request under the mapped application path is eligible for forwarding to the configured Solr destination. The README does not provide a curl command or a sample upstream response, so it does not establish a more specific observable success sequence.

Apache HttpClient, Compatibility, and Upgrade Cost

The dependency profile is more than a single HttpClient jar. The README lists `org.apache.httpcomponents:httpclient:4.5.13`, which brings in `httpcore`, `commons-logging`, and `commons-codec`. Deployments must make these runtime dependencies available in addition to the proxy artifact.

Servlet compatibility creates a separate upgrade path. Version 2.0 uses `jakarta.servlet-api` by default but retains a `javax` build selected with the classifier. Projects migrating from `javax.servlet` may therefore avoid an immediate namespace migration if they select the documented artifact variant. The `javax` dependency shown in the README is presented as a compatibility choice, not as a reason to assume both APIs are interchangeable inside the same application.

Older HttpClient compatibility is tied to older proxy releases. Version 1.8 is documented for HttpClient 4.1 and 4.2, while version 1.12 is documented for HttpClient 4.3 and 4.4. Version 2.0 supports HttpClient 4.5 and newer. This release mapping matters when an application already manages a sensitive HTTP dependency graph.

The repository is not archived, and its last push was on 2026-09-03. That is recent repository activity, but it does not erase the release gap: the most recent listed release is version 2.0 from 2023-06-29. Before upgrading, compare the application's servlet namespace, Java version, HttpClient version, dependency conflicts, and `CHANGES.md` rather than replacing a working pinned version without that review.

The project uses the Apache-2.0 license. That identifier permits reuse and modification under the license's stated terms, but deployment, distribution, and notice obligations should be checked against the repository's `LICENSE.txt` and `NOTICE.txt`. This is a license-identification note, not legal advice.

When ProxyServlet Is the Wrong Proxy Model

The clearest limitation is architectural. The README explicitly identifies this project as a reverse proxy and says the servlet-template form can blur that distinction. It is not designed as a general forwarding proxy in which a browser or client selects any destination and the proxy decides how to reach it. The fixed-target model is appropriate for an embedded gateway, while the template model should be treated as constrained routing rather than unrestricted forwarding.

An actual alternative approach is a conventional forward proxy. A forward proxy accepts client requests and uses the destination requested by the client, usually after the browser or client receives proxy configuration. `ProxyServlet` instead begins with a destination configured in `web.xml`, or from named substitutions in that configured template. The distinction changes where routing policy belongs and removes the browser-wide proxy setup associated with the conventional model.

The project is also a poor fit where transparent streaming, advanced caching, authentication schemes, response transformation, or detailed traffic policies are mandatory. The README acknowledges that more sophisticated requirements have alternatives and recommends using a well-tested proxy rather than an untested proof of concept. It does not identify those alternatives in the available documentation, so naming a specific competing product would go beyond what is established here.

Operational simplicity cuts both ways. One source file is convenient to embed and extend, but the documented surface remains small. Subclassing can adapt `targetUri` construction, and HttpClient supplies transport-level extension points. Those are useful extension paths, not evidence that complex policies should be reconstructed inside every application.

Editorial conclusion

Adopt version 2.0 when the requirement is a small, embeddable reverse proxy inside a Java servlet application and the target URL can be controlled through servlet configuration or a constrained URI template. Do not adopt it as a general-purpose forward proxy, an API gateway, or a replacement for a proxy with documented authentication, traffic filtering, caching, and observability. Verify first that your Java deployment matches the `jakarta.servlet-api` or `javax` classifier, then confirm that every client-supplied template parameter cannot select an unintended host or path. The project is not archived, and the last push was on 2026-09-03, while the newest listed release is version 2.0 from 2023-06-29.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. mitre/HTTP-Proxy-Servlet on GitHub
4. README
5. Releases