Migrating the iOS client from v4

This page takes an app from any 4.x release of the iOS client to 5.3.0. For a fresh integration, use the iOS guide instead.

Upgrade the client and the relay together

5.3.0 speaks frame version 2 and needs a v5 relay. A v4 client cannot talk to a v5 relay (the relay answers 478), and 5.3.0 cannot talk to a v4 relay. Plan the app release alongside the relay upgrade.

Package and import

The package URL is unchanged. The product and module were renamed:

// Package.swift — version, and the product name
.package(url: "https://github.com/Eclypses/mte-relay-client-ios.git", from: "5.3.0")
.product(name: "Relay", package: "mte-relay-client-ios")   // was: "MteRelay"

import Relay   // was: import MteRelay

In Xcode, remove the MteRelay product from your target and add Relay.

Minimum platform

	v4	5.3.0
iOS	14.0	16.0
Swift	5.5	5.7

The app must also be code-signed: the client keeps a small host record in the keychain.

headersToEncrypt is now unencryptedHeaders, and means the opposite

v4 encrypted only the headers you listed. 5.3.0 encrypts every header and leaves in the clear only those you list. Porting a v4 list unchanged would send exactly the headers you meant to protect in the clear, so in most cases drop the argument. List a header only when something between your app and the relay has to read it.

Content-Type, Content-Length, Host, X-MTE-Relay-Route and X-MTE-Relay-Client are reserved and always encrypted; listing one throws.

dataTask: callback to async throws

// v4
await relay.dataTask(with: request, headersToEncrypt: headers, pathnamePrefix: prefix) { data, response, error in
    // handle result
}

// 5.3.0 — the same (Data, URLResponse) URLSession returns
let (data, response) = try await relay.dataTask(with: request)

Remove any conformance to RelayResponseDelegate; the protocol is gone.

For a response you want as it arrives (a long-lived event stream, a large body), 5.3.0 adds request(with:), which yields the status first and then the body in chunks.

File transfer

// v4 — synchronous; results via RelayStreamResponseDelegate
try relay.uploadFileStream(request: request, headersToEncrypt: headers, pathnamePrefix: prefix)
try relay.downloadFileStream(request: request, downloadUrl: destinationURL,
                             headersToEncrypt: headers, pathnamePrefix: prefix)

// 5.3.0 — async; results returned
let (data, response) = try await relay.uploadFileStream(request: request)
let response = try await relay.downloadFile(with: request, to: destinationURL)

The relay's advertised request-body limit now applies to streamed uploads too. An upload over it fails before anything is sent, with RelayClientError.requestTooLarge.

Settings

// v4 — individual parameters
try await relay.adjustRelaySettings(serverUrl: url, pathnamePrefix: prefix,
                                    newStreamChunkSize: 1_048_576, newPairPoolSize: 5,
                                    persistPairs: false)

// 5.3.0 — one RelayHostSettings value
try await relay.adjustRelaySettings(
    serverUrl: url,
    pathnamePrefix: prefix,
    settings: RelayHostSettings(minPairs: 5, basePairs: 8, maxPairs: 15,
                                keepAliveInterval: 300, acquisitionWaitTime: 1.0)
)

persistPairs and the stream chunk size are gone: pairs are no longer persisted, and the relay's advertised frame size bounds every chunk.

Re-pairing

// v4
try await relay.rePairwithRelayServer("https://your-relay-server.com", pathnamePrefix: prefix)

// 5.3.0 — the argument is labelled
try await relay.rePairwithRelayServer(relayServerUrlString: "https://your-relay-server.com",
                                      pathnamePrefix: prefix)

Errors

Failures are thrown as RelayClientError. Update exhaustive switch statements for the cases added in v5, among them pairCapacityExhausted, pairReplaced, pairReplaceFailed, fullRepairSuccess, fullRepairCatastrophic, relayStatus, incompatibleRelay, requestTooLarge, invalidHeaderName and relayRejectedRequest.

Removed, because nothing produced them: the RelayError and RelayStatus enums, the serverSentEventsMalformedStream and serverSentEventsBufferLimitExceeded cases, and a FileManager.sizeOfFile(atPath:) helper the library had exposed. Delete code that names them.