add ability to disable deadline propagation

[bjlaub]

Adds a method to disable further propagation of deadline values via the Deadlines.encodeToRequest method. The use case for this is to prevent RPC call stacks from continuing to send Expect-Within: 0 after a deadline has expired, which can lead to quite a bit of noise in reported metrics and logging.

Callers can use Deadlines.disableFurtherDeadlinePropagation() to instruct the library to ignore the internal deadline state on further calls to encodeToRequest. Future calls to Deadlines.getRemainingDeadline() will return Optional.empty().

Callers are expected to use this only when they can ensure that further operations should not be subject to deadline enforcement. A primary use case for this is for requests that spin off background work which may continue to make requests, even when the original request handler has terminated. In those instances, callers may wish to stop enforcing the deadline as it is quite possible a background task will make a request well into the future after the original deadline is expired, and the semantics of that are somewhat of a judgement call. Adding this flag will allow callers to control the fate of such future requests with respect to deadline enforcement.

This change adds the following:

• the Deadlines.disableFurtherDeadlinePropagation() method, which alters the internal state of the current deadline within the TraceLocal, setting a flag to disable propagation
• changes the internal state structures to track deadline propagation via a boolean
• adds an intent tag to the deadline expiration meter metric reported via this library; this tag will be set to ignore in scenarios where encodeToRequest was called after disableFurtherDeadlinePropagation was called, and propagate otherwise

==COMMIT_MSG==
add ability to disable deadline propagation
==COMMIT_MSG==

[changelog-app]

Generate changelog in changelog/@unreleased

What do the change types mean?

• feature: A new feature of the service.
• improvement: An incremental improvement in the functionality or operation of the service.
• fix: Remedies the incorrect behaviour of a component of the service in a backwards-compatible way.
• break: Has the potential to break consumers of this service's API, inclusive of both Palantir services
  and external consumers of the service's API (e.g. customer-written software or integrations).
• deprecation: Advertises the intention to remove service functionality without any change to the
  operation of the service itself.
• manualTask: Requires the possibility of manual intervention (running a script, eyeballing configuration,
  performing database surgery, ...) at the time of upgrade for it to succeed.
• migration: A fully automatic upgrade migration task with no engineer input required.

Note: only one type should be chosen.

How are new versions calculated?

• ❗The break and manual task changelog types will result in a major release!
• 🐛 The fix changelog type will result in a minor release in most cases, and a patch release version for patch branches. This behaviour is configurable in autorelease.
• ✨ All others will result in a minor version release.

Type

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

Description

add ability to disable deadline propagation

Check the box to generate changelog(s)

• Generate changelog entry

[bjlaub]

should we encode disablePropagation as a separate tag on the meter?

[carterkozak]

I think that would be helpful

[carterkozak]

Should Optional<Duration> getRemainingDeadline() return an empty optional after this is called?

[carterkozak]

Outside of metrics, I think this should be equivalent to deadlineState.remove()

[bjlaub]

i'm not sure. disableFurtherDeadlinePropagation doesn't mean that the deadline no longer exists in the current TraceLocal state, just that we won't add the header on future calls to encodeToRequest. maybe there is a valid use case for checking the deadline value even after we have disabled propagation?

[bjlaub]

Outside of metrics, I think this should be equivalent to deadlineState.remove()

i think that's perhaps fair, though it narrows some possibilities quite a bit.

[bjlaub]

I've updated the implementation to return Optional.empty() in this case.

[carterkozak]

perhaps something like action or intent with values along the lines of [propagate, ignore]? I often find boolean metric tags a bit harder to understand, and they don't leave much opportunity to add additional states if we decide to roll out a feature flag later on

[bjlaub]

ya, i'll rephrase. it's a little nuanced as i don't want to convey that the intent was to ignore enforcement of a deadline expiration originally, just that it should be ignored from a certain point onwards (and, the meter marked with this tag will only be marked after that point and so the intent is a little ambiguous).

[bjlaub]

let me know what you think of this phrasing: https://github.com/palantir/deadlines-java/pull/42/files#diff-5415ea5dd248a8ccb374b1e951c3c3c0e320974aa75934eb6049080f95900b34R21-R33

Invalidated by push of 3de80d8

[carterkozak]

👍