Sublimation

Enable automatic discovery of your local development server on the fly

Turn your Server-Side Swift app from a mysterious vapor to a tangible solid server

Table of Contents

• Introduction
  • Requirements
• Package Ecosystem
• Usage
• Documentation
• License

Introduction

When you are developing a Full Stack Swift application, you want to easily test and debug your application on both the device (iPhone, Apple Watch, iPad, etc...) as well as your development server. If you are using simulator then setting your host server to localhost this may work but often you need to test on an actual device.

For the server and client we need a way to communicate that information without the client knowing where the server is initially.

flowchart TD
%% Nodes for devices with Font Awesome icons
    subgraph Devices
    iPhone("fa:fa-mobile-alt iPhone")
    Watch("fa:fa-square Apple Watch")
    iPad("fa:fa-tablet-alt iPad")
    VisionPro("fa:fa-vr-cardboard Vision Pro")
    end
    
%% Node for Sublimation service with Font Awesome package icon
    Sublimation("fa:fa-box Sublimation")

%% Node for API server with Font Awesome icon
    Server("fa:fa-server API Server")

%% Edge connections
    Devices <--> Sublimation
    Sublimation <--> Server

Loading

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

For older operating systems or Swift versions, check out the main branch and 1.0.0 releases.

Package Ecosystem

Repository	Description
SublimationBonjour	Sublimatory for using Bonjour for auto-discovery for development server.
SublimationNgrok	Sublimatory for using Ngrok and KVdb to create public urls and share them.
SublimationService	Use Sublimation as a Lifecycle Service.
SublimationVapor	Use Sublimation as a Vapor Lifecycle Handler.

graph TD
    A[Which Sublimation Packages to Use] --> B{Need to publicly share URL?}
    B -->|Yes| C[Use **SublimationNgrok**]
    B -->|No| D[Use **SublimationBonjour**]
    C --> E{Which server framework?}
    D --> E
    E -->|*Vapor*| F[Use **SublimationVapor**]
    E -->|*Hummingbird* or other *Lifecycle Service*| G[Use **SublimationService** ]

Loading

To use Sublimation, you'll need to choose:

• Sublimatory, that is the method by which you advertise the development server
  • Bonjour via SublimationBonjour
  • Ngrok via SublimationNgrok which is only needed if you need to advertise your address publicaly
• How it connects to the server
  • Lifecycle Handler for Vapor via SublimationVapor
  • Lifecycle Service via SublimationService for server frameworks such as Hummingbird

Usage

For instance if you were using Bonjour with Hummingbird and an iOS app your package may look something like this:

let package = Package(
  ...
  dependencies: [
    .package(url: "https://github.com/hummingbird-project/hummingbird.git", from: "2.0.0-alpha.1"),
    .package(url: "https://github.com/brightdigit/SublimationBonjour.git", from: "1.0.0"),
    .package(url: "https://github.com/brightdigit/SublimationService.git", from: "1.0.0")
  ],
  targets: [

      .target(
          name: "YouriOSApp",
          dependencies: [
            .product(name: "SublimationBonjour", package: "SublimationBonjour"),
            ...
          ]),
      ...
      .target(
          name: "YourServerApp",
          dependencies: [
            .product(name: "Hummingbird", package: "hummingbird"),
            .product(name: "SublimationBonjour", package: "SublimationBonjour"),
            .product(name: "SublimationService", package: "SublimationService"), 
            ...
          ]),
      ...
  ]
)

If you were to use Vapor and Ngrok instead, it'd look more like this:

let package = Package(
  ...
  dependencies: [
    .package(url: "https://github.com/vapor/vapor.git", from: "4.76.0"),
    .package(url: "https://github.com/brightdigit/SublimationNgrok.git", from: "1.0.0"),
    .package(url: "https://github.com/brightdigit/SublimationVapor.git", from: "1.0.0")
  ],
  targets: [

      .target(
          name: "YouriOSApp",
          dependencies: [
            .product(name: "SublimationKVdb", package: "SublimationNgrok"),
            ...
          ]),
      ...
      .target(
          name: "YourServerApp",
          dependencies: [
            .product(name: "Vapor", package: "vapor"),
            .product(name: "SublimationNgrok", package: "SublimationNgrok"),
            .product(name: "SublimationVapor", package: "SublimationVapor"), 
            ...
          ]),
      ...
  ]
)

• Why KVdb for the app?

Please check the respective package documentation from the Package Ecosystem section.

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.