add-web

name: add-web description: TRIGGER when user asks to add or modify a web handler, HTML page, file download, or raw HTTP endpoint that works with http.ResponseWriter/http.Request.

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: A web endpoint is declared as a define.Web var in <name>api/definition.go and implemented as a handler in service.go. Add the declaration and run cmd/genservice.

CRITICAL: Keep the // MARKER: Name comment on the define.Web var.

Workflow

Copy this checklist and track your progress:

Creating or modifying a web endpoint:
- [ ] Step 1: Read local CLAUDE.md file
- [ ] Step 2: Determine the method and route
- [ ] Step 3: Determine a description
- [ ] Step 4: Determine the required claims
- [ ] Step 5: Declare the endpoint in definition.go
- [ ] Step 6: Implement the logic in service.go
- [ ] Step 7: Generate the boilerplate
- [ ] Step 8: Test the handler
- [ ] Step 9: 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 Method and Route

The method of the endpoint determines the HTTP method with which it will be addressable. Use ANY to accept requests with any method.

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-web.

To set a port other than the default 443, prefix the route with the port, e.g. :123/my-web.

Encase path arguments with {} , e.g. /section/{section}/page/{page...}.

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

Step 3: Determine a Description

Describe the endpoint starting with its name, in Go doc style: MyWeb does X. This becomes the godoc comment on the define.Web var.

Describe what the endpoint does and the effect it produces, not who is expected to call it. "Renders a printable summary of the order" is good; "page used by the checkout flow" is not.

Step 4: Determine the Required Claims

Determine if the endpoint should be restricted to authorized actors only. Compose a boolean expression over the JWT claims associated with the request that if not met will cause the request to be denied. For example: roles.manager && level>2. Default to closed: in a standard ingress configuration an empty requiredClaims on a :443 endpoint (or any port the operator added to AllowedInternalPorts) is reachable by the entire internet. Leave it empty only for an intentionally public endpoint; if the endpoint wields a stored secret or a privileged side effect, it must be gated by requiredClaims and/or an internal port. See the Ports and Authentication sections of .claude/rules/microbus.md.

Step 5: Declare the Endpoint in definition.go

Append the define.Web var to myserviceapi/definition.go. A web endpoint has no In/Out structs.

// MyWeb does X.
var MyWeb = define.Web{ // MARKER: MyWeb
    Host: Hostname, Method: "ANY", Route: "/my-web",
}

• Host is always Hostname. Method and Route come from Step 2
• Add the gating and routing fields only when needed:
  • RequiredClaims: "roles.manager && level>2" for the claims from Step 4 (omit when public)
  • TimeBudget: 30 * time.Second to cap the handler's duration (omit for the default; add the "time" import if used)
  • LoadBalancing: define.None to multicast to all replicas, or LoadBalancing: "my-queue" for a named queue; omit for the default hostname queue

Step 6: Implement the Logic in service.go

Implement the web handler in service.go. Use r.PathValue("argName") to obtain path argument values by name, if needed.

// MyWeb does X.
func (svc *Service) MyWeb(w http.ResponseWriter, r *http.Request) (err error) { // MARKER: MyWeb
    // Implement logic here...
    return nil
}

Step 7: Generate the Boilerplate

From the microservice's directory, run the generator. It regenerates myserviceapi/client.go, intermediate.go, mock.go, mock_test.go, and manifest.yaml from the updated definition.go.

go run github.com/microbus-io/fabric/cmd/genservice .

The generated client method's arity depends on the method, which matters when writing the test in Step 8:

• A body method (POST, PUT, PATCH): MyWeb(ctx, relativeURL string, body any)
• A non-body method (GET, HEAD, DELETE, CONNECT, OPTIONS, TRACE): MyWeb(ctx, relativeURL string)
• ANY: MyWeb(ctx, method string, relativeURL string, body any)

Then verify the microservice compiles with go vet ./... from the project root.

Step 8: Test the Handler

Append the integration test to service_test.go. Match the client.MyWeb(...) call to the method's arity from Step 7 (the example below is for an ANY endpoint).

func TestMyService_MyWeb(t *testing.T) { // MARKER: MyWeb
    t.Parallel()
    ctx := t.Context()
    _ = ctx

    // Initialize the microservice under test
    svc := NewService()

    // Initialize the tester client
    tester := connector.New("tester.client")
    client := myserviceapi.NewClient(tester)
    _ = client

    // Run the testing app
    app := application.New()
    app.Add(
        // HINT: Add microservices or mocks required for this test
        svc,
        tester,
    )
    app.RunInTest(t)

    /*
        HINT: Use the following pattern for each test case

        t.Run("test_case_name", func(t *testing.T) {
            assert := testarossa.For(t)

            actor := jwt.MapClaims{}
            res, err := client.WithOptions(pub.Actor(actor)).MyWeb(ctx, "GET", "", payload)
            if assert.NoError(err) && assert.Expect(res.StatusCode, http.StatusOK) {
                body, err := io.ReadAll(res.Body)
                if assert.NoError(err) {
                    assert.HTMLMatch(body, "DIV.class > DIV#id", "substring")
                    assert.Contains(body, "substring")
                }
            }
        })
    */
}

Skip the remainder of this step if instructed to be "quick" or to skip tests.

Insert test cases at the bottom of the integration test function using the recommended pattern.

• You may omit the pub.Actor option if the endpoint does not require claims.
• Do not remove the HINT comments.

t.Run("test_case_name", func(t *testing.T) {
    assert := testarossa.For(t)

    actor := jwt.MapClaims{}
    res, err := client.WithOptions(pub.Actor(actor)).MyWeb(ctx, "GET", "", payload)
    if assert.NoError(err) && assert.Expect(res.StatusCode, http.StatusOK) {
        body, err := io.ReadAll(res.Body)
        if assert.NoError(err) {
            assert.HTMLMatch(body, "DIV.class > DIV#id", "substring")
            assert.Contains(body, "substring")
        }
    }
})

Step 9: Housekeeping

Follow the housekeeping skill.