javier
13b9c74a38
CI / Build and test (push) Canceled after 0s
Documentation / Build documentation (push) Canceled after 0s
Documentation / Deploy to GitHub Pages (push) Canceled after 0s
This PR contains the work done to fix a cancellation-mapping bug in `AmiiboLiveClient`, bring the client under offline test coverage, add the conformances SwiftUI and persistence need, and moves CI and documentation publishing to GitHub Actions. All public API changes are additive.
### Fix
- `AmiiboLiveClient` reported an early task cancellation as `.unknown("CancellationError()")`. The OpenAPI runtime wraps every error in `ClientError`, so the `CancellationError` check never matched; it now also checks the wrapped error and throws `.cancelled`.
### Tests
- `ThrowingTransport` and `StubTransport` test doubles let the live client run offline. New tests cover error mapping, HTTP status → error mapping, `oneOf` object-vs-list decoding, `"amiibo": null`, sorting, filter → query encoding, `Platform`/`Release` mapping, and the date transcoder.
- Models gained `package` memberwise initializers so tests can build real fixtures without `@testable`. These are not public API.
- The test target now depends on `OpenAPIRuntime` and `HTTPTypes` (both already in the dependency graph).
### API
- Models are `Codable` and `Identifiable` (`Amiibo.id` is its `identifier`; the key/name models use `key`).
- Filters are `Hashable`.
### Documentation
- Doc comments trimmed library-wide; one repeated `- Throws:` sentence appeared 24 times. `Library.md` and the README tightened to match.
### CI and docs publishing
- `ci.yml`: build and offline tests on PRs and pushes to `main`.
- `live-tests.yml`: weekly and on-demand run against the live API.
- `docs.yml`: builds DocC on PRs, deploys to GitHub Pages on `main`. Pinned to Xcode 26 because swift-docc-plugin 1.5.0 fails to launch its tools under Xcode 27.
- The generated `docs/` folder (327 files) is removed from the repository and ignored.
Reviewed-on: #31
Co-authored-by: Javier Cicchelli <javier@rock-n-code.com>
383 lines
13 KiB
Swift
383 lines
13 KiB
Swift
// ===----------------------------------------------------------------------===
|
|
//
|
|
// This source file is part of the Amiibo Service open source project
|
|
//
|
|
// Copyright (c) 2026 Röck+Cöde VoF. and the Amiibo Service project authors
|
|
// Licensed under Apache license v2.0
|
|
//
|
|
// See LICENSE for license information
|
|
// See CONTRIBUTORS for the list of Amiibo Service project authors
|
|
//
|
|
// SPDX-License-Identifier: Apache-2.0
|
|
//
|
|
// ===----------------------------------------------------------------------===
|
|
|
|
import Foundation
|
|
import OpenAPIRuntime
|
|
import OpenAPIURLSession
|
|
|
|
/// A live client for the [Amiibo API](https://www.amiiboapi.org).
|
|
///
|
|
/// It maps transport errors and unsuccessful responses to ``AmiiboServiceError``, and sorts list results by identifier or key.
|
|
public struct AmiiboLiveClient: Sendable {
|
|
|
|
// MARK: Constants
|
|
|
|
/// The base URL of the live service, from the OpenAPI specification.
|
|
///
|
|
/// A unit test guards this URL, so resolution is not expected to fail at runtime.
|
|
static let serverURL: URL = {
|
|
guard let url = try? Servers.Server1.url() else {
|
|
fatalError("The server URL defined in the OpenAPI specification could not be resolved. Verify that the 'openapi.yaml' server definition is valid.")
|
|
}
|
|
|
|
return url
|
|
}()
|
|
|
|
// MARK: Properties
|
|
|
|
/// A client generated by the OpenAPI Runtime library to perform API calls.
|
|
private let client: Client
|
|
|
|
// MARK: Initializers
|
|
|
|
/// Initializes this client.
|
|
/// - Parameter transport: A transport for HTTP operations. Defaults to a `URLSessionTransport` on the shared session.
|
|
public init(transport: any ClientTransport = URLSessionTransport()) {
|
|
self.client = .init(
|
|
serverURL: Self.serverURL,
|
|
configuration: .init(dateTranscoder: ISODateTimeTranscoder()),
|
|
transport: transport
|
|
)
|
|
}
|
|
|
|
}
|
|
|
|
// MARK: - AmiiboClient
|
|
// TODO: Remove the documentation from the functions inside the following extension as the `--enable-inherited-docs` flag when generating DocC documentation is not working as intended (?).
|
|
|
|
extension AmiiboLiveClient: AmiiboClient {
|
|
|
|
// MARK: Functions
|
|
|
|
/// Gets a list of amiibo items based on a given filter.
|
|
/// - Parameter filter: A filter for the result.
|
|
/// - Returns: A list of filtered amiibo items.
|
|
/// - Throws: An ``AmiiboServiceError`` if the call fails.
|
|
public func getAmiibos(
|
|
by filter: AmiiboFilter
|
|
) async throws(AmiiboServiceError) -> [Amiibo] {
|
|
try await fetchAmiibos(filter)
|
|
}
|
|
|
|
/// Gets a list of amiibo series based on a given filter.
|
|
/// - Parameter filter: A filter for the result.
|
|
/// - Returns: A list of filtered amiibo series.
|
|
/// - Throws: An ``AmiiboServiceError`` if the call fails.
|
|
public func getAmiiboSeries(
|
|
by filter: AmiiboSeriesFilter
|
|
) async throws(AmiiboServiceError) -> [AmiiboSeries] {
|
|
try await fetchAmiiboSeries(filter)
|
|
}
|
|
|
|
/// Gets a list of amiibo types based on a given filter.
|
|
/// - Parameter filter: A filter for the result.
|
|
/// - Returns: A list of filtered amiibo types.
|
|
/// - Throws: An ``AmiiboServiceError`` if the call fails.
|
|
public func getAmiiboTypes(
|
|
by filter: AmiiboTypeFilter
|
|
) async throws(AmiiboServiceError) -> [AmiiboType] {
|
|
try await fetchAmiiboTypes(filter)
|
|
}
|
|
|
|
/// Gets a list of game characters based on a given filter.
|
|
/// - Parameter filter: A filter for the result.
|
|
/// - Returns: A list of filtered game characters.
|
|
/// - Throws: An ``AmiiboServiceError`` if the call fails.
|
|
public func getGameCharacters(
|
|
by filter: GameCharacterFilter
|
|
) async throws(AmiiboServiceError) -> [GameCharacter] {
|
|
try await fetchGameCharacters(filter)
|
|
}
|
|
|
|
/// Gets a list of game series based on a given filter.
|
|
/// - Parameter filter: A filter for the result.
|
|
/// - Returns: A list of filtered game series.
|
|
/// - Throws: An ``AmiiboServiceError`` if the call fails.
|
|
public func getGameSeries(
|
|
by filter: GameSeriesFilter
|
|
) async throws(AmiiboServiceError) -> [GameSeries] {
|
|
try await fetchGameSeries(filter)
|
|
}
|
|
|
|
/// Gets the date when the data was last updated.
|
|
/// - Returns: A last updated date, decoded as UTC.
|
|
/// - Throws: An ``AmiiboServiceError`` if the call fails.
|
|
public func getLastUpdated() async throws(AmiiboServiceError) -> Date {
|
|
try await fetchLastUpdated()
|
|
}
|
|
|
|
}
|
|
|
|
// MARK: - Helpers
|
|
|
|
private extension AmiiboLiveClient {
|
|
|
|
// MARK: Functions
|
|
|
|
/// Fetches the amiibos matching a filter.
|
|
func fetchAmiibos(
|
|
_ filter: AmiiboFilter
|
|
) async throws(AmiiboServiceError) -> [Amiibo] {
|
|
let response = try await perform {
|
|
try await client.getAmiibos(.init(query: .init(
|
|
id: filter.identifier,
|
|
head: filter.head,
|
|
tail: filter.tail,
|
|
name: filter.name,
|
|
_type: filter.type,
|
|
amiiboSeries: filter.series,
|
|
character: filter.gameCharacter,
|
|
gameseries: filter.gameSeries,
|
|
showgames: filter.showGames,
|
|
showusage: filter.showUsage
|
|
)))
|
|
}
|
|
|
|
switch response {
|
|
case let .ok(ok):
|
|
switch ok.body {
|
|
case let .json(output):
|
|
switch output.amiibo {
|
|
case let .Amiibo(object):
|
|
return [Amiibo(object)]
|
|
case let .AmiiboList(list):
|
|
return list
|
|
.map { Amiibo($0) }
|
|
.sorted { $0.identifier < $1.identifier }
|
|
case .none:
|
|
// The service returns `"amiibo": null` when an `id` filter matches nothing.
|
|
return []
|
|
}
|
|
}
|
|
case .badRequest:
|
|
throw AmiiboServiceError.badRequest
|
|
case .notFound:
|
|
throw AmiiboServiceError.notFound
|
|
case .internalServerError:
|
|
throw AmiiboServiceError.notAvailable
|
|
case let .undocumented(statusCode, _):
|
|
throw AmiiboServiceError.undocumented(statusCode)
|
|
}
|
|
}
|
|
|
|
/// Fetches the amiibo series matching a filter.
|
|
func fetchAmiiboSeries(
|
|
_ filter: AmiiboSeriesFilter
|
|
) async throws(AmiiboServiceError) -> [AmiiboSeries] {
|
|
let response = try await perform {
|
|
try await client.getAmiiboSeries(.init(query: .init(
|
|
key: filter.key,
|
|
name: filter.name
|
|
)))
|
|
}
|
|
|
|
switch response {
|
|
case let .ok(ok):
|
|
switch ok.body {
|
|
case let .json(output):
|
|
switch output.amiibo {
|
|
case let .AmiiboSeries(payload):
|
|
return makeModels(from: [payload])
|
|
case let .AmiiboSeriesList(list):
|
|
return makeModels(from: list)
|
|
}
|
|
}
|
|
case .badRequest:
|
|
throw AmiiboServiceError.badRequest
|
|
case .internalServerError:
|
|
throw AmiiboServiceError.notAvailable
|
|
case .notFound:
|
|
throw AmiiboServiceError.notFound
|
|
case let .undocumented(statusCode, _):
|
|
throw AmiiboServiceError.undocumented(statusCode)
|
|
}
|
|
}
|
|
|
|
/// Fetches the amiibo types matching a filter.
|
|
func fetchAmiiboTypes(
|
|
_ filter: AmiiboTypeFilter
|
|
) async throws(AmiiboServiceError) -> [AmiiboType] {
|
|
let response = try await perform {
|
|
try await client.getAmiiboTypes(.init(query: .init(
|
|
key: filter.key,
|
|
name: filter.name
|
|
)))
|
|
}
|
|
|
|
switch response {
|
|
case let .ok(ok):
|
|
switch ok.body {
|
|
case let .json(output):
|
|
switch output.amiibo {
|
|
case let .AmiiboType(payload):
|
|
return makeModels(from: [payload])
|
|
case let .AmiiboTypeList(list):
|
|
return makeModels(from: list)
|
|
}
|
|
}
|
|
case .badRequest:
|
|
throw AmiiboServiceError.badRequest
|
|
case .internalServerError:
|
|
throw AmiiboServiceError.notAvailable
|
|
case .notFound:
|
|
throw AmiiboServiceError.notFound
|
|
case let .undocumented(statusCode, _):
|
|
throw AmiiboServiceError.undocumented(statusCode)
|
|
}
|
|
}
|
|
|
|
/// Fetches the game characters matching a filter.
|
|
func fetchGameCharacters(
|
|
_ filter: GameCharacterFilter
|
|
) async throws(AmiiboServiceError) -> [GameCharacter] {
|
|
let response = try await perform {
|
|
try await client.getGameCharacters(.init(query: .init(
|
|
key: filter.key,
|
|
name: filter.name
|
|
)))
|
|
}
|
|
|
|
switch response {
|
|
case let .ok(ok):
|
|
switch ok.body {
|
|
case let .json(output):
|
|
switch output.amiibo {
|
|
case let .GameCharacter(payload):
|
|
return makeModels(from: [payload])
|
|
case let .GameCharacterList(list):
|
|
return makeModels(from: list)
|
|
}
|
|
}
|
|
case .badRequest:
|
|
throw AmiiboServiceError.badRequest
|
|
case .internalServerError:
|
|
throw AmiiboServiceError.notAvailable
|
|
case .notFound:
|
|
throw AmiiboServiceError.notFound
|
|
case let .undocumented(statusCode, _):
|
|
throw AmiiboServiceError.undocumented(statusCode)
|
|
}
|
|
}
|
|
|
|
/// Fetches the game series matching a filter.
|
|
func fetchGameSeries(
|
|
_ filter: GameSeriesFilter
|
|
) async throws(AmiiboServiceError) -> [GameSeries] {
|
|
let response = try await perform {
|
|
try await client.getGameSeries(.init(query: .init(
|
|
key: filter.key,
|
|
name: filter.name
|
|
)))
|
|
}
|
|
|
|
switch response {
|
|
case let .ok(ok):
|
|
switch ok.body {
|
|
case let .json(output):
|
|
switch output.amiibo {
|
|
case let .GameSeries(payload):
|
|
return makeModels(from: [payload])
|
|
case let .GameSeriesList(list):
|
|
return makeModels(from: list)
|
|
}
|
|
}
|
|
case .badRequest:
|
|
throw AmiiboServiceError.badRequest
|
|
case .internalServerError:
|
|
throw AmiiboServiceError.notAvailable
|
|
case .notFound:
|
|
throw AmiiboServiceError.notFound
|
|
case let .undocumented(statusCode, _):
|
|
throw AmiiboServiceError.undocumented(statusCode)
|
|
}
|
|
}
|
|
|
|
/// Fetches the date when the data was last updated.
|
|
func fetchLastUpdated() async throws(AmiiboServiceError) -> Date {
|
|
let response = try await perform {
|
|
try await client.getLastUpdated()
|
|
}
|
|
|
|
switch response {
|
|
case let .ok(ok):
|
|
switch ok.body {
|
|
case let .json(output):
|
|
return output.lastUpdated
|
|
}
|
|
case .internalServerError:
|
|
throw AmiiboServiceError.notAvailable
|
|
case let .undocumented(statusCode, _):
|
|
throw AmiiboServiceError.undocumented(statusCode)
|
|
}
|
|
}
|
|
|
|
/// Performs an API call, mapping any error to an ``AmiiboServiceError``.
|
|
func perform<Output>(
|
|
_ operation: () async throws -> Output
|
|
) async throws(AmiiboServiceError) -> Output {
|
|
do {
|
|
return try await operation()
|
|
} catch {
|
|
try handle(error: error)
|
|
}
|
|
}
|
|
|
|
/// Maps key-name payloads into models sorted by key.
|
|
func makeModels<Model: KeyNameModel>(from payloads: [some KeyNamePayload]) -> [Model] {
|
|
payloads
|
|
.map { Model($0) }
|
|
.sorted { $0.key < $1.key }
|
|
}
|
|
|
|
/// Maps an error to the corresponding ``AmiiboServiceError``.
|
|
func handle(error: any Error) throws(AmiiboServiceError) -> Never {
|
|
switch error {
|
|
case is CancellationError:
|
|
throw AmiiboServiceError.cancelled
|
|
case let clientError as ClientError:
|
|
// The underlying client wraps every error, including cancellation, in a `ClientError`.
|
|
switch clientError.underlyingError {
|
|
case is CancellationError:
|
|
throw AmiiboServiceError.cancelled
|
|
case is DecodingError:
|
|
throw AmiiboServiceError.decoding
|
|
case let urlError as URLError:
|
|
switch urlError.code {
|
|
case .cancelled:
|
|
throw AmiiboServiceError.cancelled
|
|
case .cannotParseResponse:
|
|
throw AmiiboServiceError.decoding
|
|
case .cannotFindHost,
|
|
.cannotConnectToHost,
|
|
.dataNotAllowed,
|
|
.dnsLookupFailed,
|
|
.internationalRoamingOff,
|
|
.networkConnectionLost,
|
|
.notConnectedToInternet,
|
|
.secureConnectionFailed,
|
|
.timedOut:
|
|
throw AmiiboServiceError.notAvailable
|
|
default:
|
|
throw AmiiboServiceError.unknown(String(describing: urlError))
|
|
}
|
|
default:
|
|
throw AmiiboServiceError.unknown(String(describing: clientError.underlyingError))
|
|
}
|
|
default:
|
|
throw AmiiboServiceError.unknown(String(describing: error))
|
|
}
|
|
}
|
|
|
|
}
|