Core Concepts

Edsu is a network protocol, an old school one: all connections are between a client and a server, it's mostly text-based, it leans heavily on DNS and SSL/TLS, and it's federated like the ancient HTTP and SMTP protocols.

In terms of complexity and features, it's at about the level of a disk-based filesystem: more than a collection of blocks (like IDE or SCSI), but less than, say, an RDBMS or even some NoSQL databases. However, it's enough to build secure, sophisticated, multi-user applications.

The Edsu protocol is built of messages in plain text, like this:

edsu block-put payload-stop END ~ Hello world! END

Which we'll be representing visually like this:

block-put
payload-stop END
Hello world!

An Edsu server provides the following services:

Edsu is designed to be compact - this is all accomplished using the following nine messages:

hello
block-put
block-get
name-put
name-get
name-append
sub-put
sub-clear
ping

Block Storage

Blocks are immutable sequences of bytes, represented by a hash. There are two client messages related to blocks, one of which you've seen already:

block-put
payload-stop END
Hello world!

If the server gets the above message, it will respond with:

ok
hash QmNTPrxjHgastHFGJa3eJ8q6dqVaM4tJ3bFuVGhCz1E114

The block is now stored. The hash in this message is a multihash, as defined by the the IPFS project (Edsu and IPFS share similar goals, but have different ways of getting there).

If the client then later sends this message, containing that hash we got:

block-get
hash QmNTPrxjHgastHFGJa3eJ8q6dqVaM4tJ3bFuVGhCz1E114

The server will reply with the original block:

block
channel 0
payload-length 13
Hello world!

That's content-address storage: the block's contents (hashed) are used to reference it when you want to retrieve it from storage. Like any address, you can send that hash far and wide, and people can then use it to retrieve your block.

That's great, but what if later my mood changes and I want to tone it down a bit to "Oh hi world."? Then the hash will, of course, change. Which means that you'd have to tell everyone all over again what the new hash is.

This is where the naming system comes in.

The Name System

A name is a series of segments separated by dots. If I send the message:

name-put
name pub.app.edsu-org.hello-world.text
hash QmNTPrxjHgastHFGJa3eJ8q6dqVaM4tJ3bFuVGhCz1E114

The server will associate that name with that hash.

You can then get the association back again with:

name-get
name pub.app.edsu-org.hello-world.text

To which the server will respond with:

name
channel 0
name pub.app.edsu-org.hello-world.text
hash QmNTPrxjHgastHFGJa3eJ8q6dqVaM4tJ3bFuVGhCz1E114

Names are a layer of indirection that makes Edsu storage dynamic, even though blocks are immutable. So in the above mood-changing scenario, if I wanted to change the hello-world text I would hand out a name instead of a hash, and then change which block that name pointed to.

Naming a blocks has an additional important function: it stops them from getting deleted. Edsu has garbage collection for blocks; every block needs an "owner" - either a name or another block that contains its hash - or it will eventually be collected.

Pub/sub

Names also form the basis of Edsu's pub/sub system. If your friends, for whatever reason, were keenly interested your hello-world greeting and wanted to know the second that it changes, they can send your server this message:

sub-put
name pub.app.edsu-org.hello-world.text

From then on, whenever you change the name to point to a new block, they'll get:

sub-notify
channel 0
name pub.app.edsu-org.hello-world.text
hash QmNTPrxjHgastHFGJa3eJ8q6dqVaM4tJ3bFuVGhCz1E114

Where the hash is the new one you just associated with the name using a name-put message.

Permissions

Edsu has a fine-grained permissions system. When you connect to a user's Edsu server, you can identify yourself in one of three ways:

If you're anonymous, you can only block-get and name-get, and only with names beginning with "pub.".

Visitors can additionally name-get names beginning with "grp." (which stands for group), and then only if the owner has allowed them specifically by adding their username to a list of approved users.

Visitors are also able to send name-append messages, which look like this:

name-append
name grp.app.edsu-org.appender.saying-hello
hash QmNTPrxjHgastHFGJa3eJ8q6dqVaM4tJ3bFuVGhCz1E114

This lets them write to other users' storage, but only in an extremely limited way: A) they must be permitted (again, by being on a list of approved usernames), and B) they can only add a hash to a list (about 80 bytes) and then only at a specified maximum rate. Despite these limitations, this is enough to build a multiparty communications system.

Finally, if you connect as an owner, you do so using a token. This token grants capabilities (i.e. which names you can read and modify, and in what ways). This capabilities system enables the user to grant fine-grained access to their data to each different app that they use.