Skip to content

Use Bonjour for Sublimation for automatic discovery of your Swift Server.

License

Notifications You must be signed in to change notification settings

brightdigit/SublimationBonjour

Repository files navigation

Sublimation

SublimationBonjour

Use Bonjour for Sublimation for automatic discovery of your Swift Server.

SwiftPM Twitter GitHub GitHub issues GitHub Workflow Status

Codecov CodeFactor Grade codebeat badge Code Climate maintainability Code Climate technical debt Code Climate issues

Table of Contents

Introduction

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,<br/>hostnames, port, and protocol (http/https)
  BonjourSub->>NWListener: Configure with server information
  NWListener->>Network: Advertise service:<br/>1. Send encoded server data<br/>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<br/>2. Parse Text Record
  BonjourClient-->>App: Return AsyncStream<URL><br/>or first available URL
  App->>Server: Connect to server using discovered URL
Loading

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.

The iPhone or Apple Watch then uses a BonjourClient to fetch either an AsyncStream of URL via BonjourClient.urls or simply get the BonjourClient.first() one available.

Requirements

Apple Platforms

  • Xcode 16.0 or later
  • Swift 6.0 or later
  • iOS 17 / watchOS 10.0 / tvOS 17 / macOS 14 or later deployment targets

Linux

  • Ubuntu 20.04 or later
  • Swift 6.0 or later

Installation

To integrate SublimationBonjour into your app using SPM, specify it in your Package.swift file:

let package = Package(
  ...
  dependencies: [
    .package(url: "https://github.com/brightdigit/SublimationBonjour.git", from: "1.0.0")
  ],
  targets: [
      .target(
          name: "YourServerApp",
          dependencies: [
            .product(name: "SublimationBonjour", package: "SublimationBonjour"), ...
          ]),
      ...
  ]
)

Usage

Setting up your Server

Create a BindingConfiguration with:

  • a list of host names and ip address
  • port number of the server
  • whether the server uses https or http
let bindingConfiguration = BindingConfiguration(
  host: ["Leo's-Mac.local", "192.168.1.10"],
  port: 8080
  isSecure: false
)

Create a BonjourSublimatory using that BindingConfiguration and include your server's logger. Then attach it to the Sublimation object:

let bonjour = BonjourSublimatory(
  bindingConfiguration: bindingConfiguration,
  logger: app.logger
)
let sublimation = Sublimation(sublimatory : bonjour)

You can also just create a Sublimation object:

let sublimation = Sublimation(
  bindingConfiguration: bindingConfiguration,
  logger: app.logger
)

Setting up your Client

On the device, create a BonjourClient and either get an AsyncStream of URL objects via BonjourClient.urls or just ask for the first one using BonjourClient.first():

let client = BonjourClient(logger: app.logger)
let hostURL = await client.first()

Documentation

To learn more, check out the full documentation.

License

This code is distributed under the MIT license. See the LICENSE file for more info.