Skip to content

Fix GDTStorage background task not being ended on storeEvent: failure paths - #179

Open
tilltue wants to merge 2 commits into
google:mainfrom
tilltue:fix/gdtstorage-background-task-leak
Open

tilltue wants to merge 2 commits into
google:mainfrom
tilltue:fix/gdtstorage-background-task-leak

Conversation

@tilltue

@tilltue tilltue commented Sep 2, 2026 •

Copy link
Copy Markdown

Summary

-[GDTCORFlatFileStorage storeEvent:onComplete:] begins a GDTStorage background task,
but the three failure paths inside the dispatched block (encode failure, storage size
limit reached, write failure) return without ending it. While the tracked storage size
is at or over kGDTCORFlatFileStorageSizeLimit, every successfully encoded event takes
the size-limit branch, so no store attempt releases its assertion until the system
expires it.

__block GDTCORBackgroundIdentifier bgID = GDTCORBackgroundIdentifierInvalid;
bgID = [[GDTCORApplication sharedApplication]
beginBackgroundTaskWithName:@"GDTStorage"
expirationHandler:^{
// End the background task if it's still valid.
[[GDTCORApplication sharedApplication] endBackgroundTask:bgID];
bgID = GDTCORBackgroundIdentifierInvalid;
}];
dispatch_async(_storageQueue, ^{
// Check that a backend implementation is available for this target.
GDTCORTarget target = event.target;
NSString *filePath = [GDTCORFlatFileStorage pathForTarget:target
eventID:event.eventID
qosTier:@(event.qosTier)
expirationDate:event.expirationDate
mappingID:event.mappingID];
NSError *error;
NSData *encodedEvent = GDTCOREncodeArchive(event, nil, &error);
if (error) {
completion(NO, error);
return;
}
// Check storage size limit before storing the event.
uint64_t resultingStorageSize = self.sizeTracker.directoryContentSize + encodedEvent.length;
if (resultingStorageSize > kGDTCORFlatFileStorageSizeLimit) {
NSError *error = [NSError
errorWithDomain:GDTCORFlatFileStorageErrorDomain
code:GDTCORFlatFileStorageErrorSizeLimitReached
userInfo:@{
NSLocalizedFailureReasonErrorKey : @"Storage size limit has been reached."
}];
if (self.delegate != nil) {
GDTCORLogDebug(@"Delegate notified that event with mapping ID %@ was dropped.",
event.mappingID);
[self.delegate storage:self didDropEvent:event];
}
completion(NO, error);
return;
}
// Write the encoded event to the file.
BOOL writeResult = GDTCORWriteDataToFile(encodedEvent, filePath, &error);
if (writeResult == NO || error) {
GDTCORLogDebug(@"Attempt to write archive failed: path:%@ error:%@", filePath, error);
completion(NO, error);
return;
} else {
GDTCORLogDebug(@"Writing archive succeeded: %@", filePath);
completion(YES, nil);
}
// Notify size tracker.
[self.sizeTracker fileWasAddedAtPath:filePath withSize:encodedEvent.length];
// Check the QoS, if it's high priority, notify the target that it has a high priority event.
if (event.qosTier == GDTCOREventQoSFast) {
// TODO: Remove a direct dependency on the upload coordinator.
[self.uploadCoordinator forceUploadForTarget:target];
}
// Cancel or end the associated background task if it's still valid.
[[GDTCORApplication sharedApplication] endBackgroundTask:bgID];
bgID = GDTCORBackgroundIdentifierInvalid;

This change ends the task on every exit path. The success-path teardown point is
unchanged (still after the size tracker update and the high-QoS upload trigger).

Related: firebase/firebase-ios-sdk#15129 (currently closed, needs-info). Filling the
storage past the limit gives a deterministic way to exercise the leaking path (steps
below).

Testing

  • New unit tests in GDTCORFlatFileStorageTest (second commit), using the existing
    GDTCORApplicationFake: testStoreEvent_WhenSizeLimitReached_ThenBackgroundTaskIsEnded,
    testStoreEvent_WhenWritingFails_ThenBackgroundTaskIsEnded and
    testStoreEvent_WhenEventIsWritten_ThenBackgroundTaskIsEnded expect the GDTStorage
    task to begin once and end once with the identifier returned on begin. With the
    failure-path end calls removed, the size-limit and write-failure tests fail on the
    unfulfilled "Background task end" expectation.
  • Locally, unit suite GoogleDataTransport-Unit-Tests-Unit on the iOS simulator:
    113 tests, 0 failures.
  • Locally, simulator reproduction with the storage over the limit: before this change
    every GDTStorage task created during the run was left un-ended and produced the
    "was created over 30 seconds ago" warning; after this change all were ended.
Reproduction steps and measurements
  1. Run any app that uses GDT on the simulator, then terminate it.
  2. Place a >20 MB file in the app container under Library/Caches/google-sdks-events/
    (a sparse file is enough — GDTCORDirectorySizeTracker sums NSURLFileSizeKey;
    e.g. mkfile -n 21m filler).
  3. Relaunch and watch log stream --predicate 'eventMessage CONTAINS "GDTStorage"'.

My counts of Created background task / Ending task with identifier over 150 s
foreground runs:

storage created ended ">30 seconds ago" warnings
main @ 5d20ca19, baseline 8 KB 75 75 0
main @ 5d20ca19, over limit 22 MB 67 0 67
main @ 5d20ca19, filler removed 8 KB 67 67 0
this change, over limit 22 MB 161 161 0
Notes
  • Test seam: GDTCORFlatFileStorage takes the application through
    -initWithApplication:, as GDTCORTransformer does. -init passes
    +[GDTCORApplication sharedApplication] and the property is readonly. The tests create
    their own instance with GDTCORApplicationFake; the initializer is declared for them in
    a class extension in GDTCORFlatFileStorage+Testing.h. Production behaviour is
    unchanged apart from the fix.
  • bgID is accessed from the expiration handler and _storageQueue without
    synchronisation. This is pre-existing (the success path already had it, and
    GDTCORTransformer has the same pattern); the failure paths now share it. I can
    follow up separately if you would like that addressed.
  • Unit suite run with -testLanguage en -testRegion US because
    testFetchAndUpdateMetrics_WhenDecodeError compares an English
    localizedFailureReason and fails on a non-English host regardless of this change.
    Not run locally: tvOS/macOS/Catalyst/watchOS, Thread Sanitizer.
  • Environment: reproduction on GoogleDataTransport 10.1.0 (storeEvent:onComplete:
    unchanged in 10.1.1 and on main at 5d20ca19); iPhone 17 simulator, iOS 26.0,
    Xcode 26.0 (17A324). Unit tests on main at 5d20ca19 plus this PR; iPhone 18 Pro
    simulator, iOS 27.2, Xcode 27.2 (27B52), with IPHONEOS_DEPLOYMENT_TARGET=15.0
    because Xcode 27.2 rejects the pods' 9.0/12.0 deployment targets. Style checked with
    clang-format 23.1.5.

… paths

-[GDTCORFlatFileStorage storeEvent:onComplete:] begins a "GDTStorage"
background task before dispatching to the storage queue. Outside the
expiration handler, only the success path ended it: the three early
returns inside the dispatched block (encode failure, storage size limit
reached, write failure) returned without ending it, leaving the
assertion outstanding until the system expired it. Once the storage
directory reaches kGDTCORFlatFileStorageSizeLimit, every subsequent
store attempt takes the size-limit branch, so no attempt releases its
assertion.

Extract the teardown into an endBackgroundTaskIfNeeded block and call it
on each exit path. The success-path teardown point is unchanged: it still
runs after the size tracker update and the high-QoS upload trigger.

Related: firebase/firebase-ios-sdk#15129
@google-cla

google-cla Bot commented Sep 2, 2026

Copy link
Copy Markdown

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

@paulb777

Copy link
Copy Markdown
Member

Please see the following code review and address at least the test gap:

Assessment of PR #179: "Fix GDTStorage background task not being ended on storeEvent: failure paths"

Verdict: the fix is correct and worth merging. It needs a test, and a couple of small points should be checked first.

The bug is real

In -[GDTCORFlatFileStorage storeEvent:onComplete:] on main, a background task named GDTStorage is started before the dispatch_async. It is only ended on the success path at the bottom of the block. All three failure paths inside the block return early without ending it:

  1. GDTCOREncodeArchive fails.
  2. The storage size limit is exceeded.
  3. GDTCORWriteDataToFile fails.

In each case the task stays open until iOS runs the expiration handler. That shows up as "background task not ended" warnings, and it can count against the app's background time. The size-limit path is the most likely to be hit in practice: once the disk cache is full, every new event leaks a task.

The fix

  • It adds a local endBackgroundTaskIfNeeded block that ends the task only if bgID is still valid, then marks it invalid. It's called on all three failure paths and replaces the old unconditional end on the success path.
  • It covers every early return inside the block. The event == nil return happens before the task starts, so it doesn't need the call.
  • The block memory handling is fine under ARC: the local block is copied and captured by the dispatch_async block, and __block bgID is shared correctly.
  • The validity check is a small improvement: the success path no longer calls end with an ID that is already invalid (for example, after the expiration handler has run).

Concerns and suggestions

  1. No test (main gap). Add at least one unit test, ideally for the size-limit path since it's easy to trigger. It should check that the background task is ended when storing fails. If GDTCORApplication is hard to fake here, that's worth raising with the author rather than skipping the test.
  2. Existing race, not fixed but not made worse. bgID is read and written from both _storageQueue and the expiration handler (main thread) with no synchronization. The check-then-end in the new block isn't atomic, so the task could still be ended twice in a narrow window. The worst result is a UIKit log warning. This can be a separate follow-up.
  3. Style nit. A single exit point would stop the next person from reintroducing this bug. Options include restructuring the block, or wrapping completion so it always ends the task. Not required.
  4. Unrelated, optional. The comment "Check that a backend implementation is available for this target" at the top of the block is out of date and could be cleaned up while this code is being touched.

@tilltue

tilltue commented Nov 13, 2026 •

Copy link
Copy Markdown
Author

Thanks for the review. Updated in 34b10a6:

  1. Tests. GDTCORFlatFileStorage now takes the application through -initWithApplication:, as GDTCORTransformer does, so the tests can use GDTCORApplicationFake. I chose an initializer over a settable property so that tests create their own instance instead of modifying the shared one, and the property stays readonly. New tests check that the task is ended once on the success, size-limit and write-failure paths. The encode-failure path has no test: a real event always archives, so it would need a test-only subclass that opts out of NSSecureCoding.
  2. bgID race. Left for a follow-up.
  3. Single exit point. Kept the explicit calls. Wrapping completion would end the task before the size tracker update and the upload trigger. I can move the block body into a helper instead if you prefer.
  4. Outdated comment. Removed.

The initializer is declared for tests in a class extension in GDTCORFlatFileStorage+Testing.h, so the library headers are unchanged. Declaring it in the (Testing) category instead triggers -Wincomplete-implementation.

Unit tests pass locally on iOS: 113 tests. Not run on tvOS, macOS or Catalyst.

Edited after amending the commit. An earlier version described a settable property.

@tilltue
tilltue force-pushed the fix/gdtstorage-background-task-leak branch from 14f0cbd to b1c63ba Compare November 13, 2026 04:15
Make the application used for the GDTStorage background task injectable,
as GDTCORTransformer does: GDTCORFlatFileStorage gets a readonly
`application` property and -initWithApplication:, and -init passes
+[GDTCORApplication sharedApplication]. -storeEvent:onComplete: captures
the application once per call, so begin, the expiration handler and end
use the same instance. Tests declare the initializer in a class
extension in GDTCORFlatFileStorage+Testing.h. Declaring it in the
(Testing) category triggers -Wincomplete-implementation.

Add three tests that create their own storage instance with
GDTCORApplicationFake. A stored event, an event dropped because the
storage size limit is reached, and an event whose write fails each begin
and end the task exactly once with the identifier returned on begin.
Without the fix in the previous commit, the size-limit and write-failure
tests fail on the unfulfilled "Background task end" expectation. The
write fails because a regular file occupies the event's directory path.
The dropped event carries a 1 KB payload, so it cannot fit in the space
left after filling the storage.

The encode-failure branch is not tested: a real event always archives,
so reaching it would need a test-only event class that opts out of
NSSecureCoding.

testInit checks that the shared and new instances use the shared
application. Also remove an outdated comment at the top of the storage
block.
@tilltue
tilltue force-pushed the fix/gdtstorage-background-task-leak branch from b1c63ba to 34b10a6 Compare November 13, 2026 13:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants