User metadata

[THardy98]

What was changed

Added functionality for users to provide staticDetails and staticSummary metadata to workflow start commands.
These can be retrieved via describe on the workflow handler and are visibile via the UI/CLI.

Users can set currentDetails - a mutable details string within the workflow - via SetCurrentDetails and retrieve it via GetCurrentDetails. This is visible via the UI/CLI and the __temporal_workflow_metadata internal query.

Users can add a summary (short string description) when setting a timer and when starting an activity.

A notable part of the change is the addition of runWithOptions to activities. Activities can now override their activity options at call time, like so:

* // Setup Activities from module exports
 * const { httpGet, otherActivity } = proxyActivities<typeof activities>({
 *   startToCloseTimeout: '30 minutes',
 * });
 *
 * // Use activities with default options
 * const result1 = await httpGet('http://example.com');
 *
 * // Override options for specific activity calls
 * const result2 = await httpGet.executeWithOptions({
 *   staticSummary: 'Fetches data from external API',
 *   scheduleToCloseTimeout: '5m'
 * }, ['http://api.example.com']);
 *
 * const result3 = await otherActivity.executeWithOptions({
 *   staticSummary: 'Processes the fetched data',
 *   taskQueue: 'special-task-queue'
 * }, [data]);

1. Closes [Feature Request] Support user metadata #1544

2. How was this tested:
   Couple integration tests

3. Any docs updates needed?
   Maybe

[mjameswh]

Please add a short comment on all @experimental tags (see what we did elsewhere). Benefit isn't huge, but at least, it identifies which "feature" the experimental API is linked with.

[THardy98]

I believe i've done so in all the relevant places

[mjameswh]

I don't think we should have this WorkflowCommandOptions type. I even wonder if we should inline summary and details directly in ActivityInput (without the extra UserMetadata nesting). Or add these two to ActivityOptions, though that might pose some minor challenge regarding the type provided to the proxyActivities() function.

[mjameswh]

What did we do in other SDKs?

[THardy98]

Typically they are inline, I've changed it as such (aside from using ActivityOptions for summary/details for an activity, and TimerOptions as you suggested below)

[mjameswh]

I'm worried this will evolve badly. What if we then need to add description, and then other properties? Instead, I think I'd define a TimerOptions type, and take this as a second argument here. Then, we can easily add whatever properties we need.

[mjameswh]

Out of curiosity, what do we do in other SDKs?

[THardy98]

typically we inline, but went with TimerOptions here given your reasoning

[mjameswh]

🤔 That feels a bit awkward, and would prevent having an activity named withSummaries (ok, that's arguably very unlikely, but still means this approach would evolve badly).

I think we could get a better DX by using something similar to this, but at the activity-level rather than at the activities-level (mind the plural). That would also allow any extra option to be set at the call site, which is a recurring request.

For example, we could have:

const { echo } = proxyActivities<MyActivities>({ startToCloseTimeout: '5m' });

// No extra options
await echo(myArg1, myArg2);

// With extra options, higher order function style
await echo.withOptions({ summary: "..." })(myArg1, myArg2);

// Some other possible variants to be considered
await echo.withOptions({ summary: "..." }, myArg1, myArg2);
await echo.withOptions({ summary: "..." }, [myArg1, myArg2]);

I'll let you think you a bit about this, but we should probably include others in this discussion.

[THardy98]

opted for:
await echo.runWithOptions(options, args);

to allow users to override their default activity options

[THardy98]

renamed to executeWithOptions

[THardy98]

also quickly added lazy decoding summary/details from workflow description

can't do so (or at least annoying to do so) for schedule description because the description type has an invariant where the description must be a superclass of schedule options (which necessitate summary/details being strings)

the alternative being to add new fields that lazily populate the existing fields, but that feels like poor ux

[mjameswh]

What if summary is an empty string? As it is now, it will be replaced by undefined. Not sure what would be the desired result.

[mjameswh]

If we want to keep empty strings, then it might be cleaner to use some toOptionalPayload helper.

[mjameswh]

And if we don't care about empty strings, then should instead move the terniary out of this object:

      userMetadata: options?.summary
        ? {
            summary: activator.payloadConverter.toPayload(options.summary),
          }
        : undefined,

[THardy98]

I think having an empty summary string replaced with undefined is reasonable. I don't see a reason why having an empty summary would be useful (or any more useful than undefined).

[mjameswh]

I believe there should also be user metadata on:

• child workflows
• conditions
• signals
• update

[THardy98]

I believe there should also be user metadata on:

* child workflows

* conditions

* signals

* update

Added for conditions and child workflows. Signals/updates/queries have a description parameter which is used for a similar purpose: #1319 (I don't believe we've added user metadata for these in other SDKs as well, it doesn't mention it in the original feature issue).

also going to mention this again, because it's been awhile

[mjameswh]

Pointed out a few nits. Merge when ready.