qbit-record-files/docs/HTTP-CONSUMER-FIXTURE.md

Native HTTP consumer fixture (test classifier only)

com.kingsrook.qbits.recordfiles.ingestion.RecordFilesHttpConsumerFixture is an opt-in, dedicated-JVM launcher. It reuses RecordFilesFixture, the native QQQ server, installed metadata/processes, standard attachment owner, and Record Files HTTP specs. It is not application authentication or an independently deployable server.

Build and launch

Use the repository wrapper and the locally installed matching collaboration/core artifacts. From this repository, prepare the ordinary test classpath:

.\mvnw.cmd '-Drevision=0.1.0-record-files-SNAPSHOT' test-compile dependency:build-classpath '-Dmdep.includeScope=test' '-Dmdep.outputFile=target/consumer-fixture-classpath.txt'
$fixtureDependencies = (Get-Content -Raw target/consumer-fixture-classpath.txt).Trim()
$fixtureClassPath = "target/test-classes;target/classes;$fixtureDependencies"
$fixturePrivateOutput = Join-Path $env:LOCALAPPDATA 'record-files-consumer-credentials.json'
java -cp $fixtureClassPath com.kingsrook.qbits.recordfiles.ingestion.RecordFilesHttpConsumerFixture $fixturePrivateOutput 900 0

The output file must not already exist and its parent must exist. Use a new private local path for each run. The launcher creates it with owner-only POSIX permissions or an initial Windows ACL, verifies the ACL before writing, and refuses unsupported or non-private permission providers. Do not print or paste the file, include it in logs, commit it, or place it in a shared/synchronized directory. It contains test credentials.

Port 0 requests an OS-selected port; an explicit unused port is also accepted. The server binds 127.0.0.1 only. Lifetime is 1–3600 seconds. Expiry, Ctrl+C and normal shutdown stop this owned server and revoke its token map. No persistent server is started by compilation or installation. The launcher disables logging in its dedicated JVM because framework session diagnostics must not disclose test credential values.

Consumers of the Maven tests classifier also need the matching main JAR and test runtime dependencies (including JUnit, AssertJ and H2). The classpath above is the reproducible checkout route; the test JAR is not a standalone executable/fat JAR.

Identity and routes

The private JSON contains baseUrl (including /qqq/v1), expiry, session-cookie name, three actor credentials, source IDs, and three seeded retained-file IDs. Send the selected exact token as the sessionUUID cookie. Tokens are fresh random 256-bit values mapped to fixed principals; arbitrary strings, actor-name prefixes, conflicting credentials, expired tokens and automated session restoration are rejected.

Synthetic principal	Tenant	Authority
fixture-alice	a	Source read/write; Record Files manage/review/release/configure/audit
fixture-reader	a	Source and Record Files read only
fixture-bob	b	Same management permissions as Alice, different tenant

document records 1 and 2 belong to tenant a; record 3 belongs to tenant b. Alice's seeded receiving note is released, another note remains quarantined, and Bob has a separate released note. Lifecycle restrictions remain active.

Use the ordinary native metadata, table, and process routes in the application's OpenAPI contract. Record Files discovery begins with:

GET {baseUrl}/qbit/record-files/capabilities?tableName=document&recordId=1

Alice receives upload capability, the reader does not, and Bob cannot discover Alice's source. Upload/session/chunk/finalize routes are the actual registered ingestion API; see docs/INGESTION-CONTRACT.md and its generated OpenAPI schema for exact manifests. Mutations require X-Record-Files-Request: 1, the appropriate content type and current authority. Browser requests must satisfy the endpoint's same-origin rules. The fixture does not weaken CORS or origin policy for a separately hosted frontend.

Desktop capture deliberately provides no verified mobile device identity. Device attribution requiring verification is rejected. Do not use this fixture as evidence of mobile login, enrollment, scanner identity, printer authority or principal restoration.

Persistence and limits

Metadata, reservation and audit writes use the existing file-backed H2 fixture and real TableAuditPort. Staged and canonical bytes use existing synthetic storage adapters in this JVM. They disappear at shutdown, while test database files may remain under target/test-databases. This launcher does not reopen a previous fixture and makes no provider retention, WORM, crash recovery or deployment qualification claim.

Upload limits are 20 MiB per item, 40 MiB per batch, 20 items, and 64 KiB chunks. The fixture quota permits 20 active sessions, 80 MiB staging and 100 creations per quota window. MIME types: PDF, JPEG, PNG, plain text and ZPL. These are bounded synthetic testing defaults, not inferred production workload requirements.

Tracked HTTP download is currently disabled (trackedDownloadEnabled: false). Legacy synthetic storage presigns point to a non-serving example host; never treat those URLs as successful served downloads. The tracked-download owner is being verified separately before an opt-in launcher integration is added.

Verification status

ConsumerFixtureTest exercises exact-token rejection, read-only/tenant distinction, expiry, private create-only credential output, and a bounded real native HTTP server with close verification. All four passed in coordinated root run74033, as recorded below. No long-running fixture has been started as part of authoring this launcher.

Coordinated verification: root focused run74033 passed18 tests, including all four ConsumerFixtureTest cases. This confirms actual native HTTP discovery with exact synthetic token/tenant/read-only authority, owned server close, and private create-only credential output on this Windows filesystem. It does not qualify a production identity provider or external object store. No long-running consumer fixture has been launched; the only server run was the bounded automated test.

The complete Record Files snapshot was subsequently verified and installed by root: 155 tests passed, including ConsumerFixtureTest4, at23:34:41. The launcher is included in that test-classifier build. Its tracked-download flag remains disabled until an explicit optional launcher configuration is added and verified; production tracked download service verification is separate from this test launcher.