Skip to main content
You will add 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

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 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
The activity block records each call in the activity stream; the lint step shows why it is required.
2

Scaffold the handler

terminal
Output (trimmed)
It ran 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
It also wrote 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
Without the activity block from the first step, lint fails the RPC:
A name that starts with a read verb (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:
To re-check only this rule while you iterate, run 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
The key is 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_required only decides whether the caller is signed in. To limit who may archive a product, read middleware.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 generate never rewrites them.

Troubleshooting

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.
The call carried no session. Sign in through /auth/login first and send the cookie, or set auth_required: false on the RPC if it is meant to be public.

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