imip-agent

Annotated docs/wiki/FilesystemUsage

1059:861e86e687af
1053:068aa85f0c45
1039:a12150034cbd
2016-02-08 Paul Boddie file changeset files shortlog Made the retraction operation a complete transaction. Tidied up the locking and unlocking function application.
paul@988 1 
= Filesystem Usage =
paul@988 2 
 
 paul@988      3 
The behaviour and operation of imip-agent is controlled by resources stored
 
 paul@988      4 
in the filesystem on the host on which the software is running. These resources
 
 paul@988      5 
are organised as follows:
 
 paul@988      6 
 
 paul@988      7 
{{{#!table
 
 paul@988      8 
'''Resource''' || '''Default Location''' || '''Purpose'''
 
 paul@988      9 
==
 
 paul@1039     10 
Free/busy || `/var/www/imip-agent/static`
 
 paul@1039     11 
|| Per-user directories containing [[../FreeBusyPublishing|free/busy resources]]
 
 paul@1039     12 
.. for publication over the Web
 
 paul@1039     13 
==
 
 paul@1039     14 
Journal || `/var/lib/imip-agent/journal`
 
 paul@1039     15 
|| Per-quota directories containing journal information recording
 
 paul@1039     16 
.. [[../Resources|resource]] usage
 
 paul@988     17 
==
 
 paul@988     18 
Preferences || `/var/lib/imip-agent/preferences`
 
 paul@988     19 
|| Per-user directories containing [[../Preferences|preferences]] controlling
 
 paul@988     20 
.. each user's experience of the software
 
 paul@988     21 
==
 
 paul@1039     22 
Store || `/var/lib/imip-agent/store`
 
 paul@1039     23 
|| Per-user directories containing calendar objects and scheduling information
 
 paul@988     24 
}}}
 
 paul@988     25 
 
 paul@988     26 
Note that the free/busy resources are located in `/var/www` as opposed to
 
 paul@1039     27 
`/var/lib` since they are intended to be published on the Web.
 
 paul@1039     28 
 
 paul@1039     29 
== Journal Structure ==
 
 paul@1039     30 
 
 paul@1039     31 
Within the journal directory are a collection of subdirectories, each of which
 
 paul@1039     32 
represent a distinct quota group for one or more resources. When a user attempts
 
 paul@1039     33 
to reserve a resource in such a group, their ability to schedule that resource
 
 paul@1039     34 
will depend on how much they are using the other resources in that group.
 
 paul@1039     35 
 
 paul@1039     36 
The directory for each quota group contains the following entries:
 
 paul@1039     37 
 
 paul@1039     38 
{{{{#!table
 
 paul@1039     39 
'''Entry''' || '''Purpose'''
 
 paul@1039     40 
==
 
 paul@1039     41 
`freebusy`
 
 paul@1039     42 
|| A directory containing files, one per user, each containing period descriptions
 
 paul@1039     43 
.. for reservations made by that user, in chronological order, structured
 
 paul@1039     44 
.. similarly to the `freebusy` file found in each user's own store; the record is
 
 paul@1039     45 
.. consolidated for all resources in a quota group, but it is not consolidated for
 
 paul@1039     46 
.. groups of users
 
 paul@1039     47 
{{{
 
 paul@1039     48 
freebusy/USER
 
 paul@1039     49 
}}}
 
 paul@1039     50 
==
 
 paul@1039     51 
`groups`
 
 paul@1039     52 
|| A mapping from user identities to group identifiers indicating the sharing
 
 paul@1039     53 
.. of a quota across a number of users
 
 paul@1039     54 
==
 
 paul@1039     55 
`journal`
 
 paul@1039     56 
|| A directory containing transaction files, one per user or user group,
 
 paul@1039     57 
.. describing confirmed reservations and retracted (cancelled) reservations for
 
 paul@1039     58 
.. that user or group
 
 paul@1039     59 
{{{
 
 paul@1039     60 
journal/GROUP
 
 paul@1039     61 
journal/USER
 
 paul@1039     62 
}}}
 
 paul@1039     63 
==
 
 paul@1039     64 
`limits`
 
 paul@1039     65 
|| A mapping from user identities or group identifiers to quota limits
 
 paul@1039     66 
}}}}
 
 paul@988     67 
 
 paul@988     68 
== Store Structure ==
 
 paul@988     69 
 
 paul@1039     70 
Within the store directory are a collection of user-specific subdirectories
 
 paul@1039     71 
acting as each user's own store directory containing various files and further
 
 paul@1039     72 
subdirectories.
 
 paul@1039     73 
 
 paul@988     74 
The store directory for each user is considered in isolation from all other
 
 paul@1039     75 
users' directories: imip-agent ''does not'' go looking for information belonging
 
 paul@1039     76 
to other users when processing information on behalf of a particular user.
 
 paul@988     77 
 
 paul@1039     78 
The following entries are defined within a user's own store directory:
 
 paul@988     79 
 
 paul@988     80 
{{{{#!table
 
 paul@1039     81 
'''Entry''' || '''Purpose'''
 
 paul@988     82 
==
 
 paul@988     83 
`cancellations`
 
 paul@988     84 
|| Retains cancelled event details in `objects` and `recurrences` structures
 
 paul@988     85 
.. corresponding to those at the top level of the store from which the
 
 paul@988     86 
.. cancelled events originate:
 
 paul@988     87 
{{{
 
 paul@988     88 
cancellations/objects/UID
 
 paul@988     89 
cancellations/recurrences/UID/RECURRENCE-ID
 
 paul@988     90 
}}}
 
 paul@988     91 
==
 
 paul@988     92 
`counters`
 
 paul@988     93 
|| Retains counter-proposals for events in `objects` and `recurrences`
 
 paul@988     94 
.. structures corresponding to those at the top level of the store for which
 
 paul@988     95 
.. the counter-proposals are received, with a counter-proposal for each
 
 paul@988     96 
.. respondent being held for each object or recurrence involved:
 
 paul@988     97 
{{{
 
 paul@988     98 
counters/objects/UID/ATTENDEE
 
 paul@988     99 
counters/recurrences/UID/RECURRENCE-ID/ATTENDEE
 
 paul@988    100 
}}}
 
 paul@988    101 
==
 
 paul@988    102 
`freebusy`
 
 paul@988    103 
|| A file containing period descriptions in chronological order, one per line,
 
 paul@988    104 
.. indicating start and end datetimes (in UTC), unique identifier (`UID`),
 
 paul@988    105 
.. transparency, summary and organiser
 
 paul@988    106 
==
 
 paul@988    107 
`freebusy-offers`
 
 paul@988    108 
|| A file containing period descriptions in chronological order for
 
 paul@988    109 
.. scheduling offers made by counter-proposals sent by the user
 
 paul@988    110 
==
 
 paul@988    111 
`freebusy-other`
 
 paul@988    112 
|| A collection of files, one per user, each containing period descriptions
 
 paul@988    113 
.. received or deduced for that user in chronological order, structured similarly
 
 paul@988    114 
.. to the store user's own `freebusy` file
 
 paul@1039    115 
{{{
 
 paul@1039    116 
freebusy-other/USER
 
 paul@1039    117 
}}}
 
 paul@988    118 
==
 
 paul@988    119 
`freebusy-providers`
 
 paul@988    120 
|| A file containing details of [[../EventRecurrences|recurring events]] for which
 
 paul@988    121 
.. new free/busy records must be [[../CronIntegration|periodically generated]]
 
 paul@988    122 
.. because these events recur indefinitely
 
 paul@988    123 
==
 
 paul@988    124 
`objects`
 
 paul@988    125 
|| A collection of files, one per event, each bearing as its name the unique
 
 paul@988    126 
.. identifier (`UID`) of the event, with each file containing the event data:
 
 paul@988    127 
{{{
 
 paul@988    128 
objects/UID
 
 paul@988    129 
}}}
 
 paul@988    130 
==
 
 paul@988    131 
`recurrences`
 
 paul@988    132 
|| A collection of directories, one per "parent" event, each bearing as its name
 
 paul@988    133 
.. the unique identifier (`UID`) of the event, with each directory containing a
 
 paul@988    134 
.. collection of files, one per event recurrence, each bearing as its name the
 
 paul@988    135 
.. normalised recurrence identifier (`RECURRENCE-ID`) of the recurrence, with each
 
 paul@988    136 
.. file containing the data of the event recurrence:
 
 paul@988    137 
{{{
 
 paul@988    138 
recurrences/UID/RECURRENCE-ID
 
 paul@988    139 
}}}
 
 paul@988    140 
==
 
 paul@988    141 
`requests`
 
 paul@988    142 
|| A list of records, one per line, each consisting of a unique identifier (`UID`),
 
 paul@988    143 
.. normalised recurrence identifier (`RECURRENCE-ID`) if appropriate, and
 
 paul@988    144 
.. (optionally) a scheduling method, indicating the availability of an incoming
 
 paul@988    145 
.. scheduling request for handling by a user
 
 paul@988    146 
}}}}