How alibaba/jvm-sandbox-repeater works
Project Type & Purpose
• This is a multi-module Maven project implementing a full-stack, plugin-based “record & replay” solution for JVM applications.
• On the “agent” side it builds on Alibaba’s JVM-Sandbox to instrument your target application, record ingress calls (HTTP/Dubbo/Java), capture sub-calls, serialize them via Hessian, and optionally replay/mock them.
• On the “server” side it delivers a Spring‐Boot based console (with Velocity templates and a JS front end) for managing modules, browsing recorded flows, and triggering replays, backed by a relational database.
High-Level Directory Structure
• bin/ – shell‐scripts to bootstrap/healthcheck/package the agent.
• hessian-lite/ – in-house Hessian serialization library used by the agent for payload marshalling.
• repeater-module/ & repeater-plugin-api/ & repeater-plugin-core/ – the core agent components:
– repeater-module: JVM-Sandbox agent plug-in, life-cycle & classloader logic.
– plugin-api: SPI interfaces (InvokePlugin, Repeater, MockStrategy, etc.).
– plugin-core: event listener, tracing, caching, dispatch & serializer adapters.
• repeater-plugins/ – a collection of concrete plugin implementations (HTTP, Dubbo, MyBatis, Redis, etc.).
• repeater-client/ – a small client library (SpringContextAware, HTTP util) for calling console APIs from code.
• repeater-aide/ – offline comparison/diff library for analyzing recorded flows.
• repeater-console/ – the console application, split into:
– repeater-console-common (shared DTOs, exceptions, request/response objects)
– repeater-console-dal (DAO, JPA/MyBatis models & repositories)
– repeater-console-service (business services, converters, caching, Jackson config)
– repeater-console-start (Spring Boot app, controllers, Velocity UI, static assets, front-end JS)
• docs/, LICENSE, pom.xml, Readme.md, etc.
Key Insights from README
• Agent records “entranceInvocation” + “subInvocations” using JVM-Sandbox hooks (BEFORE/RETURN/THROW) and TTL for cross-thread tracing.
• Recorded data is serialized (Hessian/JSON) and can be sent to a server or kept in standalone mode.
• Replay is driven by an async EventBus, FlowDispatcher & Repeater SPI; supports mock (short-circuit) or real calls.
• Console UI for browsing, filtering, replaying flows, built as a Spring Boot application with Velocity and front-end assets.
a. Main Components
1. Application Under Test (JVM).
2. JVM-Sandbox Agent:
• Repeater-Module (Sandbox plugin loader & advices)
• Plugin-Core (EventListener → Tracer → Record/Replay Cache → FlowDispatcher → Serializer)
• Plugin-API (SPI definitions)
• Plugin Implementations (http, dubbo, mybatis, etc.)
3. Hessian-Lite Library (payload serialization).
4. Network/Transport (HTTP via HttpUtil or standalone file store).
5. Repeater-Console Server:
• API Controllers (REST + Velocity controllers)
• Service Layer (business logic, conversion, caching)
• DAL Layer (DAO, repositories, DB schema)
• Front-end (Velocity templates + static JS/CSS/ACE editor plugin)
6. Relational Database.
7. Optional Repeater-Client (embedded in other apps to call console APIs).
8. Repeater-Aide (offline diffing tool).
b. Relationships & Data Flow
1. Agent intercepts calls → builds Invocation objects → serializes → sends HTTP POST to Console API (or writes to local storage).
2. Console API receives & persists into DB via DAL → Service processes & caches → UI queries Service → templates/JS display.
3. User clicks “Replay” in UI → UI calls REST Replay endpoint → Service publishes ReplayEvent on EventBus → plugin-core in agent (subscribed via HTTP client) picks it up → replays calls in the target app.
4. MockStrategy SPI may short-circuit sub-calls by throwReturnImmediately via Sandbox.
c. Architectural Patterns & Principles
• Plugin SPI + SPI Loader (loose coupling, extensibility)
• EventBus for intra-agent async dispatch
• Tracer + TTL for context propagation across threads
• Layered architecture on server: Controllers → Services → DAL → DB
• Standalone vs. client/server modes
d. Key Technologies
• JVM-Sandbox (Java agent, byte-code instrumentation)
• Spring Boot + Velocity + jQuery/ACE for console UI
• Maven multi-module, SPI, ServiceLoader
• Hessian for binary serialization (hessian-lite)
• Relational DB (via JPA/MyBatis)