brightdigit/SublimationNgrok

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 SublimationNgrok into your app using SPM, specify it in your Package.swift file:

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

For the client-side API, you only need the SublimationKVdb product from the package.

Usage

Cloud Setup

If you haven't already setup an account with ngrok and install the command-line tool via homebrew. Next let's setup a key-value storage with kvdb.io which is currently supported. If you have another service, please create an issue in the repo. Your feedback is helpful.

Sign up at kvdb.io and get a bucket name you'll use. You'll be using that for your setup. Essentially there are three components you'll need:

• ngrok executable path

- if you installed via homebrew it's /opt/homebrew/bin/ngrok but you can find out using: which ngrok after installation

• your kvdb.io bucket name
• your kvdb.io key

- you just need to pick something unique for your server and client to use

Save these somewhere in your shared configuration for both your server and client to access, such as an enum:

public enum SublimationConfiguration {
  public static let bucketName = "fdjf9012k20cv"
  public static let key = "my-"
}

Server Setup

When creating your Sublimation object you'll want to use the provided convenience initializers TunnelSublimatory.init(ngrokPath:bucketName:key:application:isConnectionRefused:ngrokClient:) to make it easier for ngrok integration with the TunnelSublimatory:

let tunnelSublimatory = TunnelSublimatory(
  ngrokPath: "/opt/homebrew/bin/ngrok", // path to ngrok executable
  bucketName: SublimationConfiguration.bucketName, // "fdjf9012k20cv"
  key: SublimationConfiguration.key, // "dev-server"
  application: { myVaporApplication }, // pass your Vapor.Application here
  isConnectionRefused: {$.isConnectionRefused}, // supplied by `SublimationVapor`
  transport: AsyncHTTPClientTransport() // ClientTransport for Vapor
)

let sublimation = Sublimation(sublimatory: tunnelSublimatory)

Client Setup

For the client, you'll need to import the SublimationKVdb module and retrieve the url via:

import SublimationKVdb

let hostURL = try await KVdb.url(
  withKey: SublimationConfiguration.key, 
  atBucket: SublimationConfiguration.bucketName
) 

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.

Package Metadata

Repository: brightdigit/SublimationNgrok

Stars: 2

Forks: 0

Open issues: 0

Default branch: main

Primary language: swift

License: MIT

Topics: developer-tools, development-environment, ngrok, swift

README: README.md