Skip to content

[improve][misc] PIP-472: Drop Jetty ee8 usage and adapt legacy javax.servlet additional servlets - #26444

Merged
lhotari merged 2 commits into
apache:masterfrom
lhotari:lh-improve-drop-jetty-ee8
Sep 2, 2026
Merged

lhotari merged 2 commits into
apache:masterfrom
lhotari:lh-improve-drop-jetty-ee8

Conversation

@lhotari

@lhotari lhotari commented Sep 1, 2026

Copy link
Copy Markdown
Member

PIP: PIP-472 (#25700), follow-up to #25912

Motivation

PIP-472 (#25912) moved Pulsar's web tier from Jetty's ee8 environment (javax.servlet) to ee10
(jakarta.servlet). To keep AdditionalServlet plugins that are written against javax.servlet
working without recompilation, it kept a second Jetty environment — ee8 — alive inside the
same Jetty Server and registered those plugins there, via WebService.addServletEe8 (broker) and
WebServer.addServletEe8 (proxy).

Combining both environments in one Jetty instance does not work the way that design assumed. A
Jetty environment owns its own servlet context, servlet handler and — crucially — its own filter
chain
; the two are not shared. Pulsar's broker and proxy filters are jakarta.servlet-typed and
can therefore only be installed on ee10 contexts, so a servlet registered in the ee8 environment
ran outside the request pipeline that every other servlet goes through. Concretely, an
AdditionalServlet reporting AdditionalServletType.JAVAX_SERVLET was served without:

broker proxy
RateLimitingFilter ✗ ✗
AuthenticationFilter (so the requiresAuthentication / isAuthenticationEnabled argument passed to addServletEe8 had no effect) ✗ ✗
WaitUntilPulsarServiceIsReadyForIncomingRequestsFilter, AddListenerAttributeFilter ✗ —
PreInterceptFilter / ProcessHandlerFilter / ResponseHandlerFilter (broker interceptors) ✗ —
DisableDebugHttpMethodFilter, MaxRequestSizeFilter ✗ —
CustomHeaderFilter (proxyHttpResponseHeadersJson) — ✗
setDecodeAmbiguousURIs(true) ✗ ✗
popularServletParams(...) (request buffer size) — ✗

Keeping the two environments would mean maintaining two parallel, differently-typed filter chains
for the rest of PIP-472's lifetime. Running one environment and adapting the legacy servlets into it
is simpler and gives every additional servlet the same request pipeline.

Modifications

  • Drop Jetty's ee8 API from Pulsar's web tier. WebService.addServletEe8 and
    WebServer.addServletEe8 are deleted (both were introduced by [improve][misc] PIP-472: Migrate from javax.* to jakarta.* APIs #25912 and have never been in a
    release), and api(libs.jetty.ee8.servlet) is removed from pulsar-broker and pulsar-proxy.
  • Adapt legacy javax.servlet additional servlets instead. A new
    AdditionalServletUtils.toJakartaServlet(AdditionalServlet) in pulsar-broker-common returns a
    JAKARTA_SERVLET instance as it is, and wraps a JAVAX_SERVLET instance in
    org.apache.felix.http.jakartawrappers.ServletWrapper from
    org.apache.felix:org.apache.felix.http.wrappers:1.1.10 (Apache-2.0; ~91 KB; its only dependencies
    are the two servlet APIs, both already on the classpath). Both flavours are then registered through
    the ordinary addServlet path.
  • Collapse the duplicated registration branches in PulsarService.addBrokerAdditionalServlets
    and ProxyServiceStarter.addWebServerHandlers: the JAVAX_SERVLET / JAKARTA_SERVLET switch and
    its duplicated instanceof-check-log-close-skip blocks become one call. Behaviour on a mismatched
    servlet instance is unchanged (log an error, close the servlet, skip it).
  • Version catalog: add felix-http-wrappers; drop the jetty-ee8-servlets, jetty-ee8-proxy
    and jetty-ee8-websocket-jetty-server aliases, which no build file referenced. jetty-ee8-servlet
    stays for jetty-upgrade/'s patched ZooKeeper admin server, which implements ZooKeeper's own
    javax.servlet-based APIs and runs a separate Jetty server. javax.servlet:javax.servlet-api:4.0.1
    stays as the API of legacy plugins (4.0 is a floor, not a preference: the Felix wrappers reference
    Servlet 4.0 types such as javax.servlet.http.PushBuilder), and moves to pulsar-broker-common
    alongside the Felix dependency.
  • Test-only ee8 leftovers: MockBrokerService moves from org.eclipse.jetty.ee8.nested.* to an
    ee10 ServletContextHandler with a jakarta.servlet HttpServlet, and
    PrometheusMetricsTestUtil now imports org.eclipse.jetty.ee10.servlet.HttpOutput, matching
    PulsarPrometheusMetricsServlet. After this PR no Pulsar source outside jetty-upgrade/ references
    a Jetty ee8 class.
  • pip/pip-472.md is amended in place to describe the single-environment design, why the
    ee8/ee10 coexistence was replaced, and the added/removed dependencies.

Verifying this change

  • Make sure that the change passes the CI checks.

This change added tests and can be verified as follows:

  • New BrokerAdditionalServletFilterChainTest and ProxyAdditionalServletFilterChainTest register a
    javax.servlet additional servlet with authentication enabled and assert that an unauthenticated
    request is rejected with 401 while an authenticated one gets 200 and the expected body. Both
    fail on the pre-change code (verified locally: expected: 401 but was: 200 for the javax case;
    the jakarta case passes on both sides, so the test is specific to the environment split).
  • BrokerAdditionalServletTest and ProxyAdditionalServletTest gained a legacy javax.servlet
    additional servlet next to the existing jakarta.servlet one. The shared
    LegacyJavaxAdditionalServlet fixture echoes the query parameter, request URI and method it
    observes through the javax API, so a mistranslated request is visible; the proxy test also asserts
    the CustomHeaderFilter response header now reaches the javax servlet.
  • The existing container-based TestAdditionalServlets covers the real NAR path — RandomAdditionalServlet
    is a javax.servlet AdditionalServlet loaded through NarClassLoader from /pulsar/examples.
    Ran locally against a freshly built image: testBrokerAdditionalServlet and
    testProxyAdditionalServlet both pass.
  • ./gradlew quickCheck, ./gradlew sanityCheck, ./gradlew :distribution:pulsar-server-distribution:checkBinaryLicense
    and ./gradlew :distribution:pulsar-shell-distribution:checkBinaryLicense all pass. The jetty-ee8-*
    and jetty-servlet-api entries stay in LICENSE.bin.txt because the patched ZooKeeper admin server
    still brings them into lib/.

Does this pull request potentially affect one of the following parts:

If the box was checked, please highlight the changes

  • Dependencies (add or upgrade a dependency)
  • The public API
  • The schema
  • The default values of configurations
  • The threading model
  • The binary protocol
  • The REST endpoints
  • The admin CLI options
  • The metrics
  • Anything that affects deployment

Adds org.apache.felix:org.apache.felix.http.wrappers:1.1.10 (Apache-2.0) to pulsar-broker-common
and removes org.eclipse.jetty.ee8:jetty-ee8-servlet from pulsar-broker and pulsar-proxy.

The AdditionalServlet SPI itself is unchanged: plugins reporting JAVAX_SERVLET and plugins
reporting JAKARTA_SERVLET both keep working, without recompilation. addServletEe8 is removed, but
it only ever existed on master (5.0.0-M1-SNAPSHOT) and is not part of any release.

…servlet additional servlets

PIP-472 kept a second Jetty environment (ee8) alive alongside ee10 so that
AdditionalServlet plugins written against javax.servlet would keep working
without recompilation. Each Jetty environment owns its own servlet context,
servlet handler and filter chain, and Pulsar's broker/proxy filters are
jakarta.servlet-typed, so servlets registered in the ee8 environment ran
outside the request pipeline every other servlet goes through: the
requiresAuthentication argument handed to addServletEe8 had no effect.

Drop Jetty's ee8 API from Pulsar's web tier and adapt a legacy javax.servlet
handler to jakarta.servlet with the Apache Felix
org.apache.felix.http.jakartawrappers.ServletWrapper, registering it through
the ordinary ee10 path. Both flavours now share one environment and one
filter chain.

Assisted-by: Claude Code (Opus 5)

@david-streamlio david-streamlio left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed at 0443f23. I verified the substantive claims independently rather than reading the diff
and agreeing with it — the design argument holds up and the tests earn their place.

Reproduced the motivation. I put BrokerAdditionalServletFilterChainTest and
LegacyJavaxAdditionalServlet onto the pre-change tree (36ff86c) unmodified and ran them:
testJavaxAdditionalServletGoesThroughTheFilterChain fails with
expected: 401 but was: 200, and passes on this branch. So the test is specific to the environment
split rather than to anything else the PR touches, exactly as you describe. Both new filter-chain
tests pass here (BrokerAdditionalServletFilterChainTest 2/2, ProxyAdditionalServletFilterChainTest
1/1), and :pulsar-broker-common:compileJava, :pulsar-broker:compileTestJava,
:pulsar-proxy:compileTestJava are clean.

Checked the dependency claims. org.apache.felix.http.wrappers:1.1.10 is 93,676 bytes, and its
POM declares only javax.servlet-api:4.0.1 and jakarta.servlet-api:6.0.0 (both provided, so
nothing transitive) plus provided/test annotations and test libs — matching the description. It is
compiled against exactly the 4.0.1 the catalog pins. The wrapper set is complete for the paths an
additional servlet can take: AsyncContextWrapper, AsyncListenerWrapper, PartWrapper,
PushBuilderWrapper, ReadListenerWrapper, ServletInputStream/OutputStreamWrapper,
RequestDispatcherWrapper, HttpSessionWrapper. That was my main worry with an adapter approach and
it looks well covered.

Checked the cleanup is complete.

  • No addServletEe8 and no org.eclipse.jetty.ee8 reference anywhere in the tree after this PR
    except jetty-upgrade/, and that module genuinely uses libs.jetty.ee8.servlet
    (PrometheusMetricsProvider, JettyAdminServer), so keeping that one alias is right.
  • The three dropped aliases (jetty-ee8-servlets, jetty-ee8-proxy,
    jetty-ee8-websocket-jetty-server) are referenced by zero build files on master.
  • PulsarService.addBrokerAdditionalServlets and ProxyServiceStarter.addWebServerHandlers are the
    only two consumers of AdditionalServlets outside the SPI itself, so converting both covers every
    registration path.
  • Every module whose sources mention javax.servlet now declares the dependency itself
    (pulsar-broker-common implementation, pulsar-broker/pulsar-proxy testImplementation,
    java-test-plugins compileOnly) — nothing was relying on the api(libs.jetty.ee8.servlet) that
    this PR removes.

toJakartaServlet also quietly fixes a latent NPE: the old branches called
servletInstance.getClass().getName() in the mismatch log, which would itself throw if
getServletInstance() returned null. The new message handles null.

Two nits, neither blocking:

  1. Both filter-chain tests build a new OkHttpClient() per request and never shut down its
    dispatcher or connection pool. One client as a field, shut down in the @AfterClass, would keep
    the thread pools bounded — it is the kind of thing that only shows up as flakiness under a loaded
    CI runner.
  2. ProxyAdditionalServletFilterChainTest covers only the javax case, while the broker test covers
    javax and jakarta. The jakarta half is what shows the assertion is specific to the legacy
    path rather than to proxy filter wiring in general, so it is worth the few lines on the proxy side
    too.

…xy jakarta case

- Both filter-chain tests now build a single OkHttpClient in setup and shut down its
  dispatcher and connection pool in cleanup, instead of one client per request.
- ProxyAdditionalServletFilterChainTest gains the jakarta.servlet case, so the proxy
  assertion is shown to be specific to the legacy path rather than to proxy filter
  wiring in general. The jakarta fixture moves out of the broker test into a shared
  JakartaAdditionalServlet that mirrors LegacyJavaxAdditionalServlet, so both flavours
  echo the same request parts and can be compared directly.

Assisted-by: Claude Code (Opus 5)
@lhotari

lhotari commented Sep 1, 2026

Copy link
Copy Markdown
Member Author

Thanks for the careful review — and for reproducing the motivation on the pre-change tree rather than taking the description on faith.

Both nits addressed in 30d7fe2:

  1. OkHttpClient lifecycle. Each filter-chain test now creates one client in setup() and shuts down its dispatcher's executor service and evicts its connection pool in cleanup(), instead of a fresh client per request.
  2. jakarta case on the proxy side. ProxyAdditionalServletFilterChainTest now covers jakarta alongside javax, mirroring the broker test. The jakarta fixture moved out of the broker test's private inner class into a shared JakartaAdditionalServlet next to LegacyJavaxAdditionalServlet; both now echo the same param|requestURI|method shape, so the two paths are compared directly rather than through differently-shaped assertions.

Verified locally: BrokerAdditionalServletFilterChainTest 2/2, ProxyAdditionalServletFilterChainTest 2/2, BrokerAdditionalServletTest 1/1, ProxyAdditionalServletTest 1/1, plus quickCheck.

On the previous run, the only red job was CI - Unit - Brokers - Broker Group 2:
SegmentAbortedTxnProcessorTest.testPutAbortedTxnIntoProcessor timing out in waitTaskExecuteCompletely (ConditionTimeoutException ... expected:<1> but was:<0> within 10 seconds). Unrelated to this PR — nothing here touches the transaction buffer — and a sibling method in the same class has an open flaky report (#19650). It passes locally on this branch (6/6).

@lhotari

lhotari commented Sep 2, 2026

Copy link
Copy Markdown
Member Author

CI is green — all 44 checks pass on 30d7fe2.

The one red job on the first pass of this commit was CI - Integration - Kubernetes: PulsarFunctionsK8STest.testCreateFunctionInK8sWithSecrets failing with HTTP 400 {"reason":"Function test-function already exists"}, with AsyncHttpConnector.retryOperation in the stack — the admin client's HTTP retry re-sent a non-idempotent createFunctionWithUrl, so the retry collided with the function the first attempt had already created. Known flake, tracked in #25218, and unrelated to this PR (nothing here touches Functions, the Kubernetes runtime, or the admin client). It passed on rerun.

@david-streamlio re-requested — the two nits are addressed in 30d7fe2.

@lhotari lhotari added this to the 5.0.0-M2 milestone Sep 2, 2026
@lhotari
lhotari merged commit f3c7707 into apache:master Sep 2, 2026
82 of 84 checks passed
Radiancebobo pushed a commit to Radiancebobo/pulsar that referenced this pull request Oct 8, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants