An Experiment in Streaming: Bytecode Continuous Deployment
Tags: datastreaming, continuousdeployment, bytecode, jvm
Published: 2020-04-16 18:39:37

Once one starts their journey in data streaming, one starts to discover a lot of applications beyond just the standard Extract-Transform-Load pattern.

The traditional model to deliver a new version of a Java application is to stop the process, deploy the new JAR/WAR, and start the process again. This directly results in downtime: in this day and age, most companies frown upon such downtime as it directly translates into a loss of revenue.

In this blog post, we are going to use streaming to continuously deploy bytecode to a running JVM without needing to stop it.

Thanks to <a href="https://hazelcast.com/blog/author/neilstevenson/">Neil Stevenson</a> who was behind the idea.
<h1>The Attach API</h1>
Before diving into the streaming part, we need to have some solid understanding of some of the APIs offered by the Java platform - regardless of the actual language (Java, Kotlin, Scala, Clojure, etc.).

Among them, stands the <a href="https://docs.oracle.com/javase/7/docs/technotes/guides/attach/index.html" target="_blank" rel="noopener noreferrer">Attach API</a>. It’s not very well-known, but it allows us to change the code of a class inside a running JVM. Interestingly enough, it doesn’t require the former to run in <i>debug mode</i> as HotSpot class reloading does.

There are only 2 requirements for that:
<ol>
 	<li>The active JVM must be aware of the PID of the JVM which runs the to-be-modified code</li>
 	<li>Both must run on the same machine (whether virtual or physical)</li>
</ol>
The Attach API is a double-edged sword: while it can allow the continuous deployment of bytecode, it’s also a security issue. If you can update the bytecode, anybody who has access to the system can. Hence, it’s mandatory to carefully evaluate the benefits-risks ratio <b>and</b> to put security checks in place to manage the risks. That being said, it’s an extremely powerful tool in the JVM ecosystem.

The (simplified) design of the Attach API is quite straightforward:

![Attach API class diagram](https://dev-to-uploads.s3.amazonaws.com/i/7ua6t31en2thdu7oi5rj.png)

The first step is to get a handle on a <code>VirtualMachine</code> instance. This is the goal of the <code>attach()</code> method, which requires the PID of the Java process to attach to.

The second step is to actually load the Java agent. This requires a bit of an introduction.
<h1>Quick Introduction to Java Agents</h1>
In short, a Java agent is a JAR with specific data in its manifest that allows it to change classes when they are loaded by a class loader. It achieves this by using the <a href="https://docs.oracle.com/javase/7/docs/api/java/lang/instrument/Instrumentation.html">Instrumentation API</a> (one more API to know about).

Agents can be categorized into two different buckets:
<ul>
 	<li>Static agents are set once and for all during the launch of a JVM via the <code>-javaagent</code> parameter</li>
 	<li>Dynamic agents are set via the Attach API (see above section)</li>
</ul>
Here is a summary of the main differences:
<table>
<tbody>
<tr>
<td></td>
<td>Static</td>
<td>Dynamic</td>
</tr>
<tr>
<td>Entry-point</td>
<td>
<ul>
 	<li><code>public static void premain(String agentArgs, Instrumentation inst)</code></li>
 	<li><code>public static void premain(String agentArgs)</code></li>
</ul>
</td>
<td>
<ul>
 	<li><code>public static void agentmain(String agentArgs, Instrumentation inst)</code></li>
 	<li><code>public static void agentmain(String agentArgs)</code></li>
</ul>
</td>
</tr>
<tr>
<td>Manifest entry</td>
<td><code>Premain-Class</code></td>
<td><code>Agent-Class</code></td>
</tr>
</tbody>
</table>
Note, that nothing prevents a specific agent to be both available as a static agent and a dynamic agent, provided it fulfills requirements from both categories.

A simplified diagram of the Instrumentation API looks like this:

![Instrumentation API class diagram](https://dev-to-uploads.s3.amazonaws.com/i/ffwcfr1voek79abcs1lc.png)

The entry-point into the Instrumentation API is the Instrumentation interface itself. The way to get a reference of such an instance is to actually use the aforementioned <code>premain()</code> or <code>agentmain()</code> static methods, which has an <code>Instrumentation</code> parameter. The JVM will actually call that method and provide it. It can be used “on the spot” or stored for later usage.

Once one has an Instrumentation instance, it can be used to:
<ul>
 	<li>Change existing class implementation (with some limitations)</li>
 	<li>Apply automatic transformation of bytecode</li>
 	<li>etc.</li>
</ul>
Note, that it’s possible to do that even within the boundaries of the Java Platform Module System.
<h1>Continuous Deployment</h1>
Continuous Deployment is the process to deliver code from development to production in a full-automated way following a series of steps. Those are specific to each tech stack, organization and sometimes even team. Here are some steps:
<ul>
 	<li>Compilation</li>
 	<li>Unit testing</li>
 	<li>Packaging</li>
 	<li>Integration testing</li>
 	<li>Containerization</li>
 	<li>Storing in a registry</li>
 	<li>Deployment in any number of environments</li>
 	<li>Canary deployments</li>
 	<li>etc.</li>
</ul>
The traditional deployment model of Java applications is to:
<ol>
 	<li>Stop the existing running JVM</li>
 	<li>Deploy the new JAR (or WAR if inside an application server)</li>
 	<li>And start JVM again</li>
</ol>
An additional property of continuous deployment is the lack of downtime. Therefore, the process described above is not compatible. However, if we skip packaging and directly load the new compiled bytecode in the running JVM, no downtime occurs. Both Attach and Instrumentation API can help us in this regard.

Here are the involved components:
<ol>
 	<li>A JVM that runs the class. This is the production environment.</li>
 	<li>A Java agent JAR that is able to read an updated class from a specific location and to update the running class (1)</li>
 	<li>A JVM that loads the agent (2) into the production JVM (1)</li>
 	<li>A way to produce an updated class and make it accessible to the agent (2)</li>
</ol>
We now need to focus on the last part, as the rest is in place.
<h1>Bytecode Streaming</h1>
At this point, we need a way to read updated bytecode and deliver it so it can be read by the production JVM (that has been updated with agent code - cf. above section). This should be done continuously; this is the definition of streaming by the book. Hazelcast Jet fits this requirement very well.

From the <a href="https://jet-start.sh/docs/get-started/intro">Jet site</a>:
<blockquote>Hazelcast Jet allows you to write modern Java code that focuses purely on data transformation while it does all the heavy lifting of getting the data flowing and computation running across a cluster of nodes. It supports working with both bounded (batch) and unbounded (streaming) data.</blockquote>
Jet excels at traditional distributed Extract-Transform-Load pipelines:
<ul>
 	<li>Extract: read from a variety of sources, databases, files, Kafka, etc. If a source doesn’t exist, the Jet API allows you to write your own</li>
 	<li>Transform: one can filter, map, flat map, etc. the data. Not only does Jet provide the primitives from Java’s Stream, it also comes up with additional <a href="https://jet-start.sh/docs/api/stateless-transforms">stateless</a> and <a href="https://jet-start.sh/docs/api/stateful-transforms">stateful transforms</a>, such as hash- joins, aggregates, etc.</li>
 	<li>Load: Jet can write the processed data into a lot of different out-of-the-box components. The same API lets you also write your own.</li>
</ul>
Now, bytecode is just a specific kind of data. Let’s create a Jet job that:
<ol>
 	<li>Reads the bytecode generated by the compiling of the source code on a developer’s computer</li>
 	<li>Checks whether it’s the same as already existing bytecode</li>
 	<li>Makes it available in a map on a Hazelcast instance with the key as the class name and the value as the bytecode</li>
</ol>
The agent just needs to register for updates on this map. Every time the compiler creates new bytecode, it will be made available in the map by the Jet job, and the production JVM will redefine the class with the updated bytecode.

This is an overview:

![Component diagram](https://dev-to-uploads.s3.amazonaws.com/i/tk40hvpirc9j9eq6q2rp.png)

Note that only the Production JVM and the Injection JVM need to be co-hosted on the same system. The rest of the components have no location requirements.

While Jet provides the API in Java, Kotlin makes it more engaging. The following snippets will be written in Kotlin. The complete source code can be found <a href="https://github.com/hazelcast/bytecode-streaming">on GitHub</a>.

The first step requires to read the actual bytecode. There’s no such thing provided out-of-the-box, but it’s a no-brainer to create such a source:

```kotlin
fun classes() = SourceBuilder
    .stream("classes", TargetPathContext())
    .fillBufferFn(ClassPathReader())
    .build()
```

The <code>TargetPathContext</code> class is a supplier that stores… the target path:

```kotlin
class TargetPathContext : FunctionEx<Context, ContextHolder> {
    override fun applyEx(ctx: Context) = ContextHolder()
}

class ContextHolder(val classesDirectory: Path = Paths.get(System.getProperty("target")))
```

The <code>ClassPathReader</code> class is where the reading magic really happens:

```kotlin
class ClassPathReader : BiConsumerEx<ContextHolder, SourceBuffer<Pair<String, ByteArray>>> {

    override fun acceptEx(ctx: ContextHolder, buffer: SourceBuffer<Pair<String, ByteArray>>) {
        val toClassName = PathToClassName(ctx.classesDirectory)
        val visitor = ClassFileVisitor()
        Files.walkFileTree(ctx.classesDirectory, visitor)
        visitor.classes.forEach {
            val name = toClassName.applyEx(it)
            val content = Files.readAllBytes(it)
            buffer.add(name to content)
        }
    }
}
```

The final touch is the pipeline itself:

```kotlin
fun pipeline() = Pipeline.create().apply {
    val mapName = "bytecode"
    readFrom(classes())
        .withIngestionTimestamps()
        .peek { it.first }
        .filterUsingService(
            ServiceFactories.iMapService(mapName),
            CheckChange()
        )
        .map { entry(it.first, it.second) }
        .writeTo(Sinks.map(mapName))
}
```

Note, the <code>filterUsingService()</code> call. It’s used to filter out bytecode that hasn’t changed.

```kotlin
class CheckChange : BiPredicateEx<IMap<String, ByteArray>, Pair>String, ByteArray&gt;&gt; {

    override fun testEx(
       map: IMap<String, ByteArray>,
       pair: Pair<String, ByteArray>) =
        map[pair.first] == null ||
     !pair.second.contentEquals(map[pair.first]!!)
}
```

The final flow looks like that:

![Sequence diagram](https://dev-to-uploads.s3.amazonaws.com/i/bqruomup2rx8040j4hky.png)

<h1>A word on limitations</h1>
This proof-of-concept has some limitations:
<ol>
 	<li>First and foremost, compared to traditional deployment, the code that runs in production is not tagged with a specific version. This is not specific to bytecode streaming, but congruent with any incremental deployment approach.
In the real world, however, the source of the pipeline is not a developer’s machine but the result of a build job on a continuous integration server (e.g. Jenkins). Additional metadata can be set through the build (such as a timestamp, build number, version number, etc.) and streamed along to be used by the pipeline.</li>
 	<li>This prototype handles only bytecode changes, not new classes. Loading new classes requires additional class-loading magic that goes well beyond the scope of this post and its associated demo code.</li>
 	<li>By definition, the redefineClasses() “must not add, remove or rename fields or methods, change the signatures of methods, or change inheritance”</li>
</ol>
<h1>Conclusion</h1>
When one thinks about stream processing, one generally thinks about reading data from somewhere, transforming it and storing it somewhere else. In general, it’s pretty narrow. Yet, the concept of data is much larger than it appears.

In this post, we showed that bytecode is data that can be processed like any other data. If one scratches beyond the surface, there is a lot of data around that is just waiting to benefit from streaming and Jet.

{% github hazelcast/bytecode-streaming %}

Learn more about [Hazelcast Jet](https://jet-start.sh/)