ZIO HTTP

ZIO HTTP supports securing communication between clients and servers using SSL/TLS protocols. This is achieved through a Public Key Infrastructure (PKI), which uses digital certificates to verify identities and establish encrypted connections.

Key concepts:

• SSL/TLS: Cryptographic protocols for secure communication. TLS is the modern, secure successor to SSL.
• PKI (Public Key Infrastructure): The framework of digital certificates and public/private key pairs used to verify identities.
• Digital Certificate: A document binding a public key to an entity (e.g., a server domain).
• Certificate Authority (CA): A trusted third party that verifies identities and signs certificates to create a chain of trust.

ZIO HTTP provides implementation paths for various security levels, including self-signed certificates, Root CA-signed certificates, Intermediate CA-signed certificates, and Mutual TLS (mTLS).

ZIO HTTP provides several high-level capabilities for modern web development:

• Imperative and Declarative Endpoints: Choose between defining logic and shape together (imperative) or separating the endpoint description from its logic (declarative).
• Type-Driven API: Leverages Scala's type system to ensure implementation matches the endpoint description at compile time.
• Middleware: Support for cross-cutting concerns like logging, metrics, and authentication.
• WebSockets: Built-in support for real-time applications.
• JSON and Binary Codecs: Integration with ZIO Schema for encoding/decoding JSON, Protobuf, Avro, and Thrift.
• OpenAPI Support: Generate OpenAPI documentation from endpoints or generate endpoints from OpenAPI specs.
• Testkit: First-class testing utilities to test logic without a live server.
• Template System: A DSL for writing HTML templates using Scala code.

In ZIO HTTP, HttpCodec is an abstraction used to bridge the gap between raw HTTP messages (Request and Response) and structured Scala data. It acts as a pair of functions for both encoding and decoding values.

An HttpCodec defines how to:

1. Decode: Transform a Request or Response into a structured Value.
2. Encode: Transform a Value back into a Request or Response.

ZIO HTTP provides specialized versions of this trait for different parts of an HTTP message, such as the body (Content), headers, methods, query parameters, and status codes.

sealed trait HttpCodec[-AtomTypes, Value] {
  final def decodeRequest(request: Request)(implicit trace: Trace): Task[Value]
  final def decodeResponse(response: Response)(implicit trace: Trace): Task[Value]

  final def encodeRequest(value: Value): Request
  final def encodeResponse[Z](value: Value, outputTypes: Chunk[MediaTypeWithQFactor]): Response
}

The Endpoint API is a high-level, declarative DSL used to describe HTTP endpoints. Instead of manually handling routes and parsing logic, you define the endpoint's structure (path, method, inputs, and outputs) and then implement the logic separately.

Key benefits include:

• Type Safety: The compiler ensures your implementation handler matches the defined input types.
• Documentation: Automatically generates OpenAPI documentation.
• Client Generation: Enables the generation of clients based on the endpoint definitions.

To use it, you define an Endpoint and then call .implement(handler) where the handler is a function that returns a Route.

import zio.http.endpoint.Endpoint
import zio.http.RoutePattern

// 1. Define the endpoint
val endpoint = Endpoint(RoutePattern.GET / "books")
  .query(HttpCodec.query[String]("q"))
  .out[List[Book]]

// 2. Implement the logic
val route = endpoint.implement(query => BookRepo.find(query))

Concept: TestServer

TestServer is an integration testing HTTP server that simulates a real server listening on localhost. It is designed to run your routes in-process, providing a realistic request/response cycle through the full HTTP stack while remaining fast and deterministic.

Key Characteristics:

• Localhost Binding: Binds to an automatically assigned port on localhost. It uses real network I/O (loopback) but eliminates external network latency and disk I/O.
• Mutable Configuration: You can dynamically add routes or exact request/response mappings during test execution.
• Standard Interface: It implements the Server trait, meaning it works seamlessly with the standard Client interface.

When to use it: Use TestServer instead of unit testing individual handlers when you need to test:

• Multiple routes working together.
• Route precedence (which route matches first).
• State persistence across multiple sequential requests.
• Complete feature workflows involving the full HTTP stack.