Add backcompat stubs for optional header params

[gsheasby]

Before this PR

Similar to #960 - when an optional Header param is added to a method, no @Deprecated method without the header param is generated. This results in dev breaks, requiring any consumers to add either Optional.empty() or the header, as in this commit.

After this PR

==COMMIT_MSG==
When optional header params are added, Retrofit and Jersey generated code now includes deprecated methods without these headers - similar to those generated when optional query params are added.
==COMMIT_MSG==

Possible downsides?

Still not added for Dialogue - may split this into another PR.

[changelog-app]

Generate changelog in changelog/@unreleased

Type

• Feature
• Improvement
• Fix
• Break
• Deprecation
• Manual task
• Migration

Description

When optional header params are added, Retrofit and Jersey generated code now includes deprecated methods without these headers - similar to those generated when optional query params are added.

Check the box to generate changelog(s)

• Generate changelog entry

[carterkozak]

I'm worried that defining something along these lines may not compile due to multiple equivalent method signatures:

testOptionalHeaderParam:
  http: POST /test-optional
  args:
    maybeHeaderOne:
      type: optional<string>
      param-type: header
      param-id: MaybeHeaderOne
    maybeHeaderTwo:
      type: optional<string>
      param-type: header
      param-id: MaybeHeaderTwo
    maybeQueryOne:
      type: optional<string>
      param-type: query
    maybeQueryTwo:
      type: optional<string>
      param-type: query

[carterkozak]

Unsure if you're aware, we have a helper function to update the expected output ./gradlew test -Drecreate=true documented here

[carterkozak]

This example is generated into the suffixed files, but those are never compiled -- it would be helpful to define this somewhere that outputs into a source set that's also compiled for additional verification, otherwise duplicate methods with the same signature won't be caught by CI.

[gsheasby]

do you have a place in mind where I could put this example?

I think the cases where type clashes may cause the headers to not compile would be exactly when the first query param is optional and has the same type as any header param. This could be detected in code and worked around by not generating backcompat methods for header params if they would clash. It's likely a corner case in practice, but I appreciate that we need something that always compiles.

[carterkozak]

Adding it to a new service defined in ete-service.yml should provide compilation verification. Using a new service instead of an existing one means you won't need to update any resource implementations to stub the method.

Is there danger in upgrading from an endpoint with an optional header to an endpoint with an optional header and optional query parameter that the same parameter index and type becomes used for another field?

[gsheasby]

I guess to be safe you'd want there to always be a non-optional param (of any kind) directly after the last optional header param.

[gsheasby]

Caught up with @carterkozak via DM. Given the complexities involved in determining whether it's safe to have two dimensions of compatibility backfill methods (headers and query params), we won't be merging this.

[iamdanfox]

@gsheasby is it one specific library that you're concerned about here? Could we explore a local codegen & relocation workflow to make it invincible to any kind of java ABI/API change?

[a-k-g]

@carterkozak - would something like this work, to avoid the concern of equivalent method signatures:

1. Parameters in the generated methods would be in the same order as declared in the conjure definition. AuthHeader should always be the first, and any request object should be the last param. So for the example you gave, we should generate

testOptionalHeaderParam(request);
testOptionalHeaderParam(maybeHeaderOne, request);
testOptionalHeaderParam(maybeHeaderOne, maybeHeaderTwo, request);
testOptionalHeaderParam(request, maybeHeaderOne, maybeHeaderTwo, maybeQueryOne, request);
testOptionalHeaderParam(request, maybeHeaderOne, maybeHeaderTwo, maybeQueryOne, maybeQueryTwo, request);

2. Any time new parameters are added, we enforce (using conjure-backcompat) that they have to be added at the end. checkConjureBackCompat should fail if there is an attempt to add a new parameter in between existing ones.