Support resolving external content with topic images (#469)

* Support resolving external content with topic images

rdar://100501774

* Apply suggestions from code review

Co-authored-by: Ethan Kusters <[email protected]>

* Address additional code review feedback

* Don't create an DataAssetManager for assets from the external content

* Test resolving two external topics with images on the same page

---------

Co-authored-by: Ethan Kusters <[email protected]>

Author: d-ronnqvist

Sources/SwiftDocC/Infrastructure/DocumentationContext.swift

@@ -223,6 +223,10 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
     /// unresolvable asset references using a fallback resolver (if one is set for the reference's bundle identifier.)
     public var fallbackAssetResolvers = [BundleIdentifier: FallbackAssetResolver]()
 
+    // This protocol only exist to workaround a limitation. It should be removed when it's no longer needed.
+    // FIXME: https://github.com/apple/swift-docc/issues/468
+    public var _externalAssetResolvers = [BundleIdentifier: _ExternalAssetResolver]()
+    
     /// All the symbol references that have been resolved from external sources.
     ///
     /// This is tracked to exclude external symbols from the build output. Information about external references is still included for the local pages that makes the external reference.
@@ -2655,6 +2659,12 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
             return externallyResolvedAsset
         }
 
+        if let externalAssetResolver = _externalAssetResolvers[bundleIdentifier],
+           let externallyResolvedAsset = externalAssetResolver._resolveExternalAsset(named: name, bundleIdentifier: bundleIdentifier) {
+            // Don't create a new DataAssetManager for the external bundle.
+            return externallyResolvedAsset
+        }
+        
         // If no fallbackAssetResolver is set, try to treat it as external media link
         if let externalMediaLink = URL(string: name),
            externalMediaLink.isAbsoluteWebURL {
@@ -2679,7 +2689,15 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
     /// - Returns: The best matching storage key if it was found, otherwise `nil`.
     public func identifier(forAssetName name: String, in parent: ResolvedTopicReference) -> String? {
         let bundleIdentifier = parent.bundleIdentifier
-        return assetManagers[bundleIdentifier]?.bestKey(forAssetName: name)
+        if let assetManager = assetManagers[bundleIdentifier] {
+            return assetManager.bestKey(forAssetName: name)
+        } else {
+            if _externalAssetResolvers[bundleIdentifier]?._resolveExternalAsset(named: name, bundleIdentifier: parent.bundleIdentifier) != nil {
+                return name
+            } else {
+                return nil
+            }
+        }
     }
 
     /// Attempt to resolve an unresolved code listing.

Sources/SwiftDocC/Infrastructure/External Data/ExternalAssetResolver.swift

@@ -0,0 +1,22 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2023 Apple Inc. and the Swift project authors
+ Licensed under Apache License v2.0 with Runtime Library Exception
+
+ See https://swift.org/LICENSE.txt for license information
+ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/
+
+import Foundation
+
+/// An asset resolver that can be used to resolve assets that couldn't be resolved locally.
+public protocol _ExternalAssetResolver {
+    // This protocol only exist so that externally resolved media references can be returned separately from the external
+    // content that is known to reference them. See details in OutOfProcessReferenceResolver.addImagesAndCacheMediaReferences(to:from:)
+    // We should remove it when that's no longer necessary.
+    // FIXME: https://github.com/apple/swift-docc/issues/468
+    
+    /// Attempts to resolve an asset that couldn't be resolved externally given its name and the bundle it's apart of.
+    func _resolveExternalAsset(named assetName: String, bundleIdentifier: String) -> DataAsset?
+}

Sources/SwiftDocC/Infrastructure/External Data/OutOfProcessReferenceResolver.swift

@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2021-2022 Apple Inc. and the Swift project authors
+ Copyright (c) 2021-2023 Apple Inc. and the Swift project authors
  Licensed under Apache License v2.0 with Runtime Library Exception
 
  See https://swift.org/LICENSE.txt for license information
@@ -172,7 +172,7 @@ public class OutOfProcessReferenceResolver: ExternalReferenceResolver, FallbackR
             name = .conceptual(title: resolvedInformation.title)
         }
 
-        return DocumentationNode(
+        var node = DocumentationNode(
             reference: reference,
             kind: resolvedInformation.kind,
             sourceLanguage: resolvedInformation.language,
@@ -182,6 +182,10 @@ public class OutOfProcessReferenceResolver: ExternalReferenceResolver, FallbackR
             semantic: maybeSymbol,
             platformNames: resolvedInformation.platformNames
         )
+        
+        addImagesAndCacheMediaReferences(to: &node, from: resolvedInformation)
+        
+        return node
     }
 
     /// Returns the web URL for the external topic.
@@ -247,7 +251,7 @@ public class OutOfProcessReferenceResolver: ExternalReferenceResolver, FallbackR
             variants: resolvedInformation.variants
         )! // This entity was resolved from a symbol USR and is known to be a symbol.
 
-        return DocumentationNode(
+        var node = DocumentationNode(
             reference: reference,
             kind: resolvedInformation.kind,
             sourceLanguage: resolvedInformation.language,
@@ -257,6 +261,49 @@ public class OutOfProcessReferenceResolver: ExternalReferenceResolver, FallbackR
             semantic: symbol,
             platformNames: resolvedInformation.platformNames
         )
+        
+        addImagesAndCacheMediaReferences(to: &node, from: resolvedInformation)
+        
+        return node
+    }
+    
+    private func addImagesAndCacheMediaReferences(to node: inout DocumentationNode, from resolvedInformation: ResolvedInformation) {
+        // Because DocC renders external content in the local context, external media also needs to be added to the local context.
+        // If the external content was treated as pre-rendered then this wouldn't be necessary. (rdar://78718811)
+        // FIXME: https://github.com/apple/swift-docc/issues/468
+        
+        // `@PageImage` directives isn't meant to be created in code like this but it's the only way to associate topic images
+        // with a render node.
+        
+        if let topicImages = resolvedInformation.topicImages, !topicImages.isEmpty {
+            let metadata = node.metadata ?? Metadata(originalMarkup: BlockDirective(name: "Metadata", children: []), documentationExtension: nil, technologyRoot: nil, displayName: nil)
+            
+            metadata.pageImages = topicImages.map { topicImage in
+                let purpose: PageImage.Purpose
+                switch topicImage.type {
+                case .card: purpose = .card
+                case .icon: purpose = .icon
+                }
+                
+                return PageImage._make(
+                    purpose: purpose,
+                    source: ResourceReference(bundleIdentifier: node.reference.bundleIdentifier, path: topicImage.identifier.identifier),
+                    alt: (resolvedInformation.references?.first(where: { $0.identifier == topicImage.identifier }) as? ImageReference)?.altText
+                )
+            }
+            
+            node.metadata = metadata
+        }
+        
+        // Since the DocumentationNode doesn't have any media references, the external media references can't be returned with the node.
+        // Instead they are added to the cache so that they are returned from later requests.
+        
+        for reference in (resolvedInformation.references ?? []) {
+            guard let mediaReference = reference as? MediaReference else { continue }
+            
+            assetCache[.init(assetName: mediaReference.identifier.identifier, bundleIdentifier: node.reference.bundleIdentifier)] = mediaReference.asset
+        }
+        
     }
 
     /// Returns the web URL for the external symbol.
@@ -400,6 +447,14 @@ public class OutOfProcessReferenceResolver: ExternalReferenceResolver, FallbackR
     }
 }
 
+extension OutOfProcessReferenceResolver: _ExternalAssetResolver {
+    public func _resolveExternalAsset(named assetName: String, bundleIdentifier: String) -> DataAsset? {
+        // We don't want to make additional requests for these external assets.
+        // If they were already resolved, return them from the cache.
+        return assetCache[AssetReference(assetName: assetName, bundleIdentifier: bundleIdentifier)]
+    }
+}
+
 private protocol ExternalLinkResolving {
     func sendAndWait<Request: Codable & CustomStringConvertible, Response: Codable>(request: Request?) throws -> Response
 }
@@ -689,6 +744,10 @@ extension OutOfProcessReferenceResolver {
 
     /// A type used to transfer information about a resolved reference to DocC from from a reference resolver in another executable.
     public struct ResolvedInformation: Codable {
+        // This type is duplicating the information from LinkDestinationSummary with some minor differences.
+        // Changes generally need to be made in both places. It would be good to replace this with LinkDestinationSummary.
+        // FIXME: https://github.com/apple/swift-docc/issues/468
+        
         /// Information about the resolved kind.
         public let kind: DocumentationNode.Kind
         /// Information about the resolved URL.
@@ -719,8 +778,14 @@ extension OutOfProcessReferenceResolver {
             return platforms.map { platforms in Set(platforms.compactMap { $0.name }) }
         }
 
+        /// Images that are used to represent the summarized element.
+        public var topicImages: [TopicImage]?
+                
+        /// References used in the content of the summarized element.
+        public var references: [RenderReference]?
+        
         /// The variants of content (kind, url, title, abstract, language, declaration) for this resolver information.
-        public let variants: [Variant]?
+        public var variants: [Variant]?
 
         /// Creates a new resolved information value with all its values.
         ///
@@ -743,6 +808,8 @@ extension OutOfProcessReferenceResolver {
             availableLanguages: Set<SourceLanguage>,
             platforms: [PlatformAvailability]?,
             declarationFragments: DeclarationFragments?,
+            topicImages: [TopicImage]?,
+            references: [RenderReference]?,
             variants: [Variant]? = nil
         ) {
             self.kind = kind
@@ -753,6 +820,8 @@ extension OutOfProcessReferenceResolver {
             self.availableLanguages = availableLanguages
             self.platforms = platforms
             self.declarationFragments = declarationFragments
+            self.topicImages = topicImages
+            self.references = references
             self.variants = variants
         }
 
@@ -889,3 +958,55 @@ extension OutOfProcessReferenceResolver {
         )
     }
 }
+
+extension OutOfProcessReferenceResolver.ResolvedInformation {
+    enum CodingKeys: CodingKey {
+        case kind
+        case url
+        case title
+        case abstract
+        case language
+        case availableLanguages
+        case platforms
+        case declarationFragments
+        case topicImages
+        case references
+        case variants
+    }
+    
+    public init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        
+        kind = try container.decode(DocumentationNode.Kind.self, forKey: .kind)
+        url = try container.decode(URL.self, forKey: .url)
+        title = try container.decode(String.self, forKey: .title)
+        abstract = try container.decode(String.self, forKey: .abstract)
+        language = try container.decode(SourceLanguage.self, forKey: .language)
+        availableLanguages = try container.decode(Set<SourceLanguage>.self, forKey: .availableLanguages)
+        platforms = try container.decodeIfPresent([OutOfProcessReferenceResolver.ResolvedInformation.PlatformAvailability].self, forKey: .platforms)
+        declarationFragments = try container.decodeIfPresent(OutOfProcessReferenceResolver.ResolvedInformation.DeclarationFragments.self, forKey: .declarationFragments)
+        topicImages = try container.decodeIfPresent([TopicImage].self, forKey: .topicImages)
+        references = try container.decodeIfPresent([CodableRenderReference].self, forKey: .references).map { decodedReferences in
+            decodedReferences.map(\.reference)
+        }
+        variants = try container.decodeIfPresent([OutOfProcessReferenceResolver.ResolvedInformation.Variant].self, forKey: .variants)
+        
+    }
+    
+    public func encode(to encoder: Encoder) throws {
+        var container = encoder.container(keyedBy: CodingKeys.self)
+        
+        try container.encode(self.kind, forKey: .kind)
+        try container.encode(self.url, forKey: .url)
+        try container.encode(self.title, forKey: .title)
+        try container.encode(self.abstract, forKey: .abstract)
+        try container.encode(self.language, forKey: .language)
+        try container.encode(self.availableLanguages, forKey: .availableLanguages)
+        try container.encodeIfPresent(self.platforms, forKey: .platforms)
+        try container.encodeIfPresent(self.declarationFragments, forKey: .declarationFragments)
+        try container.encodeIfPresent(self.topicImages, forKey: .topicImages)
+        try container.encodeIfPresent(references?.map { CodableRenderReference($0) }, forKey: .references)
+        try container.encodeIfPresent(self.variants, forKey: .variants)
+    }
+}
+