feat: add upload service client

[alanshaw]

Adds an upload service client that allows the 2 UCAN RPC invocations to be made.

1. /customer/add - registers a customer account to the upload service. This is necessary for provisioning a space (which allows it to be used). The idea is that Hilt will be configured with a UCAN delegation allowing it to add customers. This can be manual initially. The fil.one app will be managing customer (tenant) logins and billing, but the upload service is also capable of this and needs a customer to be registered before uploads are allowed to a space. This simply allows Hilt to inject a customer from fil.one into the upload service.
2. /provider/add - provision a space. This is the process of creating a "subscription", which associates the space with a customer account. A space must be provisioned before blobs can be uploaded to it.

Depends on:

• feat: customer add command libforge#40
• feat: implement customer add handler sprue#25

[Copilot]

Pull request overview

Adds a new Go client for interacting with the upload service via UCAN RPC invocations, along with structured logging helpers to make invocation arguments/metadata easier to inspect in logs.

Changes:

• Introduce pkg/client.UploadClient with RegisterCustomer (/customer/add) and ProvisionSpace (/provider/add) operations.
• Add pkg/lib/zapucan helpers for logging UCAN invocations and decoding CBOR-encoded IPLD maps into zap fields.
• Bump github.com/fil-forge/libforge dependency version.

Reviewed changes

Copilot reviewed 6 out of 7 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
pkg/lib/zapucan/raw_map.go	Adds RawMap zap object marshaler to decode CBOR IPLD maps for logging.
pkg/lib/zapucan/raw_map_test.go	Adds coverage to ensure RawMap can be logged for valid/empty/invalid inputs.
pkg/lib/zapucan/invocation.go	Adds WithInvocation helper to attach invocation fields to a logger.
pkg/client/upload.go	Implements the upload service client with customer registration and space provisioning calls.
pkg/client/upload_test.go	Adds in-process server tests validating requests/receipts for the new client methods.
go.mod	Updates libforge version required by the module.
go.sum	Adds checksums for the updated libforge version.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[lanzafame]

@alanshaw Am I correct in believing a Space is equivalent to a Bucket?

[alanshaw]

Correct 👍

[bajtos]

Whoa, that's a lot to unpack here!

/customer/add - registers a customer account to the upload service. This is necessary for provisioning a space (which allows it to be used). The idea is that Hilt will be configured with a UCAN delegation allowing it to add customers.

Interesting. My impression from the discussions was that Forge will not deal with user accounts, only with spaces & buckets.

This can be manual initially.

"this" means "configuring Hilt with a UCAN delegation" or "provisioning a space"? I agree that the process for configuring Hilt can be manual. I don't think it's a good idea to have a manual process for provisioning a space, because that will prevent us from integrating Forge into FilOne Console, where bucket creation if fully automated & API-driven.

The fil.one app will be managing customer (tenant) logins and billing, but the upload service is also capable of this and needs a customer to be registered before uploads are allowed to a space. This simply allows Hilt to inject a customer from fil.one into the upload service.

I would like to better understand why the upload service needs to understand FilOne customers. The RFC does not mention any customers or subscriptions.

Have you considered removing customer-management-related code from the upload service instead?

/provider/add - provision a space. This is the process of creating a "subscription", which associates the space with a customer account. A space must be provisioned before blobs can be uploaded to it.

I find it confusing that "provider add" is provisioning a space. I think /space/provision or perhaps /subscription/add would be more fitting names.

Maybe it's just my lack of understanding of Sprue's API. Where can I find documentation for the command /provider/add? (I found the source code but there is no documentation there.)