Implement container support

This adds an OCI image and support for structured request logs. This allows for quixote to be run as a container inside multi-container virtual network integration tests.
io7m-com · Apr 3, 2024 · 4b3d517 · 4b3d517
1 parent d31ebba
commit 4b3d517
Show file tree

Hide file tree

Showing 49 changed files with 3,682 additions and 8 deletions.
diff --git a/README-CHANGES.xml b/README-CHANGES.xml
@@ -11,12 +11,13 @@
         <c:change date="2023-11-03T00:00:00+00:00" summary="Add an API for controlling the web server address binding."/>
       </c:changes>
     </c:release>
-    <c:release date="2024-03-31T20:38:47+00:00" is-open="true" ticket-system="com.github.io7m.quixote" version="1.2.0">
+    <c:release date="2024-04-03T10:20:43+00:00" is-open="true" ticket-system="com.github.io7m.quixote" version="1.2.0">
       <c:changes>
         <c:change date="2024-03-31T00:00:00+00:00" summary="Update ch.qos.logback:logback-classic:1.4.14 → 1.5.3"/>
         <c:change date="2024-03-31T00:00:00+00:00" summary="Update org.slf4j:slf4j-api:2.0.10 → 2.0.12"/>
         <c:change date="2024-03-31T00:00:00+00:00" summary="Update org.junit.jupiter:junit-jupiter-api:5.10.1 → 5.10.2"/>
-        <c:change date="2024-03-31T20:38:47+00:00" summary="Update org.junit.jupiter:junit-jupiter-engine:5.10.1 → 5.10.2"/>
+        <c:change date="2024-03-31T00:00:00+00:00" summary="Update org.junit.jupiter:junit-jupiter-engine:5.10.1 → 5.10.2"/>
+        <c:change date="2024-04-03T10:20:43+00:00" summary="Add OCI container support."/>
       </c:changes>
     </c:release>
   </c:releases>

diff --git a/README-LICENSE.txt b/README-LICENSE.txt
@@ -1,4 +1,4 @@
-Copyright © 2023 Mark Raynsford <[email protected]> https://www.io7m.com
+Copyright © 2024 Mark Raynsford <[email protected]> https://www.io7m.com
 
 Permission to use, copy, modify, and/or distribute this software for any
 purpose with or without fee is hereby granted, provided that the above

diff --git a/README.in b/README.in
@@ -9,7 +9,7 @@ A tiny embedded HTTP server for unit testing.
   * Conveniently enqueue responses to arbitrary requests.
   * Verify that requests were received as expected.
   * Zero dependencies.
-  * Written in pure Java 17.
+  * Written in pure Java 21.
   * [OSGi](https://www.osgi.org/) ready.
   * [JPMS](https://en.wikipedia.org/wiki/Java_Platform_Module_System) ready.
   * ISC license.
@@ -82,3 +82,155 @@ public void tearDown()
   this.server.close();
 }
 ```
+
+### OCI
+
+The `quixote` server is also capable of acting as a standalone web server
+for use in integration tests involving containers. This is primarily useful
+for situations where an integration test starts multiple containers inside
+an isolated virtual network, and one or more of the test containers need to
+speak to a fake web server, and the host running the test suite needs to
+observe the requests in question. This particular configuration can be
+difficult to set up in an automated manner, as most virtual networking
+solutions don't allow for containers to "talk back" to the host machine. Using
+`quixote` as a container allows for it to be present inside the virtual network,
+and for the host to download and parse request logs after the test has
+completed, sidestepping the need for any containers to know about the host
+machine.
+
+In other words:
+
+1. The host creates a virtual network using its container engine of choice.
+2. The host creates several containers inside the virtual network.
+3. The host writes a `quixote` configuration file in the host directory.
+4. The host creates a `quixote` container inside the virtual network, mounting
+   the host directory into the container as a volume mount.
+5. The host runs the test. This causes the containers inside the virtual
+   network to make requests to the `quixote` container.
+6. The host reads the resulting request log from the host directory and
+   verifies that the correct requests were made for the test.
+
+![Virtual Network](net.png)
+
+Given a configuration file conforming to the provided
+[schema](com.io7m.quixote.xml/src/main/resources/com/io7m/quixote/xml/configuration-1.xsd),
+the `quixote` server can be started using a container engine such as
+[Podman](https://podman.io).
+
+```
+$ cat quixote/config.xml
+
+<?xml version="1.0" encoding="UTF-8" ?>
+
+<Configuration xmlns="urn:com.io7m.quixote:configuration:1"
+               Port="20001"
+               GZIP="true">
+  <Responses>
+    <Response Method="GET"
+              Path="/"
+              Status="200">
+      <Headers>
+        <Header Name="Content-Type"
+                Value="application/octet-stream"/>
+      </Headers>
+      <ContentUTF8>Hello world!</ContentUTF8>
+    </Response>
+  </Responses>
+</Configuration>
+```
+
+```
+$ podman run \
+  --rm \
+  --interactive \
+  --tty \
+  --volume quixote:/quixote/data:rw \
+  --publish 20001:20001/tcp \
+  quay.io/io7mcom/quixote:1.2.0-SNAPSHOT \
+  /quixote/data/config.xml \
+  /quixote/data/output.bin
+INFO com.io7m.quixote.main.Main: Quixote running at http://localhost:20001/
+```
+
+```
+$ curl http://localhost:20001/
+Hello world!
+```
+
+The server appends every received request to a file consisting of an
+array of request records in a trivial binary format. A request record has the
+following structure:
+
+```
+RequestRecord
+{
+  Unsigned64  quixote;
+  Unsigned32  version;
+  Unsigned64  length;
+  Unsigned8   data[length];
+}
+```
+
+All integer values are in big-endian byte order.
+
+The `quixote` field of the `RequestRecord` structure always has the value
+`0x515549584F544521` ("QUIXOTE!" in ASCII). The `version` field of the
+`RequestRecord` field currently has the value `0x00000001`.
+
+The `data` field is a sequence of `length` bytes that represents a serialized
+[java.util.Properties](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/Properties.html)
+XML document. For example, the `curl` request above resulted in the following
+record being appended to `/quixote/output.bin`:
+
+```
+0000:0000 | 51 55 49 58  4F 54 45 21  00 00 00 01  00 00 00 00 | QUIXOTE!........
+0000:0010 | 00 00 01 BF  3C 3F 78 6D  6C 20 76 65  72 73 69 6F | ...¿<?xml versio
+0000:0020 | 6E 3D 22 31  2E 30 22 20  65 6E 63 6F  64 69 6E 67 | n="1.0" encoding
+0000:0030 | 3D 22 55 54  46 2D 38 22  3F 3E 0A 3C  21 44 4F 43 | ="UTF-8"?>.<!DOC
+0000:0040 | 54 59 50 45  20 70 72 6F  70 65 72 74  69 65 73 20 | TYPE properties
+0000:0050 | 53 59 53 54  45 4D 20 22  68 74 74 70  3A 2F 2F 6A | SYSTEM "http://j
+0000:0060 | 61 76 61 2E  73 75 6E 2E  63 6F 6D 2F  64 74 64 2F | ava.sun.com/dtd/
+0000:0070 | 70 72 6F 70  65 72 74 69  65 73 2E 64  74 64 22 3E | properties.dtd">
+0000:0080 | 0A 3C 70 72  6F 70 65 72  74 69 65 73  3E 0A 3C 65 | .<properties>.<e
+0000:0090 | 6E 74 72 79  20 6B 65 79  3D 22 48 65  61 64 65 72 | ntry key="Header
+0000:00A0 | 2E 72 65 6D  6F 74 65 2D  61 64 64 72  22 3E 31 32 | .remote-addr">12
+0000:00B0 | 37 2E 30 2E  30 2E 31 3C  2F 65 6E 74  72 79 3E 0A | 7.0.0.1</entry>.
+0000:00C0 | 3C 65 6E 74  72 79 20 6B  65 79 3D 22  49 6E 66 6F | <entry key="Info
+0000:00D0 | 2E 4D 65 74  68 6F 64 22  3E 47 45 54  3C 2F 65 6E | .Method">GET</en
+0000:00E0 | 74 72 79 3E  0A 3C 65 6E  74 72 79 20  6B 65 79 3D | try>.<entry key=
+0000:00F0 | 22 48 65 61  64 65 72 2E  68 74 74 70  2D 63 6C 69 | "Header.http-cli
+0000:0100 | 65 6E 74 2D  69 70 22 3E  31 32 37 2E  30 2E 30 2E | ent-ip">127.0.0.
+0000:0110 | 31 3C 2F 65  6E 74 72 79  3E 0A 3C 65  6E 74 72 79 | 1</entry>.<entry
+0000:0120 | 20 6B 65 79  3D 22 49 6E  66 6F 2E 50  61 74 68 22 |  key="Info.Path"
+0000:0130 | 3E 2F 3C 2F  65 6E 74 72  79 3E 0A 3C  65 6E 74 72 | >/</entry>.<entr
+0000:0140 | 79 20 6B 65  79 3D 22 48  65 61 64 65  72 2E 61 63 | y key="Header.ac
+0000:0150 | 63 65 70 74  22 3E 2A 2F  2A 3C 2F 65  6E 74 72 79 | cept">*/*</entry
+0000:0160 | 3E 0A 3C 65  6E 74 72 79  20 6B 65 79  3D 22 48 65 | >.<entry key="He
+0000:0170 | 61 64 65 72  2E 75 73 65  72 2D 61 67  65 6E 74 22 | ader.user-agent"
+0000:0180 | 3E 63 75 72  6C 2F 38 2E  37 2E 31 3C  2F 65 6E 74 | >curl/8.7.1</ent
+0000:0190 | 72 79 3E 0A  3C 65 6E 74  72 79 20 6B  65 79 3D 22 | ry>.<entry key="
+0000:01A0 | 48 65 61 64  65 72 2E 68  6F 73 74 22  3E 31 32 37 | Header.host">127
+0000:01B0 | 2E 30 2E 30  2E 31 3A 32  30 30 30 31  3C 2F 65 6E | .0.0.1:20001</en
+0000:01C0 | 74 72 79 3E  0A 3C 2F 70  72 6F 70 65  72 74 69 65 | try>.</propertie
+0000:01D0 | 73 3E 0A                                           | s>.
+```
+
+Extracting the XML document and formatting it gives:
+
+```
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
+<properties>
+<entry key="Header.remote-addr">127.0.0.1</entry>
+<entry key="Info.Method">GET</entry>
+<entry key="Header.http-client-ip">127.0.0.1</entry>
+<entry key="Info.Path">/</entry>
+<entry key="Header.accept">*/*</entry>
+<entry key="Header.user-agent">curl/8.7.1</entry>
+<entry key="Header.host">127.0.0.1:20001</entry>
+</properties>
+```
+
+We can see that the client made a `GET` request to the `/` path. The
+[QWebRequestLogging](com.io7m.quixote.core/src/main/java/com/io7m/quixote/core/QWebRequestLogging.java)
+class provides convenient functions to read and write request logs.
diff --git a/README.md b/README.md
@@ -24,7 +24,7 @@ A tiny embedded HTTP server for unit testing.
   * Conveniently enqueue responses to arbitrary requests.
   * Verify that requests were received as expected.
   * Zero dependencies.
-  * Written in pure Java 17.
+  * Written in pure Java 21.
   * [OSGi](https://www.osgi.org/) ready.
   * [JPMS](https://en.wikipedia.org/wiki/Java_Platform_Module_System) ready.
   * ISC license.
@@ -98,3 +98,155 @@ public void tearDown()
 }
 ```
 
+### OCI
+
+The `quixote` server is also capable of acting as a standalone web server
+for use in integration tests involving containers. This is primarily useful
+for situations where an integration test starts multiple containers inside
+an isolated virtual network, and one or more of the test containers need to
+speak to a fake web server, and the host running the test suite needs to
+observe the requests in question. This particular configuration can be
+difficult to set up in an automated manner, as most virtual networking
+solutions don't allow for containers to "talk back" to the host machine. Using
+`quixote` as a container allows for it to be present inside the virtual network,
+and for the host to download and parse request logs after the test has
+completed, sidestepping the need for any containers to know about the host
+machine.
+
+In other words:
+
+1. The host creates a virtual network using its container engine of choice.
+2. The host creates several containers inside the virtual network.
+3. The host writes a `quixote` configuration file in the host directory.
+4. The host creates a `quixote` container inside the virtual network, mounting
+   the host directory into the container as a volume mount.
+5. The host runs the test. This causes the containers inside the virtual
+   network to make requests to the `quixote` container.
+6. The host reads the resulting request log from the host directory and
+   verifies that the correct requests were made for the test.
+
+![Virtual Network](net.png)
+
+Given a configuration file conforming to the provided
+[schema](com.io7m.quixote.xml/src/main/resources/com/io7m/quixote/xml/configuration-1.xsd),
+the `quixote` server can be started using a container engine such as
+[Podman](https://podman.io).
+
+```
+$ cat quixote/config.xml
+
+<?xml version="1.0" encoding="UTF-8" ?>
+
+<Configuration xmlns="urn:com.io7m.quixote:configuration:1"
+               Port="20001"
+               GZIP="true">
+  <Responses>
+    <Response Method="GET"
+              Path="/"
+              Status="200">
+      <Headers>
+        <Header Name="Content-Type"
+                Value="application/octet-stream"/>
+      </Headers>
+      <ContentUTF8>Hello world!</ContentUTF8>
+    </Response>
+  </Responses>
+</Configuration>
+```
+
+```
+$ podman run \
+  --rm \
+  --interactive \
+  --tty \
+  --volume quixote:/quixote/data:rw \
+  --publish 20001:20001/tcp \
+  quay.io/io7mcom/quixote:1.2.0-SNAPSHOT \
+  /quixote/data/config.xml \
+  /quixote/data/output.bin
+INFO com.io7m.quixote.main.Main: Quixote running at http://localhost:20001/
+```
+
+```
+$ curl http://localhost:20001/
+Hello world!
+```
+
+The server appends every received request to a file consisting of an
+array of request records in a trivial binary format. A request record has the
+following structure:
+
+```
+RequestRecord
+{
+  Unsigned64  quixote;
+  Unsigned32  version;
+  Unsigned64  length;
+  Unsigned8   data[length];
+}
+```
+
+All integer values are in big-endian byte order.
+
+The `quixote` field of the `RequestRecord` structure always has the value
+`0x515549584F544521` ("QUIXOTE!" in ASCII). The `version` field of the
+`RequestRecord` field currently has the value `0x00000001`.
+
+The `data` field is a sequence of `length` bytes that represents a serialized
+[java.util.Properties](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/Properties.html)
+XML document. For example, the `curl` request above resulted in the following
+record being appended to `/quixote/output.bin`:
+
+```
+0000:0000 | 51 55 49 58  4F 54 45 21  00 00 00 01  00 00 00 00 | QUIXOTE!........
+0000:0010 | 00 00 01 BF  3C 3F 78 6D  6C 20 76 65  72 73 69 6F | ...¿<?xml versio
+0000:0020 | 6E 3D 22 31  2E 30 22 20  65 6E 63 6F  64 69 6E 67 | n="1.0" encoding
+0000:0030 | 3D 22 55 54  46 2D 38 22  3F 3E 0A 3C  21 44 4F 43 | ="UTF-8"?>.<!DOC
+0000:0040 | 54 59 50 45  20 70 72 6F  70 65 72 74  69 65 73 20 | TYPE properties
+0000:0050 | 53 59 53 54  45 4D 20 22  68 74 74 70  3A 2F 2F 6A | SYSTEM "http://j
+0000:0060 | 61 76 61 2E  73 75 6E 2E  63 6F 6D 2F  64 74 64 2F | ava.sun.com/dtd/
+0000:0070 | 70 72 6F 70  65 72 74 69  65 73 2E 64  74 64 22 3E | properties.dtd">
+0000:0080 | 0A 3C 70 72  6F 70 65 72  74 69 65 73  3E 0A 3C 65 | .<properties>.<e
+0000:0090 | 6E 74 72 79  20 6B 65 79  3D 22 48 65  61 64 65 72 | ntry key="Header
+0000:00A0 | 2E 72 65 6D  6F 74 65 2D  61 64 64 72  22 3E 31 32 | .remote-addr">12
+0000:00B0 | 37 2E 30 2E  30 2E 31 3C  2F 65 6E 74  72 79 3E 0A | 7.0.0.1</entry>.
+0000:00C0 | 3C 65 6E 74  72 79 20 6B  65 79 3D 22  49 6E 66 6F | <entry key="Info
+0000:00D0 | 2E 4D 65 74  68 6F 64 22  3E 47 45 54  3C 2F 65 6E | .Method">GET</en
+0000:00E0 | 74 72 79 3E  0A 3C 65 6E  74 72 79 20  6B 65 79 3D | try>.<entry key=
+0000:00F0 | 22 48 65 61  64 65 72 2E  68 74 74 70  2D 63 6C 69 | "Header.http-cli
+0000:0100 | 65 6E 74 2D  69 70 22 3E  31 32 37 2E  30 2E 30 2E | ent-ip">127.0.0.
+0000:0110 | 31 3C 2F 65  6E 74 72 79  3E 0A 3C 65  6E 74 72 79 | 1</entry>.<entry
+0000:0120 | 20 6B 65 79  3D 22 49 6E  66 6F 2E 50  61 74 68 22 |  key="Info.Path"
+0000:0130 | 3E 2F 3C 2F  65 6E 74 72  79 3E 0A 3C  65 6E 74 72 | >/</entry>.<entr
+0000:0140 | 79 20 6B 65  79 3D 22 48  65 61 64 65  72 2E 61 63 | y key="Header.ac
+0000:0150 | 63 65 70 74  22 3E 2A 2F  2A 3C 2F 65  6E 74 72 79 | cept">*/*</entry
+0000:0160 | 3E 0A 3C 65  6E 74 72 79  20 6B 65 79  3D 22 48 65 | >.<entry key="He
+0000:0170 | 61 64 65 72  2E 75 73 65  72 2D 61 67  65 6E 74 22 | ader.user-agent"
+0000:0180 | 3E 63 75 72  6C 2F 38 2E  37 2E 31 3C  2F 65 6E 74 | >curl/8.7.1</ent
+0000:0190 | 72 79 3E 0A  3C 65 6E 74  72 79 20 6B  65 79 3D 22 | ry>.<entry key="
+0000:01A0 | 48 65 61 64  65 72 2E 68  6F 73 74 22  3E 31 32 37 | Header.host">127
+0000:01B0 | 2E 30 2E 30  2E 31 3A 32  30 30 30 31  3C 2F 65 6E | .0.0.1:20001</en
+0000:01C0 | 74 72 79 3E  0A 3C 2F 70  72 6F 70 65  72 74 69 65 | try>.</propertie
+0000:01D0 | 73 3E 0A                                           | s>.
+```
+
+Extracting the XML document and formatting it gives:
+
+```
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
+<properties>
+<entry key="Header.remote-addr">127.0.0.1</entry>
+<entry key="Info.Method">GET</entry>
+<entry key="Header.http-client-ip">127.0.0.1</entry>
+<entry key="Info.Path">/</entry>
+<entry key="Header.accept">*/*</entry>
+<entry key="Header.user-agent">curl/8.7.1</entry>
+<entry key="Header.host">127.0.0.1:20001</entry>
+</properties>
+```
+
+We can see that the client made a `GET` request to the `/` path. The
+[QWebRequestLogging](com.io7m.quixote.core/src/main/java/com/io7m/quixote/core/QWebRequestLogging.java)
+class provides convenient functions to read and write request logs.
+
diff --git a/checkstyle-filter.xml b/checkstyle-filter.xml
@@ -5,5 +5,8 @@
   "https://checkstyle.org/dtds/suppressions_1_0.dtd">
 
 <suppressions>
-
+  <suppress files="QWX1ContentUTF8.java"
+            checks="IllegalInstantiation"/>
+  <suppress files="QWX1ContentBase64.java"
+            checks="IllegalInstantiation"/>
 </suppressions>
diff --git a/com.io7m.quixote.core/src/main/java-descriptor-testing/module-info.java b/com.io7m.quixote.core/src/main/java-descriptor-testing/module-info.java
@@ -0,0 +1,30 @@
+/*
+ * Copyright © 2022 Mark Raynsford <[email protected]> https://www.io7m.com
+ *
+ * Permission to use, copy, modify, and/or distribute this software for any
+ * purpose with or without fee is hereby granted, provided that the above
+ * copyright notice and this permission notice appear in all copies.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+ * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+ * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
+ * SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+ * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR
+ * IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+ */
+
+/**
+ * Embedded test suite web server (Core)
+ */
+
+module com.io7m.quixote.core
+{
+  requires static org.osgi.annotation.bundle;
+  requires static org.osgi.annotation.versioning;
+
+  requires java.logging;
+  requires nanohttpd;
+
+  exports com.io7m.quixote.core;
+}