feat(docs/application): Add message headers concept

docs/application/concepts/120-message-headers.mdx

@@ -0,0 +1,176 @@
+---
+title: Message headers
+description: Additional information attached to Vert.x messages
+---
+
+<!--
+Concept
+=======
+
+=== When to use this template:
+Use this template when you need to describe a concept, technology,
+or something similar. In other words: whenever you need to write an
+article that describes a concept where the concept's name can be the
+article's title (e.g., "Vert. x", "Verticle", "Event Bus")
+
+=== When not to use this template:
+Do not use these templates for articles that give context on how
+to use/approach the topic. Instead, it would be best if you used a guide for that.
+
+Writing a guide and a concept article are not mutually exclusive. Instead,
+you should, in most cases, write both, where the concept gives a brief overview
+of what it is, and the guide is a longer article explaining best practices on using
+it.
+
+E.g.:
+Concept: Event Bus
+Guide: Interacting with the Event Bus
+
+
+=== Writing tips:
+- Write in the present tense
+- Use neutral pronouns (they/them instead of he/she and him/her)
+- Be respectful to everyone
+- Be aware of the potential for cultural misunderstandings
+-->
+
+<!-- Relevant imports: -->
+
+import { Reference, Image } from '/components';
+
+<!-- Brief Description (1-3 lines) of the concept: -->
+
+Message headers are additional information that can be attached to Vert.x messages.
+These information are like [HTTP headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers) and completely optional.
+
+Vert.x provides basic functionality for header information via 
+[MultiMaps](https://javadoc.io/static/io.vertx/vertx-core/4.2.6/index.html?io/vertx/core/MultiMap.html).
+Telestion takes this approach and extends the MultiMap's functionality via the
+[HeaderInformation](https://javadoc.io/doc/de.wuespace.telestion/telestion-api/latest/de/wuespace/telestion/api/message/HeaderInformation.html)
+class.
+
+## Vert.x Multi Map
+
+Vert.x Multi Maps store basic string type information in a key-value list format.
+
+Take a look at the following example:
+
+```java
+// create new and empty multi map
+var map = MultiMap.caseInsensitiveMultiMap();
+
+// add some values
+map.add("key1", "value1_1");
+map.add("key2", "value2_1");
+
+// later
+map.add("key1", "value1_2");
+logger.debug("Values on key1: {}", map.getAll("key1")); // Values on key1: ["value1_1", "value1_2"]
+logger.debug("Values on key2: {}", map.getAll("key2")); // Values on key2: ["value2_1"]
+
+// set a value (-> removes existing information)
+map.set("key1", "value1_3");
+logger.debug("Values on key1: {}", map.getAll("key1")); // Values on key1: ["value1_3"]
+```
+
+As you can see, a multi map can store multiple strings in one keyslot.
+
+## Telestion Header Information
+
+Telestion uses the same approach as the Vert.x Multi Map and provides a similar interface but with support
+for all primitive data types in Java.
+
+Look at the following example:
+
+```java
+// create new and empty header information
+var information = new HeaderInformation();
+
+// add some values
+information.add("key1", true).add("key2", 42);
+
+// and extract them again
+logger.debug("Boolean value on key1: {}", information.getBoolean("key1"));
+logger.debug("Integer value on key2: {}", information.getInteger("key2"));
+```
+
+As you can see, the Telestion Header Information API follows the Vert.x Multi Map API
+and also provides support for other data types, e.g. booleans or integers.
+
+## Headers and messages
+
+Headers can be attached to message before they pass the event bus and can be extracted
+on the the receiving side.
+
+The attached headers aren't part of the body and reside next to the content.
+
+<Image
+	src="/static/img/drawio-diagrams/vertx/message-structure.drawio.svg"
+	invertible
+    center
+/>
+
+Take a look at the following example:
+
+```java title="PublishVerticle.java"
+public class PublishVerticle extends TelestionVerticle<NoConfiguration> implements WithEventBus {
+    @Override
+    public void onStart() {
+        var information = new HeaderInformation().add("send-time", System.currentTimeInMillis());
+        // attach information to publish message
+        publish("some-address", "Important information", information);
+    }
+}
+```
+
+```java title="ReceiveVerticle.java"
+public class ReceiveVerticle extends TelestionVerticle<NoConfiguration> implements WithEventBus {
+    @Override
+    public void onStart() {
+        register("some-address", message -> {
+            // extract information from received message
+            var receivedInformation = HeaderInformation.from(message);
+            logger.debug("Received content: {}", message.body());
+            logger.debug("Send time: {}", receivedInformation.getLong("send-time"));
+        });
+    }
+}
+```
+
+As you can see, Telestion provides excellent support for Vert.x Multi Maps
+and Telestion Header Information especially in verticles.
+
+## See also
+
+<Reference to="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers">
+    HTTP Headers
+</Reference>
+
+<Reference to="https://javadoc.io/static/io.vertx/vertx-core/4.2.6/index.html?io/vertx/core/MultiMap.html">
+    <code>MultiMap</code> API reference
+</Reference>
+
+<Reference to="https://javadoc.io/doc/de.wuespace.telestion/telestion-api/latest/de/wuespace/telestion/api/message/HeaderInformation.html">
+    <code>HeaderInformation</code> API reference
+</Reference>
+
+<Reference to="/application/concepts/traits/">
+    Traits concept
+</Reference>
+
+<Reference to="https://javadoc.io/doc/de.wuespace.telestion/telestion-api/latest/de/wuespace/telestion/api/verticle/trait/WithEventBus.html">
+	<code>WithEventBus</code> API reference
+</Reference>
+
+<!--
+Snippets
+--------
+
+<Reference to="../other-article">
+    Relative Link to other article
+</Reference>
+
+<Reference to="https://www.example.com">
+    Example Website
+</Reference>
+-->