mockserver-monorepo: Instructions file for Codex

MockServer — Agent Instructions

Instruction Priority

1. Direct user instructions (highest)
2. Rules in .opencode/rules/
3. This file (AGENTS.md)
4. Skills in .opencode/skills/

Project Overview

MockServer is an open-source HTTP(S) mock server and proxy for testing, written in Java. It uses Netty as the HTTP server framework, Maven for builds, and is deployed as Docker containers, JARs, and WARs.

Tech stack: Java 17+ (minimum supported), Netty 4.2, Jackson 2.22, Maven (multi-module), Node.js/TypeScript (UI + client), Python 3.9+ (client), Ruby 3.0+ (client), Docker, Helm, Jekyll (documentation site) CI/CD: Buildkite (primary CI — including all Docker image builds), GitHub Actions (CodeQL, scheduled hygiene jobs such as certificate-expiry, and issue/label automation) Infrastructure: AWS (Buildkite build agents, documentation site hosting), Docker Hub (container images) Repository: GitHub (github.com)

Local Development Environment

Docker is available locally. Docker Desktop runs on the developer Mac, so Docker is available to agents in this environment (not only in CI). This means:

• Docker-gated tests CAN and SHOULD be run locally, not just in CI. Tests that guard on Assume.assumeTrue(DockerAvailability.isAvailable(...)) (Testcontainers live-broker tests, NET_ADMIN transparent-proxy e2e, QUIC/HTTP-3 client tests, etc.) will actually execute here — validate them by running and passing them, not merely by confirming they skip.
• Keep the Docker-gating in place anyway. The assumeTrue(...) guard is still the correct design so the suite degrades gracefully on any CI agent or machine without Docker. Docker being present locally changes how we validate, not how we write the tests.
• org.mockserver.test.DockerAvailability (in mockserver-testing) is the canonical availability probe. NEVER call DockerClientFactory.instance().isDockerAvailable() directly. Despite its javadoc ("true if Docker is available, false if not") that method converts only IllegalStateException into false — it throws for everything else, because it also starts the Ryuk reaper and runs version/mount checks. A BadRequestException (privileged Ryuk rejected by a user-namespace-remapped daemon), a ContainerFetchException, or an Error such as NoClassDefFoundError from an incomplete test classpath all escape it, turning "no usable Docker" into a hard ERROR and defeating the assume guard — and Testcontainers caches that failure and rethrows it for the rest of the JVM. Write:

  Assume.assumeTrue("Docker is not available",
      DockerAvailability.isAvailable(() -> DockerClientFactory.instance().isDockerAvailable()));
  

  Pass a lambda, not a method reference — instance() must be evaluated inside the wrapper's try/catch. Testcontainers is the preferred harness, and works with Testcontainers 1.21.4+ (docker-java 3.4.2) on Docker Desktop 4.67 / Engine 29.x / API 1.54. (Earlier versions — Testcontainers 1.20.6 / docker-java 3.4.1 — got a 400 on the info endpoint and the probe returned false even though Docker worked.)
• A Docker-gated suite that runs in CI needs a fail-closed assertion too. A fail-safe probe means an unusable Docker SKIPS rather than errors, which is right off-CI but is a silent false positive in CI. Pair it with .buildkite/scripts/steps/assert-suite-ran.sh over the suite's surefire reports so a skip fails the build loudly.
• docker CLI commands (docker build, docker run) are also available for Dockerfile smoke checks in the commit workflow.