[mstoykov]

What?

Stack 2 of 6

Base: feature/async-context (stack PR 1, #6340)

Head: async-group-base

The next PR will target this branch and add timer callback propagation.

When async-metric-context is enabled, this PR allows group() callbacks to return Promises or
Promise-like thenables. The group's complete metric context follows Promise reactions, and
group_duration is emitted once when the returned asynchronous result settles.

group() still invokes its callback immediately. A non-thenable result follows the synchronous path
and is returned unchanged. For an asynchronous result, the implementation:

• snapshots the parent context and the group's entry context;
• restores the parent as soon as the callback returns or throws;
• attaches per-invocation fulfillment and rejection handlers;
• preserves the fulfillment value or rejection reason;
• uses a native-Promise fast path and assimilates generic thenables into a real Sobek Promise; and
• emits one duration sample on fulfillment or rejection, including for synchronously settling or
  throwing custom thenables.

The disabled path retains the existing rejection of native async callbacks and the existing mutable
tag behavior for synchronous callbacks.

This deliberately makes synchronous and asynchronous groups use the same duration context when the
feature is enabled. group_duration uses the tags and metadata captured at group entry. Mutations
made inside the callback affect metrics emitted there, but they do not retag group_duration and the
complete parent context is restored when group() returns. Without the feature, the legacy
synchronous path records group_duration with the context present when the callback finishes and
leaves non-group tag and metadata mutations live.

Five one-second benchmark runs with GOMAXPROCS=1 measured an awaited resolved Promise at
4.934 us/op, 5,376 B/op, and 89 allocations with the feature enabled, versus 4.828 us/op,
5,328 B/op, and 87 allocations with it disabled. Returning a group around a resolved Promise
measured 8.796 us/op, 8,424 B/op, and 135 allocations; awaiting it measured 11.711 us/op,
10,584 B/op, and 173 allocations.

Why?

Today, group() restores its tag as soon as the callback returns. Work after an await or inside a
Promise handler therefore loses the group, and group_duration measures only the synchronous prefix.
That makes groups unreliable for k6's increasingly asynchronous APIs, as reported in #2728 and
summarized in #5435 and #5673.

Duration ownership is kept separate from the general context tracker. The tracker answers which
metric context a Promise reaction should run under; each group() invocation owns its own start time,
entry snapshot, and settlement state. This separation is what lets several groups overlap without one
group completing or retagging another.

Using the entry snapshot for group_duration also keeps its attribution independent of when a
callback mutates tags or metadata. Applying completion-time context only to synchronous callbacks
would preserve the old behavior under the feature flag, but would make otherwise equivalent sync and
async groups report duration with different contexts.

The callback is intentionally called before checking its return value. This preserves the existing
synchronous group() behavior and supports ordinary, bound, proxied, or transpiled functions that
happen to return a Promise. It also preserves the execution order A, C, B for a callback that does
work A, awaits, then does work B, followed by synchronous caller work C.

Alternatives considered:

• k6: group special async function treatment #2863 detected the callback's AsyncFunction class and deferred the whole callback through a
  Promise job. That changes ordering to C, A, B, misses ordinary functions returning Promises, and
  couples group lifetime to async-function tracking rather than the returned value.
• Change how group() calls async functions #2848 proposes deferring async callback invocation. This PR deliberately does not adopt that
  scheduling change; its regression test locks in immediate invocation. The issue is related but is
  not closed by this PR.
• Looking only for native Promises would be simpler, but valid Promise-like return values would either
  finish too early or make await group(...) resume with the return value of then(). Generic
  thenables are therefore assimilated into a real Promise.
• Emitting duration when the callback returns would preserve legacy timing but would not measure the
  asynchronous operation. A never-settling result consequently has no completed duration, matching
  the fact that the group itself never completes.

Checklist

• I have performed a self-review of my code.
• I have commented on my code, particularly in hard-to-understand areas.
• I have added tests for my changes.
• I have run linter and tests locally (make check) and all pass.

Checklist: Documentation (only for k6 maintainers and if relevant)

Please do not merge this PR until the following items are filled out.

• I have added the correct milestone and labels to the PR.
• I have updated the release notes: TBD for the complete experimental stack
• I have updated or added an issue to the
  k6-documentation: TBD; the group() documentation must
  describe the feature flag, asynchronous lifetime, and entry-context semantics of group_duration
• I have updated or added an issue to the
  TypeScript definitions:
  not applicable; the existing generic return type already preserves a Promise returned by the
  callback

Related PR(s)/Issue(s)

• Parent stack PR: async metric-context foundation
• group doesn't work with async calls well (#2728)
• Change how group() calls async functions (#2848)
  — related ordering proposal, intentionally not closed
• Try to use Sobek's AsyncContextTracker for async groups
  (#3392)
• Design doc for supporting async code in groups (#5435), now
  closed
• Implement AsyncContext via the TC39 standard for async groups
  (#5673)
• Earlier implementation attempt: #2863

[szkiba]

LGTM. Good work.

[janHildebrandt98]

nit: nil check is obsolete :)

[janHildebrandt98]

Could update this error message to explain that there is a feature flag now