A Collection maintains Units of information;
Units with various content. These Units do not simply appear and
disappear as files in a directory in a directory do: Units
have a life-cycle. Units enter their Collection in multiple
steps before they become visible. And they may remove themselves with
a plan as well.
Unit State mechanics
The Collection (~managing process) will "run" each Unit through
some states. It will need to inspect the content of an uploaded Unit to
determine its state transitions. Collection owners can influence
the state transitions of the Unit via Rules.
Place yourself in the role of the Collection manager. You need to
get the Unit in a distributable state (usually Published), and clean
it up later. Any single Unit will go through each of the states below,
from top to the center. However, many of the intermediate states will
probably be passed in one go.
Life-cycle transition diagram per Unit
Does not show states "Incomplete" and "Broken" (yet)
Not all state transitions have equal features; it depends on their
purpose. The Collection Rules can be modified by the Collector owners
to adjust the behavior per transition. For instance, some rule may put
an automatic expiration on any incoming Unit.
Rules may also determine
that the Collection managers have to agree on state transitions via
the voting mechanism.
TBD: the exact features still need to be designed.
Releasing a new Revision
You may upload a new revision of the Unit.
For instance, when you want to set a deprecation of expiration date.
The new Unit will transition step-by-step to reach the same UnitState
as the original Unit. When it reaches that state, the original Unit
revision will usually be removed (unless you configured to keep historical
revisions). Some discovered changes are logged: deprecation, expiration
and publication dates, content changes, ownership changes.
The Unit States
(Not to be confused with the United States :-)
The states below are in "natural order", which means that the Collector
will default in facilitating transitions from top to bottom. However,
this pattern can be influenced in various ways. The usual interference
is halting a certain step to be made.
ms:UnitState
Purpose and features
Free
This is a condition: there is no Unit with a specific name.
Reserved
The client would like to upload a certain Unit, of which the payload
may still need to be created. At first, the client requests to be
allowed to use a certain name.
The reservation request is a partial Unit. It MUST contain owners.
It MAY already specify authors, unit-type, size, etcetera. When it
contains a payload, it will progress to the Uploaded state.
The Collection Rules may refuse to reserve the name. For instance,
some of the provided conditions already fails. Of course, it is
better to fail before a large upload than after.
The rules may require a vote from Collection owners to progress,
for instance to be able to manually ban unpleasant names before they
appear.
The Constitution Rules may specify a relative expire time for the
reservation. The Unit must reach Verified State before that moment.
The Unit itself may also give an absolute moment of expiration. Whichever
comes first will expire the name reservation.
Uploaded
The Unit data is complete, and uploaded in full to the Collector. The
client can disconnect: the life-cycle is managed by the Collector as an
asynchronous activity. Problems are reported via
notifications.
Without explicit name reservation, you can upload some Unit. Of course,
all rules which relate to the Reserved state will be applied.
Verified
The Collection may want to verify the payload of the Unit. Does it
match the unit type? This might be expensive. Clients which use the
content SHOULD not trust the content as well, as every good programmer
knows.
The server which runs the Collection has hooks which enable you to add
your own validator.
Broken
The Unit cannot reach a usable state, for some reason, but may stay
in the Collection for some time to simplify debugging and repair. The
life-cycle log will contain error messages.
Incomplete
The verified Unit is up for voting: do we permit the Unit to be
published? The voting rules MAY require confirmation from one or more
people from explicit named Identities, the Owners, or Authors. The people
which are allowed to vote have access to this Unit to verify it.
The Collection will also check whether all required dependencies are
available (at least in 'Verified' state within the same server) before
they can be Published all at the same time.
At any time, Units may get set back (from nearly any state) to the
Incomplete state when one of the prerequisits disappears.
Accepted
When Accepted, the Unit may need to wait before it gets Published. Some
clients may have access (for instance Collection replicators).
Published
When the publication date has passed (defaults to 'now'), the normal
client access rules get into effect. This is the state you expect
the Unit to be in for most of its existence.
Discouraged
There is some reason (documented) to use alternatives of this Unit,
but not as bad that the Unit becomes deprecated towards end-of-life.
This state is meant to offer developments a smooth, long term improvement
into something better.
The client is usually not warned when it uses the Unit, but the fresh
developer will be informed to search for alternatives.
Deprecated
On a moment of time, which is pre-specified in the Unit, its use
MAY get deprecated. This typically comes with some explanation.
The normal access restrictions do still apply.
The Client may warn the user actively in (daily) condensed reports.
Expired
On an absolute date, which is pre-specified in the Unit, access gets
restricted to the Owners of the archive. Clients MAY warn users
before expiration.
Withdrawn
This payload of the Unit MUST NOT be used anymore. This state will
contain a reason for this action, for instance triggered by legal
take-down requests. This state is more serious than removal of the
Unit: it reflects the instruction to clients to return to a situation as
if this Unit had never existed immediately.
Blocked
The Unit itself does not exist anymore, and cannot be recreated until
an provided absolute date or relative time span in the Rules.
Owners of a Collection are able to push any Unit into Expired,
Withdrawn, Blocked, or Free state.
Free
The name of the Unit is reusable for an unrelated Unit.
