Development

Development

JDK 21; the Gradle wrapper is included. No lint step is wired in — keep to the style of the surrounding code.

Building and testing

./gradlew build                                   # compile + full test suite
./gradlew jvmTest                                 # JVM unit + live integration (needs .env)
./gradlew jvmTest --tests '*CaptchaRetry*'        # one test class
./gradlew compileCommonMainKotlinMetadata         # catches JVM-only calls in commonMain, on any host
./gradlew iosSimulatorArm64Test                   # native runtime; macOS only
./gradlew assemble -Pkotlin.native.ignoreDisabledTargets=true   # every target this host can build

A green jvmTest says nothing about Native: the JVM run never compiles the native test binaries. Off macOS, check jvmTest plus compileCommonMainKotlinMetadata, and keep commonTest inside the Native rules: no JVM-only APIs (synchronized, java.util.concurrent, Thread), no , in backtick test names, and test functions that return Unit (runBlocking<Unit> { }). 0.9.0 failed its release twice on exactly these.

Live tests

Integration tests read credentials from a git-ignored .env and skip themselves without them:

PIKPAK_USERNAME=you@example.com
PIKPAK_PASSWORD=your-password

They create folders named pikpak-kotlin-* and delete them permanently when done. Listings trail mutations, so they poll the listing rather than assert on it at once (Measurements).

Opt-in measurements, each asserting nothing about speed:

Test	Switch	Measures
RangeReaderSmokeTest	always (live)	The playback path end to end: magnet, task, range reads, fan-out
WeakLinkSmokeTest	PIKPAK_WEAKLINK=1	One connection against eight, alternating; cold open and seek. Run it throttled
CdnNetworkProbeTest	PIKPAK_PROBE=1	HTTP version, per-connection rate, concurrency cap, idle survival
MultiFileConcurrencyProbeTest	PIKPAK_MULTIFILE_PROBE=1	The account-wide connection limit across files
HostAssignmentProbeTest	PIKPAK_HOST_PROBE=1	Which edge hosts links land on, and their latency
LeaseRebuildProbeTest	PIKPAK_LEASE_PROBE=1	Whether a gcid can be instant-created again after its only object was deleted and PIKPAK_LEASE_PROBE_WAIT_MIN minutes passed (70 by default); what every rebuild of a leased handle depends on
MirrorProbeTest	PIKPAK_MIRROR_PROBE=1	Swapping a link's host, per-host speed, the API address list, the four root domains, probeDomain, steering end to end. Local only: it runs on the session in ~/.piko and reads without writing; PIKPAK_MIRROR_PROBE_PHASES picks from hosts,api,roots,probe,steer,domain (domain exchanges the refresh token)

Behind a fake-ip TUN proxy every connection is re-dialled by its SNI, so an address the test pins is silently replaced. PIKPAK_PROBE_BIND=<address of the physical interface> makes MirrorProbeTest bind its sockets to that interface and resolve over DNS-over-HTTPS, which is the only way to see the direct route from such a machine.

Gradle skips a test whose inputs did not change even when the environment did; add --rerun when only variables moved. Tests must not hard-code a magnet of a copyrighted work: TestFixtures.ARCH_ISO_MAGNET is the shared input.

Releasing

A vX.Y.Z tag triggers release.yml: every shipped target's cell must pass before anything is published to Maven Central. Step by step, including the one-time signing setup, in RELEASING.md.

Every release updates this wiki. Before tagging:

1. Read the diff since the last tag for anything a page describes: public API, defaults, behaviour, measurements.
2. Update those pages, and the version on Home and Getting Started.
3. A new measurement goes into Measurements with its date; one that contradicts an old Fact replaces it and says so.
4. Removed or reshaped API goes into History with the reason.
5. Push the wiki before the tag, so the release never points at pages describing the previous version.

This wiki

The wiki is a git repository of its own: git clone git@github.com:NihilDigit/pikpak-kotlin.wiki.git. Page names are file names with - for spaces; _Sidebar.md is the navigation. Write for someone about to change the code: the mechanism and the measurement, not only the conclusion.