Fetch assets for multiple identities in one pipelined batch - #59

Closes #58.

Adds POST /assets, which returns the owned and possessed assets of several identities in one call, using the request pipelining added in go-node-connector v2.3.0.

Callers that needed assets for many identities previously had to fan out N*2 requests, one per identity per asset kind, which saturated the connection pool. PrefetchOwnedAndPossessedAssets writes all 2N requests back to back on a single connection and demultiplexes the responses by DejaVu nonce, so a batch costs roughly one round trip for the whole set.

API

curl -X POST localhost:8000/assets \
  -H 'Content-Type: application/json' \
  -d '{"identities":["IGJQ...MKBC","AFZP...PCVJ"]}'

Returns {identity, ownedAssets[], possessedAssets[]} per identity, in request order. Every requested identity appears in the response, with empty lists if it holds nothing.

A few decisions worth flagging for review:

• One combined RPC rather than separate owned/possessed batch endpoints. The connector always fetches both in a single batch, so splitting them would make the node do both halves of the work and discard one.
• POST rather than GET. An identity is 60 characters, so a batch of any useful size would push a GET URL past common proxy limits. Follows the existing body: "*" precedent from BroadcastTransaction and QuerySmartContract.
• Response reuses the existing OwnedAsset / PossessedAsset messages, so a client that already parses /assets/{identity}/owned needs no new parsing code.

Validation

All validation runs before a pooled connection is taken, so malformed input never costs one. Empty lists, batches over the limit, malformed identities and duplicates are rejected with INVALID_ARGUMENT. The limit defaults to 15 and is configurable via QUBIC_API_SIDECAR_SERVER_MAX_BATCH_IDENTITIES.

A failed batch leaves the connection byte-unaligned, so the handler closes it rather than returning it to the pool. There is a test pinning that specifically, since putting a dead connection back would poison the pool for later requests.

⚠️ Behavior change to an existing endpoint

The nested owned_asset of /assets/{identity}/possessed was built from the possession record's own fields rather than the ownership record it wraps. Only ownerIdentity was correct. It reported:

These are two independently unmarshalled structs with identical field names, which is how they got mixed up. That the issuanceIndex slot is really an ownership index is visible in the connector's parallel struct, which names it OwnershipIndex.

Extracting the duplicated conversion into shared converters fixes this by construction, since the converter reads only the ownership record it is handed. TestAssetConverter_convertPossessedAsset gives the possession and its nested ownership record deliberately different values so this cannot silently regress — I verified it fails against the old behavior. README samples updated to match; the other nested sample values are unchanged real-node output I could not re-verify, so a second look from someone with a node handy is welcome.

/assets/{identity}/owned and /assets/{identity}/issued output is unchanged.

Testability

The issue asks for unit-testable code. Server.qPool was the concrete *qubic.Pool, whose Get returns a client holding a real socket, so no handler could be tested. Handlers now reach the pool through a nodePool / nodeClient seam.

The seam covers every client method the handlers already use, which is why no existing handler body changed — only the field type and one function parameter. var _ nodeClient = (*qubic.Client)(nil) keeps the interface honest as the client evolves.

Tests

20 new cases, none requiring a live node:

• Converters: owned, possessed (the regression test above), issued, order preservation, non-nil empty slices, and the batch mapping.
• Handler: happy path, identity holding no assets, all four rejection paths, pool-get failure, and prefetch failure closing rather than returning the connection.

Verification

go build, go vet and go test ./... -race all pass, and each of the three commits builds and tests green on its own. I also ran the service and exercised the real HTTP route: all four validation errors return before touching the pool, a valid request reaches the node layer, and the existing /assets/... routes are not shadowed by the new POST /assets.

Incidental

protobuff/Makefile did not pass the protobuf include path to its openapi-v3 target, only to the Go codegen target, so on macOS make all always failed to find the well-known types and never regenerated the OpenAPI document. One-line fix, included so ./make.sh works.

Note this touches protobuff/*.proto, so merging will dispatch doc rebuilds to qubic/integration and qubic/docs.

🤖 Generated with Claude Code