simon/dog-and-duck
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity
dog-and-duck/docs/codox/intro.html

102 lines
16 KiB
HTML
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html PUBLIC ""
"">
<html><head><meta charset="UTF-8" /><title>The Old Dog and Duck</title><link rel="stylesheet" type="text/css" href="css/default.css" /><link rel="stylesheet" type="text/css" href="css/highlight.css" /><script type="text/javascript" src="js/highlight.min.js"></script><script type="text/javascript" src="js/jquery.min.js"></script><script type="text/javascript" src="js/page_effects.js"></script><script>hljs.initHighlightingOnLoad();</script></head><body><div id="header"><h2>Generated by <a href="https://github.com/weavejester/codox">Codox</a></h2><h1><a href="index.html"><span class="project-title"><span class="project-name">Dog-and-duck</span> <span class="project-version">0.1.0</span></span></a></h1></div><div class="sidebar primary"><h3 class="no-link"><span class="inner">Project</span></h3><ul class="index-link"><li class="depth-1 "><a href="index.html"><div class="inner">Index</div></a></li></ul><h3 class="no-link"><span class="inner">Topics</span></h3><ul><li class="depth-1 "><a href="Desiderata.html"><div class="inner"><span>Desiderata</span></div></a></li><li class="depth-1 "><a href="Using_ActivityPub.html"><div class="inner"><span>Using ActivityPub</span></div></a></li><li class="depth-1 "><a href="Validation_Faults.html"><div class="inner"><span>Validation Faults in ActivityPub documents</span></div></a></li><li class="depth-1 current"><a href="intro.html"><div class="inner"><span>The Old Dog and Duck</span></div></a></li></ul><h3 class="no-link"><span class="inner">Namespaces</span></h3><ul><li class="depth-1"><div class="no-link"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>dog-and-duck</span></div></div></li><li class="depth-2"><div class="no-link"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>quack</span></div></div></li><li class="depth-3 branch"><a href="dog-and-duck.quack.cli.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>cli</span></div></a></li><li class="depth-3"><a href="dog-and-duck.quack.picky.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>picky</span></div></a></li><li class="depth-4 branch"><a href="dog-and-duck.quack.picky.collections.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>collections</span></div></a></li><li class="depth-4 branch"><a href="dog-and-duck.quack.picky.constants.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>constants</span></div></a></li><li class="depth-4 branch"><a href="dog-and-duck.quack.picky.control-variables.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>control-variables</span></div></a></li><li class="depth-4 branch"><a href="dog-and-duck.quack.picky.distribution.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>distribution</span></div></a></li><li class="depth-4 branch"><a href="dog-and-duck.quack.picky.objects.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>objects</span></div></a></li><li class="depth-4 branch"><a href="dog-and-duck.quack.picky.scratch.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>scratch</span></div></a></li><li class="depth-4 branch"><a href="dog-and-duck.quack.picky.time.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>time</span></div></a></li><li class="depth-4"><a href="dog-and-duck.quack.picky.utils.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>utils</span></div></a></li><li class="depth-3"><a href="dog-and-duck.quack.quack.html"><div class="inner"><span class="tree" style="top: -269px;"><span class="top" style="height: 278px;"></span><span class="bottom"></span></span><span>quack</span></div></a></li><li class="depth-2"><div class="no-link"><div class="inner"><span class="tree" style="top: -362px;"><span class="top" style="height: 371px;"></span><span class="bottom"></span></span><span>scratch</span></div></div></li><li class="depth-3 branch"><a href="dog-and-duck.scratch.parser.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>parser</span></div></a></li><li class="depth-3"><a href="dog-and-duck.scratch.scratch.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>scratch</span></div></a></li><li class="depth-2"><div class="no-link"><div class="inner"><span class="tree" style="top: -83px;"><span class="top" style="height: 92px;"></span><span class="bottom"></span></span><span>utils</span></div></div></li><li class="depth-3"><a href="dog-and-duck.utils.process.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>process</span></div></a></li></ul></div><div class="document" id="content"><div class="doc"><div class="markdown"><h1><a href="#the-old-dog-and-duck" name="the-old-dog-and-duck"></a>The Old Dog and Duck</h1>
<p>A Clojure library designed to implement the ActivityPub protocol, obviously.</p>
<p><img src="https://simon-brooke.github.io/dog-and-duck/images/Dog_and_Duck_tavern.jpg" alt="The Dog and Duck, St George’s Fields, London, 1647" /></p>
<h2><a href="#introduction" name="introduction"></a>Introduction</h2>
<p>The Old Dog and Duck is clearly a pub, and it’s a pub related to an activity; to whit, hunting ducks with dogs. Yes, of course one could also hunt dogs with ducks, but in practice that doesn’t work so well. The point isn’t whether or not I approve of hunting ducks with dogs (or vice versa); to be clear, I don’t. The point is that it’s a pub related to an activity, and is therefore an <a href="https://www.w3.org/TR/activitypub/">ActivityPub</a>.</p>
<p>Are we clear?</p>
<p>Good.</p>
<p>Let us proceed.</p>
<p><strong>The Old Dog and Duck</strong> is intended to be a set of libraries to enable people to build stuff which interacts with ActivityPub. It isn’t intended to be a replacement for, or clone of, Mastodon. I do think I might implement my own ActivityPub server on top of The Old Dog and Duck, that specifically might allow for user-pluggable feed-sorting algorithms and with my own user interface/user experience take, but that project is not (yet, at any rate) this project.</p>
<h2><a href="#status" name="status"></a>Status</h2>
<p>This is still pre-alpha. Everything will change. There’s still a lot of code that was written when I was feeling my way around the problems, which is redundant and should now be pruned. Feel free to play, but do so at your own risk. Contributions welcome.</p>
<h2><a href="#usage" name="usage"></a>Usage</h2>
<p>At present, only the duck-typing validator works. To play with it, build the uberjar (or download it from github) and run it with</p>
<pre><code>java -jar target/dog-and-duck-0.1.0-standalone.jar -i resources/activitystreams-test-documents/vocabulary-ex10-jsonld.json -f html -o report.html -s info
</code></pre>
<p>The full range of command-line switches is as follows:</p>
<pre><code> -i, --input SOURCE standard input The file or URL to validate
-o, --output DEST standard output The file to write to, defaults to standard out
-f, --format FORMAT :edn The format to output, one of `edn` `csv` `html`
-l, --language LANG en-GB The ISO 639-1 code for the language to output
-s, --severity LEVEL :info The minimum severity of faults to report
-h, --help Print this message and exit
</code></pre>
<p>Note, though, that internationalisation files for languages other than British English have not yet been written, and that one is not complete.</p>
<p>The following severity levels are understood:</p>
<ol>
<li><code>info</code> things which are not actuallys fault, but issues noted during validation;</li>
<li><code>minor</code> things which I consider to be faults, but which don’t actually breach the spec;</li>
<li><code>should</code> instances where the spec says something <em>SHOULD</em> be done, which isn’t;</li>
<li><code>must</code> instances where the spec says something <em>MUST</em> be done, which isn’t;</li>
<li><code>critical</code> instances where I believe the fault means that the object cannot be meaningfully processed.</li>
</ol>
<p>Note that it is almost certain that in some places I have misinterpreted the spec. Of all 205 documents in the <a href="https://github.com/w3c-social/activitystreams-test-documents">activitystreams-test-documents repository</a>, not a single one passes validation, and that must be wrong.</p>
<p>Nevertheless I think that this is a basis on which a useful validator can be built. Feedback and contributions welcome.</p>
<h2><a href="#documentation" name="documentation"></a>Documentation</h2>
<p>Full documentation is <a href="https://simon-brooke.github.io/dog-and-duck/">here</a>.</p>
<h2><a href="#architecture" name="architecture"></a>Architecture</h2>
<p>There are a number of separate concerns required to implement ActivityPub. They include</p>
<ol>
<li>Parsing ActivityStreams messages received from peers and from clients;</li>
<li>Persisting ActivityStreams objects;</li>
<li>Delivering ActivityStreams objects to peers;</li>
<li>Delivering ActivityStreams objects to clients.</li>
</ol>
<h2><a href="#some-motivations" name="some-motivations"></a>Some motivations</h2>
<h3><a href="#empowering-users" name="empowering-users"></a>Empowering users</h3>
<p>The <a href="https://www.w3.org/TR/activitypub/#Overview">ActivityPub spec</a> starts by saying:</p>
<blockquote>
<p>ActivityPub provides two layers:</p>
<ol>
<li>A server to server federation protocol (so decentralized websites can share information)</li>
<li>A client to server protocol (so users, including real-world users, bots, and other automated processes, can communicate with ActivityPub using their accounts on servers, from a phone or desktop or web application or whatever).</li>
</ol>
</blockquote>
<p>I’m interested in driving much more functionality down to the the client, for example feed ordering and presentation. This would allow users, for example, to choose their own (or roll their own) feed-ordering algorithms.</p>
<p>My proposal would be to deliver exactly the same ActivityStreams format to my client as to other servers. There may be a valid reason for not doing this, but if there is I will discover it in due course.</p>
<h3><a href="#enhanced-resiliency" name="enhanced-resiliency"></a>Enhanced resiliency</h3>
<p>The <a href="https://www.w3.org/TR/activitystreams-core/">ActivityStreams</a> spec seems predicated on ‘always up’ communication between at least servers, which is perhaps why there is a two tier network of ‘servers’ and ‘clients’. It also depends on HTTPS certificates to identify servers, which implies it’s vulnerable to disruption by a hostile actor with the ability to revoke certificates.</p>
<p>My own history with social media dates back to Usenet over UUCP, a system designed explicitly for intermittent low bandwidth connections; such a system is immensely resilient in the face of disruption to infrastructure.</p>
<p>Social media is useful to concerted popular action in periods of disruption, whether in the case of civil ememrgency such as earthquakes, wild fires and floods, in the case of wars, or in the case of intrusive surveillance by authoritarian governments. But to be useful in such situations it needs to be resilient, and one of the things it needs to be resilient to is parts of the network being intermittently available, or requiring rerouting.</p>
<p>In this I’m influenced by and hope to try to implement ideas from <a href="https://blog.locut.us/about/">Ian Clarke</a>’s <a href="https://en.wikipedia.org/wiki/Freenet">Freenet</a> and <a href="http://tahrirproject.org/">Tahrir</a> projects, especially <a href="https://en.wikipedia.org/wiki/Web_of_trust">webs of trust</a>.</p>
<p>To be clear, it is important for The Old Dog and Duck to be able to interact with other existing ‘vanilla’ ActivityStreams implementations, but I hope to experiment with enhanced communication between Dog and Duck servers to provide more FreeNet-like resiliency.</p>
<h2><a href="#proposed-dog-and-duck-libraries" name="proposed-dog-and-duck-libraries"></a>Proposed dog-and-duck libraries</h2>
<p><strong>NOTE THAT</strong> at the present stage all the proposed libraries are in one package, namely this package, but that it is proposed that in future they will form separate libraries in separate packages.</p>
<h3><a href="#bar" name="bar"></a>Bar</h3>
<p>Where conversations happen. Handle interactions with clients.</p>
<h3><a href="#cellar" name="cellar"></a>Cellar</h3>
<p>Where things are stored. Persistance for ActivityStreams objects; I may at least initially simply copy the Mastodon postgres schema, but equally I may not.</p>
<h3><a href="#pantry" name="pantry"></a>Pantry</h3>
<p>Where deliveries are ordered and arrive; and from where deliveries onwards are despatched. Handle interactions with peers.</p>
<h3><a href="#quack" name="quack"></a>Quack</h3>
<p>Duck-typing for ActivityStreams objects.</p>
<p>As of version 0.1.0, this is substantially the only part that is yet at all useful, and it is still a long way from finished or robust.</p>
<h3><a href="#bouncer" name="bouncer"></a>Bouncer</h3>
<p>Enhanced tools for moderators (I have as yet absolutely no idea what this looks like).</p>
<h3><a href="#scratch" name="scratch"></a>Scratch</h3>
<p>What the dog does when bored. Essentially, a place where I can learn how to make this stuff work, but perhaps eventually an ActivityPub server in its own right.</p>
<h2><a href="#building" name="building"></a>Building</h2>
<h3><a href="#clj-activitypub" name="clj-activitypub"></a>clj-activitypub</h3>
<p><strong>NOTE THAT</strong> <code>dog-and-duck</code> depends on Jahfer’s <code>clj-activitypub</code>, which is also currently not yet released and under rapid development and consequently currently <em>very</em> unstable. For this reason it’s probably best to clone <a href="https://github.com/simon-brooke/clj-activitypub">my fork</a> rather than <a href="https://github.com/jahfer/clj-activitypub">the original</a>, because that way you are less likely to encounter version incompatibilities.</p>
<p><code>clj-activitypub</code> is configured to build with <a href="https://clojure.org/guides/tools_build">tools.bui;d</a>. To prepare <code>clj-activitypub</code> before building <code>dog-and-duck</code>, do</p>
<pre><code class="bash">$ git clone git@github.com:simon-brooke/clj-activitypub.git
$ cd clj-activitypub/
$ clj -T:build jar
$ clj -T:build install
</code></pre>
<p>I shall keep <code>dog-and-duck</code> and my fork of <code>clj-activitypub</code> in sync at least until Jahfer makes a production release of his project to <a href="">Clojars</a>.</p>
<h3><a href="#leiningen" name="leiningen"></a>Leiningen</h3>
<p><code>dog-and-duck</code> itself is still set up to build with <a href="https://leiningen.org/">Leiningen</a>. Yes, I know that’s not what the cool kids are using any more but hey, I’m an old man, leave me be. To get <code>dog-and-duck</code> up to a point where you can start to play,</p>
<pre><code class="bash">$ git clone git@github.com:simon-brooke/dog-and-duck.git
$ cd dog-and-duck
$ lein repl
</code></pre>
<h2><a href="#testing" name="testing"></a>Testing</h2>
<p>Prior to testing, you should clone <a href="https://github.com/w3c-social/activitystreams-test-documents">activitystreams-test-documents</a> into the <code>resources</code> directory. You can then test with</p>
<pre><code class="bash">lein test
</code></pre>
<h2><a href="#license" name="license"></a>License</h2>
<p>Copyright © Simon Brooke, 2022.</p>
<p>This program and the accompanying materials are made available under the terms of the GNU General Public License as published by the Free Software Foundation, either version 2 of the License, or (at your option) any later version.</p></div></div></div></body></html>
Reference in a new issue View git blame Copy permalink