From 9dcc20d9bed4cefb6dd5aceec702cb539902dcb3 Mon Sep 17 00:00:00 2001 From: Leo Dion Date: Fri, 23 Aug 2024 16:53:27 -0400 Subject: [PATCH] adding Bonjour docs --- .../BindingConfiguration.swift | 29 +++++++++-- .../BonjourSublimatory.swift | 49 +++++++++---------- .../Client/BonjourClient.swift | 14 +++--- .../SublimationBonjour/Client/Untitled.swift | 16 ++++++ .../Documentation.docc/Documentation.md | 28 +++-------- ...8-23-182043.svg => SublimationBonjour.svg} | 0 ...182036.svg => SublimationBonjour~dark.svg} | 0 .../Sublimation+Bonjour.swift | 3 +- 8 files changed, 78 insertions(+), 61 deletions(-) create mode 100644 Sources/SublimationBonjour/Client/Untitled.swift rename Sources/SublimationBonjour/Documentation.docc/Resources/{mermaid-diagram-2024-08-23-182043.svg => SublimationBonjour.svg} (100%) rename Sources/SublimationBonjour/Documentation.docc/Resources/{mermaid-diagram-2024-08-23-182036.svg => SublimationBonjour~dark.svg} (100%) diff --git a/Sources/SublimationBonjour/BindingConfiguration.swift b/Sources/SublimationBonjour/BindingConfiguration.swift index 043a10d..665bba7 100644 --- a/Sources/SublimationBonjour/BindingConfiguration.swift +++ b/Sources/SublimationBonjour/BindingConfiguration.swift @@ -1,12 +1,33 @@ // -// Untitled.swift +// BindingConfiguration.swift // SublimationBonjour // -// Created by Leo Dion on 8/23/24. +// Created by Leo Dion. +// Copyright © 2024 BrightDigit. +// +// Permission is hereby granted, free of charge, to any person +// obtaining a copy of this software and associated documentation +// files (the “Software”), to deal in the Software without +// restriction, including without limitation the rights to use, +// copy, modify, merge, publish, distribute, sublicense, and/or +// sell copies of the Software, and to permit persons to whom the +// Software is furnished to do so, subject to the following +// conditions: +// +// The above copyright notice and this permission notice shall be +// included in all copies or substantial portions of the Software. +// +// THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, +// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES +// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +// NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT +// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +// WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +// OTHER DEALINGS IN THE SOFTWARE. // extension BindingConfiguration { - /// Information to advertise how to connect to the server. /// /// ``` @@ -27,7 +48,7 @@ extension BindingConfiguration { /// - port: The port number of the server. /// - isSecure: Whether to use https or http. /// - public init (hosts: [String], port: Int = 8080, isSecure: Bool = false) { + public init(hosts: [String], port: Int = 8080, isSecure: Bool = false) { self.init() self.hosts = hosts self.isSecure = isSecure diff --git a/Sources/SublimationBonjour/BonjourSublimatory.swift b/Sources/SublimationBonjour/BonjourSublimatory.swift index 52f8737..2dac56a 100644 --- a/Sources/SublimationBonjour/BonjourSublimatory.swift +++ b/Sources/SublimationBonjour/BonjourSublimatory.swift @@ -37,27 +37,25 @@ public import Logging -public struct BonjourSublimatory: Sublimatory { - public init( - bindingConfiguration: BindingConfiguration, - logger: Logger, - listener: NWListener, - name: String = Self.defaultName, - type: String = Self.defaultHttpTCPServiceType, - listenerQueue: DispatchQueue = .global(), - connectionQueue: DispatchQueue = .global() - ) { - self.bindingConfiguration = bindingConfiguration - self.logger = logger - self.listener = listener - self.name = name - self.type = type - self.listenerQueue = listenerQueue - self.connectionQueue = connectionQueue - } - + public struct BonjourSublimatory: Sublimatory { + public init( + bindingConfiguration: BindingConfiguration, + logger: Logger, + listener: NWListener, + name: String = Self.defaultName, + type: String = Self.defaultHttpTCPServiceType, + listenerQueue: DispatchQueue = .global(), + connectionQueue: DispatchQueue = .global() + ) { + self.bindingConfiguration = bindingConfiguration + self.logger = logger + self.listener = listener + self.name = name + self.type = type + self.listenerQueue = listenerQueue + self.connectionQueue = connectionQueue + } - public init( bindingConfiguration: BindingConfiguration, logger: Logger, @@ -78,10 +76,9 @@ public struct BonjourSublimatory: Sublimatory { connectionQueue: connectionQueue ) } - - let bindingConfiguration: BindingConfiguration - let logger: Logger - let listener: NWListener + let bindingConfiguration: BindingConfiguration + let logger: Logger + let listener: NWListener let name: String let type: String let listenerQueue: DispatchQueue @@ -131,9 +128,7 @@ public struct BonjourSublimatory: Sublimatory { // return addresses // } - public func shutdown() { - listener.cancel() - } + public func shutdown() { listener.cancel() } public func run() async throws { let data = try self.bindingConfiguration.serializedData() let txtRecordValues = data.base64EncodedString().splitByMaxLength(199) diff --git a/Sources/SublimationBonjour/Client/BonjourClient.swift b/Sources/SublimationBonjour/Client/BonjourClient.swift index 70e571a..fe3c043 100644 --- a/Sources/SublimationBonjour/Client/BonjourClient.swift +++ b/Sources/SublimationBonjour/Client/BonjourClient.swift @@ -38,15 +38,13 @@ public import Logging #endif - public struct URLDefaultConfiguration { - public init(isSecure: Bool = false, port: Int = 8080) { - self.isSecure = isSecure - self.port = port - } - public let isSecure: Bool - public let port: Int - } + +/// Client for fetching the url of the host server. +/// ``` +/// let depositor = BonjourClient(logger: app.logger) +/// let hostURL = await depositor.first() +/// ``` public actor BonjourClient { private let browser: NWBrowser private let streams = StreamManager() diff --git a/Sources/SublimationBonjour/Client/Untitled.swift b/Sources/SublimationBonjour/Client/Untitled.swift new file mode 100644 index 0000000..ae9c5ac --- /dev/null +++ b/Sources/SublimationBonjour/Client/Untitled.swift @@ -0,0 +1,16 @@ +// +// Untitled.swift +// SublimationBonjour +// +// Created by Leo Dion on 8/23/24. +// + + +public struct URLDefaultConfiguration { + public init(isSecure: Bool = false, port: Int = 8080) { + self.isSecure = isSecure + self.port = port + } + public let isSecure: Bool + public let port: Int +} diff --git a/Sources/SublimationBonjour/Documentation.docc/Documentation.md b/Sources/SublimationBonjour/Documentation.docc/Documentation.md index f0a85f0..cc6593d 100644 --- a/Sources/SublimationBonjour/Documentation.docc/Documentation.md +++ b/Sources/SublimationBonjour/Documentation.docc/Documentation.md @@ -2,27 +2,9 @@ Use Bonjour for automatic discovery of your Swift Server. -## Overview +![SublimationBonjour Diagram](SublimationBonjour.svg) -```mermaid -sequenceDiagram - participant Server as Hummingbird/Vapor Server - participant BonjourSub as BonjourSublimatory - participant NWListener as NWListener - participant Network as Local Network - participant BonjourClient as BonjourClient - participant App as iOS/watchOS App - - Server->>BonjourSub: Start server, provide IP addresses,
hostnames, port, and protocol (http/https) - BonjourSub->>NWListener: Configure with server information - NWListener->>Network: Advertise service:
1. Send encoded server data
2. Use Text Record for additional info - App->>BonjourClient: Request server URL - BonjourClient->>Network: Search for advertised services - Network-->>BonjourClient: Return advertised service information - BonjourClient->>BonjourClient: 1. Receive and decode server data
2. Parse Text Record - BonjourClient-->>App: Return AsyncStream
or first available URL - App->>Server: Connect to server using discovered URL -``` +## Overview When the Swift Server begins it will tell Sublimation the ip addresses or host names which are available to access the server from (including the port number and whether to use https or http). This is called a `BonjourSublimatory`. The `BonjourSublimatory` then uses `NWListener` to advertise this information both by send the data encoded using Protocol Buffers as well as inside the Text Record advertised. @@ -30,6 +12,7 @@ The iPhone or Apple Watch then uses a `BonjourClient` to fetch either an `AsyncS ### Setting up your Server + ``` let bindingConfiguration = BindingConfiguration( host: ["Leo's-Mac.local", "192.168.1.10"], @@ -45,6 +28,11 @@ let sublimation = Sublimation(sublimatory : bonjour) ### Setting up your Client +``` +let depositor = BonjourClient(logger: app.logger) +let hostURL = await depositor.first() +``` + ## Topics ### Group diff --git a/Sources/SublimationBonjour/Documentation.docc/Resources/mermaid-diagram-2024-08-23-182043.svg b/Sources/SublimationBonjour/Documentation.docc/Resources/SublimationBonjour.svg similarity index 100% rename from Sources/SublimationBonjour/Documentation.docc/Resources/mermaid-diagram-2024-08-23-182043.svg rename to Sources/SublimationBonjour/Documentation.docc/Resources/SublimationBonjour.svg diff --git a/Sources/SublimationBonjour/Documentation.docc/Resources/mermaid-diagram-2024-08-23-182036.svg b/Sources/SublimationBonjour/Documentation.docc/Resources/SublimationBonjour~dark.svg similarity index 100% rename from Sources/SublimationBonjour/Documentation.docc/Resources/mermaid-diagram-2024-08-23-182036.svg rename to Sources/SublimationBonjour/Documentation.docc/Resources/SublimationBonjour~dark.svg diff --git a/Sources/SublimationBonjour/Sublimation+Bonjour.swift b/Sources/SublimationBonjour/Sublimation+Bonjour.swift index 112711f..cc00657 100644 --- a/Sources/SublimationBonjour/Sublimation+Bonjour.swift +++ b/Sources/SublimationBonjour/Sublimation+Bonjour.swift @@ -34,7 +34,7 @@ extension Sublimation { /// Initializes a `Sublimation` instance with the provided parameters. - /// + /// /// - Parameters: /// - bindingConfiguration: A configuration with addresses, port and tls configuration. /// - name: Service name. @@ -64,7 +64,6 @@ ) self.init(sublimatory: sublimatory) } - public convenience init( bindingConfiguration: BindingConfiguration, logger: Logger,