Converter hints

[cretz]

What was changed

A concept of "converter hint" has been added. In most user-facing places where an object may get serialized or deserialized, a converter hint can be provided to help custom converters get contextual information about what to do. The default converters do nothing with this today, but custom converters can use these as "type hints" to know things like what type to deserialize into.

While this PR is significant, it should only affect those that choose to use the feature.

💥 BACKWARDS INCOMPAT - There are technically backwards incompatible changes to the signature of converters for those with custom converters today. This is considered an acceptable tradeoff for those rare cases pre-GA.

Checklist

1. Closes [Feature Request] Support "hints" for payload conversion #271

[Sushisource]

Not to blow up your whole thing here, but... did you consider having a class like RawPayload but instead ObjectWithHint or something, that could be used as a wrapper around the user's input/return value/whatever so that we don't have to have these hints as extra parameters to so many APIs?

[cretz]

Not to blow up your whole thing here, but... did you consider having a class like RawPayload but instead ObjectWithHint or something

This doesn't help deserialization, because you need to know what type you want to deserialize into before the deserialization happens. So you have to provide that hint somewhere. Ruby simply has no concept of type hinting where we can determine what type you intend.

that could be used as a wrapper around the user's input/return value/whatever so that we don't have to have these hints as extra parameters to so many APIs?

Sure, users can still use wrappers like that with their converters if they want. But we would like to be like other SDKs and let the definitions of the things (e.g. activities, workflows, signals, queries, updates, nexus operations, etc) apply the hints, not the caller. All the other hint parameters are as overrides or for when you don't have the definition present.

So for a workflow for instance, users using this feature will set workflow_arg_hint and workflow_result_hint on their workflow and that's it. Now callers get it (client and child workflow) and implementers get it (deserialization of args, serialization of result). This matches behavior by other SDKs. We tried to make it generic enough that it's effectively just "converter metadata at declaration time".

[Sushisource]

Yeah, that makes sense. Just a bit depressing how much surface area this affects, but, I don't have any reasonable ideas on how to solve that.