ArchiveProduct to the catalog service: an RPC that takes a product off sale without deleting it. Forge writes the handler stub, a test table and a typed React hook from the proto declaration. You write the body.
Anything that is not plain create, read, update or delete is a custom RPC, and its logic is yours. Adding a feature summarizes the rules; this guide runs them end to end.
Before you begin
- The
shopproject from Build a Go and React app with Connect RPC, with itsProductentity. Add a database table is optional. - Forge v1.6 or later. Inside Reliant, run it as
reliant forge, and check the version withreliant forge --versioninside the project. - No account. Every step runs locally.
1
Declare the RPC in the proto
Add the RPC to the service block and its two messages to the file. An RPC named exactly The
Create<E>, Get<E>, Update<E>, Delete<E> or List<Es> would be wired as CRUD, so a verb like Archive makes it custom. Forge never invents an RPC: if the service block does not name it, it does not exist.proto/services/catalog/v1/catalog.proto
activity block records each call in the activity stream; the lint step shows why it is required.2
Scaffold the handler
terminal
Output (trimmed)
generate for you, in about 9 seconds here. The stub sits in a file of its own, so two people implementing two RPCs never edit the same file:internal/handlers/catalog/rpc_archive_product.go
handlers_scaffold_archive_product_test.go. Its single row passes only while the stub is in place, so it fails as soon as you implement the RPC.3
Write the handler
Replace the stub. The handler validates, does the work through
s.deps, and returns every error through svcerr.Wrap:internal/handlers/catalog/rpc_archive_product.go
svcerr.Wrap keeps the code and message of an error you created (invalid_argument, not_found). Any other error, such as a raw database error, reaches the client as internal server error, and the original is logged with the request ID, so you never write a connect.Code switch. db.UpdateProductMasked and productToProto are generated; hand-written queries go in internal/db/product_repo_ext.go.4
Replace the scaffold test row
Swap the stub row for real cases. The test harness starts a real Postgres for you:
internal/handlers/catalog/handlers_scaffold_archive_product_test.go
terminal
5
Regenerate and run the gate
terminal
activity block from the first step, lint fails the RPC:Get, List, Search, …) or option idempotency_level = NO_SIDE_EFFECTS; marks a read instead. To opt a mutation out, write activity: { none: "<why>" }. The rule’s reference has the details. With the block in place:reliant forge lint --conventions, which takes under a second. The full run took 80 seconds here.6
Call it from React
generate added a mutation hook to the service’s hooks file:terminal
frontends/web/src/hooks/catalog-service-hooks_gen.ts
catalogServiceKeys.all: a custom mutation’s hook invalidates every query on its service, so a list rendered with useListProducts refetches after an archive. While the handler was a stub, catalogServiceImplemented.archiveProduct was false; the generate after you implemented it set it to true. Call it like any React Query mutation: const archive = useArchiveProduct(); archive.mutate({ id }).7
Verify it against the running API
Start the stack with
reliant forge env up dev, sign in as the development user from idp-steps.yaml, and call the RPC over plain HTTP with the session cookie:terminal
active is missing from the JSON because it is now false, the default. An unknown ID answers {"code":"not_found","message":"product not found"}, and an empty one answers {"code":"invalid_argument","message":"id is required"}. The API log at .forge/logs/dev/api.log has an activity.event line with "verb":"archive". Stop the stack with reliant forge env down dev.What this does not do
- No access control.
auth_requiredonly decides whether the caller is signed in. To limit who may archive a product, readmiddleware.GetUser(ctx)in the handler and check it there. - No business logic. Forge writes the stub, the test table and the hook. The handler body and its tests are yours, and
generatenever rewrites them.
Troubleshooting
forgeconv-activity-declared: ... mutates ... but declares no activity event
forgeconv-activity-declared: ... mutates ... but declares no activity event
Add an
activity block to the RPC’s forge.v1.method option, or activity: { none: "<why>" }, then run reliant forge generate before lint. Lint reads the result that generate records.Next steps
Add a worker or cron job
Run work on a schedule in the same server process
Add a table
Generate the CRUD API and pages for a new entity
How forge generate works
What each generate step writes, and why a re-run is cheap
Adding a feature
The everyday loop: services, RPCs, migrations, the gate