Sputnik: Versium

Anonymous users must enter captcha below.

Don't put anything here

Page Name (for URL)

Page Title

Advanced Fields

Page Content

<span class="teaser">
  Versium is a simple storage API used by Saci and Sputnik.  It makes
  it easy to switch from one storage method to another.
</span>

<i>This page has been updated to reflect the current state of affairs
in the [[Source|source]] repository.  The latest release of Sputnik works
a bit differently.</i>

[[Saci]] handles turning nodes of data into Lua objects, but does
not concern itself with the actual physical storage.  This is done by
modules that implement an interface called "Versium".  Versium
implementations can store and retrieve data represented as byte
strings with ids.  They also keep track of history for that data.

typically support

## The Versium API

Each Versium implementation is a Lua module that can be loaded with
"require".  They are typically distributed as [[LuaRocks]].

### Capabilities

Since many parts of the API are optional, each implementation must
define a table that specifies what it does and does not support.  For instance:

capabilities = {
       can_save = true,  -- an implementation can be read-only
       has_history = true, -- some implementations don't keep track of history
       is_persistent = true, -- we'll still have the data if the server goes down
       supports_extra_fields = true, -- revisions can have fields other than time stamp and author ID
    }

### Creating a new instance

A new instance of the implementation is created by a function called
"new()".  This function can take parameters, which are
implementation-specific.  Note that new() does not create any storage
system (such as a database).  It creates an Lua object that represents a
_connection_ to a storage system.

For instance:
    
    local versium_implementation = require(module_name)
    local my_versium_instance = versium_implementation.new(params)

### Methods

Once the client creates an instance, they interact with the storage system
using this instance.

#### node_exists(id)

Returns true or false depending on whether there is a node with this ID.

#### get\_node_history(id, prefix)

Returns the history of the node as a list of tables, sorted in reverse
chronological order.  Each table represents a revision of the node and
has the following fields:

1. "version" - the id of the revision
2. "author" - the author who made the revision
3. "timestamp" - the time whe the edit was made (it should look like
   "2008-04-20T22:12:49")
4. "comment" - the comment attached to the revision (or nil),
5. "extra" - a table of additional fields (or nil).

Note that all of those values must be stored as strings and the time
format is fixed.  However, each implementation can use its own way of
assigning version IDs.

The history can be filtered by a time prefix.  For instace

history = my_versium:get_node_history("Foo", "2008-02")

would return all revisions for February 2008.

#### get\_node_info(id, version)

Returns the information for a specific revision of the node,
identified by "version".  If "version" is not specified, then the
latest revision should be returned.

`get_node_info("Foo")` should give us the same table as
`get_node_history("Foo")[1]` (but potentially a lot faster).  Also, if
we obtain pick some revision from the history like this:

version = my_versium:get_node_history("Foo")[i].version

then `get_node_info("Foo", version)` should give us the same table as `get_node_history("Foo")[i]`.

_The version parameter is not actually implemented at the moment, but
coming soon._

#### get_node(id, version)

Returns the data stored in the node as a string.  Returns nil if the node doesn't exist.
Throws an error if anything else goes wrong.

For instance:

data = get_node("Foo")

After that "data" will be set to the content of the node (some byte
string).

#### save_version(id, data, author, comment, extra, timestamp)

Saves a new revision of the node.  The first three parameters are required and specify respectively the node that is being updated, the data that it is being updated with, and the user name that will be associated with the change.  The comment parameter is optional.  The extra parameter is optional and may be set to a table of additional fields.  The implementation or may not support optional fields and is free to just ignore this parameter.
The timestamp parameter is similarly optional for the client and for the implementation.

#### get\_node_ids(prefix, limit)

Returns a list of existing node ids, up to a certain limit.  (If no limit
is specified, all ids are returned, up to a limit set by the implementation.)
If the optional argument prefix is supplied, then only nodes starting with
this prefix should be returned.  (The prefix should be treated as a string, not
a Lua pattern.)  If the prefix is set, then the limit applies to the number
of ids that are being _returned_.  The ids can be returned in any order.
If "limit" is exhausted but there are more ids left, then a second value of
"true" should be returned.

## Implementations

### FileDir

"FileDir" is the default implementation of Versium, which just stores nodes and their history on disk in directories.
See [[File Storage]]. FileDir is installed by default together with versium, available as "versium.filedir".

### Virtual

"Virtual" implementation is non-persistent and just stores nodes in memory.  It is installed by default together with versium and is available as "versium.virtual".  The currentl version available in the [[Source|source repository]] is out of date but will be updated soon.

### Versium-SQL

Versium-SQL stores nodes in a relational database.  It is distributed as a separate rock, "versium-sql".
Currently available in the [[Source|source repository]].

### Versium-SVN

Versium-SVN stores nodes in a subversion repository.  It is distributed as a separate rock, "versium-svn".
The current version in the [[Source|source repository]] is out of date but will be updated for [[Earth]].

### Versium-Git

Versium-Git will store nodes in a Git repository.  It will distributed as a separate rock, "versium-git".
It will be checked into the [[Source|source repository]] shortly.

About This Edit

Minor Edit

Edit Summary

Don't put anything here