working on client setup and server setup for SublimationNgrok

Sources/SublimationNgrok/Documentation.docc/Documentation.md

@@ -0,0 +1,76 @@
+# ``SublimationNgrok``
+
+Share your local development server easily with your Apple devices via Ngrok.
+
+![SublimationNgrok Diagram](SublimationNgrok.svg)
+
+## Overview
+
+Ngrok is a fantastic service for setting up local development server for outside access. Let's say you need to share your local development server because you're testing on an actual device which can't access your machine via your local network. You can run `ngrok` to setup an https address which tunnels to your local development server:
+
+```bash
+> vapor run serve -p 1337
+> ngrok http 1337
+```
+Now you'll get a message saying your vapor app is served through ngrok:
+
+```
+Forwarding https://c633-2600-1702-4050-7d30-cc59-3ffb-effa-6719.ngrok.io -> http://localhost:1337 
+```
+
+With Sublimation you save the address (such as `https://c633-2600-1702-4050-7d30-cc59-3ffb-effa-6719.ngrok.io`) to a key-value storage and pull that address from your Apple device during development.
+
+### 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`:
+
+```swift
+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 convience initializers ``SublimationTunnel/TunnelSublimatory/init(ngrokPath:bucketName:key:application:isConnectionRefused:ngrokClient:)`` to make it easier for **ngrok** integration with the ``SublimationTunnel/TunnelSublimatory``:
+
+```swift
+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:
+
+```swift
+let hostURL = try await KVdb.url(
+  withKey: SublimationConfiguration.key, 
+  atBucket: SublimationConfiguration.bucketName
+) 
+```
+
+## Topics
+
+### Creating a Sublimatory
+
+- ``SublimationTunnel/TunnelSublimatory``

Sources/SublimationNgrok/NgrokCLIAPIConfiguration.swift

@@ -31,13 +31,7 @@ public import Logging
 public import SublimationCore
 public import SublimationTunnel
 
-/// Configuration for the Ngrok CLI API server.
-///
-/// - Note: This configuration conforms to `NgrokServerConfiguration` protocol.
-///
-/// - Note: This configuration conforms to `NgrokVaporConfiguration` protocol.
-///
-/// - SeeAlso: `NgrokCLIAPIServer`
+/// Configuration for the  ``NgrokCLIAPIServer``.
 public struct NgrokCLIAPIConfiguration: TunnelServerConfiguration {
   /// The type of server to use.
   public typealias Server = NgrokCLIAPIServer
@@ -51,16 +45,15 @@ public struct NgrokCLIAPIConfiguration: TunnelServerConfiguration {
 
 extension NgrokCLIAPIConfiguration {
   ///   Initializes a new instance of
-  ///   `NgrokCLIAPIConfiguration` using a `ServerApplication`.
+  ///   ``NgrokCLIAPIConfiguration`` using a server `Application`.
   ///
   ///   - Parameter serverApplication: The server application to use for configuration.
   internal init(serverApplication: any Application) {
     self.init(port: serverApplication.httpServerConfigurationPort, logger: serverApplication.logger)
   }
 
-  ///   Initializes a new instance of `NgrokCLIAPIConfiguration`
-  ///   using a `Vapor.Application`.
+  ///   Initializes a new instance of `NgrokCLIAPIConfiguration`.
   ///
-  ///   - Parameter application: The Vapor application to use for configuration.
+  ///   - Parameter application: The Server application to use for configuration.
   public init(application: any Application) { self.init(serverApplication: application) }
 }

Sources/SublimationNgrok/NgrokCLIAPIServer.swift

@@ -33,12 +33,7 @@ public import Ngrokit
 public import OpenAPIRuntime
 public import SublimationTunnel
 
-/// A server implementation for Ngrok CLI API.
-///
-/// - Note: This server conforms to the `NgrokServer` and `Sendable` protocols.
-///
-/// - SeeAlso: `NgrokServer`
-/// - SeeAlso: `Sendable`
+/// A `TunnelServer` server implementation using the Ngrok CLI API.
 public struct NgrokCLIAPIServer: TunnelServer, Sendable {
   public typealias ConnectionErrorType = ClientError
 

Sources/SublimationNgrok/NgrokCLIAPIServerFactory.swift

@@ -31,13 +31,7 @@ import Foundation
 public import Ngrokit
 public import SublimationTunnel
 
-/// A factory for creating Ngrok CLI API servers.
-///
-/// This factory conforms to the `NgrokServerFactory` protocol.
-///
-/// - Note: This factory requires the `NgrokCLIAPI` type to be `Processable`.
-///
-/// - SeeAlso: `NgrokServerFactory`
+/// A factory for creating ``NgrokCLIAPIServer``.
 public struct NgrokCLIAPIServerFactory<ProcessType: Processable>: TunnelServerFactory {
   /// The configuration type for the Ngrok CLI API server.
   public typealias Configuration = NgrokCLIAPIConfiguration
@@ -46,12 +40,17 @@ public struct NgrokCLIAPIServerFactory<ProcessType: Processable>: TunnelServerFa
   private let cliAPI: any NgrokCLIAPI
 
   private let ngrokClient: @Sendable () -> NgrokClient
-
-  public init(cliAPI: any NgrokCLIAPI, ngrokClient: @escaping @Sendable () -> NgrokClient) {
+  
+  private init(cliAPI: any NgrokCLIAPI, ngrokClient: @escaping @Sendable () -> NgrokClient) {
     self.cliAPI = cliAPI
     self.ngrokClient = ngrokClient
   }
 
+
+  /// Sets up a factory to create ``NgrokCLIAPIServer``
+  /// - Parameters:
+  ///   - ngrokPath: Path to the `ngrok` executable.
+  ///   - ngrokClient: Creates a client to consume the local `ngrok` REST API.
   public init(ngrokPath: String, ngrokClient: @escaping @Sendable () -> NgrokClient) {
     self.init(
       cliAPI: NgrokProcessCLIAPI<ProcessType>(ngrokPath: ngrokPath),