Developer SDK

Swift examples

Install the SDK · View source on GitHub ↗

embed/Sources/EmbedCore/Fetch.swift

swift
// Obtaining the client JWT and reading the caps (EMBED_CONTRACT.md,
// "Obtaining the client JWT" and "App lifecycle"), over a replaceable HTTP
// function: the app passes urlSessionHttp and the self-test a stand-in server.
// fetchClientJwt is the one function to replace with your own sign-in: it posts
// this installation's instance-id to your backend and keeps the scoped client
// JWT that comes back. Nothing here prints a client JWT or the demo session.

import Foundation

#if canImport(FoundationNetworking)
  import FoundationNetworking
#endif

/// One HTTP request. authorization is the bearer token, sent as
/// "Authorization: Bearer <token>"; body, when set, is sent as application/json.
public struct HttpRequest: Equatable {
  public var method: String
  public var url: String
  public var authorization: String
  public var body: Data?

  /// A request with the given fields.
  public init(method: String, url: String, authorization: String, body: Data?) {
    self.method = method
    self.url = url
    self.authorization = authorization
    self.body = body
  }
}

/// One HTTP answer.
public struct HttpResponse: Equatable {
  public var status: Int
  public var body: Data

  /// An answer with the given status and body.
  public init(status: Int, body: Data) {
    self.status = status
    self.body = body
  }
}

/// No answer arrived: the server is unreachable, the answer is too large, or a
/// timeout.
public struct HttpError: Error, CustomStringConvertible {
  public let description: String

  /// An error with the given text.
  public init(_ description: String) {
    self.description = description
  }
}

/// Sends one request; throws HttpError when no answer arrived.
public typealias HttpFunction = (HttpRequest) throws -> HttpResponse

public let defaultApiUrl = "https://api.bringyour.com"
public let clientTokenPath = "/urnetwork/client-token"
public let clientDataCapPath = "/network/client-data-cap"

/// Whether text is a host name: letters, digits, dots and hyphens.
func isHostName(_ text: Substring) -> Bool {
  return !text.isEmpty && text.count <= 253
    && text.allSatisfy { $0.isASCII && ($0.isLetter || $0.isNumber || $0 == "." || $0 == "-") }
}

/// Whether text is a bracketed IPv6 literal such as "[::1]".
func isIpv6Literal(_ text: Substring) -> Bool {
  guard text.count >= 3, text.first == "[", text.last == "]" else {
    return false
  }
  return text.dropFirst().dropLast().allSatisfy { $0.isHexDigit || $0 == ":" || $0 == "." }
}

/// Checks an origin, as the allocators do: an HTTPS origin, or explicit loopback
/// HTTP (localhost, 127.0.0.1, [::1]) for local testing, optionally with a
/// port, and no credentials, path beyond "/", query or fragment. Returns the
/// origin with path appended; nil for any other text.
public func originUrl(_ origin: String, path: String) -> String? {
  let https = origin.hasPrefix("https://")
  let http = origin.hasPrefix("http://")
  if !https && !http {
    return nil
  }
  let schemeLength = https ? 8 : 7
  let rest = origin.dropFirst(schemeLength)
  let authorityEnd = rest.firstIndex(where: { "/?#".contains($0) }) ?? rest.endIndex
  let authority = rest[..<authorityEnd]
  let after = rest[authorityEnd...]
  // nothing after the authority but one optional "/"
  if !after.isEmpty && after != "/" {
    return nil
  }
  if authority.contains("@") {
    return nil
  }
  // the host, then an optional ":port"
  var hostEnd = authority.endIndex
  if authority.first == "[" {
    guard let close = authority.firstIndex(of: "]") else {
      return nil
    }
    hostEnd = authority.index(after: close)
  } else if let colon = authority.firstIndex(of: ":") {
    hostEnd = colon
  }
  let host = authority[..<hostEnd]
  let port = authority[hostEnd...]
  if !port.isEmpty {
    let digits = port.dropFirst()
    guard port.first == ":", (1...5).contains(digits.count),
      digits.allSatisfy({ $0.isASCII && $0.isNumber }), let number = Int(digits),
      (1...65535).contains(number)
    else {
      return nil
    }
  }
  let loopback = host == "localhost" || host == "127.0.0.1" || host == "[::1]"
  if http && !loopback {
    return nil
  }
  if !isHostName(host) && !isIpv6Literal(host) {
    return nil
  }
  return String(origin.prefix(schemeLength + authority.count)) + path
}

/// The outcome of a token fetch, with its exit code and GUI state
/// (EMBED_CONTRACT.md, "Obtaining the client JWT").
public enum FetchResult: Equatable {
  case ok
  /// 401 unauthorized, 409 installation_limit or client_limit: exit 78, GUI
  /// signed out
  case refused
  /// unreachable, 5xx, or an invalid answer: exit 1, GUI stopped
  case failed
}

/// The token server's answer, checked.
public struct Token: Equatable {
  public var clientId: String
  /// never print it
  public var clientJwt: String
  public var dataCap: Cap?
}

/// A fetch's result, its token when ok, and the reason otherwise.
public struct FetchOutcome {
  public var result: FetchResult
  public var token: Token?
  public var error: String
}

/// The token server's answer JSON.
struct TokenAnswer: Decodable {
  var clientId: String
  var byClientJwt: String

  /// The token server's field names.
  enum CodingKeys: String, CodingKey {
    case clientId = "client_id"
    case byClientJwt = "by_client_jwt"
  }
}

/// A refusal's {"error": {"message": ...}}.
struct RefusalAnswer: Decodable {
  struct Body: Decodable {
    var message: String?
  }
  var error: Body?
}

/// Obtains this installation's client JWT from the token server: posts the
/// instance-id with the demo session as the bearer token to
/// POST /urnetwork/client-token, checks that by_client_jwt carries a client_id
/// claim equal to client_id, and saves it as client.jwt. A 401 or 409 is a
/// refusal; no answer, another status or an invalid answer is a failure. The
/// token server's data_cap, when present, is the first cap reading.
public func fetchClientJwt(
  http: HttpFunction, tokenServerUrl: String, demoSession: String, stateDir: String,
  instanceId: String
) -> FetchOutcome {
  func failed(_ error: String) -> FetchOutcome {
    return FetchOutcome(result: .failed, token: nil, error: error)
  }
  guard let url = originUrl(tokenServerUrl, path: clientTokenPath) else {
    return failed("the token server URL is not an HTTPS origin")
  }
  // the instance id is a canonical uuid, which needs no json escaping
  let body = Data(#"{"installation_id":"\#(instanceId)"}"#.utf8)
  let response: HttpResponse
  do {
    response = try http(
      HttpRequest(method: "POST", url: url, authorization: demoSession, body: body))
  } catch {
    return failed("the token server is unreachable: \(error)")
  }
  if response.status == 401 || response.status == 409 {
    let message =
      (try? JSONDecoder().decode(RefusalAnswer.self, from: response.body))?.error?.message
      ?? (response.status == 401 ? "unauthorized" : "conflict")
    return FetchOutcome(
      result: .refused, token: nil, error: "the token server refused this installation: \(message)")
  }
  if response.status != 200 {
    return failed("the token server answered HTTP \(response.status)")
  }
  guard let answer = try? JSONDecoder().decode(TokenAnswer.self, from: response.body),
    let answerClientId = UUID(uuidString: answer.clientId)?.uuidString.lowercased()
  else {
    return failed("the token server's answer is not valid")
  }
  let claimClientId: String
  do {
    claimClientId = try parseClientJwtClientId(answer.byClientJwt)
  } catch {
    return failed("the token server's answer is not valid: \(error)")
  }
  if claimClientId != answerClientId {
    return failed("the token server's client JWT belongs to another client")
  }
  do {
    try saveClientJwt(stateDir: stateDir, clientJwt: answer.byClientJwt)
  } catch {
    return failed("save \(clientJwtFileName): \(error)")
  }
  // data_cap: a cap object, or null when the token server could not read it
  var dataCap: Cap?
  if let object = try? JSONSerialization.jsonObject(with: response.body) as? [String: Any],
    let value = object["data_cap"], !(value is NSNull),
    let capData = try? JSONSerialization.data(withJSONObject: value)
  {
    dataCap = parseCap(capData)
  }
  return FetchOutcome(
    result: .ok,
    token: Token(clientId: answerClientId, clientJwt: answer.byClientJwt, dataCap: dataCap),
    error: "")
}

/// A failed cap read.
public struct CapReadError: Error, CustomStringConvertible {
  public let description: String
}

/// The cap read answered the Embed-not-enabled refusal, which clears the last
/// reading.
public struct EmbedNotEnabledError: Error, CustomStringConvertible {
  public var description: String { embedNotEnabledMessage }
}

/// Reads this client's caps with its own client JWT:
/// GET /network/client-data-cap at the api origin. Throws CapReadError for no
/// answer, another status (a server without the cap routes answers 404) or an
/// answer that is not a cap object, and EmbedNotEnabledError for the
/// Embed-not-enabled refusal.
public func readCaps(http: HttpFunction, apiUrl: String, clientJwt: String) throws -> Cap {
  guard let url = originUrl(apiUrl, path: clientDataCapPath) else {
    throw CapReadError(description: "the API URL is not an HTTPS origin")
  }
  let response: HttpResponse
  do {
    response = try http(HttpRequest(method: "GET", url: url, authorization: clientJwt, body: nil))
  } catch {
    throw CapReadError(description: "\(error)")
  }
  if !(200..<300).contains(response.status) {
    throw CapReadError(description: "HTTP \(response.status)")
  }
  guard let cap = parseCap(response.body) else {
    if capNotEnabled(response.body) {
      throw EmbedNotEnabledError()
    }
    throw CapReadError(description: "the answer is not a cap object")
  }
  return cap
}

/// The settings of a run, as the environment gives them; nil when unset.
public struct EmbedSettings {
  public var stateDir: String?
  public var tokenServerUrl: String?
  public var demoSession: String?
  public var apiUrl: String?

  /// The settings with the given values.
  public init(stateDir: String?, tokenServerUrl: String?, demoSession: String?, apiUrl: String?) {
    self.stateDir = stateDir
    self.tokenServerUrl = tokenServerUrl
    self.demoSession = demoSession
    self.apiUrl = apiUrl
  }

  /// The settings from the environment.
  public static func fromEnvironment() -> EmbedSettings {
    let environment = ProcessInfo.processInfo.environment
    return EmbedSettings(
      stateDir: environment["URNETWORK_EMBED_STATE_DIR"],
      tokenServerUrl: environment["URNETWORK_TOKEN_SERVER_URL"],
      demoSession: environment["URNETWORK_DEMO_SESSION"],
      apiUrl: environment["URNETWORK_API_URL"])
  }
}

/// The configuration of a run, loaded at start.
public struct EmbedConfig {
  public var stateDir: String
  /// the run loop replaces it when the SDK refreshes the token
  public var clientJwt: String
  public var clientId: String
  public var instanceId: String
  /// the cap read's origin, checked
  public var apiUrl: String
  /// the token server's data_cap, the first cap reading
  public var firstCap: Cap?
}

/// A configuration, or the exit code and the reason it did not load.
public enum EmbedConfigResult {
  case loaded(EmbedConfig)
  case failed(exitCode: Int32, error: String)
}

/// Whether the demo session can go in an Authorization header: printable ascii
/// without spaces.
func isBearerToken(_ text: String) -> Bool {
  return !text.isEmpty && text.utf8.allSatisfy { $0 > 0x20 && $0 <= 0x7e }
}

/// Loads the configuration of a run: checks the state directory and the URLs,
/// creates instance-id on first run, and obtains the client JWT from the token
/// server when one is configured, otherwise from client.jwt. A configuration or
/// credential problem is exit code 78, a token server failure 1.
public func loadEmbedConfig(settings: EmbedSettings, http: HttpFunction) -> EmbedConfigResult {
  func isSet(_ value: String?) -> Bool {
    return !(value ?? "").isEmpty
  }
  do {
    let stateDir = settings.stateDir ?? ""
    try checkStateDir(stateDir)
    guard
      let apiUrl = originUrl(isSet(settings.apiUrl) ? settings.apiUrl! : defaultApiUrl, path: "")
    else {
      throw EmbedConfigError(
        "URNETWORK_API_URL must be an HTTPS origin, or loopback HTTP for local testing")
    }
    let tokenServer = isSet(settings.tokenServerUrl)
    if tokenServer != isSet(settings.demoSession) {
      throw EmbedConfigError(
        "set both URNETWORK_TOKEN_SERVER_URL and URNETWORK_DEMO_SESSION, or neither")
    }
    var tokenServerUrl: String?
    if tokenServer {
      tokenServerUrl = originUrl(settings.tokenServerUrl!, path: "")
      if tokenServerUrl == nil {
        throw EmbedConfigError(
          "URNETWORK_TOKEN_SERVER_URL must be an HTTPS origin, or loopback HTTP for local testing")
      }
      if !isBearerToken(settings.demoSession!) {
        throw EmbedConfigError("URNETWORK_DEMO_SESSION must hold the demo session token")
      }
    }
    let instanceId = try loadOrCreateInstanceId(stateDir: stateDir)
    if let tokenServerUrl {
      let outcome = fetchClientJwt(
        http: http, tokenServerUrl: tokenServerUrl, demoSession: settings.demoSession!,
        stateDir: stateDir, instanceId: instanceId)
      guard outcome.result == .ok, let token = outcome.token else {
        return .failed(
          exitCode: outcome.result == .refused ? EmbedExitCode.config : EmbedExitCode.failure,
          error: outcome.error)
      }
      return .loaded(
        EmbedConfig(
          stateDir: stateDir, clientJwt: token.clientJwt, clientId: token.clientId,
          instanceId: instanceId, apiUrl: apiUrl, firstCap: token.dataCap))
    }
    guard let stored = try loadClientJwt(stateDir: stateDir) else {
      throw EmbedConfigError(
        "no token server and no \(clientJwtFileName): set URNETWORK_TOKEN_SERVER_URL and URNETWORK_DEMO_SESSION, or write \(clientJwtFileName) with your backend tool's provision"
      )
    }
    return .loaded(
      EmbedConfig(
        stateDir: stateDir, clientJwt: stored.clientJwt, clientId: stored.clientId,
        instanceId: instanceId, apiUrl: apiUrl, firstCap: nil))
  } catch let error as EmbedConfigError {
    return .failed(exitCode: EmbedExitCode.config, error: error.description)
  } catch {
    return .failed(exitCode: EmbedExitCode.failure, error: "\(error)")
  }
}

/// The largest answer the app reads.
let responseByteLimit = 1024 * 1024

/// Refuses redirects: the app talks to exactly the origin it was given.
final class NoRedirect: NSObject, URLSessionTaskDelegate {
  /// Answers every redirect with no new request.
  func urlSession(
    _ session: URLSession, task: URLSessionTask, willPerformHTTPRedirection response: HTTPURLResponse,
    newRequest request: URLRequest, completionHandler: @escaping (URLRequest?) -> Void
  ) {
    completionHandler(nil)
  }
}

/// The app's HTTP function on URLSession: one request, no redirects, an
/// ephemeral session without cookies or caches, a bounded answer and a
/// timeout. It blocks the calling thread until the answer arrives.
public func urlSessionHttp(_ request: HttpRequest) throws -> HttpResponse {
  guard let url = URL(string: request.url) else {
    throw HttpError("invalid URL")
  }
  var urlRequest = URLRequest(url: url, timeoutInterval: 15)
  urlRequest.httpMethod = request.method
  urlRequest.setValue("Bearer " + request.authorization, forHTTPHeaderField: "Authorization")
  urlRequest.setValue("application/json", forHTTPHeaderField: "Accept")
  if let body = request.body {
    urlRequest.setValue("application/json", forHTTPHeaderField: "Content-Type")
    urlRequest.httpBody = body
  }
  let configuration = URLSessionConfiguration.ephemeral
  configuration.timeoutIntervalForRequest = 15
  configuration.timeoutIntervalForResource = 15
  let session = URLSession(configuration: configuration, delegate: NoRedirect(), delegateQueue: nil)
  defer { session.finishTasksAndInvalidate() }
  let done = DispatchSemaphore(value: 0)
  /// The task's outcome, written once before done is signaled.
  final class Outcome: @unchecked Sendable {
    var data: Data?
    var response: URLResponse?
    var error: Error?
  }
  let outcome = Outcome()
  let task = session.dataTask(with: urlRequest) { data, response, error in
    outcome.data = data
    outcome.response = response
    outcome.error = error
    done.signal()
  }
  task.resume()
  done.wait()
  if let error = outcome.error {
    throw HttpError(error.localizedDescription)
  }
  guard let http = outcome.response as? HTTPURLResponse else {
    throw HttpError("no HTTP answer")
  }
  let data = outcome.data ?? Data()
  if responseByteLimit < data.count {
    throw HttpError("the answer is too large")
  }
  return HttpResponse(status: http.statusCode, body: data)
}