Introduce ReferenceDelegates (#1222)

* Bump sequence number on resume token refresh

* Style

* Fix comment formatting

* Add FSTReferenceDelegate definition and documentation

* Add methods to return nil for delegates, wire up inMemoryPins

* Add hook for removing a reference

* Start work on reference delegates

* Fix up tests to support adding documents at a sequence number

* Implement removing references

* Remove from target when dropped from local view

* Fix warning

* Add hooks for removal from mutation queue

* Add hooks for limbo document updates

* Style

* Drop commented-out code

* Fixup after merging master

* Drop sequence number plumbing

* Style

* Drop errant semicolon

1 files changed, 57 insertions, 0 deletions

diff --git a/Firestore/Source/Local/FSTPersistence.h b/Firestore/Source/Local/FSTPersistence.h
index 2294ef1..417ff3f 100644
--- a/Firestore/Source/Local/FSTPersistence.h
+++ b/Firestore/Source/Local/FSTPersistence.h
@@ -16,12 +16,16 @@
 
 #import <Foundation/Foundation.h>
 
+#import "Firestore/Source/Core/FSTTypes.h"
 #import "Firestore/Source/Util/FSTAssert.h"
 #include "Firestore/core/src/firebase/firestore/auth/user.h"
 
+@class FSTDocumentKey;
 @protocol FSTMutationQueue;
 @protocol FSTQueryCache;
+@class FSTQueryData;
 @protocol FSTRemoteDocumentCache;
+@class FSTReferenceSet;
 
 NS_ASSUME_NONNULL_BEGIN
 
@@ -56,6 +60,7 @@ NS_ASSUME_NONNULL_BEGIN
  * of its reads and writes in order to avoid relying on being able to read back uncommitted writes.
  */
 struct FSTTransactionRunner;
+@protocol FSTReferenceDelegate;
 @protocol FSTPersistence <NSObject>
 
 /**
@@ -87,6 +92,12 @@ struct FSTTransactionRunner;
 
 @property(nonatomic, readonly, assign) const FSTTransactionRunner &run;
 
+/**
+ * This property provides access to hooks around the document reference lifecycle. It is initially
+ * nullable while being implemented, but the goal is to eventually have it be non-nil.
+ */
+@property(nonatomic, readonly, strong) _Nullable id<FSTReferenceDelegate> referenceDelegate;
+
 @end
 
 @protocol FSTTransactional
@@ -97,6 +108,52 @@ struct FSTTransactionRunner;
 
 @end
 
+/**
+ * An FSTReferenceDelegate instance handles all of the hooks into the document-reference lifecycle.
+ * This includes being added to a target, being removed from a target, being subject to mutation,
+ * and being mutated by the user.
+ *
+ * Different implementations may do different things with each of these events. Not every
+ * implementation needs to do something with every lifecycle hook.
+ *
+ * Implementations that care about sequence numbers are responsible for generating them and making
+ * them available.
+ */
+@protocol FSTReferenceDelegate
+
+/**
+ * Registers an FSTReferenceSet of documents that should be considered 'referenced' and not eligible
+ * for removal during garbage collection.
+ */
+- (void)addInMemoryPins:(FSTReferenceSet *)set;
+
+/**
+ * Notify the delegate that a target was removed.
+ */
+- (void)removeTarget:(FSTQueryData *)queryData;
+
+/**
+ * Notify the delegate that the given document was added to the given target.
+ */
+- (void)addReference:(FSTDocumentKey *)key target:(FSTTargetID)targetID;
+
+/**
+ * Notify the delegate that the given document was removed from the given target.
+ */
+- (void)removeReference:(FSTDocumentKey *)key target:(FSTTargetID)targetID;
+
+/**
+ * Notify the delegate that a document is no longer being mutated by the user.
+ */
+- (void)removeMutationReference:(FSTDocumentKey *)key;
+
+/**
+ * Notify the delegate that a limbo document was updated.
+ */
+- (void)limboDocumentUpdated:(FSTDocumentKey *)key;
+
+@end
+
 struct FSTTransactionRunner {
 // Intentionally disable nullability checking for this function. We cannot properly annotate
 // the function because this function can handle both pointer and non-pointer types. It is an error