Commit f95dc740 authored by  Hayley Patton's avatar Hayley Patton 🐢

Update the README

parent cb81e266
......@@ -14,55 +14,11 @@ It uses a distributed hash table, digital signatures and a collection of
relatively simple text formats to allow objects to be stored without possibly
being tampered with, regardless of implementation or application details.
There's a lot of those, because they were unhappy with the already existing
thingamabobs for whatever reason. We're unhappy with the already existing
thingamabobs because:
- (Most) federated systems have central points of failure, in that a user's
identity is connected to a single server or domain. When one server goes down,
it is true that the rest of the network is unaffected, but users of that
server are unable to do anything about it. Clever users might try to avoid
this by creating multiple identities across several servers, but those are
still different to the system and can't be used interchangably.
- Most federated systems also tend to have users cluster around a few servers,
usually those hosted and promoted by the developers of those systems. This may
be because vetting the moderation behaviour and community of other servers is
difficult; which leads to:
- Federated systems can be tampered with to some extent by server operators.
This is usually localised to the content provided by the server, but that is
a lot of power, including sending messages from identities without their
owners' permission.
- Typically, operators play the role of moderators as well; and the excuse is
usually that if one does not like the moderation of one server, they are "free" to
leave for another, which is *incredibly* impolite.
We feel obligated to state that it's analogous to "suggesting" that one should
leave their country if they are not happy with how it is governed, which they
often find unhelpful, except that finding another server is usually easier
than moving to another country.
- The other hyped system is to use a blockchain; the proof-of-work sorts
consume [obscene amounts of electricity](https://digiconomist.net/bitcoin-energy-consumption)
comparable to that of entire countries,
- Blockchains also have large storage overheads as every "full" node has to replicate
the entire blockchain. (However, I read Ethereum is going to implement
["sharding"](https://github.com/ethereum/wiki/wiki/Sharding-FAQ) to
reduce this overhead, which distributes the load like a distributed hash-table
would.)
- They also require some sort of currency to be run on the network to provide
an "incentive" for running the infrastructure (but only if you're a miner;
node operators don't get a cent!) and promote the a "rich get richer" feedback
loop that creates centralisation.
- Another note is that few systems are sufficiently "general", which we consider
to be the range of programs one can express while using a system as it is
intended to be used. They also may not know anything about the objects they are
sending, blindly sending blocks of text or barely-structured data around.
We intend to improve on these systems by:
- using identities that aren't tied to servers or domains. Netfarm uses a
hash of a user information object, which includes their public keys, as
a universal identifier for a user,
We intend to improve on other internet thingamabobs by:
- using identities and data that aren't tied to servers or domains. Netfarm
uses a hash of a user information object, which includes their public keys,
as a universal identifier for a user,
- storing objects across a distributed hash-table to reduce the load on
each node, and using the Kademlia algorithms to provide simple and efficient
object retrieval,
......@@ -79,16 +35,9 @@ We intend to improve on these systems by:
- providing reproducible side effects and scripting using a bytecode interpreter
and separate computed values
## Implementation notes
This implementation makes extensive use of the Common Lisp Object System's
meta-object protocol to create objects which are both easily consumed by
the portability layers in the Netfarm library and user code, with relatively
little marshalling; creating classes on the fly when objects are found with
schemas the application has had hard-coded, ensuring classes have
representations that other implementations can use, and providing a protocol
to navigate objects that application code has not seen before similar to the
CLOS protocol for slots.
For more details on why Netfarm may be more useful than other thingamabobs,
read the introduction of
[the Netfarm book](https://cal-coop.gitlab.io/netfarm/documentation/).
## Installing
......@@ -102,20 +51,23 @@ CLOS protocol for slots.
2. **Download Netfarm.** Similarly, you need to put Netfarm somewhere Quicklisp
looks. Hopefully you have the URL since either you're looking at the README
there, or you've downloaded this library already.
3. **Download cl-decentralise2.**
3. If you want to test out networking, **Download cl-decentralise2.**
[decentralise2](https://gitlab.com/cal-coop/netfarm/cl-decentralise2)
is a library we wrote to handle object synchronisation and things like that
so that the Netfarm library could be mostly independent of network code, and
to ensure that the interactions between Netfarm and decentralise2 code are
minimal.
**Download netfarm-networking.**
[netfarm-networking](https://gitlab.com/cal-coop/netfarm/netfarm-networking)
glues decentralise2 and Netfarm together, as to not clutter the object-system
code repository.
## Examples
Cool, what can you do now?
- Write out a random Lisp object to its Netfarm form then parse it back into Lisp.
We can take lists, strings, integers, byte vectors and booleans (encoded as
`:true` or `:false`).
- Write out a random Lisp object to its Netfarm form then parse it back into
Lisp data
We can take lists, strings, integers, byte vectors and booleans (encoded as
`:true` or `:false`).
```lisp
CL-USER> (netfarm:render 42)
......@@ -125,9 +77,10 @@ CL-USER> (netfarm:parse *)
```
- Create a class and render an instance of it:
As mentioned previously, this implementation of Netfarm hooks into the
meta-object protocol by providing a metaclass `netfarm:netfarm-class`. A hash
of the class will be used to identify the schema, as will every Netfarm object.
As mentioned previously, this implementation of Netfarm hooks into the
meta-object protocol by providing a metaclass `netfarm:netfarm-class`. A hash
of the class will be used to identify the schema, as will every Netfarm
object.
```lisp
CL-USER> (defclass foo-class ()
......@@ -173,10 +126,10 @@ Slots with :INSTANCE allocation:
COMPUTED-VALUES = #<HASH-TABLE :TEST EQUAL :COUNT 0 {100DDA3BF3}>
SOURCE = NIL
NAME = NIL
```
```
You can also experiment with the server and client using a
"passing connection" from decentralise2:
"passing connection" from decentralise2, after cloning the networking code:
```lisp
CL-USER> (ql:quickload '(:netfarm-client :netfarm-server))
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment