Repository navigation
v0.1.0
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/GetRemoteConfigurationwith the
Connect protocol in binary, over Ktor (OkHttp on Android and the JVM,NSURLSessionon iOS). Its copy of
config.protois 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 atoString. Every call names
the SDK in itsUser-Agent(squiddy-kotlin/<version>), times out after 10 seconds by default and follows no
redirect. - Initialization from the app's context.
Squiddy.initializetakesSquiddyOptions(host,apiKey,appId,
appVersionasYYYY.MM.DD,appMode, and optionallycustomParams,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.configis aStateFlow<SquiddyState>:Pending, then
Readywith itsConfigurationOrigin(CACHEorNETWORK), orFailedwith the error and the last valid
configuration.RemoteConfigurationgives the version, theServerApiblock and its settings, whose
asInt(),asDouble()andasBoolean()throw aSettingTypeExceptionfor a value of another type.refresh()
asks for an update, andclose()ends the instance. - Typed errors.
SquiddyErrorhas one case per failure of the data plane:Unauthenticated,AppNotPublished,
InvalidRequest,IncompleteConfiguration,TenantSuspended,ServerError(with Squiddy'sexceptionCode),
RateLimited(withretryAfter),Network,TimeoutandMalformedResponse. - 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 innoBackupFilesDiron Android, in
Application Supporton iOS (kept out of backups), and in the app's directory of the system's data directory on
the JVM: on macOS inApplication Support, kept out of Time Machine withtmutil 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
answersnot_modifiedor leaves out what did not change; the SDK merges the partial answer into the stored one.
From a Squiddy that echoeslang_fingerprintwith unchanged languages (release20261118-39b4121and 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 everyrefreshIntervalwhile 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 anot_modifiedanswer. The
foreground comes from the activities on Android, fromUIApplication'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 honoursRetry-Afterafter a 429, and afterUnauthenticatedit stops untilrefresh(). The README counts the
installations in the foreground that a key of each plan holds. - Mandatory updates and maintenance.
Squiddy.gateis aStateFlow<AppGate>:None,UpdateRequiredor
Maintenance, with the title and message Squiddy sends in the app's language, also from the stored configuration.
The notices are readable asRemoteConfiguration.appUpdateandinfoPoint. - Localized strings.
Squiddy.string(key)andstring(key, fallback)read the configuration's strings in the
app's language, then in the default language, then the fallback;Squiddy.stringsobserves 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 ofAppGatekeep their meaning: empty when the configuration gives none. - The language follows the user and the app.
Squiddy.setLanguage(language)(in Swifttry setLanguage(_:),
which throwsSquiddyLanguageError) chooses the language of the requests, andnullfollows the user's again. The
user's language is followed while the app runs: through the app's configuration changes on Android,
NSCurrentLocaleDidChangeNotificationon 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 ofgatefollow;
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 toSquiddy.pushTopicand passes the data of the
messages it receives toSquiddy.handlePush(data)(in SwifthandlePush(_ userInfo:), in Java
getPushTopic()andhandlePush(Map)), which returnstruefor Squiddy's (squiddy=refresh) and checks the
configuration after a random wait of up topushRefreshJitter(60 seconds by default, zero allowed; in Java
SquiddyOptionsBuilder.pushRefreshJitter(Duration)), in the background too. The wait respectsRetry-After, the
backoff and the stop afterUnauthenticated, 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
SquiddyLoggerreceives the SDK'sDEBUGandWARNINGlines, never the API key. - No disk access on the calling thread.
initializereads 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
configisPendinguntil 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 fornoBackupFilesDir. 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'sandroidx.startupinitializer 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 asjava.time.Duration(on Android below API 26 with core library
desugaring, as any use ofjava.time), and creates an instance with a static call:SquiddyJvm.initialize(options)
orSquiddyJvm.initialize(options, storageDirectory), andSquiddyAndroid.initialize(context, options). It follows
config,gateandstringswithaddConfigListener,addGateListenerandaddStringsListener, which call a
SquiddyListeneron a background thread of the SDK and return aSquiddyObservationtocancel(), and reads the
retryAfterof aRateLimitedwithSquiddyErrors.retryAfter(error).refresh(),setLanguage(...)andclose()
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 moduleSquiddy. - The Swift API.
import Squiddy:try Squiddy.initialize(_:)with aSquiddyOptionsstruct whose durations are
seconds;config,gateandstringswithvalue,observe(_:)(on the main thread, cancellable, a Combine
Cancellable) andvalues(anAsyncStream);SquiddyErrorandSettingTypeExceptionas SwiftErrors, and
the Swift enumsSquiddyInitializationErrorandSquiddyLanguageError;setLanguage(_:),pushTopicand
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,SquiddyErrorwith its subclasses, the enumsConfigurationOriginand
SquiddyLogLevel, and in Swift the enumsConfigurationOrigin,SquiddyLogLevel,SquiddyInitializationErrorand
SquiddyLanguageErrorcan be matched with an exhaustivewhenorswitch, without anelseordefault. 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.