You are reading content from Scuttlebutt
@gwil

ssb-patchql client devdiary 26/04/2019

Getting up and running

  • Pulled down new changes
  • Rebuilt
  • Deleted and recreated dev.sqlite
  • Got the server running
  • Ran the process mutation again

And querying the endpoint gets me posts and threads. nice.

What can ssb-patchql tell us?

Let's get into the mindset of potential client authors. They possibly know a bit about how SSB works, that all data is stored locally and replicated to other devices via local connections and pubs – but all the guts of how it really works is a mystery. All they really care about is getting data regarding messages and the authors who create them, and exposing that via some kind of interface.

They're going to be using the schema of ssb-patchql to guide them, to tell them what data is available and how they can interact with it. How do we find out what the schema can do for us?

In addition the user-defined fields, a schema's Query type also has __schema and __type fields that can tell us what kind of data we can ask for from this endpoint. This is how the GraphiQL tool automatically creates docs from a schema: it sends an introspection query and uses that response to create the interactive docs.

We can also use the response to an introspection query to build a GraphQL SDL representation of the schema. This representation is useful both for humans who want to understand the shape of a schema, and for development tooling that can do stuff like validate queries in your source.

Here's the SDL of ssb-patchql's schema as of today, in a gist: https://gist.github.com/sgwilym/ea96ec2904745ac7c57bca4af78abefd

Taken from there, here's the definition of the post Post type:

type Post {
  id: String!
  author: Author!
  likes: [Like!]!
  likesConnection: LikeConnection!
  text: String!
  forksFromKey: String
  rootKey: String
  references: [Post!]!
  forks: [Post!]!
}

The properties of Post are the fields we can query, and the values are what kind of data will be returned. An exclamation mark indicates the value is non-nullable, and [] brackets indicate a list of that data type will be returned.

Reading the SDL

Now that I have the whole schema in one place, here's the stuff that jumps out at me – a mixture of things I'd like and things I don't understand:

  • Author
    • Can name really be nullable?
    • Are posts or threads fields planned?
  • ContactState
    • Past tense (e.g. FOLLOWED) would make these look more like states that actions, but that's a nitpick.
  • DbMutation
    • Eventually this endpoint will be able to do more than just process things for the local DB, right? Like create new posts?
  • Like
    • What does the value of a like indicate?
  • Post
    • What are Post's forks? Are they represented as replies in clients like Patchbay?
  • PublicPrivateContactStatus
    • How can users have separate public and private contact states?
  • The connection types are very heavy, i.e. they have a lot of arguments. That threads ORs all the conditions while posts ANDs them is definitely going to result in some hair pulling for someone out there, even if there are descriptions saying so. An approach many GraphQL APIs take is to provide more use-case focused, specialised fields e.g. postsAuthoredBy(id: ID!): PostConnection!.

To me, the gaping whole here there is no way to get the most important information: the posts and threads of people I follow, and my profile, all within GraphQL. GraphQL APIs are usually very viewer oriented (i.e. results change depending on who is asking for it). As a client author, I'd be beelining for a field with a name like viewer or currentUser that exposes the machine's SSB profile, and gives me fields to grab the threads of people I follow, PMs, my profile info, etc.

The GraphQL API should be a one-stop-shop for clients, they shouldn't have to look anywhere outside of it for pertinent information, and they should be able to fulfil the data an interface needs in a single request (in most scenarios).

Sidethoughts

  • Would using ssb-patchql be easier to build a native iOS client, as iirc the big blocker for manyverse iOS is getting libsodium building in a non-node environment?
  • ssb-patchql being able to serve SSB data over http opens up the interesting possibility of remote SSB clients. Imagine having a Pi or something running at home that you could use to access a single SSB profile from many different devices. In exchange for requiring internet access, you circumvent issues regarding disk space and multi-user/sameAs stuff.

#dev-diaries #ssb-patchql #graphql

@Luandro
Voted this
@gwil

Small addition to the sidethought about native iOS client: make it easier to build a native iOS react native client?

@seanb

@gwil Your posts are teaching me a lot about graphql; thank you! How did you extract/create the SDL?

I can answer a few things (@Piet please correct me if I get anything wrong):

  • Author
    • Can name really be nullable?

Author name is null if the identity hasn't self-assigned a name, by posting an about message (via a profile edit in patchwork, say).

  • DbMutation
    • Eventually this endpoint will be able to do more than just process things for the local DB, right? Like create new posts?

Yes! This is blocked by the immaturity of the rust stack, but we hope to be able to author and append messages to the user's feed and gossip them out "soon".

  • Like
    • What does the value of a like indicate?

Likes are actually votes with value > 0. Seems to me that the value field could be removed from the graphql Like type (unless there are superlikes with value > 1, I suppose), or maybe Like could be replaced by type Vote { value: Int!, reason: String }?

  • PublicPrivateContactStatus
    • How can users have separate public and private contact states?

I think 'Ignore' is implemented as a private message (encrypted for only you) of type contact with "blocking": true, so you can publicly follow someone, and privately block them (to preserve your friend's feelings, I suppose). I think you could also privately follow someone, which would presumably result in your client syncing that person's feed, but people who follow you wouldn't know that you follow them, so they wouldn't sync that person's feed. ssb-patchql can't decrypt private messages yet, so there won't be any private states (afaik). (I can't find 'Ignore' in patchwork; not sure if/where it exists..)

no way to get the most important information: the posts and threads of people I follow, and my profile, all within GraphQL

This is very much a WIP, of course. At the moment, it's just consuming an offset log file which contains messages authored by a bunch of different IDs, and it doesn't have any way of knowing which ID is "me". The goal is definitely for this to eventually be the only API that a complete client app would have to talk to.

@seanb
  • Post
    • What are Post's forks? Are they represented as replies in clients like Patchbay?

Here's an example of a thread with a fork: %edp/DhZ...

(Seems that ssb-patchql doesn't currently provide the posts that reference a given post).

@gwil on his dearest's laptop

@seanb cool, thank you for the explanations! I am going to learn a lot about SSB too.

I don't have my introspection script to reference on this machine, but the npm graphql/utilities module exports a few functions you can use to create a printed SDL from an introspection query. That's how I do it, anyway.

Likes being a kind of Vote is interesting. Like you suggested, renaming the type to Vote is a good idea, and you could maybe use a union type e.g. union PostVote = Vote | Like to show that Likes are a convention within SSB.

Sorry for sounding pushy about missing fields, I completely appreciate that ssb-patchql is a work in progress!

@Connor

@mijkl check this out :)

@Connor

@Wollum you too

@maackle
Voted this
@seanb

@gwil @ home No worries! I'm very happy that you're testing this out and providing feedback, and I think Piet is too (if I can speak for him). I'm not really working on patchql directly, but I'm really excited to see it develop into a mature, friendly API layer, and I'm glad that you're lending your experience to help make that happen.

@gwil on his dearest's laptop

cc @Piet just making sure you at least get wind of these

@piet

Yay thanks for this @gwil / @gwil @ home

I've done a little more work just now.

I discovered the graphql-cli tool.

I've used it to generate a schema file which I'll keep up to date. (cc @seanb
)
It also has a linting tool built in, and I've removed something like 65 warnings, most of which were about missing documentation. So now every single bit of the api has some kind of documentation.

The linter also complains about things that don't meet the relay spec and I've been fixing those where it's easy, now I have 3 more harder ones left to do.

@piet
Voted this
@buoyantair
Voted this
@buoyantair

Oh my god, are we really going to have a GraphQL interface to interact with #sbot? And even cooler, everything in SSB stack is being rewritten in #rust via #sunrise-choir ? This is like one of the BEST software stack I have come across! :heart_eyes: @gwil ALL OF MY CHEERS TO YOU AND #sunrise-choir TEAM :heart_eyes:

@mix
Voted this
@gwil

@Piet That everything has some kind of documentation now makes me way more excited than it has any right to :smile:

@buoyantair I'm as excited as you are! I haven't done anything for ssb-patchql yet, and the #sunrise-choir team is doing a bang-up job.

@miles

boom this is just what i need in my life right now
thanks @gwil

@Georg
Voted this
@jiangplus
Voted this
@seanb
Voted this
@seanb
Voted this
@seanb
Voted this
@seanb
Voted this
@mikey
Voted this
User has chosen not to be hosted publicly
@mikey
Re: %UQ8mavv8N

hi @SoapDog!

you might be interested in what the #sunrise-choir is up to lately: :sunrise: :pray: :notes:

@mix.exe
Voted this
Join Scuttlebutt now