vertex ought to be (primarily) an agent, not a library

[glyph]

First and foremost: writing applications that use Vertex should be easy from any language, not just Python. This means we need to make it reusable across different languages, which means requiring as little of it to be in-process as possible.

Also, the local instance of Vertex stores some sensitive information: the user's private keys, their buddy list, and their trust store. There's no reason that any application should be able to read this information.

[glyph]

One of the early sub-tasks here is to make a Twisted client library which allows an arbitrary Twisted app talk to a vertex agent. The form of this API should be endpoint string descriptions - both client and server.

Such an endpoint might be:

--listen vertex:an-interesting-app

"I am a vertex service listening on the an-interesting-app protocol, on whatever the default registered user's Q2Q ID is"

or (if you have multiple accounts)

--listen vertex:an-interesting-app:me@myhost.example.com

which hopefully I can leave as an exercise for the reader. Symmetrically there would be a client endpoint syntax like:

--connect vertex:you@yourhost.example.com:an-interesting-app

and similarly the current user's Q2Q ID could be implied, or specified, analogously to the TCP bindAddress parameter.

[glyph]

The Q2Q "protocol" field here - an-interesting-app - is analogous to the TCP "listening port"; it's the thing-about-which users may want to communicate. (There's still a lot of convention to be worked out here; it might be useful to have some kind of path convention for these, or maybe reverse FQDN notation... this has an implication for discoverability but probably doesn't need to be part of this layer of the API)

[glyph]

Another important feature is --connect vertex:select or somesuch; an endpoint syntax which leaves selecting the relevant endpoint up to user interaction.

[glyph]

Allowing the user to select a connection peer this way is important because we may not want to disclose to the application what peers are available. In other words, the vertex agent presents a buddy list.