io7m | single-page | multi-page | epub | Looseleaf User Manual
1. Introduction
Previous
Front Matter
Up
3. Installation
Next

# 2. Model

- 2.1. Overview
- 2.2. Value
- 2.3. Key
- 2.4. Key Expression
- 2.5. Action
- 2.6. Grant
- 2.7. Role
- 2.8. User
- 2.9. Read-Update-Delete

## 2.1. Overview

1
The looseleaf server provides a persistent key/value database with ACID semantics. Keys and values are arbitrary UTF-8 strings, and a fine-grained role-based access control system is provided to control how users are allowed to perform operations on the database.

## 2.2. Value

1
A value is an arbitrary UTF-8 encoded string.

## 2.3. Key

1
A key is a unique name for a value. The core functionality of the looseleaf server is a persistent database of keys and values that can be updated atomically. A key is a UTF-8 encoded string with an associated UTF-8 string value. Key names must begin with / and consist of an arbitrarily long sequence of segments separated with / characters. Repeated sequences of / characters are automatically reduced to a single / character. Key names, effectively, resemble absolute UNIX paths. Key names are ordered lexicographically, so the path /a is considered to be less than /b.

## 2.4. Key Expression

1
A key expression describes a set of keys. The syntax of key expressions is identical to keys, except that a key expression is allowed to end with a wildcard character *. A key expression /x/y/z matches exactly one key: /x/y/z, whilst the key expression /x/y/z* matches all keys that begin with /x/y/z.

## 2.5. Action

1
An action defines an operation that may be performed upon a key. An action may be READ or WRITE, where READ means that the value of a given key may be retrieved, and WRITE means that the value of a given key may be modified, or the key created and/or removed as desired.

## 2.6. Grant

1
A grant combines a key expression and an action, and effectively declares that the given action is allowed to be performed on the keys described by the key expression. For example, a grant with action READ and key expression /x/y/* allows reading the values of any keys that begin with /x/y/. A grant with action WRITE and key expression /a/b/c allows the key /a/b/c to be created, modified, and/or deleted.
2
Any action not explicitly allowed by a grant is denied.

## 2.7. Role

1
A role is a uniquely named (with respect to other roles) container that defines a set of grants. A user may have zero or more roles.

## 2.8. User

1
A user is a uniquely named (with respect to other users) container that combines a set of roles with a password. All operations in the looseleaf server are conducted on behalf of authenticated users; no operations are anonymous.

## 2.9. Read-Update-Delete

1
All operations that occur in the looseleaf server occur in terms of single atomic read-update-delete operations, or RUDs. An RUD operation specifies a set of keys that will be read, followed by a set of keys that will be updated, followed by a set of keys that will be deleted. The reads, updates, and deletes are specified to occur in that order, and the operation as whole will occur atomically; either all read/update/delete operations succeed, or it is as if none of them took place at all. More formally, an RUD can be specified as a 3-tuple (R,U,D), where R is the set of keys to read, U is the set of keys to update, and D is the set of keys to delete. If any of the keys specified in U do not exist, then they will be created by the update operation. It follows that:

### 2.9.2. Operations

- Reading a single key k can be expressed as the operation (k,∅,∅).
- Updating a single key k can be expressed as the operation (∅,k,∅).
- Deleting a single key k can be expressed as the operation (∅,∅,k).

3
As mentioned previously, operations are specified to occur in R → U → D order. This means that, for example, the operation (∅,k,k) for any k is a no-op.
1. Introduction
Previous
Front Matter
Up
3. Installation
Next
io7m | single-page | multi-page | epub | Looseleaf User Manual