# jenkinsci/remoting architecture

> Architecture diagram of the GitHub repository jenkinsci/remoting, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jenkinsci/remoting
- Repository: https://github.com/jenkinsci/remoting

## Overview

##### 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) ]

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Jenkins Controller JVM"
        subgraph "Remoting"
            CB["ChannelBuilder"]:::yellow
            CH["Channel"]:::yellow
            PS["ProtocolStack"]:::yellow
            AL["ApplicationLayer"]:::yellow
            CHL["ConnectionHeadersFilterLayer"]:::green
            SSL["SSLEngineFilterLayer (opt)"]:::green
            NL["NetworkLayer (BIO/NIO)"]:::blue
            Socket1["TCP Socket"]:::blue
            IOHub1["IOHub"]:::yellow
            Engine1["Engine"]:::yellow
            JarCache1["JarCache"]:::yellow
            Forwarder1["Forwarding Service"]:::yellow
        end
    end

    subgraph "Remoting Agent JVM"
        subgraph "Remoting"
            CB2["ChannelBuilder"]:::yellow
            CH2["Channel"]:::yellow
            PS2["ProtocolStack"]:::yellow
            AL2["ApplicationLayer"]:::yellow
            CHL2["ConnectionHeadersFilterLayer"]:::green
            SSL2["SSLEngineFilterLayer (opt)"]:::green
            NL2["NetworkLayer (BIO/NIO)"]:::blue
            Socket2["TCP Socket"]:::blue
            IOHub2["IOHub"]:::yellow
            Engine2["Engine"]:::yellow
            JarCache2["JarCache"]:::yellow
            Forwarder2["Forwarding Service"]:::yellow
        end
    end

    %% Connections Controller
    Socket1 -->|raw bytes| NL
    NL -->|framed| SSL
    SSL -->|secured| CHL
    CHL -->|framed headers| AL
    AL -->|commands| Engine1
    Engine1 -->|results| CH
    CH -->|multiplexed| Socket1
    NL --- IOHub1
    IOHub1 --- CHL

    %% Connections Agent
    Socket2 -->|raw bytes| NL2
    NL2 -->|framed| SSL2
    SSL2 -->|secured| CHL2
    CHL2 -->|framed headers| AL2
    AL2 -->|commands| Engine2
    Engine2 -->|results| CH2
    CH2 -->|multiplexed| Socket2
    NL2 --- IOHub2
    IOHub2 --- CHL2

    %% Cross-JVM Links
    Socket2 -->|TCP + optional SSL + JNLP handshake| Socket1

    %% Click Events
    click CB "https://github.com/jenkinsci/remoting/blob/master/src/main/java/hudson/remoting/ChannelBuilder.java"
    click CH "https://github.com/jenkinsci/remoting/blob/master/src/main/java/hudson/remoting/Channel.java"
    click PS "https://github.com/jenkinsci/remoting/blob/master/src/main/java/org/jenkinsci/remoting/protocol/ProtocolStack.java"
    click NL "https://github.com/jenkinsci/remoting/blob/master/src/main/java/org/jenkinsci/remoting/protocol/NetworkLayer.java"
    click SSL "https://github.com/jenkinsci/remoting/blob/master/src/main/java/org/jenkinsci/remoting/protocol/impl/SSLEngineFilterLayer.java"
    click CHL "https://github.com/jenkinsci/remoting/blob/master/src/main/java/org/jenkinsci/remoting/protocol/impl/ConnectionHeadersFilterLayer.java"
    click AL "https://github.com/jenkinsci/remoting/blob/master/src/main/java/org/jenkinsci/remoting/protocol/ApplicationLayer.java"
    click IOHub1 "https://github.com/jenkinsci/remoting/blob/master/src/main/java/org/jenkinsci/remoting/protocol/IOHub.java"
    click Engine1 "https://github.com/jenkinsci/remoting/blob/master/src/main/java/hudson/remoting/Engine.java"
    click JarCache1 "https://github.com/jenkinsci/remoting/blob/master/src/main/java/hudson/remoting/JarCache.java"
    click Forwarder1 "https://github.com/jenkinsci/remoting/blob/master/src/main/java/hudson/remoting/forward/Forwarder.java"
    click CB2 "https://github.com/jenkinsci/remoting/blob/master/src/main/java/hudson/remoting/ChannelBuilder.java"
    click CH2 "https://github.com/jenkinsci/remoting/blob/master/src/main/java/hudson/remoting/Channel.java"
    click PS2 "https://github.com/jenkinsci/remoting/blob/master/src/main/java/org/jenkinsci/remoting/protocol/ProtocolStack.java"
    click NL2 "https://github.com/jenkinsci/remoting/blob/master/src/main/java/org/jenkinsci/remoting/protocol/NetworkLayer.java"
    click SSL2 "https://github.com/jenkinsci/remoting/blob/master/src/main/java/org/jenkinsci/remoting/protocol/impl/SSLEngineFilterLayer.java"
    click CHL2 "https://github.com/jenkinsci/remoting/blob/master/src/main/java/org/jenkinsci/remoting/protocol/impl/ConnectionHeadersFilterLayer.java"
    click AL2 "https://github.com/jenkinsci/remoting/blob/master/src/main/java/org/jenkinsci/remoting/protocol/ApplicationLayer.java"
    click IOHub2 "https://github.com/jenkinsci/remoting/blob/master/src/main/java/org/jenkinsci/remoting/protocol/IOHub.java"
    click Engine2 "https://github.com/jenkinsci/remoting/blob/master/src/main/java/hudson/remoting/Engine.java"
    click JarCache2 "https://github.com/jenkinsci/remoting/blob/master/src/main/java/hudson/remoting/JarCache.java"
    click Forwarder2 "https://github.com/jenkinsci/remoting/blob/master/src/main/java/hudson/remoting/forward/Forwarder.java"

    classDef blue fill:#cfe2f3,stroke:#6c8ebf;
    classDef green fill:#d9ead3,stroke:#6aa84f;
    classDef yellow fill:#fff2cc,stroke:#e69138;
    classDef gray fill:#eeeeee,stroke:#cccccc;
```
