For agents: start with the agent guide. Every page is Markdown by default; add Accept: text/html for HTML.

HTTP success needs a status check and a decoder

Schema defines accepted values and checks data at runtime. An adapter implements an application interface for a provider.¶

A fulfilled HTTP request is not proof of application success. Check the status and decode the body before passing provider data into the application. Use the effect/http modules.¶

Check the protocol response

The deployment checker decodes tool discovery through ToolsResponse. It also requires status 200 and the expected tool names.¶

          const document =
            yield* HttpClientResponse.schemaBodyJson(ToolsResponse)(response);

          return (
            response.status === 200 &&
            ["search", "read", "execute"].every((name) =>
              document.result.tools.some((tool) => tool.name === name)
            )
          );
        })

Use the in-memory fixture below when learning.¶

Reject an unacceptable response before trusting its data

HttpClient.filterStatusOk accepts 2xx status codes. An adapter can require a narrower status when its protocol needs one. The fixture applies the filter before decoding a version response.¶

    const client = (yield* HttpClient.HttpClient).pipe(
      HttpClient.filterStatusOk
    );

    const response = yield* client
      .get("https://provider.example.test/version")
      .pipe(
        Effect.mapError(
          (cause) => new ResponseFixtureError({ cause, phase: "status" })
        )
      );

    return yield* HttpClientResponse.schemaBodyJson(Reply)(response).pipe(
      Effect.mapError(
        (cause) => new ResponseFixtureError({ cause, phase: "body" })
      )
    );
  }

schemaBodyJson handles JSON parsing and schema decoding²⁵. ResponseFixtureError retains the cause and names the failed phase.¶

The fixture groups request and status failures into its status phase. It groups parsing and schema failures into its body phase. A production adapter should choose failure names that match its job and repair path.¶

Supply the transport in tests

The test supplies a client that creates responses in memory. It does not start an HTTP server or call a provider.¶

      Effect.sync(() =>
        HttpClientResponse.fromWeb(
          request,
          new Response(scenario.body, {
            headers: { "content-type": "application/json" },
            status: scenario.status,
          })
        )
      )
    );

    const result = yield* readValidatedResponse().pipe(
      Effect.provideService(HttpClient.HttpClient, client),
      Effect.result
    );

• 200, integer version: Decoded version¶
• 503, otherwise valid body: Named status-phase failure¶
• 200, malformed JSON: Named body-phase failure¶
• 200, string instead of integer: Named body-phase failure¶

These tests of the HTTP client interface establish the fixture’s status and decoding policy. Check live endpoint health separately.¶

Decide whether replay is safe before adding retries

A transient failure may be temporary. retryTransient can retry transient responses and errors. Its classification does not prove that repeating an operation is safe. A write can complete remotely even when its response is lost.¶

Before retrying a write:¶

1. Identify the operation’s replay or idempotency¹⁴ guarantee: whether repeating it can create a second change.¶
2. Decide which failures allow another attempt.¶
3. Measure the retry budget¹⁰, the allowed attempts or time, and select the schedule.¶
4. Preserve the final named failure when the budget ends.¶

Do not copy example delays or retry counts into production as measured limits. The fixture establishes no production retry budget¹⁰.¶

Common mistakes

• Treat fulfilled fetch as success despite a failed status.¶
• Trust an object because JSON parsing succeeded.¶
• Replace the whole adapter in a test and stop exercising its decoder.¶
• Retry a write only because the transport calls its error transient.¶

Effect idiom and house rule

• Supply HttpClient, compose request policies, decode responses, and translate failures at the adapter’s interface with the provider.¶
• In rat-stack, core owns service interfaces named for application jobs. Provider clients remain in adapters under hexagonal architecture²⁷.¶
• In rat-stack, machines own finite retry lifecycles²⁶. Effect also has native schedules and retry operators.¶

Read schemas²⁵ and failures³⁹ before defining the adapter’s accepted data. Then read tracing⁷ to observe the operation without exposing private values. Return to the Effect reading order²⁹.¶

Last changed 2026-10-24 in abefe39. Source on GitHub. Change log.

Content updated 2026-10-06.