Skip to content

v0.1.0

Choose a tag to compare

@inTouchSRL inTouchSRL released this 19 Nov 01:29

The Squiddy SDK 0.1.0 for iOS, as a Swift package: add https://github.com/squiddy-cloud/squiddy-swift in Xcode, or .package(url: "https://github.com/squiddy-cloud/squiddy-swift", from: "0.1.0") in a Package.swift. Android and JVM projects take the same version from Maven Central, cloud.squiddy:squiddy:0.1.0.

SquiddyCore.xcframework.zip is the SDK's Kotlin framework, which the package downloads (checksum ad92e34d2250562c4dfe1ba7750181a9e2565ad1b62c3be19c2aa1eaba1e8e92).

The first version of the SDK: everything below is new.

Added

  • On Maven Central. Android and JVM projects add implementation("cloud.squiddy:squiddy:0.1.0"), and Gradle picks
    the artifact of the platform (squiddy-android, squiddy-jvm, and the iOS klibs for a Kotlin Multiplatform app).
    Every artifact comes with its sources and its API reference, and is signed.
  • One SDK for Android, the JVM and iOS. A Kotlin Multiplatform library under the Apache License 2.0, for Android
    API 24 and later (compiled against API 37, which OkHttp 5.5 requires of the apps too), Java 17 and later, and iOS 15
    and later on devices and on the simulators of Apple silicon and Intel Macs.
  • The data-plane contract of Squiddy. The SDK calls squiddy.v1.ConfigService/GetRemoteConfiguration with the
    Connect protocol in binary, over Ktor (OkHttp on Android and the JVM, NSURLSession on iOS). Its copy of
    config.proto is Squiddy's file byte for byte, and the protocol's messages stay inside the SDK.
  • The API key travels only in X-API-Key. It never appears in a log line, a URL or a toString. Every call names
    the SDK in its User-Agent (squiddy-kotlin/<version>), times out after 10 seconds by default and follows no
    redirect.
  • Initialization from the app's context. Squiddy.initialize takes SquiddyOptions (host, apiKey, appId,
    appVersion as YYYY.MM.DD, appMode, and optionally customParams, bundleId, language, entityId,
    timeout, refreshInterval, pushRefreshJitter, logger). It validates them and reads the rest from the
    platform: the app type (android, ios, desktop), the bundle id and the language. It reads and writes no file
    on the calling thread (see below).
  • The configuration as observable state. Squiddy.config is a StateFlow<SquiddyState>: Pending, then
    Ready with its ConfigurationOrigin (CACHE or NETWORK), or Failed with the error and the last valid
    configuration. RemoteConfiguration gives the version, the ServerApi block and its settings, whose
    asInt(), asDouble() and asBoolean() throw a SettingTypeException for a value of another type. refresh()
    asks for an update, and close() ends the instance.
  • Typed errors. SquiddyError has one case per failure of the data plane: Unauthenticated, AppNotPublished,
    InvalidRequest, IncompleteConfiguration, TenantSuspended, ServerError (with Squiddy's exceptionCode),
    RateLimited (with retryAfter), Network, Timeout and MalformedResponse.
  • Offline first. The last valid configuration is stored on the device and served before the network, also across
    launches. It is written atomically, and the API key is never stored. It lives in noBackupFilesDir on Android, in
    Application Support on iOS (kept out of backups), and in the app's directory of the system's data directory on
    the JVM: on macOS in Application Support, kept out of Time Machine with tmutil addexclusion, and on Windows in
    %LOCALAPPDATA%, which a roaming profile does not carry.
  • Gradual rollouts. Each installation gets an id of its own, a UUID sent as entity_id, so that a percentage
    rollout reaches a stable share of the installations. A backup restored onto another device, a Mac set up from a
    Time Machine backup or a roaming Windows profile does not carry it. An app can pass its own id instead
    (entityId).
  • Conditional requests. A call carries the fingerprints of the stored configuration and languages, so Squiddy
    answers not_modified or leaves out what did not change; the SDK merges the partial answer into the stored one.
    From a Squiddy that echoes lang_fingerprint with unchanged languages (release 20261118-39b4121 and later), an
    answer without languages and without the echo removes the stored languages: the configuration no longer has any for
    the app. The archive remembers whether its server has echoed, so the answers of an earlier server keep the
    languages as before.
  • The refresh policy. The SDK checks the configuration at every start, whenever the app comes back to the
    foreground, and every refreshInterval while it stays there (5 minutes by default, at least 30 seconds); never in
    the background. A check is a conditional call: an unchanged configuration costs a not_modified answer. The
    foreground comes from the activities on Android, from UIApplication's notifications on iOS, and is permanent on the
    JVM. After a failure it keeps serving the stored configuration and retries with an exponential backoff with jitter.
    It honours Retry-After after a 429, and after Unauthenticated it stops until refresh(). The README counts the
    installations in the foreground that a key of each plan holds.
  • Mandatory updates and maintenance. Squiddy.gate is a StateFlow<AppGate>: None, UpdateRequired or
    Maintenance, with the title and message Squiddy sends in the app's language, also from the stored configuration.
    The notices are readable as RemoteConfiguration.appUpdate and infoPoint.
  • Localized strings. Squiddy.string(key) and string(key, fallback) read the configuration's strings in the
    app's language, then in the default language, then the fallback; Squiddy.strings observes them. An empty string is
    a missing translation, as a cell left blank in the dashboard's translations grid: the lookup falls back and never
    returns an empty text. The titles of AppGate keep their meaning: empty when the configuration gives none.
  • The language follows the user and the app. Squiddy.setLanguage(language) (in Swift try setLanguage(_:),
    which throws SquiddyLanguageError) chooses the language of the requests, and null follows the user's again. The
    user's language is followed while the app runs: through the app's configuration changes on Android,
    NSCurrentLocaleDidChangeNotification on iOS, and at every check on the JVM. After a change the strings are read in
    the new language at once, and the SDK checks with Squiddy at once, in the foreground, so the texts of gate follow;
    the archive keeps the language each configuration was received in, and no call is made for a language it already has.
  • Push update. Squiddy can ask an app's installations to update now, with a data-only message of Firebase Cloud
    Messaging sent to the configuration's topic. The app subscribes to Squiddy.pushTopic and passes the data of the
    messages it receives to Squiddy.handlePush(data) (in Swift handlePush(_ userInfo:), in Java
    getPushTopic() and handlePush(Map)), which returns true for Squiddy's (squiddy = refresh) and checks the
    configuration after a random wait of up to pushRefreshJitter (60 seconds by default, zero allowed; in Java
    SquiddyOptionsBuilder.pushRefreshJitter(Duration)), in the background too. The wait respects Retry-After, the
    backoff and the stop after Unauthenticated, and a burst of notifications costs one call. The topic follows a rule
    Squiddy computes in the same way, from the key's SHA-256 and the app id (the README has it, with its test vectors),
    so each environment has its own topic. The SDK does not depend on Firebase; the README shows the wiring on Android
    and iOS.
  • Logging. A SquiddyLogger receives the SDK's DEBUG and WARNING lines, never the API key.
  • No disk access on the calling thread. initialize reads and writes no file on the thread that calls it, on every
    platform: the SDK finds and readies its directory and reads and writes its files on its own I/O threads, and
    config is Pending until the stored configuration is read. On Android it runs under a StrictMode thread policy
    that detects disk reads and writes without a violation, also when it asks for noBackupFilesDir. No member of an
    instance waits for the disk.
  • Android artifact. An AAR that asks only for INTERNET, publishes R8 consumer rules and declares no component or
    initializer of its own (OkHttp's androidx.startup initializer stays, and the README says how to remove it).
  • JVM artifact. A JAR of Java 17 class files.
  • A Java facade, on the JVM and on Android. Java builds the options with SquiddyOptionsBuilder, every option
    included, the timeout and the refresh interval as java.time.Duration (on Android below API 26 with core library
    desugaring, as any use of java.time), and creates an instance with a static call: SquiddyJvm.initialize(options)
    or SquiddyJvm.initialize(options, storageDirectory), and SquiddyAndroid.initialize(context, options). It follows
    config, gate and strings with addConfigListener, addGateListener and addStringsListener, which call a
    SquiddyListener on a background thread of the SDK and return a SquiddyObservation to cancel(), and reads the
    retryAfter of a RateLimited with SquiddyErrors.retryAfter(error). refresh(), setLanguage(...) and close()
    are plain Java. The listeners serve Kotlin without coroutines as well.
  • iOS artifact. SquiddyCore.xcframework, a dynamic framework with a device slice and a simulator slice for both
    kinds of Mac, under the Swift module Squiddy.
  • The Swift API. import Squiddy: try Squiddy.initialize(_:) with a SquiddyOptions struct whose durations are
    seconds; config, gate and strings with value, observe(_:) (on the main thread, cancellable, a Combine
    Cancellable) and values (an AsyncStream); SquiddyError and SettingTypeException as Swift Errors, and
    the Swift enums SquiddyInitializationError and SquiddyLanguageError; setLanguage(_:), pushTopic and
    handlePush(_:). No member of the SDK's types takes or returns a Kotlin type.
  • Versions and a guarded API. The version comes from the release tag vX.Y.Z, and every other build is a
    -SNAPSHOT. The public API is dumped for the JVM, Android and iOS (Kotlin) and for SquiddyCore's Objective-C header
    (Swift), and the CI fails when the API changes without its dump. docs/COMPATIBILITY.md says
    what each version promises.
  • Closed sets. AppGate, SquiddyState, SquiddyError with its subclasses, the enums ConfigurationOrigin and
    SquiddyLogLevel, and in Swift the enums ConfigurationOrigin, SquiddyLogLevel, SquiddyInitializationError and
    SquiddyLanguageError can be matched with an exhaustive when or switch, without an else or default. From
    1.0.0 a new member of one of them comes only in a MAJOR version. Before 1.0.0 a MINOR may change them, with an entry
    here that names the member, and a PATCH never does. Golden tests, in Kotlin and in Swift, list the members and fail
    on any change of them, so none goes out unannounced.