Skip to content

PR1: Standardize emulator reset() contract + conformance test - #1

Merged
dksingh1997 merged 1 commit into
mainfrom
pr1-control-contract
Jun 22, 2026
Merged

PR1: Standardize emulator reset() contract + conformance test#1
dksingh1997 merged 1 commit into
mainfrom
pr1-control-contract

Conversation

@dksingh1997

Copy link
Copy Markdown
Owner

Tier 1 — PR 1 of 4 (control plane foundation)

First PR toward the control plane (see PLAN.md). Establishes the emulator contract every service must follow so the launcher, probe, and forthcoming control-plane server can introspect and reset any emulator uniformly.

What changed

  • Standardized reset() across the catalog. Audited all 250 services; 6 networked emulators lacked a reset() method — added it to cassandra, kafka, mysql, rabbitmq, elasticsearch, and supabase. State initialization moved into reset() and called from the constructor, so state init and reset can never drift. Behavior-preserving — only refactors where state is initialized.
  • New conformance meta-test (test/conformance.test.ts). Across the whole catalog it asserts:
    • every manifest is valid (name, port, protocol) and the name matches the slug,
    • ports are unique catalog-wide,
    • every networked service ships src/server.js exporting a *Server class,
    • that class implements start(), stop(), and reset(),
    • plus a live boot → /healthreset() smoke test for a representative sample (stripe, openai, s3, sendgrid, elasticsearch, supabase, pinecone, github).
  • Docs: CONTRIBUTING.md now documents the full contract (reset() required; all state initialized in reset()) and the PR checklist references the conformance test. Added CHANGELOG.md. Added PLAN.md (10-PR roadmap) and SKILL.md (implementation guide for agents).

Why

A reliable reset() is the prerequisite for per-test isolation and for the control plane (PR 2) to wipe state between test cases without restarting containers. The conformance test prevents convention drift as the catalog grows (the apigateway-stub class of problem).

Verification

  • Full suite green on 3 consecutive runs: 252 files / 5466 tests (was 5457; +9 from conformance).
  • Edited services' own real-driver test suites pass (79 tests across the 6).
  • Live real-driver round-trips confirmed for the 4 edited TCP services: mysql SELECT 1, kafka listTopics, rabbitmq assertQueue, cassandra system.local.

Contract (now documented)

export class MyServiceServer {
  constructor(port, options) { /* config only */ this.reset(); }
  reset() { /* clears ALL in-memory state; idempotent, no I/O */ }
  start() { /* resolves once listening */ }
  stop()  { /* resolves once closed */ }
}

Part of: Tier 1 control plane. Next: PR 2 (control-plane HTTP server).

Establishes the emulator contract (constructor/start/stop/reset) that the
launcher, probe, and forthcoming control plane rely on:

- Add reset() to the 6 services that lacked it (cassandra, kafka, mysql,
  rabbitmq, elasticsearch, supabase). State init moved into reset() and
  called from the constructor; behavior-preserving (verified via each
  service's real-driver test suite + live round-trips).
- Add test/conformance.test.ts: asserts valid manifests, unique ports,
  *Server class export, and start/stop/reset across the whole catalog,
  plus a live boot/health/reset smoke test for a representative sample.
- Document the contract in CONTRIBUTING.md + SKILL.md; add CHANGELOG.md.
- Add PLAN.md (10-PR roadmap) and SKILL.md (implementation guide).

Full suite: 252 files / 5466 tests, green on 3 consecutive runs.
@dksingh1997
dksingh1997 merged commit 05c99db into main Jun 22, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant