Skip to content

Merge the Smithy server into org.restlet.ext.smithy, on par with its client - #1674

Merged
jlouvel merged 6 commits into
3.0from
feat/smithy-server-in-ext
Nov 16, 2026
Merged

jlouvel merged 6 commits into
3.0from
feat/smithy-server-in-ext

Conversation

@jlouvel

@jlouvel jlouvel commented Nov 14, 2026 •

Copy link
Copy Markdown
Collaborator

Closes #1673. The Smithy server of #1638 moves into org.restlet.ext.smithy, beside the client, and catches up with it.

One artifact

SmithyServerAdapter and SmithyServerHost move into org.restlet.ext.smithy, and the org.restlet.ext.smithy.server artifact goes away. It has never been released, so changes.md rewrites its Milestone 2 entry rather than recording a breaking change.

smithy-java 1.8.0's server-api and server-core still split package software.amazon.smithy.java.server (smithy-java#1437), so the module can't require them:

  • server-core is an optional dependency, so client-only users don't get it. Maven puts it on the class path, outside the module graph.
  • The module compiles with --add-reads org.restlet.ext.smithy=ALL-UNNAMED. @SuppressWarnings("exports") covers the SDK types that the public API exposes.
  • Named consumers of the server pass the same --add-reads, at compile time and at run time. SmithyModuleTestCase.namedConsumerHostsAService covers this case.

Decision to check in review: whether this class-path-reading setup is acceptable in a named module until #1437 ships. The alternative is to keep a separate artifact without a descriptor.

Parity with the client

Client Server, before Server, now
SDK discovery ClientTransportFactory restlet none ServerProvider restlet: by name, or when Netty is absent (priority -1, Netty 0)
Explicit API SmithyClientAdapter SmithyServerAdapter SmithyServerAdapter, and a new public SmithyServerBuilder
Protocols tested restJson1, RPCv2 CBOR restJson1 restJson1, RPCv2 CBOR, over HTTP/1.1 and HTTP/2
Named modules tested class path only tested, with --add-reads

SmithyServerBuilder implements the SDK's ServerBuilder, with one Restlet server connector per endpoint (http or https) and one adapter per route:

  • numberOfWorkers sets each route's concurrent-call limit.
  • context(Context) passes connector parameters (HTTP/2, TLS), and maxRequestBytes and maxCallDuration set the adapters' limits.
  • A call goes to the first route whose path prefix (decoded), host name, and connector port and scheme match it, and whose services resolve its operation; otherwise it falls through to the next route, as attachTo scores routes. The port and scheme come from the connector that took the call, not from the Host header.
  • When routes only set path prefixes, the longest matching prefix wins: the SDK's builder keeps addService(path, …) mappings in a HashMap, so a / route could otherwise take calls meant for a longer prefix. Routes that also match hosts, ports or schemes keep the order they were added in.
  • The SDK's ServiceMatcher is not used for this. It ignores host names, and compares an unset port (null) with -1.
  • Endpoints need a host, and may only have a scheme, a host and a port. IPv6 hosts lose their brackets before reaching the connector.
  • A failed start keeps its cause when stopping what started fails too.
  • Without server-core, the discovered provider fails with a clear error rather than a NoClassDefFoundError at build time.
  • The provider has priority -1 so that adding this extension for its client doesn't replace an application's Netty server.

The provider is declared only in META-INF/services. A provides clause would need the split package, so Server.builder() discovers the builder on the class path only.

Upstream findings (smithy-java 1.8.0, unchanged on main)

  • The RPCv2 server serializes a modeled error without its __type, so clients get a CallException rather than the modeled error. cborModeledErrorsLoseTheirTypeUpstream pins it.
  • Over RPCv2 CBOR, missing @required members aren't rejected: the input comes with zero values. Range and length constraints are still enforced, and invalidInputIsRejected tests one.

Tests (70, coverage met, no SpotBugs findings)

  • SmithyServerBuilderTestCase (new, 17): fallthrough to a route resolving the call, decoded prefixes, IPv6 addresses, a CBOR round trip over HTTP/1.1 and HTTP/2, validation, the upstream error bug, prefix, port, scheme and host routing, a Host header naming another port, the longest prefix winning, host routes keeping their order, limits, invalid settings, single use, a failed start stopping what it started, and the provider.
  • SmithyModuleTestCase: the server jars are now kept off the module path, and two child-JVM consumers are added:
    • a named module hosting the generated restJson1 Notes service;
    • a class-path consumer whose server comes from Server.builder() discovery and whose CBOR client uses the discovered transport.
  • SmithyServerAdapterTestCase moved unchanged, apart from the generated package.
  • Test code generation now uses one smithy-build projection per model: greeter, notes and the new counter.

🤖 Generated with Claude Code

jlouvel and others added 4 commits November 14, 2026 10:32
…ient

The server moves from the org.restlet.ext.smithy.server artifact into
org.restlet.ext.smithy, which reads the SDK server, an optional
dependency, on the class path: smithy-java 1.8.0 splits its package.
A ServerProvider named restlet and a public SmithyServerBuilder let
Server.builder() discover Restlet connectors, as SDK clients discover
the transport. RPCv2 CBOR, a named consumer hosting a service and
class-path discovery are now tested.

Closes #1673

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Routes match the port and scheme of the connector that took a call,
not those of its Host header. Path prefixes are only reordered when
routes set nothing else, so that routes on hosts, ports or schemes
keep their order. Endpoints with a path, query, fragment or user info,
routes without services and null durations are rejected. The server
provider now comes after the SDK's Netty server, so that adding the
extension for its client doesn't change an application's server.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A call now goes to the first matching route whose services resolve its
operation, so a longer prefix or an earlier route no longer hides the
operations of later ones. Prefixes match the decoded path, endpoints
need a host, IPv6 hosts lose their brackets, a failed start keeps its
cause, and the provider reports a missing server-core clearly. The
server class moves next to the adapter, holding each route with its
adapter.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Like the compiler, the Javadoc tool needs --add-reads
org.restlet.ext.smithy=ALL-UNNAMED to resolve the smithy-java server
types, which stay outside the module graph.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Copilot AI 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.

🟡 Changes recommended

Path decoding incorrectly converts literal plus signs to spaces, causing prefix-matching errors, and the module-access instructions omit the consumer’s required class-path access flag.

2 open issues
What changed in this PR

Merges experimental Smithy server hosting into org.restlet.ext.smithy, placing client and server support in one artifact, consistent with other Restlet extensions.

Changes:

  • Adds a public server builder and class-path provider discovery, with configurable routing, connectors, and request limits.
  • Supports named-module server use through class-path read flags while keeping server dependencies optional.
  • Expands tests for RPCv2 CBOR, HTTP/2, routing, lifecycle, and consumer discovery.
File Description
readme.md Describes unified Smithy client and server support.
pom.xml Removes the separate server module from the reactor.
org.restlet.ext.smithy/​src/​test/​smithy/​smithy-build.json Defines separate code-generation projections for three models.
org.restlet.ext.smithy/​src/​test/​smithy/​notes.smithy Moves the restJson1 server test model into the unified extension.
org.restlet.ext.smithy/​src/​test/​smithy/​counter.smithy Adds an RPCv2 CBOR test service.
org.restlet.ext.smithy/​src/​test/​java/​org/​restlet/​ext/​smithy/​SmithyServerBuilderTestCase.java Tests builder settings, routing, protocols, lifecycle, and provider behavior.
org.restlet.ext.smithy/​src/​test/​java/​org/​restlet/​ext/​smithy/​SmithyServerAdapterTestCase.java Updates moved tests to the generated Notes namespace.
org.restlet.ext.smithy/​src/​test/​java/​org/​restlet/​ext/​smithy/​SmithyModuleTestCase.java Adds named-server and class-path discovery consumer tests.
org.restlet.ext.smithy/​src/​main/​resources/​META-INF/​services/​software.amazon.smithy.java.server.ServerProvider Registers the Restlet server provider for class-path discovery.
org.restlet.ext.smithy/​src/​main/​java/​org/​restlet/​ext/​smithy/​SmithyServerBuilder.java Adds the public builder with endpoint, routing, and limit configuration.
org.restlet.ext.smithy/​src/​main/​java/​org/​restlet/​ext/​smithy/​SmithyServerAdapter.java Integrates the moved adapter with builder routing and module documentation.
org.restlet.ext.smithy/​src/​main/​java/​org/​restlet/​ext/​smithy/​RestletSmithyServer.java Implements connector lifecycle and route dispatch.
org.restlet.ext.smithy/​src/​main/​java/​org/​restlet/​ext/​smithy/​internal/​SmithyServerHost.java Moves SDK request handling into the unified extension.
org.restlet.ext.smithy/​src/​main/​java/​org/​restlet/​ext/​smithy/​internal/​RestletServerProvider.java Adds the named provider, yielding to Netty by default.
org.restlet.ext.smithy/​src/​main/​java/​module-info.java Documents the server’s class-path workaround; module declarations remain unchanged.
org.restlet.ext.smithy/​pom.xml Adds optional server dependencies, read flags, and expanded test generation.
org.restlet.ext.smithy.server/​src/​test/​smithy/​smithy-build.json Removes the superseded server-only code-generation configuration.
org.restlet.ext.smithy.server/​pom.xml Removes the separate server artifact definition.
changes.md Updates the unreleased Smithy entry for unified hosting and discovery.

Review effort: Balanced

…t the consumer's read of the class path

Reference.decode() uses URLDecoder, which turned a '+' in the request path into a space before
the route prefix was matched. The '+' is now escaped first, so the path is decoded with URI path
semantics. The Javadoc and changes.md now also give the --add-reads flag a named consumer module
needs for SDK and generated service types.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Copilot AI 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.

🔵 Needs a closer look

Malformed percent escapes in request paths can throw an uncaught IllegalArgumentException, causing the Netty connector to abort the connection without an HTTP response instead of treating the route as unmatched.

No open issues 🎉

1 previously missed issue

In code that hasn't changed since last review

Medium severity Handle invalid percent escapes as unmatched routes

org.restlet.ext.smithy/​src/​main/​java/​org/​restlet/​ext/​smithy/​RestletSmithyServer.java:199

A request path such as /service/%GG/operation/Add reaches this decoder unchanged. Reference.decode throws IllegalArgumentException, which escapes the dispatcher and causes the Netty connector to abort the connection without an HTTP response. Catch invalid escapes and treat the route as unmatched, consistent with the host's guarded URI resolution.

2 resolved since last review

Review effort: Balanced

…prefix

URLDecoder throws IllegalArgumentException on an escape such as %zz, which escaped the
dispatcher and aborted the connection without a response. Such a path now matches no prefix.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@jlouvel

jlouvel commented Nov 14, 2026

Copy link
Copy Markdown
Collaborator Author

Copilot's review of 537e1ec reported one finding in its body only, "Handle invalid percent escapes as unmatched routes" (RestletSmithyServer.java). Fixed in e3fc35e: matches now catches the IllegalArgumentException that URLDecoder throws on an escape such as %zz, and treats the path as matching no prefix, so the dispatcher answers 404 instead of aborting the connection. Covered by malformedPercentEscapesMatchNoPrefix.

@sonarqubecloud

Copy link
Copy Markdown

Copilot AI 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.

🔵 Needs a closer look

Human assessment is needed because regression coverage does not establish that an already-started endpoint is stopped when a later connector fails.

No open issues 🎉

Review effort: Balanced

@jlouvel
jlouvel merged commit a56f6bd into 3.0 Nov 16, 2026
4 of 5 checks passed
@jlouvel
jlouvel deleted the feat/smithy-server-in-ext branch November 16, 2026 13:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants