Topic Mapping: Addressed concurrency issues introduced by Lazy-Loading

OnTopic.Tests/BindingModels/NestedReferenceAttributeTopicBindingModel.cs

@@ -0,0 +1,26 @@
+/*==============================================================================================================================
+| Author        Ignia, LLC
+| Client        Ignia, LLC
+| Project       Topics Library
+\=============================================================================================================================*/
+using OnTopic.ViewModels.BindingModels;
+
+namespace OnTopic.Tests.BindingModels;
+
+/*==============================================================================================================================
+| BINDING MODEL: NESTED REFERENCE ATTRIBUTE TOPIC
+\-----------------------------------------------------------------------------------------------------------------------------*/
+/// <summary>
+///   Provides a minimal implementation of a custom topic binding model with both a scalar value and a reference property, for
+///   use as an item within a <see cref="ContentTypeDescriptorTopicBindingModel.Attributes"/> collection.
+/// </summary>
+/// <remarks>
+///   This is a sample class intended for test purposes only; it is not designed for use in a production environment.
+/// </remarks>
+public class NestedReferenceAttributeTopicBindingModel : AttributeDescriptorTopicBindingModel {
+
+  public NestedReferenceAttributeTopicBindingModel(string key) : base(key, "TextAttributeDescriptor") { }
+
+  public AssociatedTopicBindingModel? BaseTopic { get; set; }
+
+} //Class

OnTopic.Tests/ITopicLazyLoadableTest.cs

@@ -3,6 +3,7 @@
 | Client        Ignia, LLC
 | Project       Topics Library
 \=============================================================================================================================*/
+using OnTopic.Associations;
 using OnTopic.Repositories;
 using OnTopic.Tests.TestDoubles;
 using Xunit;
@@ -19,6 +20,11 @@ namespace OnTopic.Tests;
 [ExcludeFromCodeCoverage]
 public class ITopicLazyLoadableTest {
 
+  /*============================================================================================================================
+  | PROPERTY: CANCELLATION TOKEN
+  \---------------------------------------------------------------------------------------------------------------------------*/
+  private static CancellationToken CancellationToken => TestContext.Current.CancellationToken;
+
   /*============================================================================================================================
   | TEST: IS LOADED: NON-RECURSIVE: IGNORES UNLOADED CHILDREN
   \---------------------------------------------------------------------------------------------------------------------------*/
@@ -161,7 +167,39 @@ public void IsLoaded_NotLoadedChildren_NeverTriggersLoad() {
   [Fact]
   public void EnsureLoaded_NullResolver_DoesNotThrow() {
     var topic                   = new Topic("Topic", "Page");
-    ((ITopicLazyLoadable)topic).EnsureLoaded(TopicPayload.All);
+    ((ITopicLazyLoadable)topic).EnsureLoaded(TopicPayload.All, CancellationToken);
+  }
+
+  /*============================================================================================================================
+  | TEST: ENSURE LOADED: CLEARED RELATIONSHIP: DOES NOT RESURRECT
+  \---------------------------------------------------------------------------------------------------------------------------*/
+  /// <summary>
+  ///   Registers a <see cref="Topic.Relationships"/> deferred entry, then calls <see cref=
+  ///   "TopicRelationshipMultiMap.Clear(String)"/> on that key. Confirms that a subsequent <see cref=
+  ///   "ITopicLazyLoadable.EnsureLoaded(TopicPayload,System.Threading.CancellationToken)"/> for <see cref=
+  ///   "TopicPayload.Relationships"/> never reaches the <see cref="ITopicLazyLoader"/>; since <see cref=
+  ///   "TopicRelationshipMultiMap.Clear(String)"/> already purged the deferred entry, there is nothing left to resolve, and the
+  ///   previously cleared relationship isn't resurrected.
+  /// </summary>
+  [Fact]
+  public async Task EnsureLoaded_ClearedRelationship_DoesNotResurrect() {
+
+    var topic                   = new Topic("Test", "Page", null, 1);
+    var rawLoadable             = (ITopicLazyLoadable)topic;
+    var rawTopic                = (ITopicBackingAccessor)topic;
+    var loader                  = new TrackingTopicLazyLoader();
+
+    // Set up and clear via the backing accessor so this doesn't itself trigger a load once LoadState flips to NotLoaded; the
+    // loader is stamped afterward, ahead of the explicit EnsureLoaded() call below
+    rawTopic.Relationships.Deferred.SetValue("Related", 999);
+    rawTopic.Relationships.Clear("Related");
+    rawLoadable.Loader          = loader;
+
+    await rawLoadable.EnsureLoaded(TopicPayload.Relationships, CancellationToken);
+
+    Assert.False(loader.WasCalled);
+    Assert.Empty(rawTopic.Relationships.GetValues("Related"));
+
   }
 
   /*============================================================================================================================

OnTopic.Tests/ReverseTopicMappingServiceTest.cs

@@ -15,6 +15,7 @@
 using OnTopic.TestDoubles.Metadata;
 using OnTopic.Tests.BindingModels;
 using OnTopic.Tests.Fixtures;
+using OnTopic.Tests.TestDoubles;
 using Xunit;
 
 namespace OnTopic.Tests;
@@ -325,6 +326,112 @@ public async Task Map_NestedTopics_ReturnsMappedTopic() {
 
   }
 
+  /*============================================================================================================================
+  | TEST: MAP: NESTED TOPICS: STAGGERED COMPLETION: PRESERVES SOURCE ORDER
+  \---------------------------------------------------------------------------------------------------------------------------*/
+  /// <summary>
+  ///   Establishes a <see cref="ReverseTopicMappingService"/> backed by a <see cref="StaggeredStubTopicRepository"/> whose
+  ///   per-item topic reference lookups resolve out of call order: The first-declared item resolves slowest, the last-declared
+  ///   item resolves instantly. Confirms nested topics still land in the binding model's source order, since <see cref=
+  ///   "ReverseTopicMappingService"/> maps and adds each child sequentially rather than racing completions.
+  /// </summary>
+  [Fact]
+  public async Task Map_NestedTopics_StaggeredCompletion_PreservesSourceOrder() {
+
+    // Declared in call order; delays fall in reverse, so the first-added item resolves last
+    List<(string UniqueKey, TimeSpan Delay)> attributes = [
+      ("Root:Configuration:ContentTypes:Attributes:Key", TimeSpan.FromMilliseconds(120)),
+      ("Root:Configuration:ContentTypes:Attributes:ContentType", TimeSpan.FromMilliseconds(60)),
+      ("Root:Configuration:ContentTypes:Attributes:Title", TimeSpan.Zero)
+    ];
+
+    var delaysByKey             = attributes.ToDictionary(attribute => attribute.UniqueKey, attribute => attribute.Delay);
+    var topicRepository         = new StaggeredStubTopicRepository(delaysByKey);
+    var mappingService          = new ReverseTopicMappingService(topicRepository);
+    var bindingModel            = new ContentTypeDescriptorTopicBindingModel("Test");
+
+    for (var i = 0; i < attributes.Count; i++) {
+      bindingModel.Attributes.Add(
+        new NestedReferenceAttributeTopicBindingModel($"Attribute{i + 1}") {
+          BaseTopic             = new() {
+            UniqueKey           = attributes[i].UniqueKey
+          }
+        }
+      );
+    }
+
+    var topic                   = new ContentTypeDescriptor("Test", "ContentTypeDescriptor");
+    var target                  = (ContentTypeDescriptor?)await mappingService.MapAsync(bindingModel, topic);
+    var container               = target?.Children.GetValue("Attributes");
+
+    Assert.NotNull(container);
+    Assert.Equal(
+      Enumerable.Range(1, attributes.Count).Select(i => $"Attribute{i}"),
+      container.Children.Select(child => child.Key)
+    );
+
+  }
+
+  /*============================================================================================================================
+  | TEST: MAP: SPARSE TOPIC: FILLS EXTENDED ATTRIBUTES ONCE
+  \---------------------------------------------------------------------------------------------------------------------------*/
+  /// <summary>
+  ///   Maps a scalar-only binding model onto a target stamped with a <see cref="TrackingTopicLazyLoader"/> whose <see cref=
+  ///   "Topic.Attributes"/> are <see cref="LoadState.NotLoaded"/>. Confirms <see cref="ReverseTopicMappingService"/> warms <see
+  ///   cref="TopicPayload.ExtendedAttributes"/> exactly once at the start of the map, rather than leaving it to the attribute
+  ///   collection's own synchronous autoload.
+  /// </summary>
+  [Fact]
+  public async Task Map_ScalarProperties_FillsExtendedAttributesOnce() {
+
+    var bindingModel            = new TextAttributeTopicBindingModel("Test") {
+      ContentType               = "TextAttributeDescriptor",
+      DefaultValue              = "World"
+    };
+
+    var target                  = new TextAttributeDescriptor("Test", "TextAttributeDescriptor");
+    var loader                  = new TrackingTopicLazyLoader(markLoaded: true);
+
+    ((ITopicLazyLoadable)target).Loader = loader;
+    target.Attributes.LoadState = LoadState.NotLoaded;
+
+    _                           = await _mappingService.MapAsync(bindingModel, target);
+
+    Assert.Equal(1, loader.CallCount);
+    Assert.Equal(TopicPayload.ExtendedAttributes, loader.Payloads[0]);
+
+  }
+
+  /*============================================================================================================================
+  | TEST: MAP: NESTED TOPICS: FILLS CONTAINER CHILDREN
+  \---------------------------------------------------------------------------------------------------------------------------*/
+  /// <summary>
+  ///   Maps a nested-topic binding model onto a target whose <c>Attributes</c> container is stamped with its own <see cref=
+  ///   "TrackingTopicLazyLoader"/> and left <see cref="LoadState.NotLoaded"/>, even though the target's own <see cref=
+  ///   "Topic.Children"/> are already loaded. Confirms <see cref="ReverseTopicMappingService"/> warms the container
+  ///   independently before <c>PopulateTargetCollectionAsync</c> probes its existing children.
+  /// </summary>
+  [Fact]
+  public async Task Map_NestedTopics_FillsContainerChildren() {
+
+    var bindingModel              = new ContentTypeDescriptorTopicBindingModel("Test");
+
+    bindingModel.Attributes.Add(new TextAttributeTopicBindingModel("Attribute1"));
+
+    var target                    = new ContentTypeDescriptor("Test", "ContentTypeDescriptor");
+    var container                 = new Topic("Attributes", "List", target);
+    var containerLoader           = new TrackingTopicLazyLoader(markLoaded: true);
+
+    ((ITopicLazyLoadable)container).Loader = containerLoader;
+    container.Children.LoadState  = LoadState.NotLoaded;
+
+    _                              = (ContentTypeDescriptor?)await _mappingService.MapAsync(bindingModel, target);
+
+    Assert.Equal(1, containerLoader.CallCount);
+    Assert.Equal(TopicPayload.Children, containerLoader.Payloads[0]);
+
+  }
+
   /*============================================================================================================================
   | TEST: MAP: TOPIC REFERENCES: RETURNS MAPPED TOPIC
   \---------------------------------------------------------------------------------------------------------------------------*/

OnTopic.Tests/TestDoubles/BlockingStubLazyLoadingTopicRepository.cs

@@ -76,6 +76,16 @@ internal sealed class BlockingStubLazyLoadingTopicRepository: StubLazyLoadingTop
   /// </summary>
   public void ReleaseEnsureLoadedGate() => _ensureLoadedGate?.SetResult();
 
+  /*============================================================================================================================
+  | METHOD: FAULT ENSURE LOADED GATE
+  \---------------------------------------------------------------------------------------------------------------------------*/
+  /// <summary>
+  ///   Faults a suspended <see cref="EnsureLoaded"/> call "armed" via <see cref="ArmEnsureLoadedGate"/> with the supplied
+  ///   <paramref name="exception"/>, so a test can simulate a lazy load that throws while a second pass awaits the same entry.
+  /// </summary>
+  /// <param name="exception">The exception to surface from the suspended <see cref="EnsureLoaded"/> call.</param>
+  public void FaultEnsureLoadedGate(Exception exception) => _ensureLoadedGate?.SetException(exception);
+
   /*============================================================================================================================
   | METHOD: LOAD
   \---------------------------------------------------------------------------------------------------------------------------*/

OnTopic.Tests/TestDoubles/FakeViewModelLookupService.cs

@@ -35,12 +35,18 @@ public FakeViewModelLookupService() {
     Add(typeof(AmbiguousRelationTopicViewModel));
     Add(typeof(AscendentSpecializedTopicViewModel));
     Add(typeof(AscendentTopicViewModel));
+    Add(typeof(CircularConstructorTopicViewModel));
     Add(typeof(CircularTopicViewModel));
+    Add(typeof(ConcurrentExpansionRootTopicViewModel));
+    Add(typeof(ConcurrentExpansionSharedTopicViewModel));
+    Add(typeof(ConcurrentReferenceTopicViewModel));
     Add(typeof(ConstructedTopicViewModel));
     Add(typeof(DefaultValueTopicViewModel));
     Add(typeof(DescendentSpecializedTopicViewModel));
     Add(typeof(DescendentTopicViewModel));
     Add(typeof(DisableMappingTopicViewModel));
+    Add(typeof(ExpansionParentTopicViewModel));
+    Add(typeof(ExpansionSharedTopicViewModel));
     Add(typeof(FallbackViewModel));
     Add(typeof(FilteredTopicViewModel));
     Add(typeof(FlattenChildrenTopicViewModel));
@@ -58,6 +64,7 @@ public FakeViewModelLookupService() {
     Add(typeof(RelationWithChildrenTopicViewModel));
     Add(typeof(RequiredObjectTopicViewModel));
     Add(typeof(RequiredTopicViewModel));
+    Add(typeof(SharedConcurrentTopicViewModel));
     Add(typeof(TopicReferenceAttributeDescriptorTopicViewModel));
     Add(typeof(TopicReferenceTopicViewModel));