Add Outbound Event

CRITICAL: Do NOT explore or analyze other microservices unless explicitly instructed to do so. The instructions in this skill are self-contained to this microservice.

CRITICAL: An outbound event is declared as a define.OutboundEvent var in myserviceapi/definition.go. Add the declaration and run cmd/genservice. An outbound event has no handler in service.go - this microservice fires it; other microservices sink it.

CRITICAL: Keep the // MARKER: OnMyEvent comment on the define.OutboundEvent var and on its In/Out structs.

IMPORTANT: Outbound events are not exposed via OpenAPI. The connector's built-in :888/openapi.json handler filters them out automatically.

Workflow

Copy this checklist and track your progress:

Creating or modifying an outbound event:
- [ ] Step 1: Read local CLAUDE.md file
- [ ] Step 2: Determine the signature
- [ ] Step 3: Determine the method and route
- [ ] Step 4: Determine a description
- [ ] Step 5: Define complex types
- [ ] Step 6: Declare the event in definition.go
- [ ] Step 7: Generate the boilerplate
- [ ] Step 8: Trigger the event
- [ ] Step 9: Test the outgoing event
- [ ] Step 10: Housekeeping

Step 1: Read Local CLAUDE.md File

Read the local CLAUDE.md file in the microservice's directory. It contains microservice-specific instructions that should take precedence over global instructions.

Step 2: Determine the Signature

Determine the Go signature of the outgoing event.

func OnMyEvent(ctx context.Context, input1 string, input2 ThirdPartyStruct) (output1 map[string]MyStruct, err error)

Constraints:

• The first input argument must be ctx context.Context
• The function must return an err error
• Maps must be keyed by string, e.g. map[string]any
• Complex types (structs) are allowed by value or by reference, e.g. MyStruct or *MyStruct
• All input or output arguments must be serializable into JSON, including complex types
• Arguments must not be named t or svc
• Argument names must start with a lowercase letter
• The event name must start with On followed by an uppercase letter

Step 3: Determine the Method and Route

The method of the endpoint determines the HTTP method with which it will be addressable. The most common approach is to use POST.

The route of the endpoint is resolved relative to the hostname of the microservice to determine how it is addressed. The common approach is to use the name of the endpoint in kebab-case as its route, e.g. /my-event.

Events should be set on a dedicated port to allow blocking external requests from reaching them. The recommended port to use for events is 417. Prefix the route with the port, e.g. :417/on-my-event.

Do not use path arguments in events.

Prefix the route with // to set a hostname other than that of this microservice, e.g. //another.host.name:417/on-something

Step 4: Determine a Description

Describe the event starting with its name, in Go doc style: OnMyEvent is triggered when X. This becomes the godoc comment on the define.OutboundEvent var.

Step 5: Define Complex Types

Identify the struct types in the signature and define each in the myserviceapi directory following the add-type skill: one file per type, camelCase json tags with omitzero, jsonschema_description tags, optional dv8 validation tags, and an optional pure Validate method for cross-field invariants. A type owned by another microservice is aliased rather than redefined. Skip this step if there are no complex types.

Note that dv8 tags on an event's In struct are enforced at every sink when the event is received: the source authors the payload contract and its validation together.