skills.rest
reliant-labs
reliant-labsOFFICIAL
Explore all skills by this author →
WebsiteGitHub

handlers

Translate proto requests to internal service calls with svcerr error wrapping.

4|1|Updated Apr 12, 2026
Search Tags:#service layer#auth middleware#error mapping#connect rpc#svcerr#handler pattern#proto translation
One-click install
npx skills add https://github.com/reliant-labs/forge --skill handlers-reliant-labs
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: handlers
Source: https://github.com/reliant-labs/forge/tree/main/internal/templates/project/skills/forge/api/handlers
Command: npx skills add https://github.com/reliant-labs/forge --skill handlers-reliant-labs

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

It prevents business logic, database work, and error-mapping duplication from creeping into Connect RPC handlers, keeping your API layer predictable and maintainable.

Core Features & Use Cases

  • Thin translation layer: validate requests, extract auth claims, convert proto ↔ internal types, call a service method, convert results back to proto, and wrap errors with svcerr.Wrap.
  • Consistent error handling: maps domain failures from the service layer to the correct Connect error codes using svcerr sentinels/constructors (no per-service error-mapping helpers).
  • Clear separation of concerns: enforces that validators stay pure, invariants live in services, and DB/orchestration/logging stay out of handlers.

Use Case: When adding a new RPC method, implement only the canonical six-step handler shape, delegate domain failures to internal/<svc>/contract.go using svcerr, and return stable wire responses without leaking internal details.

Quick Start

Implement your Connect RPC method handler in the handlers layer by following the six-step shape and delegating business logic and domain errors to the service contract, then wrap failures with svcerr.Wrap.

Frequently Asked Questions about handlers

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

FAQPage Schema
How do I keep Connect RPC handlers thin and separate proto models from business logic?▼

To keep Connect RPC handlers thin, follow a canonical six-step shape: validate requests, extract auth context, translate proto to internal input, invoke the service contract, convert results back to proto, and wrap errors using svcerr.Wrap. This strict separation ensures proto/wire models never leak into business logic.

What is the best way to map service layer domain failures to Connect RPC error codes?▼

The best way to map domain failures to Connect error codes is by using the svcerr library. Instead of writing per-service error-mapping helpers, you delegate errors from internal service contracts to svcerr sentinels and constructors, which centralizes handler-side error mapping and ensures tenant-scoped failures map to correct Connect codes consistently.

How do I structure a Connect RPC handler to prevent database access and logging from leaking into the API layer?▼

To prevent database access and logging from leaking into handlers, enforce a strict separation of concerns where validators remain pure and DB orchestration stays in internal/<svc>/contract.go. The handler acts only as a translation layer, delegating all business decisions and database work to the service contract before wrapping failures with svcerr.Wrap.

Does the Connect RPC handler pattern work for both CRUD and domain-specific service endpoints?▼

Yes, the thin Connect RPC handler pattern applies to both CRUD and domain-specific RPC endpoints. It enforces a consistent six-step translation shape that validates requests, extracts auth claims, and converts internal results back to stable wire responses without leaking internal details, regardless of the endpoint type.

Why should validators remain pure when implementing a Connect RPC service layer?▼

Validators should remain pure to maintain a strict separation of concerns within the service layer. By keeping validation separate from DB access and business decisions, the handler can safely translate proto types to internal inputs, invoke the service contract, and rely on svcerr.Wrap to map any domain failures to the correct Connect error codes.

When do I need to use svcerr.Wrap for error mapping in my Connect RPC handlers?▼

You need to use svcerr.Wrap when converting internal service results back to proto responses and handling domain failures. It wraps errors from the service contract using svcerr sentinels and constructors, ensuring that tenant-scoped failures and business logic errors map to the correct Connect error codes without duplicating error-mapping logic across handlers.

Related Skills

Explore More Software Engineering Skills→
reliant-labsreliant-labs
4

service-layer

Implement service-layer boundaries with domain-shaped interfaces and injected dependencies.

Official
Intermediate
castlemilkcastlemilk
3

api-endpoints

Define and wire Connect-RPC API endpoints in the Shorts backend.

Community
Advanced
reliant-labsreliant-labs
4

auth

Generate JWT and API key authentication middleware with RBAC and tenant scoping.

Official
Advanced
anicdhanicdh

go-handlers

Creates Go HTTP handlers with thin-controller architecture and Chi routing.

Community
Advanced