feat: NSE helper - WPB-22200 by KaterinaWire · Pull Request #4389 · wireapp/wire-ios

KaterinaWire · 2026-03-04T09:42:17Z

WPB-22200 [iOS] Research into background calls issues

Issue

NSE Helper is a lightweight AVS instance that runs inside the Notification Service Extension (NSE). Its purpose is to process call-related events while the main app is not running and determine whether a call should be started, updated, or ended.

Unlike the current implementation, where the NSE attempts to infer call state itself, the “NSE Helper” uses the same call-state logic as AVS and acts as the source of truth for call decisions within the NSE process. It processes call events received during notification sync and produces high-level actions such as "incoming call", "missed call", or "close call".

The NSE Helper and the main app each run their own AVS instance and do not share runtime state. Instead, they independently derive call state from the same stream of call events, ensuring that call decisions are made by AVS logic rather than by custom state-tracking code in the NSE.

The NSE helper should call wcall_event_create() during initialization and retain the returned handle for all subsequent API calls.

When a notification is received, the helper should call wcall_event_start(). During the notification sync process, every call-related event encountered should be passed to wcall_event_process().

Once syncing is complete, the helper should call wcall_event_end(). At that point, the library will evaluate all processed events and invoke the callbacks that were registered with wcall_event_create(). Depending on the final state of each call, one of the following callbacks will be triggered:

incomingh for a new incoming call
missedh for a missed call
closeh for a call that should be closed

This allows the NSE to process all call events as a batch and receive the resulting call actions only after synchronization has finished.

https://wearezeta.atlassian.net/wiki/spaces/CS1/pages/2395111536/iOS+AVS+background+calls#iOS-workaround

TODO:

add tests
add logs

Testing

All the calling notifications.

Checklist

Title contains a reference JIRA issue number like [WPB-XXX].
Description is filled and free of optional paragraphs.
Adds/updates automated tests.

UI accessibility checklist

If your PR includes UI changes, please utilize this checklist:

Make sure you use the API for UI elements that support large fonts.
All colors are taken from WireDesign.ColorTheme or constructed using WireDesign.BaseColorPalette.
New UI elements have Accessibility strings for VoiceOver.

sonarqubecloud · 2026-04-20T11:40:49Z

Quality Gate passed

Issues
4 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

github-actions · 2026-06-15T07:44:02Z

Test Results

2 files 188 suites 22s ⏱️
846 tests 846 ✅ 0 💤 0 ❌
847 runs 847 ✅ 0 💤 0 ❌

Results for commit 59a99e2.

♻️ This comment has been updated with latest results.

Summary: workflow run #28586749119
Allure report (download zip): html-report-31456-feat_avs_for_nse

samwyndham · 2026-06-15T15:00:12Z

+
+    private var callingService: any AVSCallingEventServiceProtocol {
+        shared {
+            AVSCallingEventService(


question: Is it OK to have multiple instances of AVSCallingEventService alive simultaneously? Asking this as an NSE can have multiple instances of a NSEClientScope.

It's a good question. From Dusan's words, wcall_event_create should be called only once when the NSE starts. And every time we receive a push notification, we create a new instance of NSEClientScope, which will contain only one instance of AVSCallingEventService.

netbe

left some comments before approving

netbe · 2026-06-15T15:12:17Z

+    }
+}
+
+private struct AVSIdentifier {


question: don't we have this logic already somewherw?

Yes, this is in the WireRequestStrategy, because all the calling logic is currently in the RS and SE, I didn't want to significantly change and change the existing legacy architecture to save time and efforts (implementation + testing, especially since we do call testing manually). We plan to migrate this logic to Kalium soon.

netbe · 2026-06-15T15:13:00Z

+///
+/// Callback-triggered CallKit work is tracked as pending tasks so the NSE can wait
+/// for reporting to finish before continuing with regular notification generation.
+final class CallKitReportingCoordinator {


suggestion: is it possible to make this an actor instead of relying on locks

netbe · 2026-06-15T15:19:16Z

+            notificationEventStream = AsyncStream<[UpdateEvent]> { continuation in
+                for batch in eventBatches {
+                    continuation.yield(batch)
+                }
+                continuation.finish()
+            }


question: is there a need for this? can't you just pass eventStream

netbe · 2026-06-15T15:25:11Z

+        timestamp: Date,
+        isMLS: Bool
+    ) async -> AVSCallParams? {
+        let callingConvID = callingProto.qualifiedConversationID


nit-pic:

Suggested change

let callingConvID = callingProto.qualifiedConversationID

let callingConversationID = callingProto.qualifiedConversationID

netbe · 2026-06-15T15:30:37Z

@@ -0,0 +1,49 @@
+# NSE Calling Events
+
+## Overview


praise: documentation added

netbe · 2026-06-15T15:33:44Z

+        eventBatches: [[UpdateEvent]],
+        callKitReportingCoordinator: CallKitReportingCoordinator
+    ) async {
+        callingService.start()


todo: add cancellation checks in case the NSE cancels the outer task

netbe · 2026-06-16T06:43:10Z

+    func waitForCompletion() async {
+
+        while true {
+            let snapshot: [Task<Void, Never>] = {


todo: add cancellation checks

netbe · 2026-06-16T06:43:52Z

+        let task = Task {
+            do {
+                try await CXProvider.reportNewIncomingVoIPPushPayload(callKitContent)
+            } catch {


question: could you explain why we have this registration mechanism of tasks?
Should we handle cancellation here ?

johnxnguyen

Looks good, just a few questions

johnxnguyen · 2026-06-17T06:44:11Z

+                    callKitReportingCoordinator.setCallerName(
+                        params.callerName,
+                        for: params.conversationId
+                    )


question: what is the purpose of this?

don't worry, I see now it's because it'll be used later if we report the call.

johnxnguyen · 2026-06-17T06:49:51Z

+
+    private func avsParametersForProteus(
+        _ event: ConversationProteusMessageAddEvent
+    ) async -> [AVSCallParams] {


question: why does this return an array when the buildParams function it uses returns AVSCallParams?, which is then wrapped in an array and returned, only for the calling function avsParameters(from event) just takes the first value of this array?

johnxnguyen · 2026-06-17T06:58:38Z

+        }
+
+        avsService.onMissedCall = { [self] _, _, _ in
+            markCallbackReceived()


question: why don't we handle the missed call event?

johnxnguyen · 2026-06-17T07:30:57Z

+        callerNamesByConversationID[conversationID.storageKey] = callerName
+    }
+
+    /// Wait for all callback-started CallKit tasks to finish.


question: how many callbacks do we realistically expect to occur? Just one at a time? Or it's valid that there may be multiple?

johnxnguyen · 2026-06-17T07:33:57Z

+            var eventBatches: [[UpdateEvent]] = []
+            for await batch in eventStream {
+                eventBatches.append(batch)
+            }
+
+            _ = callKitReportingCoordinator
+            await processCallingEventsUseCase.invoke(
+                eventBatches: eventBatches,
+                callKitReportingCoordinator: callKitReportingCoordinator
+            )
+
+            notificationEventStream = AsyncStream<[UpdateEvent]> { continuation in
+                for batch in eventBatches {
+                    continuation.yield(batch)
+                }
+                continuation.finish()
+            }


question: do I understand this correctly, we will collect all the events, then pass them all to the AVS helper (which may wake the main app to report the call), and only then continue with normal execution to display any other notifications?

Copilot

Pull request overview

Introduces an “NSE Helper” path in WireDomain to batch-process call-related notification sync events through AVS (wcall_event_*) inside the Notification Service Extension, and to translate AVS callback results into CallKit reporting actions.

Changes:

Adds a new calling-event processing pipeline: ProcessCallingEventsUseCase + AVSCallingEventService + CallKitReportingCoordinator.
Gates legacy CallKit notification behavior behind DeveloperFlag.enableNSEHelper.
Updates WireDomain docs and package dependencies to support the new NSE calling-event flow.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
WireDomain/Sources/WireDomain/WireDomain.docc/WireDomain.md	Adds navigation entry for NSE calling-event documentation.
WireDomain/Sources/WireDomain/WireDomain.docc/nse-calling-events.md	Documents the intended NSE helper event-batching flow and AVS callbacks.
WireDomain/Sources/WireDomain/Notifications/ShowNotificationUseCase.swift	Skips waking the main app via `CXProvider.reportNewIncomingVoIPPushPayload` when the helper flag is enabled.
WireDomain/Sources/WireDomain/Notifications/Protocols/ProcessCallingEventsUseCaseProtocol.swift	Adds protocol for the new calling-event batching use case.
WireDomain/Sources/WireDomain/Notifications/ProcessCallingEventsUseCase.swift	Implements extraction + forwarding of calling payloads from synced events into AVS.
WireDomain/Sources/WireDomain/Notifications/Components/NSEClientScope.swift	Integrates calling-event batching into NSE sync flow behind a developer flag.
WireDomain/Sources/WireDomain/Notifications/Components/CallKitReportingCoordinator.swift	Adds CallKit reporting orchestration for AVS callback results and completion waiting.
WireDomain/Sources/WireDomain/Notifications/Components/AVSCallingEventService.swift	Adds the AVS `wcall_event_*` bridge and callback plumbing for the NSE helper.
WireDomain/Sources/WireDomain/Notifications/Builders/Conversation/ConversationCallingEventNotificationBuilder.swift	Disables building CallKit call notifications when helper flag is enabled.
WireDomain/Package.swift	Adds WireAVS dependency to WireDomain.
wire-ios-utilities/Source/DeveloperFlag.swift	Introduces `enableNSEHelper` developer flag.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+    public init(userID: String, clientID: String) {
+        self.handle = 0
+        wcall_set_log_handler({ _, msgPtr, _ in
+            guard let msg = msgPtr.flatMap({ String(cString: $0) }) else { return }
+            WireLogger.calling.debug(msg, attributes: .newNSE, .safePublic)
+        }, nil)
+        let retained = Unmanaged.passRetained(self)


+        let service = Unmanaged<AVSCallingEventService>.fromOpaque(contextRef).takeUnretainedValue()
+        WireLogger.mls.info("12345 \(service.onIncomingCall == nil), conversationId = \(conversationId)")
+        service.onIncomingCall?(


+                        conversationId: params.conversationId,
+                        userId: params.userId,
+                        clientId: clientID,
+                        conversationType: params.conversationType
+                    )


+        case let .conversation(.proteusMessageAdd(e)):
+            await avsParametersForProteus(e).first
+        case let .conversation(.mlsMessageAdd(e)):
+            await avsParametersForMLS(e).first
+        default:


+            _ = callKitReportingCoordinator
+            await processCallingEventsUseCase.invoke(
+                eventBatches: eventBatches,
+                callKitReportingCoordinator: callKitReportingCoordinator
+            )


+            var eventBatches: [[UpdateEvent]] = []
+            for await batch in eventStream {
+                eventBatches.append(batch)
+            }


+final class ProcessCallingEventsUseCase: ProcessCallingEventsUseCaseProtocol {
+
+    private let callingService: any AVSCallingEventServiceProtocol
+    private let clientID: String
+    private let conversationLocalStore: any ConversationLocalStoreProtocol


sonarqubecloud · 2026-07-02T11:38:49Z

Quality Gate passed

Issues
5 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

KaterinaWire added 3 commits February 25, 2026 18:05

temp

85f560e

Merge branch 'develop' into feat/avs_for_nse

9866454

fix conversation ID

9e61dcd

github-actions Bot assigned KaterinaWire Mar 4, 2026

github-actions Bot added the Fix PR Title 🤦‍♂️ label Mar 4, 2026

KaterinaWire added 6 commits March 6, 2026 10:59

refactoring

c850412

Merge branch 'develop' into feat/avs_for_nse

2df105d

add more logs

1a1aad1

Merge branch 'develop' into feat/avs_for_nse

faff95c

added CallKitReportingCoordinator

46eaba2

temp

a383703

KaterinaWire changed the title ~~feat: NSE helper~~ feat: NSE helper - DRAFT (THIS MEANTS THAT SOME INFO AND LOGS WILL BE REMOVED) May 29, 2026

KaterinaWire and others added 17 commits June 5, 2026 14:53

resolve merge conflicts

7ae5965

Merge branch 'develop' into feat/avs_for_nse

8a352c8

temp add resolveCallerNameSync

b373fc3

Merge branch 'develop' into feat/avs_for_nse

fed33ea

temp - user name

3c74fd6

Merge branch 'develop' into feat/avs_for_nse

d4e1689

clean up

1da1fe5

remove logs

6b907d0

remove logs

8048931

remove commented code from NSEClientScope

915beee

clean up NSEClientScope

1ede72e

remove commented code

ad4ffa2

add and support enableNSEHelper developer flag

c2d885d

Merge branch 'develop' into feat/avs_for_nse

ef86f7b

add documentation

f14a446

add documentation

f7b5a2e

add comments and protocol to the ProcessCallingEventsUseCase

3ba4e26

KaterinaWire added 2 commits June 15, 2026 09:26

add comments

0abefc2

add comments

eafb317

KaterinaWire changed the title ~~feat: NSE helper - DRAFT (THIS MEANTS THAT SOME INFO AND LOGS WILL BE REMOVED)~~ feat: NSE helper Jun 15, 2026

Merge branch 'develop' into feat/avs_for_nse

0d65146

KaterinaWire marked this pull request as ready for review June 15, 2026 07:33

KaterinaWire requested review from johnxnguyen, netbe and samwyndham June 15, 2026 07:34

KaterinaWire changed the title ~~feat: NSE helper~~ feat: NSE helper - WPB-22200 Jun 15, 2026

github-actions Bot removed the Fix PR Title 🤦‍♂️ label Jun 15, 2026

Merge branch 'develop' into feat/avs_for_nse

fc22a59

samwyndham reviewed Jun 15, 2026

View reviewed changes

netbe reviewed Jun 16, 2026

View reviewed changes

Merge branch 'develop' into feat/avs_for_nse

8248d50

johnxnguyen reviewed Jun 17, 2026

View reviewed changes

Merge branch 'develop' into feat/avs_for_nse

135afda

Copilot AI review requested due to automatic review settings June 30, 2026 07:43

Copilot started reviewing on behalf of KaterinaWire June 30, 2026 07:43 View session

Copilot AI reviewed Jun 30, 2026

View reviewed changes

temp

59a99e2

	let callingConvID = callingProto.qualifiedConversationID
	let callingConversationID = callingProto.qualifiedConversationID

Uh oh!

Conversation

KaterinaWire commented Mar 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Issue

Testing

All the calling notifications.

Checklist

UI accessibility checklist

Uh oh!

sonarqubecloud Bot commented Apr 20, 2026

Quality Gate passed

Uh oh!

github-actions Bot commented Jun 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Test Results

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

netbe left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

johnxnguyen left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

sonarqubecloud Bot commented Jul 2, 2026

Quality Gate passed

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

KaterinaWire commented Mar 4, 2026 •

edited

Loading

github-actions Bot commented Jun 15, 2026 •

edited

Loading