Centralised Messaging for User Scripts

[shakyShane]

Please review the release process for BrowserServicesKit here.

Required:

Task/Issue URL:
iOS PR:
macOS PR:
What kind of version bump will this require?: Major/Minor/Patch

Optional:

TODO

• Catalina/encryption support needs to be added to the new messaging broker

tl;dr - multiple features will soon be messaging from single UserScripts

/// An example of how to conform to `SubFeature`
/// It contains 3 examples that are typical of a feature that needs to
/// communicate to a UserScript
struct TestDelegate: Subfeature {
    weak var broker: UserScriptMessageBroker?

    var featureName = "fooBarFeature"

    /// This feature will accept messages from .all - meaning every origin
    ///
    /// Some features may want to restrict the origin's that it accepts messages from
    var messageOriginPolicy: MessageOriginPolicy = .all

    /// An example of how to provide different handlers bad on
    func handler(forMethodNamed methodName: String) -> Subfeature.Handler? {
        switch methodName {
        case "notifyExample": return notifyExample
        case "errorExample": return errorExample
        case "responseExample": return responseExample
        default:
            return nil
        }
    }

    /// An example of a simple Encodable data type that can be used directly in replies
    struct Person: Encodable {
        let name: String
    }

    /// An example that represents handling a [NotificationMessage](https://duckduckgo.github.io/content-scope-scripts/classes/Messaging_Schema.NotificationMessage.html)
    func notifyExample(params: Any, original: WKScriptMessage) async throws -> Encodable? {
        print("not replying...")
        return nil
    }

    /// An example that represents throwing an exception from a handler
    ///
    /// Note: if this happens as part of a 'request', the error string will be forwarded onto the client side JS
    func errorExample(params: Any, original: WKScriptMessage) async throws -> Encodable? {
        let error = NSError(domain: "MyHandler", code: 0, userInfo: [NSLocalizedDescriptionKey: "Some Error"])
        throw error
    }

    /// An example of how a handler can reply with any Encodable data type
    func responseExample(params: Any, original: WKScriptMessage) async throws -> Encodable? {
        let person = Person(name: "Kittie")
        return person
    }
}

contentScopeUserScript.registerSubFeature(delegate: TestDelegate())

Description:

• Content Scope Scripts is adding features that require messaging - there will be multiple such features in the future.

• Therefor, on the JS side we've created a standardised system for messaging to and from WebViews that include enough information for the native platforms to distribute the messages as they see fit.

• CC @jaceklyp

• We have Specified a number of types that native platforms must implement and understand, such as

  • NotificationMessage (a fire-and-forget message)
  • RequestMessage (a notification that requires a response)
  • MessageResponse (a response to a RequestMessage)
  • SubscriptionEvent (ability to push data to WebViews)

• Messaging https://duckduckgo.github.io/content-scope-scripts/modules/Messaging.html

• MessagingSchema https://duckduckgo.github.io/content-scope-scripts/modules/Messaging_Schema.html

Steps to test this PR:
1.
1.

OS Testing:

• iOS 14
• iOS 15
• iOS 16
• macOS 10.15
• macOS 11
• macOS 12

---

Internal references:

Software Engineering Expectations
Technical Design Template

[shakyShane]

Current dependencies on/for this PR:

• main
  • PR Centralised Messaging for User Scripts #299 👈

This comment was auto-generated by Graphite.

[shakyShane]

@ayoy @Bunn @jaceklyp this was just my way of making the new standardised messaging platform work with minimal changes to BSK (it just adds a new protocol, it doesn't alter any existing User Scripts)

Let me know if it's the wrong the direction, or if you can suggest any parts to re-write :p - I'm really just interested in supporting the idea of 'multiple features per User Script' and ensuring it follows what we have documented in C-S-S.

[Bunn]

Added some comments there, I think it looks good, but I haven't used UserScript before in a level that I feel comfortable knowing some of the impacts here for existing features. @jaceklyp do you mind taking a second look? And @ayoy as well because of the Duck Player messaging.

From what I'm seeing and using it for DBP, LGTM.

Edit: To be clear, I approved the PR but it doesn't mean it can be merged 😅 just approving the direction

[jaceklyp]

let's discuss it over MM

[jaceklyp]

Hey Shane, thank you for this! 🙏 Added several comments - if you have any questions let's discuss them. I would like to give another round of review after your fixes.

[shakyShane]

@jaceklyp - thanks for the feedback, please feel free to check this again.

Because this work deliberately DOES NOT alter how existing User Scripts work, it should be fairly low-risk to merge and then iterate if we need to following further feedback of course :)

[ayoy]

@jaceklyp please have another look after @shakyShane has addressed your comments.

[jaceklyp]

I believe it shoud be init(privacyConfigManager, let's not hide the external label in init

[jaceklyp]

pretty much all selfs are not needed here

[jaceklyp]

Subfeature :) here and above

[jaceklyp]

Great work, sir!

[shakyShane]

@jaceklyp updated! thanks :)