How jenkinsci/remoting works
Main System “Actors” and Components
• Jenkins Controller JVM – hosts the master side of Remoting
• Remoting Agent JVM – any inbound/outbound agent or CLI invoking Remoting
• Network Transport – TCP (BIO/NIO), optional SSL/TLS, JNLP handshake
• ProtocolStack – a stack of layered protocol/filter components
• IOHub – multiplexes/demultiplexes streams for filters & application
• Channel – a multiplexed, bidirectional “virtual pipe” for commands/streams
• Engine – executes Callable tasks over the Channel
• Classloading Subsystem – JarCache, RemoteClassLoader, dynamic class download
• Forwarding Service – port forwarding (hudson.remoting.forward)
Relationships & Data Flow
• Controller JVM loads remoting.jar → ChannelBuilder → establishes TCP connection
• Handshake: JNLP protocol handler negotiates version, security (roles, SSL)
• On top of socket, ProtocolStack layers are installed in sequence:
– NetworkLayer (BIO or NIO)
– SSLEngineFilterLayer (optional)
– ConnectionHeadersFilterLayer (version, headers)
– ApplicationLayer (handles Engine & Channel)
• IOHub sits between NetworkLayer and Filters, routing bytes to correct filter chain
• Channel multiplexes Commands and Streams:
– Commands: Callable, GCCommand, UnexportCommand, etc.
– Streams: Stdout, Stderr, RemoteInputStream, RemoteOutputStream
• Engine executes incoming Callables on user threads (Asynchronous or Synchronous executors)
• Classloading subsystem intercepts Class requests, fetches JARs over the channel, caches via JarCache
Architectural Patterns & Design Principles
• Layered Protocol Stack – separation of concerns for transport, framing, SSL, application
• Inversion of Control – ChannelBuilder abstracts over network transport choice (BIO vs. NIO)
• Decorator Pattern – CallableDecoratorAdapter, FilterLayer, SSLEngineFilterLayer
• Multiplexing – IOHub and Channel multiplex many logical streams over a single TCP socket
• Pluggable Classloading – RemoteClassLoader bridges class definitions across JVMs
Key Technologies & Frameworks
• Java NIO & BIO (java.nio.channels, java.net.Socket)
• JNLP protocol (hudson.remoting.jnlp package)
• SSL/TLS via SSLEngineFilterLayer
• Maven for build (pom.xml, assembly descriptors)
• JUnit & SpotBugs for testing (src/test/java, src/spotbugs)
Diagramming Conventions
• Use clear labels: e.g., “BIO NetworkLayer,” “SSLEngineFilterLayer,” “ApplicationLayer”
– Data flow through ProtocolStack from bottom (socket) to top (application) and back
– Commands flowing into Engine and results back over Channel
– Blue for Transport layers (NetworkLayer, Socket)
– Green for Protocol/Filter layers (SSLEngineFilterLayer, ConnectionHeadersFilterLayer)
– Yellow for Application components (Channel, Engine, Classloader)
– Gray for External (Jenkins master core, Agent runtime)
Essential Details to Capture
• Dual‐sided nature: both Controller and Agent have symmetric stacks
• The multiplexed Channel concept (virtual channels over one socket)
• Pluggability/configurability: choice of transport, SSL, filters, thread pools
• Dynamic classloading across JVMs
Putting It All Together
[ ApplicationLayer ]
[ ConnectionHeadersFilterLayer ]
[ SSLEngineFilterLayer (opt) ]
[ NetworkLayer (BIO/NIO) ]