implement-handler

Implements thin Connect-RPC handlers in Go mapping protobuf requests to usecase inputs.

Updated Sep 14, 2026
One-click install
npx skills add https://github.com/nakamori-naoya/go-convention-plugins --skill implement-handler-nakamori-naoya
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: implement-handler
Source: https://github.com/nakamori-naoya/go-convention-plugins/tree/main/plugins/go-convention/skills/implement-handler
Command: npx skills add https://github.com/nakamori-naoya/go-convention-plugins --skill implement-handler-nakamori-naoya

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Implementing RPC handlers in Go often leads to bloated server code that mixes business logic, error translation, logging, and dependency wiring into one place. This Skill enforces a strict convention for writing thin Connect-RPC handlers where each RPC maps to exactly one usecase, conversions are pure functions, and cross-cutting concerns live in interceptors. ## Core Features & Use Cases - Thin server implementation: Each RPC method follows a fixed four-line shape (caller, convert, Execute, respond) with no branching, logging, or error translation inside the handler. - Pure conversion functions: Request-to-input and output-to-response mapping functions named {source}To{target} that reject missing required fields with public sentinels instead of defaulting nil timestamps to 1970. - Interceptor-based cross-cutting concerns: A Logging interceptor that recovers panics, logs once per RPC, and translates errors to connect.Code via a single translation table, plus an Auth interceptor that places the caller identity into request scope. - Composition root wiring: A NewMux(Deps) function assembling tx, repositories, usecases, server, and interceptors inside-out, with main calling run(ctx) error for graceful shutdown. - Use Case: Given a proto file defining a ReservationService and existing usecases, generate the server struct, mapping functions, error table entries, and wiring so the RPC compiles and passes pre-written red tests. ## Quick Start Implement the ConfirmReservation RPC handler from this proto file, connecting it to the existing usecase with conversion functions and interceptor wiring.

Frequently Asked Questions about implement-handler

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I implement a Connect-RPC handler in Go?▼

Create a server struct satisfying the generated ServiceHandler interface, with each method following four steps: read the caller from context, convert the request to usecase input, call Execute, and convert the output to a response. Keep all error translation and logging in interceptors, not the server.

How to map protobuf requests to usecase inputs in Go?▼

Write pure functions named like confirmRequestToInput in the handler package that take only proto types, usecase types, and time.Time. Validate required Timestamps with IsValid to avoid nil becoming 1970, and pass operation time as an argument from the server Clock rather than calling time.Now.

Does connectrpc.com/connect v2 work with this handler pattern?▼

This convention pins connectrpc.com/connect v1.21.0 and explicitly does not adopt v2 because it is alpha. The server implementation, interceptors, and wiring examples all target the v1 API surface.

Where should error translation to connect.Code happen?▼

Error translation belongs in a single codeTable inside the Logging interceptor, which maps sentinels to codes via errors.Is and returns Internal with a fixed message for unlisted errors. Server methods must never call connect.NewError or branch on errors.Is.

Why should handlers not call repositories or transactions directly?▼

Handlers are a thin boundary layer; transactions and persistence belong to the usecase, which owns the tx.Manager and repository ports. Calling them from a handler duplicates orchestration logic and breaks the one-RPC-to-one-usecase rule.

When should I stop instead of implementing an RPC handler?▼

Stop when no usecase exists for the RPC, when one RPC needs multiple usecases, when asked to fill missing inputs with defaults, or when the authentication method is undecided. Propose the missing usecase or decision rather than embedding business logic in the handler.