add varlink note

Signed-off-by: Robert Günzler <r@gnzler.io>

5 files changed, 78 insertions, 0 deletions

diff --git a/src/inc/index.htm b/src/inc/index.htm
index fdd90d9..66353ee 100644
--- a/src/inc/index.htm
+++ b/src/inc/index.htm
@@ -22,5 +22,6 @@
 <li><a href="/site/sony-wf1000xm3-battery.html">sony-wf1000xm3-battery</a></li>
 <li><a href="/site/toyama.html">toyama</a></li>
 <li><a href="/site/unicode-range.html">unicode-range</a></li>
+<li><a href="/site/varlink.html">varlink</a></li>
 <li><a href="/site/yamanashi.html">yamanashi</a></li>
 </ul>
diff --git a/src/inc/notes.htm b/src/inc/notes.htm
index a6f9d3f..fbf96f3 100644
--- a/src/inc/notes.htm
+++ b/src/inc/notes.htm
@@ -1,5 +1,6 @@
 <!-- Generated file, you may edit and discard notes.md :) -->
 <ul>
+<li><code>2025-11-12</code> — {varlink}</li>
 <li><code>2025-05-14</code> — {porta}</li>
 <li><code>2025-03-07</code> — {unicode-range}</li>
 <li><code>2025-01-24</code> — {plan9-cursors}</li>
diff --git a/src/inc/notes.md b/src/inc/notes.md
index 56f0b7b..0d6d298 100644
--- a/src/inc/notes.md
+++ b/src/inc/notes.md
@@ -1,3 +1,4 @@
+* `2025-11-12` —  {varlink}
 * `2025-05-14` —  {porta}
 * `2025-03-07` —  {unicode-range}
 * `2025-01-24` —   {plan9-cursors}
diff --git a/src/inc/varlink.htm b/src/inc/varlink.htm
new file mode 100644
index 0000000..7de95de
--- /dev/null
+++ b/src/inc/varlink.htm
@@ -0,0 +1,33 @@
+<!-- Generated file, you may edit and discard varlink.md :) -->
+<p><a href="https://varlink.org" target="_blank">varlink</a> is a neat
+little standard for doing debuggable IPC. It takes some of the nice
+properties of DBUS, like the introspection capabilities, and combines
+them with simple standard tools/technologies in the form of unix sockets
+and JSON.</p>
+<p>For C, there is a library by <a href="https://emersion.fr"
+target="_blank">emersion</a> called vali, which does pretty much all you
+need to get going: <a
+href="https://emersion.fr/blog/2025/announcing-vali/" class="uri"
+target="_blank">https://emersion.fr/blog/2025/announcing-vali/</a></p>
+<p>When you have written your service, here is how to interact with it
+just using standard utils, socat and jq:</p>
+<div class="sourceCode" id="cb1"><pre class="sourceCode sh"><code class="sourceCode bash"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a><span class="fu">cat</span> <span class="op">&lt;&lt;-EOF</span> <span class="kw">|</span> <span class="ex">jq</span> <span class="at">--raw-output0</span> <span class="kw">|</span> <span class="ex">socat</span> STDIO UNIX-CONNECT:<span class="st">&quot;</span><span class="va">$SOCKET</span><span class="st">&quot;</span> <span class="kw">|</span> <span class="ex">jq</span></span>
+<span id="cb1-2"><a href="#cb1-2" aria-hidden="true" tabindex="-1"></a><span class="st">    {</span></span>
+<span id="cb1-3"><a href="#cb1-3" aria-hidden="true" tabindex="-1"></a><span class="st">        &quot;method&quot;: &quot;org.varlink.service.GetInfo&quot;,</span></span>
+<span id="cb1-4"><a href="#cb1-4" aria-hidden="true" tabindex="-1"></a><span class="st">    }</span></span>
+<span id="cb1-5"><a href="#cb1-5" aria-hidden="true" tabindex="-1"></a><span class="op">EOF</span></span></code></pre></div>
+<p>This is equivalent to using the varlink cli tool and running:
+<code>varlink info $SOCKET</code></p>
+<div class="sourceCode" id="cb2"><pre class="sourceCode sh"><code class="sourceCode bash"><span id="cb2-1"><a href="#cb2-1" aria-hidden="true" tabindex="-1"></a><span class="fu">cat</span> <span class="op">&lt;&lt;-EOF</span> <span class="kw">|</span> <span class="ex">jq</span> <span class="at">--raw-output0</span> <span class="kw">|</span> <span class="ex">socat</span> STDIO UNIX-CONNECT:<span class="st">&quot;</span><span class="va">$SOCKET</span><span class="st">&quot;</span> <span class="kw">|</span> <span class="ex">jq</span></span>
+<span id="cb2-2"><a href="#cb2-2" aria-hidden="true" tabindex="-1"></a><span class="st">    {</span></span>
+<span id="cb2-3"><a href="#cb2-3" aria-hidden="true" tabindex="-1"></a><span class="st">        &quot;method&quot;: &quot;org.varlink.service.GetInterfaceDescription&quot;,</span></span>
+<span id="cb2-4"><a href="#cb2-4" aria-hidden="true" tabindex="-1"></a><span class="st">        &quot;parameters&quot;: {</span></span>
+<span id="cb2-5"><a href="#cb2-5" aria-hidden="true" tabindex="-1"></a><span class="st">            &quot;interface&quot;: &quot;com.example.Foobar&quot;</span></span>
+<span id="cb2-6"><a href="#cb2-6" aria-hidden="true" tabindex="-1"></a><span class="st">        }</span></span>
+<span id="cb2-7"><a href="#cb2-7" aria-hidden="true" tabindex="-1"></a><span class="st">    }</span></span>
+<span id="cb2-8"><a href="#cb2-8" aria-hidden="true" tabindex="-1"></a><span class="op">EOF</span></span></code></pre></div>
+<p>This will return the service interface (if the service listening at
+the socket actually implements it.</p>
+<p>Note the use of <code>jq --raw-output0</code>. It is possible to omit
+the jq invocations, the input JSON data should be followed by a NUL
+byte.</p>
diff --git a/src/inc/varlink.md b/src/inc/varlink.md
new file mode 100644
index 0000000..bb65dea
--- /dev/null
+++ b/src/inc/varlink.md
@@ -0,0 +1,42 @@
+[varlink][1] is a neat little standard for doing debuggable IPC. It takes some
+of the nice properties of DBUS, like the introspection capabilities, and
+combines them with simple standard tools/technologies in the form of unix
+sockets and JSON.
+
+For C, there is a library by [emersion][2] called vali, which does pretty much
+all you need to get going: https://emersion.fr/blog/2025/announcing-vali/
+
+When you have written your service, here is how to interact with it just using
+standard utils, socat and jq:
+
+```sh
+cat <<-EOF | jq --raw-output0 | socat STDIO UNIX-CONNECT:"$SOCKET" | jq
+    {
+        "method": "org.varlink.service.GetInfo",
+    }
+EOF
+```
+
+This is equivalent to using the varlink cli tool and running:
+`varlink info $SOCKET`
+
+```sh
+cat <<-EOF | jq --raw-output0 | socat STDIO UNIX-CONNECT:"$SOCKET" | jq
+    {
+        "method": "org.varlink.service.GetInterfaceDescription",
+        "parameters": {
+            "interface": "com.example.Foobar"
+        }
+    }
+EOF
+```
+
+This will return the service interface (if the service listening at the socket
+actually implements it.
+
+Note the use of `jq --raw-output0`. It is possible to omit the jq invocations,
+the input JSON data should be followed by a NUL byte.
+
+
+[1]: https://varlink.org
+[2]: https://emersion.fr