WebActionFactory produces duplicate JSON variants when gRPC and protobuf POST coexist on same path

[tklovett]

Summary

A server that wants to support both gRPC and protobuf POST over HTTP on the same path cannot do so — WebActionsServlet throws IllegalArgumentException at startup due to duplicate JSON variant routing.

Problem

WebActionFactory.transformActionIntoJson() automatically creates a JSON variant of every protobuf-based WebAction:

• @WireRpc actions: JSON variant changes dispatch from GRPC to POST with JSON media types.
• @Post + @RequestContentType(APPLICATION_PROTOBUF) actions: JSON variant replaces protobuf media types with JSON equivalents.

Since @WireRpc and @RequestContentType are mutually exclusive on the same function (enforced in Actions.kt), supporting both gRPC and protobuf POST requires two separate WebAction classes. Each independently produces a JSON variant, and the two JSON variants have identical routing:

Action	Dispatch	Accepted Media	Response Content Type
gRPC original	GRPC	application/grpc	application/grpc
gRPC JSON variant	POST	application/json	application/json;charset=utf-8
Protobuf POST original	POST	application/x-protobuf	application/x-protobuf
Protobuf POST JSON variant	POST	application/json	application/json;charset=utf-8

WebActionsServlet's init block checks all bound actions pairwise via BoundAction.hasIdenticalRouting(), finds the two JSON variants identical, and throws:

IllegalArgumentException: Actions [MyGrpcAction, MyProtobufPostAction] have identical routing annotations.

Why existing deduplication doesn't help

collectBoundActions() deduplicates with actions.distinctBy { it.action }, but this only operates within a single WebAction class. It does not deduplicate across separate classes — each class goes through newBoundAction() independently from the WebActionsServlet init block.

No workaround available

Attempt: @WireRpc + @Post without @RequestContentType

Putting both annotations on one function avoids the duplicate routing error (the @Post variant defaults to MediaRange.ALL_MEDIA, so no JSON variant is created for it). However, without @ResponseContentType, the action's responseContentType is null, and ResponseBodyMarshallerFactory cannot find a marshaller for a proto return type:

IllegalArgumentException: no marshaller for null as HelloReply
    at ResponseBodyMarshallerFactory.genericMarshallerFor(ResponseBodyMarshallerFactory.kt:33)
    at ResponseBodyMarshallerFactory.create(ResponseBodyMarshallerFactory.kt:20)
    at ResponseBodyFeatureBinding$Factory.create(ResponseBodyFeatureBinding.kt:122)

Adding @ResponseContentType(APPLICATION_PROTOBUF) fixes the marshaller but re-triggers transformActionIntoJson creating a JSON variant — bringing back the original duplicate routing error.

Prior art: Armeria unframed requests

Armeria handles this with enableUnframedRequests(true) on a GrpcService. A single gRPC service definition automatically supports gRPC, gRPC-Web, JSON POST (application/json), and protobuf POST (application/protobuf) — no separate actions, no variant collisions.

This matters for servers migrating from Armeria to Misk: Armeria clients using protobuf POST (unframed) to call a service will break after that service migrates to Misk, since Misk can't register both gRPC and protobuf POST on the same path.

Possible fixes

1. Cross-class JSON variant deduplication: Move deduplication from collectBoundActions() (per-class) to WebActionsServlet's init block (global). When two bound actions have identical routing, keep one and discard the duplicate instead of throwing.

2. Allow suppressing JSON variant creation: Add an annotation (e.g. @NoJsonVariant) that tells transformActionIntoJson to skip creating a JSON variant for a specific action.

3. Lift the @WireRpc + @RequestContentType restriction: Allow a single function to carry both annotations so one WebAction class can serve gRPC and protobuf POST, with the per-class distinctBy deduplication handling the single JSON variant.

Relevant code

• WebActionFactory.transformActionIntoJson() — misk/src/main/kotlin/misk/web/actions/WebActionFactory.kt
• WebActionsServlet init block — misk/src/main/kotlin/misk/web/jetty/WebActionsServlet.kt
• BoundAction.hasIdenticalRouting() — misk/src/main/kotlin/misk/web/BoundAction.kt
• KFunction.asAction() — misk/src/main/kotlin/misk/Actions.kt
• ResponseBodyMarshallerFactory — misk/src/main/kotlin/misk/web/interceptors/ResponseBodyMarshallerFactory.kt

[tklovett]

Also relates to:

• Allow a single action method to support multiple request content types #82
• Added DispatchMechanism to Action #1049

[tklovett]

cc @swankjesse and @adrw

[tklovett]

Possible fix #4: Unframed requests — automatic protobuf POST variant for gRPC actions

In addition to the three fixes listed in the issue, there's a fourth option that both solves the duplicate routing error and eliminates the need for a second WebAction class entirely.

Concept

transformActionIntoJson already creates a synthetic JSON POST variant for every gRPC action. We can add a symmetric transformActionIntoProtobufPost that creates a synthetic protobuf POST variant from the same gRPC action:

Variant	Dispatch	Accepted Media	Response Content Type	Source
gRPC (original)	GRPC	application/grpc	application/grpc	@WireRpc
JSON POST (existing)	POST	application/json	application/json;charset=utf-8	transformActionIntoJson
Protobuf POST (new)	POST	application/x-protobuf	application/x-protobuf	transformActionIntoProtobufPost

One @WireRpc action → three protocols. No second action class needed.

Why no serialization changes are needed

The protobuf POST variant uses DispatchMechanism.POST, so GrpcFeatureBinding does not activate (it guards on dispatchMechanism == GRPC). Instead, requests flow through the standard RequestBodyFeatureBinding / ResponseBodyFeatureBinding pipeline:

• Request: Content-Type: application/x-protobuf → existing Protobuf.UnmarshallerFactory uses ProtoAdapter.decode() to read raw (unframed) protobuf bytes.
• Response: responseContentType = application/x-protobuf → existing Protobuf.MarshallerFactory uses ProtoAdapter.encode() to write raw protobuf bytes.

No gRPC framing (length-prefixed messages, compression flag, trailers) is involved — exactly what "unframed" means. The existing Protobuf.kt marshaller/unmarshaller already handles this for @Post + @RequestContentType(APPLICATION_PROTOBUF) actions today.

Implementation sketch

~20 lines in WebActionFactory:

// New method — mirrors transformActionIntoJson
private fun transformActionIntoProtobufPost(action: Action): Action? {
    if (action.dispatchMechanism != DispatchMechanism.GRPC) return null
    if (action.parameters.size != 1) return null  // unary only

    val mappedParameters = action.parameters.toMutableList()
    mappedParameters[0] = mappedParameters[0].withAnnotations(listOf(requestBodyAnnotation()))
    return action.copy(
        dispatchMechanism = DispatchMechanism.POST,
        acceptedMediaRanges = protobufMediaRanges,
        responseContentType = protobufMediaType,
        parameters = mappedParameters,
    )
}

Wire into collectBoundActions():

val jsonVariant = transformActionIntoJson(action)
val protobufPostVariant = transformActionIntoProtobufPost(action)

listOfNotNull(
    newBoundAction(provider, pathPattern, action),
    jsonVariant?.let { newBoundAction(provider, pathPattern, it) },
    protobufPostVariant?.let { newBoundAction(provider, pathPattern, it) },
)

No changes to Actions.kt, BoundAction, or the routing model.

Opt-in vs always-on

The JSON variant is always-on today. I'd recommend making the protobuf POST variant opt-in initially (e.g. @UnframedRequests annotation on the action function) to avoid unexpectedly increasing the protocol surface area of existing gRPC services. It can be made always-on later once adoption is validated.

Streaming limitation

Only applies to unary gRPC (1 parameter). Streaming actions require gRPC framing and have no plain POST equivalent. The parameters.size != 1 guard excludes them. This matches Armeria's unframed requests, which also limits to unary methods.

Backward compatibility

For servers that already have both a @WireRpc action and a separate @Post + @RequestContentType(APPLICATION_PROTOBUF) action on the same path, the new automatic variant would collide with the explicit one. Fix #1 (cross-class deduplication in WebActionsServlet) should be applied alongside to handle this gracefully — replacing the IllegalArgumentException with dedup + warning log.

Comparison

Fix	Solves duplicate routing	Eliminates second action class	Scope of change
#1 Cross-class dedup	Yes	No	WebActionsServlet only
#2 @NoJsonVariant	Yes (manual)	No	WebActionFactory + annotation
#3 Lift annotation restriction	Yes (with extensive changes)	Yes	Actions.kt, WebActionFactory, BoundAction
#4 Unframed requests	Yes (with #1 for compat)	Yes	WebActionFactory + annotation

I wrote this up in more detail in docs/json-variant-duplicate-routing.md on branch ai-tlovett/json-variant-dupe.