Versioning, history, find commits from resource

[joepio]

One of the advantages of using and storing Commits, is that we have a full history of every single resource. However, we currently have no way of browsing this information.

Wishes

• I want to click on a link on a resource page to see all versions.
• I want to see a log of changes of some resource. This might be different from the versions.
• I want to see a previous version of some resource, and I want to share its URL.
• I want to restore a previous version of some resource, yet keep the previous changes.

Considerations

• For any list of things (commits for some resource, we should use the Collections model.

Approaches

Versions endpoint

example.com/versions?subject=someresource lists all the version for the resource included in the Subject query parameter. It returns a collection. Perhaps first define the Endpoints feature?

1. User requests a list of versions for some resource
2. A collections is constructed, containing all (or some subset of) the existing versions, one for each Commit. Each version points to a URL of a resource that needs to be constructed (e.g. example.com/versions?subject=someresource&version=signatureHashBlablabla)
3. user requests a specific version
4. That version is constructed by the server, using the commits

Introduce sequential TPF queries

Knowing which commits are linked to a resource, can be done using two TPF queries:

1. Get me all the items where is-a = commit
2. AND subject = mySubject

Some time ago, the great Ruben Verborgh told me that you can actually convert (all?) SPARQL queries into a set of sequential TPF queries. That's pretty cool. How should we create an interface to facilitate this? It probably requires some form of nesting queries, and some form of combined queries.

But... this kind of discussion quickly turns into a difficult discussion of which methods need to be included in the newly designed query language, and will kind of lead to some almost-turing-complete language, but not fully. Therefore, we might want to try a plugin-like approach, where the query logic resides in code.

Plugin (endpoint + extend resources)

Atomic Plugins are currently just a bunch of thoughts, but perhaps Versions is a logical first plugin. Plugins should be apps that can be added to an Atomic Server at runtime. They might be run using a WASM runtime. In any case, they need to add functionality to an Atomic Server.

Ideally, the Versioning plugin will have:

• An endpoint (see above) for constructing a version of a resource, and listing all versions / commits of a resource
• Maybe add some links to resources, so you can find the versions of a resource from the resource page.
• A way to restore previous versions (by producing a Commit that reverts some changes)

Constructing a version

A Version is a representation of some Resource at some point in time. Constructing one can (theoretically be done in several ways:

• Get the initial commit of a resource, and apply all commits until you get to the requested version
• Persist all versions and representations (costly!)
• Persist reverse actions, which describe how you can do the inverse of a Commit.

I feel like the first approach is the most logical.

I have a problem with this, though. Some resources don't have commits: for example, resources that are imported from a static AD3 file (such as the default atomic data).

I think this should simply be handled by the plugin. If you try to construct a version for a resource that has no commits, just return an error. Or should it return the static version that?

[joepio]

Flow for discovering versions from the browser

Let's assume we look at some resource, and want to see the previous version. How do we get there?

• Extend resource. Start with the Resource. the get_extended_resource functions adds Add a property to every resource which links to it's versions, e.g. /versioning?resource=subject.
• Extend view. The HTML template creates a URL when rendering the page. This means that it is not discoverable through the data itself.

What does this endpoint return

• A Collection of links to dynamic resources, namely versions, like /versioning?version=commitUrl. This is created by doing two TPF queries,

How does the library construct a version

• User fetches that URL, server asks the store a TPF query for all Commits for that resource. User can select any version. On opening that version, it is constructed.

[joepio]

I was considering using get_resource_extended for constructing a Versioned item. This basically enables atomic_lib users to simply user URL strings as the API, instead of relying on a Server.

This brings me to another consideration. Who should calculate the Version? A /version?commit={} URL can be resolved, as long as the Commit itself is resolvable (which is the case for HTTP or IPFS urls). Currently, I use a TPF query on a local store to find all commits.

Made a new issue about this more abstract problem: #89

[joepio]

Endpoint design

Should there be one endpoint for looking at one specific /version and a collection of /versions for one commit?

Say we have one versioning endpoint. Depending on the query param set, it will return either a Collection of versions, or a single resource. Having wildly different types of one resource from one endpoint feels odd, and I haven't even discussed the awkwardness of dealing with multiple query parameters. So this seems like a bad idea. Yeah, we need two endpoints.

If you open the versions endpoint without passing any query parameters, what should be returned?

• As a browser visitor, I want to see a page that explains the endpoint, and offers a simple way of using the endpoint, ideally through a webform.
• As an API user / machine, I might want to render my own custom form

Hmm. I think it might be possible to define an abstract endpoint class, which has a generic view. Basically this: atomicdata-dev/atomic-data-docs#15

[joepio]

I've got the first test passing (yay!), but it's incredibly slow. That's because I create a new store where the new Resources are to be made, and that means that all props first have to be fetched. And that is done by retrieving all the needed props from atomicdata.dev.

A different approach may be to use the normal store, and to temporarily remove the existing resource, and set it back after creating the older version.

[joepio]

The Versioning endpoints

Where are they going to live?

Custom Actix handler in atomic-server

Add an actix handler. Manually parse incoming query parameters. Generate a Resource depending on the request.

• Existing actix features could be useful

Custom Handler in atomic-lib

Get's called by get_extended_resource through existing match statement, similar to how Collections work - except for that now it also checks paths!

• More flexibility
• Moves routing to atomic

Add Endpoint resources in the default store

• Everything lives in data, which means more extendability if done right
• Not sure if this is actually going to work

Add 'register_endpoint' feature in store or server?

[joepio]

I've opted for creating an Endpoints abstraction, which seems like a decent abstraction for extending functionality of an Atomic Server. See atomicdata-dev/atomic-data-docs#15

[joepio]

Things are working! But I still have a problem to solve: showing the 'versions' button in a resource. There's a couple of approaches to:

Add an action link to all (versionable) resources, register extenders

In the get_resource_extended method, we could iterate over a bunch of registered extenders, which add properties to resources. Seems like a powerful abstraction.
Prevents that the button is shown when versioning is not possible.

Add components in the front-end.

Is easy to do, but this will result in buttons for things that have no versions (such as collections).

[joepio]

I think this has been working for quite a while now. Also, this helps to find commits, and removes the need for a different endpoint: #172