activitystreams2 (5 out of 5)

Minimal ActivityPub update client

Today I finished morph, a client for posting ActivityStreams2 Update activities to an endpoint. The server handles this update activity however it wants, but the obvious thing to do is take the object of the activity and make the indicated changes.

So far it:

• Doesn't have proper authentication, just a field to enter in a key that the server uses to verify me.
• Doesn't do endpoint discovery, so I have to type that in as well.
• Only understands how to display ActivityStreams2 Collections, and only knows how to edit items within the Collections.
• Specifically only knows how to add name, published and tags to items in a Collection.

Will be expanding its object editing abilities soon.

Code on github. See also: Minimal ActivityPub update endpoint.

🏷 activitypub activitystreams2 activitystreams as2 client cv hacking json morph photos php resume social socialwg swwg

Mon 30th of May 2016 at 11:28pm (-04:00)

Minimal ActivityPub update endpoint

ActivityPub updates objects by posting an ActivityStreams2 Update Activity to the authenticated user's outbox (discovered from their profile).

I store my photo albums as ActivityStreams2 Collections, so this morning I made a minimal AP-compliant update endpoint today that lets me add captions to them. This is just the server componant. It lets me do:

 curl -vX POST -H "Content-Type: application/activity+json" -H "Authorization: secret-token" -d @as-update.json https://path/to/endpoint

where as-update.json contains:

{
  "@context": "http://www.w3.org/activitystreams#",
  "type": "Update",
  "name": "Amy captioned a photo.",
  "actor": "https://rhiaro.co.uk/about#me",
  "object": {
    "id": "https://uri/of/photo.jpg",
    "name": "A brand new caption."
  }
}

So far this replaces the entire object with the object embedded in the Activity. Hopefully we'll have a syntax to indicate partial updates in AP soon.

The code (PHP) at https://path/to/endpoint contains a few functions that are at the discretion of the server (how to verify the authenticated user can write, what to do with the activity once it gets it, and exactly how to perform the update):

function verify_token($token){
    // Magic to verify token passed in Authorization header here.
    // I check it against a protected file on the server that contains a randomly generated long string.
    return $response;
}

function store_activity($activity){
    // Arbitrary server logic to store the activity that was posted.
    // I just dump the JSON in a file.
    return true;
}

function make_update($activity){
    // Arbitrary server logic to perform the update on the object.
    // I parse the value of object in the activity to work out where its data is stored in the filesystem, then rewrite the appropriate JSON file.
    return true;
}

And here's the overall flow:

// Authentication
$headers = apache_request_headers();
if(isset($headers['Authorization'])) {
  $token = $headers['Authorization'];
  $response = verify_token($token);
  $me = @$response['me'];
  $iss = @$response['issued_by'];
  $client = @$response['client_id'];
  $scope = @$response['scope'];
}else{
  header("HTTP/1.1 403 Forbidden");
  echo "403: No authorization header set.";
  exit;
}

if(empty($response)){
  // Something went wrong with verification
  header("HTTP/1.1 401 Unauthorized");
  echo "401: Access token could not be verified.";
  exit;
}elseif(stripos($me, "rhiaro.co.uk") === false || $scope != "update"){
  // The wrong person and scope was returned when the token was verified.
  header("HTTP/1.1 403 Forbidden");
  echo "403: Access token was not valid.";
  exit;
}else{

  // Verified, good to go..

  if(empty($_POST)){
    $post = file_get_contents('php://input');
  }

  if(isset($post) && !empty($post)){

    // Store activity
    $id = date("Y-m-d_h:i:s")."_".uniqid();
    if(store_activity($post)){

      // Perform the update 
      if(make_update($post)){
        header("HTTP/1.1 201 Created");
        echo "Resource updated";
      }else{
        header("HTTP/1.1 500 Internal Server Error");
        echo "500: Could not make update (probably a permissions issue). ";
      }

    }else{
      header("HTTP/1.1 500 Internal Server Error");
      echo "500: Could not store activity log (probably a permissions issue).";
    }

  }else{
    header("HTTP/1.1 400 Bad Request");
    echo "400: Nothing posted";
  }

}

?>

Obviously I've stripped out my implementation-specific stuff to make it easier to read. The actual code on my server is here: github/rhiaro/img/pub.php.

The next thing I need to do is make a client that...

• authenticates the user (I usually use IndieAuth, delegating the hardparts to https://indieauth.com),
• discovers the update endpoint from their profile (which to conform to AP right now would be via a JSON property outbox),
• presents a UI that lets the user choose a collection to edit (could be discoverable from profile via streams property, but to start with I'll probably just offer a URL input),
• posts the new values to the update endpoint.

🏷 activitypub activitystreams2 activitystreams as2 hacking json photos php server social socialwg swwg

Sat 28th of May 2016 at 8:01pm (+01:00)

Things and happenings: modelling social for the web

The online social world is simultaneously and varyingly a mirror, augmentation, and reduction of our offline social lives. Human behaviours are complex and nuanced and context-dependant, inconsistent, sprinkled across many different media, subject to multiple interpretations.. and all kinds of other words that mean it's difficult to wrangle this space into a coherant or complete data model. But, we (computer scientists, software developers) do it anyway.

For some reason, nobody has come up with a solution that pleases everybody yet.

It seems probable, given the diversity of systems, requirements, desires and general worldviews, nobody ever will. So here I come, blazing in with neither history nor experience, to try to write about how I see things. There's a lot of interesting past work in this space, and a full literature(/mailing list/blog post) review is worth doing. But for now, in the interests of time and sanity, I'm sticking to the current state of things as I understand them. In this post, I look at only two different (but overlapping) models. I also want to emphasise that there can't possibly be a single right way of looking at this space. Such models aren't in conflict (as some may think) but simply different ways of looking at the same thing. Where proponants of one may see shortcomings in the other, the opposite is equally true. People's different experiences and needs have led them a way of looking at things that they find perfectly intuitive. Often, this means alternative perspectives are seen as unintuitive and perhaps even in competition. Of course, there's a fine line between accounting for different perspectives, and losting interoperability entirely.

So, let's take stuff. We start with the idea that there is stuff on the social web that we want to describe. One subset of stuff is people. I'm not thinking about modelling people and relationships here.

Other subsets of stuff, which I want to focus on right now, are things and happenings. I'm deliberately trying to pick silly terminology to keep this abstract. You might also think of things as content, items or objects, and happenings as events, interactions or activities.

The two social data models I've spent the most time thinking about recently are ActivityStreams 2.0 and microformats2 (AS2 and mf2 henceforth) and the relationship between them. To various degrees, I've written about them before.

AS2

ActivityStreams was designed as a model for logging happenings (as opposed to a command language, which in some systems it has been used for). AS2's strength is happenings. A happening is modelled as an Activity, which may have a relation to a thing, aka an Object. (Technically an Activity is a type of Object, as is everything else, Actor, Collection, etc, but what I'm referring to here are generic Objects that don't belong to one of these other special classes). There are more specific types of Activity in the AS1 vocab than there are Objects.

mf2

Microformats was designed for marking up all kinds of web documents, and a subset of mf2 is focusing on social, specifically feeds and blog posts. Most people who work with mf2 find that they can adequately represent anything they need to as a thing. mf2's strength is things. The most common type of thing is an entry (a post), and you're also likely to see feeds and cards (profiles). All things can have relationships with other things. There's no particular language for logging happenings with mf2; the existence of a set of things serves that purpose. And no specific types of thing; rather, types of thing are inferred from the semantics of their properties and relationships with other things.

jf2

Both have JSON representations. This is the default for AS2, but mf2 is embedded in html, which means their JSON representation is generated by a parser. Even though there are a set of parsing rules, output can be complicated and vary depending on the structured of the html being parsed, and I've found myself writing my own 'parsing rules' to extract what I want from parsed mf2. Fortunately Aaron and Ben are working on a vastly simplified JSON representation of mf2, called jf2.

All together now

AS2 is already under the remit of the W3C Social Web WG (edited by James), and at the recent face-to-face, jf2 was (somewhat controversially) accepted as an Editor's Draft for the group as well.

The WG is chartered to produce a 'social syntax'. AS2 works great for those with happenings-centric worldviews, but doesn't always sit right with those who want to focus on things. On that basis, I think the two syntaxes have the potential to complement each other. I don't see why the WG can't produce two syntaxes for these two perspectives, which can be used together in systems which mix and match things and happenings. Not everyone agrees. There are certainly some redundancies and overlaps with both specs in their current state, and thus a lot more work to be done. But the editors are all keen to work together to iron these out, and I'm hopeful that now there's more of a feeling that these specs are complementary rather than competing, working on this will improve both. The strengths of one can plug the weaknesses of the other, and everyone can benefit. We also need to leave room for expansion in the future, as obviously this is anything but a static space.

An addendum for those who are adamantly opposed to one or the other of the models, because the other is obviously right/better: I encourage you to accept that different experiences lead to different conclusions, and if there was an obviously right/better way of doing this we'd have solved it long ago. Bringing together the different experiences of different people in order to benefit everyone is kind of the point of the WG.

These are the two models being considered because their supporters wrote them up as specifications and can demonstrate history and implementation experience. Anyone have a different model of the social world they wish to bring to the table..?

🏷 activitystreams2 as2 phd social web socialwg

Mon 7th of December 2015 at 5:07pm (+00:00)

Generating an ActivityStream

Part one: posts-for-all-the-things

If you've been paying attention to me IRL or in IRC lately, you'll have had me try to persuade you that activities and posts are basically the same thing. People advocating post-centric views and people advocating activity-centric views are really describing the same thing from different angles, and with slightly different data models.

An activity looks generally like:



And a post looks generally like:



Colour coding indicates what correlates between the two. Differences:

	Activity	Post
type	explicit	implied by properties
relationship to another object	object	value of arbitrary property
meta	some on activity, some on result	all on post

But you can see that the data they contain are basically the same. Bear with me.

What are activities for?

To propagate changes through a network. To tell people that somebody did something.

What are posts for?

Posts are content, an end in themselves.

Who cares?

As someone who just wants to publish stuff and interact on the web, do I care if I'm creating and pushing around posts, or activities? Probably not. I just want to do stuff, and have people see it.

As a developer, I want to post objects around that contain as much data as needed, and no more. I want the right people to know when something has changed. Whether I prefer to do this with activities or posts (or JSON or HTML) is, as far as I see it, personal preference. I don't think there's an inherant advantage to one over the other.

So which to start with?

Starting with a blog perspective, the most important thing is that people see my content. Posts are my content, so I start there.

• I create a post, which are objects with various properties.
• If I want to explicitly notify someone of a post - because I'm replying to them, favouriting, bookmarking, sharing, tagging, etc, I send them a webmention.
  • The reciever is then free to act upon this as they like: display my post on their site, update their own internal friends list, add my post to a collection, ignore it completely, or whatever.
• If I want to make a general announcement that something has changed on my site (eg. a new post) I either use PuSH and the hub lets subscribers know, or I don't do anything, and wait for interested parties to pull (visit my homepage, or open their reader) and find out for themselves.



For humans, the posts are displayed in html, and for machines they're marked up with minimal microformats, which allows a reader such as Woodwind to parse out the relevant information and display however necessary. (Mine are also avaiable as RDF, but to the best of my knowledge nobody has built a blog reader that consumes RDF yet).

In the ActivityStreams model, rather than creating posts directly, the user performs some activity which may generate as a side-effect a post. The activty could be something like Post, Share, Like (with many other terms currently in the vocab), with an optional target of an object being acted upon, and an optional result of a new object being created. Upon creation, the activity is sent by the server to the servers of anyone who is expected to receive it - either a default list such as people who have subscribed to the author, or a specific list of other people specified when the activity is created, or anyone mentioned or replied-to etc. Anyone for whom the activity ends up on their inbox might get a notification, and their server can fetch the associated post for them.



Not all activities generate a result post and some activities generate a result that is the same as the object. In these cases, I would argue that an activity == a post...

Currently, when I like something I create a like post, that looks like this:



A like activity looks like this:



See how similar they are?!

So given this apparent direct mapping between posts and activities...

Posts as activities

Dreaming of interoperability with ActivityPump implementations, I want to generate AS2.0 compliant activities that I can send out. I stuck to super basic representations for now, nesting as little as possible (figuring everything with a URI can be dereferenced anyway, so all of the data doesn't need to be present in the first layer of JSON).

So for a new post such as:

<article class="h-entry">
  <h1 class="p-name">Post title</h1>
  <div class="e-content">
    <p>This is a post!</p>
  </div>
  <time class="dt-published" datetime="2015-05-15T13:06:00+02:00"><a href="https://rhiaro.co.uk/2015/05/a-post" class="u-url u-uid">15th May 2015 13:06</a></time>
  <p class="h-card p-author p-name"><a href="https://rhiaro.co.uk/about#me" class="u-url">Amy Guy</a></p>
</article>

The activity generated looks like:

{
  "@type": "Post",
  "published": "2015-05-15T13:06:00+02:00",
  "actor": "https://rhiaro.co.uk/about#me",
  "object": "https://rhiaro.co.uk/2015/05/a-post",
  "result": {
    "@id": "https://rhiaro.co.uk/2015/05/a-post"
  }
}

With no explicit audience specified, an ActivityPump compliant server would post this to the inboxes of all of my followers. Their server would see the new activity and insert it into their feed; they could click it and view the object (the post). Note that the object of the activity and the result here are the same, so there's some redundancy.

For a like post - because I start with posts, I keep the result of the activity as the like post and retain this redundancy, though this isn't necessary and (see diagram above) you could in fact consider the activity to be equivalent to the like post, and use the ID of the activity to interact with it (if someone wanted to like my like, etc). I have no explicit post types, so it's implicitly considerd a 'like' post due to the like-of microformats property:

<article class="h-entry">
  <p class="p-name e-content">I like <a href="https://theperplexingpariah.co.uk/2015/05/a-post" class="u-like-of">Jessica's post</a>.</p>
  <time class="dt-published" datetime="2015-05-15T13:06:00+02:00"><a href="https://rhiaro.co.uk/2015/05/a-like" class="u-url u-uid">15th May 2015 13:06</a></time>
  <p class="h-card p-author p-name"><a href="https://rhiaro.co.uk/about#me" class="u-url">Amy Guy</a></p>
</article>

And the activity:

{
  "@type": "Like",
  "published": "2015-05-15T13:06:00+02:00",
  "actor": "https://rhiaro.co.uk/about#me",
  "object": "https://theperplexingpariah.co.uk/2015/05/a-post",
  "result": {
    "@id": "https://rhiaro.co.uk/2015/05/a-like"
  }
}

In this case, as well as any explicit or default audience specified, my server would post this activity to Jessica's inbox, whether Jessica is following me or not, as it's a like of her post. Her server can notify her, insert this into her feed, and it's also her server's job to send this activity out to everyone (probably Jessica's followers) who recieved the original post (the one I'm liking), so the 'like' counter can be incremented consistently for everyone, whether they know you or not.

Without activities (my current setup), I'd send a webmention to Jessica, and there's nothing specified about how her server should handle this (beyond checking it's valid), so propagating the like out to everyone who had seen her post wouldn't necessarily happen. However, she is likely to display the number of 'likes' on her post, so a reader could pull the new number of likes each time anyone viewed it (or poll continuously if it wanted a live-update), which puts a lot of burden on the client rather than the server.

Microformats to ActivityStreams

So I generate activities like this for all of my posts so far. As I removed all explicit post types from my storage, I rely only on the properties of a post to decide how to display it. I implemented similar rules to generate the activity types required by AS2.0. These rules cascade:

• name exists (object has a title) -> Post
• location exists -> Arrive
• like-of exists -> Like
• bookmark-of exists -> Save
• repost-of exists -> Share
• otherwise -> Post
• in-reply-to exists and has category "rsvp" -> Accept
  • otherwise -> Respond

I also check nameless posts for eat and sleep tags, as these indicate a lifelog post for eating or sleeping, and use types _:Consume and _:Sleep (my own namespace, as AS2.0 doesn't have these types. TODO: Reuse an existing vocab for these). I'll be adding running, yoga, hiking, listening to music and committing code imminantly, so I might need more activity types. I probably need to model these better than relying on tags (but... maybe not. We'll see).

Known issues

If you noticed that the object of a Consume activity is a blog post, you're a semantic pedant, and you're right, this doesn't make sense. The next best option given the data I currently store is the object being blank node with a label of the contents of the post, eg:

{
  "@type": "Consume",
  "published": "2015-05-15T13:06:00+02:00",
  "actor": "https://rhiaro.co.uk/about#me",
  "object": {
    "title": "An apple"
  },
  "result": {
    "@id": "https://rhiaro.co.uk/2015/05/a-nom"
  }
}

But ideally the object would have it's own URI. This probably isn't something I'm going to do any time soon.

Note an object (a post) is still created as a result of the Consume activity. This isn't necessary - as with likes, the pure activity could be sent and displayed to people - but since I start with posts, I wouldn't drop them.

If you're squinting at my location -> Arrive rule, note my own special rules for displaying checkins. This is subject to change.

Part two: Maybe not posts-for-all-the-things

Activities as posts

Sometimes, when you want to do something on the web, it doesn't feel like making a post. For example, if I want to delete a blog post, I need to tell everyone who received it that it's deleted. In indiewebland, you just delete the post, return a 410, and send a webmention to anyone who needs it. However, this doesn't leave any record of when it was deleted (or when it was created). You might have noticed I like tracking everything, so the ActivityPump way of deleting - which retains a trace of the deletion - appeals to me:

{
  "@type": "Delete",
  "@id": "https://rhiaro.co.uk/2015/05/delete-bad-post",
  "published": "2015-05-15T13:06:00+02:00",
  "actor": "https://rhiaro.co.uk/about#me",
  "object": "https://rhiaro.co.uk/2015/05/bad-post",
  "result": {
    "@id": "https://rhiaro.co.uk/2015/05/bad-post",
    "deleted": "2015-05-15T13:06:00+02:00"
  }
}

(In the current ActivityPump spec, the result is a shell of the object that is being deleted, so the URI of the deleted post is retained with a deletion date attached, but all other properties deleted).

But when you think about deleting a post, you're not thinking about creating a delete post which references the post you want to delete (if this is how you think about it, I'd love to hear from you). You want to hit delete, and have everyone suitably notified. The same for updates/edits/modifications (of your own post - creating a diff post as an edit to somene else's post or a wiki page is a different matter).

Nonetheless, if I wanted to display the delete activity for humans, I could mark it up in HTML with microformats, just as if it were a post, something like:

<article class="h-entry">
  <p class="p-name e-content">I deleted <a href="https://rhiaro.co.uk/2015/05/bad-post" class="u-delete-of">a post</a>.</p>
  <time class="dt-published" datetime="2015-05-15T13:06:00+02:00"><a href="https://rhiaro.co.uk/2015/05/delete-bad-post" class="u-url u-uid">15th May 2015 13:06</a></time>
  <p class="h-card p-author p-name"><a href="https://rhiaro.co.uk/about#me" class="u-url">Amy Guy</a></p>
</article>

Note:

• I have invented microformat property u-delete-of, this doesn't currently exist.
• There is content in the HTML version that is not present in the JSON version. Probably a content (or existing displayName) property on the activity could be used for this. Where this content comes from could be implementation-dependant, with some sensible default fallback.

So even though they're basically the same thinking about 'delete' as an activity rather than a post feels easier and it is still possible to treat as a post for display if you need to.

At the moment I store a modified date and just update this whenever I edit a post. For now I plan to add something that checks all posts for a updated date and slots Update activities into the stream (even though there is no explicit update-of post). When I can update posts properly with micropub, I will generate the update activity then.

There are other activities ((un)follow/add/remove/join/leave) that I also think would be simpler to think of in this way. I don't currently know of anyone in indieweb who is displaying posts for these marked up with microformats, though I have a couple of experimantal follows posts with u-follow-of.

Next

Once I have AS2.0 compliant activities, I could post them to inboxes of [ActivityPump]() compliant servers. Someone should implement one please :)

Addendum

Certain activities (like Follow) may trigger special side-effects (a user is added to another users followers collection according to pump.io and ActivityPump (not ActivityStreams)). In indieweb, if you want to follow someone you type their URL into a reader and it fetches their content. What's missing is the reader being able to post a follow activity to your site via micropub so that others (including who you have just followed) can be notified of your follow, and if you have a public list of follows, that can be updated too.

This is out of scope for this post, but I think core side-effects like this need to be clearly defined, and we also need a clear way of defining new side-effects as extensions.

🏷 http://vocab.amy.so/blog#Doing http://vocab.amy.so/blog#Doing activities activitystreams2 activitystreams as2 hacking indieweb microformats2 posts slogd social web socialwg

Wed 20th of May 2015 at 2:32pm (+01:00)

Amy's mini Alpine Adventure

I picked Innsbruck pretty randomly as a mid-point between Dusseldorf (where I was for IWC) and Florence (where I need to be for WWW). I haven't been to Austria before, or even the Alps bar a day-trip during a school trip to France like ten years ago. The first day I was here was clear, sunny and crazy hot, so I started loving Innsbruck pretty immediately. I wandered around town, got a feel for the place, and found the only place I could get vegan pizza and eiskaffee.

The Inn river is fast-flowing and a cartoonish blue-green. The houses are bright colours, and everywhere is walkable. The town is surrounded by a ring of snow-capped mountains.

I booked a hostel so I wouldn't have to socialise too much, as I need a break from people between all of these conferences. The hostel is super quiet, and mostly pretty good. The first night I shared my dorm with two Canadian girls. They told me the funicular up one of the mountains is reasonably priced, and that it was silly to think of walking to the base as it's really far, and I should get the bus. Also that I should pay the EUR 2.60 for a bus ticket, as one of them didn't and got caught and fined ;)

Yesterday I hacked a bunch on Slog'd in the morning, then at 2pm set off with vague intentions of either climbing a mountain or swimming in a lake, ideally both. I ignored the advice of the Canadian girls, and walked to Hungerburg where the cable car starts. It was less than an hour from the hostel, and the mountain parts were easy. Turns out the cable car to the top is over 25 EUR, and it's about a 3 hour climb to Seegrube. And climbing is WAY more interesting. However, from Seegrube to the summit at Halekefar I was advised there is too much snow for climbing, so the cable car for that stretch is mandatory (and Seegrube-Halekefar is EUR 6.10 return, which I can handle). So I figured I'd climb to Seegrube, take the cable car to the summit and back, and climb all the way back on foot. But by that point, the odds of me making it to Seegrube before the cablecar stopped running at 1730 were pretty slim. I toyed with trying to find an ATM and taking the cablecar all the way, but decided I'd prefer to climb anyway and can come back the next day, earlier.

Then I walked to Lake Rossau, which the internet claims cost EUR 3.50 to swim in but I mean, it's a lake, so nobody seemed to be enforcing this. So I swam in the lake surrounded by mountains and it was beautiful.

Then I came back to the hostel and added a first pass at ActivityStreams2.0 JSON to my site. Woo! Productive day.

Today it is raining heavily and the mountains are shrouded in clouds. Naturally. Turns out I'm going to give getting to Halekefar a shot anyway, even if I can't see anything from the top, thanks to encouragement from my new hostel roomie, a fairly old Vietnamese lady who lives in Belgium.

Also, I'll post some photos just as soon as I implement display of albums and attaching Collections to posts on Slog'd.... Aaaaany day now.

🏷 http://vocab.amy.so/blog#Done http://vocab.amy.so/blog#Done activitystreams2 as2 austria hacking innsbruck json lake mountain slogd travel

Fri 15th of May 2015 at 9:42am (+01:00)