District Core for Swift
The shared Swift core of the native District AI
apps: the models, networking, data repositories, sign-in logic and call state machines
that the iPhone, iPad and Mac clients have in common. It builds and tests on Linux as
well as on Apple platforms, so almost all of the apps' logic is tested without a
simulator, a network or an account.
Consumers:
This package was extracted from district-ios at 0b2354b, with its history. 7.1.0 is the
current release.
Links: project page ·
GitLab mirror (read-only
mirror; issues and pull requests live on GitHub) · CHANGELOG ·
CONTRIBUTING · SECURITY
The District AI service the package talks to is not open source; signing in needs a
District AI account. Without one you can still build the package and run every test.
Without an account with us. Today the District AI apps need a District AI account to
sign in. We want them to work without an account with us too. We have not worked out
what that looks like or whether it can work, and the answer depends on what people would
use them with, so we are asking before we build anything:
tell us what you would connect them to.
Using it
Swift 6.2 or later, Swift 6 language mode. Platforms: iOS 17 and macOS 14 (the
deployment targets in Package.swift), plus Linux for building and testing.
dependencies: [
.package(url: "https://github.com/distronode-corporation/district-core-swift", exact: "7.1.0"),
],
Pin an exact version. The apps do, so that a core change reaches a store build only
through a reviewed version bump.
In an XcodeGen project.yml:
packages:
DistrictCore:
url: https://github.com/distronode-corporation/district-core-swift
exactVersion: 7.1.0
Modules
Each module is a library product. All of them import only Foundation (and
FoundationNetworking on Linux).
| Module | What it holds |
|---|
DistrictL10n | Every piece of display text the core produces, in English or Canadian French, generated from the catalogs in l10n/; the language switch (L10nRuntime); and the formats for money, dates, times, durations, numbers, percentages and lists (L10nFormat), held byte for byte to the website's. Also the API error code sentences (ApiErrorText) and the wire value labels (WireLabel). Depends on nothing. |
DistrictModel | Codable DTOs for every response the apps decode, and the single normalised error type, ApiError. Depends only on DistrictL10n. |
DistrictAuthCore | PKCE (S256), the Sign in with Apple nonce, token refresh coordination, revocation and sign-out. Token storage is the TokenStore protocol; each app implements it with the Keychain. |
DistrictNetwork | Every endpoint and path, the API client, error-envelope normalisation and the native sign-in exchanges. The HTTP transport is the HTTPTransport protocol, so libcurl and Darwin URLSession differences never reach feature code. |
DistrictData | Repositories and paging over DistrictNetwork. |
DistrictCall | Everything about a call that is not the media SDK or the OS call registry: the CallEngine seam, the outbound and inbound state machines and the commands they emit. |
DistrictLive | Live updates: the telemetry socket's state machine (TelemetryConnection) and the actor that runs it, with the live transcript's ops; a call's live transcript (TranscriptReducer); the Mac's presence (PresenceController) and the ring gate (DesktopRingGate). The socket is the TelemetrySocketTransport protocol and time is the LiveClock protocol, so every rule is tested on Linux without a server or a wait; the URLSessionWebSocketTask adapter lives in the macOS app. |
The one external dependency is apple/swift-crypto,
pinned exact:, for SHA-256 on Linux (and swift-asn1 through it). Package.resolved is
committed.
Build and test
swift build
swift test --enable-code-coverage
ci/coverage-gate.sh # per-module line-coverage floors, all at 100%
ci/Dockerfile defines the Linux toolchain CI uses (swift:6.2.4, SwiftLint, SwiftFormat).
Lint, from the repository root:
swiftformat --lint . # SwiftFormat 0.63.0
swiftlint --strict # SwiftLint 0.65.1
Languages
The core writes English, and Canadian French once an app turns it on by setting
L10nRuntime.locale (to DistrictL10n.locale(fromPreferred:) of the device's preferred
languages). Until an app sets it, everything is English.
- The text is in four TOML catalogs under
l10n/, in the format
tools/l10n/ reads: core.toml and countries.toml are written by
hand; api_errors.toml and wire.toml are generated from contracts/i18n/.
python3 scripts/gen-l10n.py writes those two catalogs, the Swift in
Sources/DistrictL10n/Generated/ and the test that calls every accessor in both
languages. Never edit a generated file; change a catalog and run the script.
python3 scripts/gen-l10n.py --check is what CI runs.tools/l10n/ is a vendored copy (SOURCE.toml names the commit;
python3 tools/l10n/l10n.py vendor --check --dest tools/l10n verifies it).- Formats are not CLDR:
L10nFormat is a set of tables tested against
contracts/i18n/format-vectors.json, so a customer reads the same bytes on every OS
version and on the website.
The contract gate
contracts/ holds recorded responses from the District AI service, generated by the
service's own test suite and copied here unchanged (see contracts/README.md).
contracts/mobile/ is the set the iOS and Android apps decode; contracts/desktop/ is the
desktop clients' additions.
ContractFixtureTests runs every mobile fixture that has a Swift model through a strict
gate: no null outside a reviewed allow-list, decode, re-encode, and the re-encoded keys
must equal the fixture's at every level. It asserts the exact number of fixtures (187)
and an explicit list of fixtures that have no model yet, so a missing directory or a
newly added fixture is a failure rather than a silent pass. Set DISTRICT_CONTRACTS_DIR
to read the fixtures from somewhere else.
DesktopContractFixtureTests does the same for contracts/desktop/: an exact count (13)
and one verifier per file, twelve through the strict gate and the scheduling hand-off
through the client's own hand-written decoder. Set DISTRICT_DESKTOP_CONTRACTS_DIR to
read them from somewhere else.
The strictness is in the tests only. The decoders ignore unknown fields, so an installed
app keeps working when the service adds one.
Continuous integration
.github/workflows/ci.yml runs on every push to main and
every pull request, and uses no secrets:
- verify (Linux,
swift:6.2.4): SwiftFormat, SwiftLint, the Foundation-only import
rule, the Package.resolved guard, swift test, a floor on the number of tests run,
and the coverage floors.
- hygiene (Linux): no em or en dashes, internal host names or GitLab URLs other than
this repository's own mirror
(
scripts/check-public-hygiene.py), the licence
files present, the vendored catalog tools unmodified, every generated string file
current, and the French rules (frcheck).
- gitleaks (Linux): the full git history, with
.gitleaks.toml.
- zizmor (Linux): static analysis of the workflows.
- darwin (macOS):
swift test, then xcodebuild for generic iOS and generic macOS.
- dependency graph (Linux): submits the
Package.resolved pins to GitHub's dependency graph,
which cannot see them on its own; on pushes to main and pull requests from this
repository.
- dependency-review (Linux, pull requests): fails a pull request that adds a
dependency with a known moderate-or-worse vulnerability or a licence this package cannot
ship, compared after the snapshot above has landed.
codeql.yml (the workflows, on every pull request),
codeql-swift.yml (the library targets, on pushes to
main that change them, weekly and on demand) and
scorecard.yml add CodeQL and the OpenSSF Scorecard.
Changing the core
Changes land here first, in a pull request with its tests. A release is a version tag;
each app then bumps its exact pin in a pull request of its own. See
CONTRIBUTING.md.
Contributing, security and conduct
Questions about a District AI account, number or bill go to
District AI support.
License and trademarks
Apache License 2.0. See LICENSE and NOTICE.
District AI, Distronode and the District AI and Distronode logos and app icons are
trademarks of Distronode Corporation. They are not licensed under the Apache License 2.0:
an app you distribute that uses this package must use its own name, icon and bundle
identifier.
