imip-agent

Annotated docs/wiki/FilesystemUsage

1384:9baa0aae5b43
1196:7153fc86ae7d
2017-10-31 Paul Boddie file changeset files shortlog Provided a convenience function for instantiating handler objects. Added a mode that produces output instead of sending messages without also producing debugging information. client-editing-simplification
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@1089     29 
Meanwhile, the journal and store resources are only present in the filesystem
 
 paul@1089     30 
if the [[../FileStore|file store]] is in use. Where a
 
 paul@1089     31 
[[../DatabaseStore|database store]] is being used instead, such resources are
 
 paul@1089     32 
located in a database system.
 
 paul@1089     33 
 
 paul@1039     34 
== Journal Structure ==
 
 paul@1039     35 
 
 paul@1039     36 
Within the journal directory are a collection of subdirectories, each of which
 
 paul@1196     37 
represent a distinct quota group for one or more [[../Resources|resources]].
 
 paul@1196     38 
When a user attempts to reserve a resource in such a group, their ability to
 
 paul@1196     39 
schedule that resource will depend on how much they are using the other
 
 paul@1196     40 
resources in that group.
 
 paul@1039     41 
 
 paul@1039     42 
The directory for each quota group contains the following entries:
 
 paul@1039     43 
 
 paul@1039     44 
{{{{#!table
 
 paul@1039     45 
'''Entry''' || '''Purpose'''
 
 paul@1039     46 
==
 
 paul@1196     47 
`delegates`
 
 paul@1196     48 
|| A file containing details of the identities employing this quota to consolidate
 
 paul@1196     49 
.. their schedules, between which delegation may take place if their schedules
 
 paul@1196     50 
.. permit it
 
 paul@1196     51 
==
 
 paul@1192     52 
`freebusy-other`
 
 paul@1192     53 
|| A directory containing files, one per user (each containing period descriptions
 
 paul@1039     54 
.. for reservations made by that user, in chronological order, structured
 
 paul@1192     55 
.. similarly to the `freebusy` file found in each user's own store) or one per
 
 paul@1192     56 
.. group (for reservations made by users belonging to the groups defined for the
 
 paul@1192     57 
.. quota); the record in each file is consolidated for all resources in a quota
 
 paul@1192     58 
.. group
 
 paul@1039     59 
{{{
 
 paul@1192     60 
freebusy-other/GROUP
 
 paul@1192     61 
freebusy-other/USER
 
 paul@1039     62 
}}}
 
 paul@1039     63 
==
 
 paul@1196     64 
`freebusy-providers`
 
 paul@1196     65 
|| A file containing details of [[../EventRecurrences|recurring events]] for which
 
 paul@1196     66 
.. new free/busy records must be [[../CronIntegration|periodically generated]]
 
 paul@1196     67 
.. because these events recur indefinitely
 
 paul@1196     68 
==
 
 paul@1039     69 
`groups`
 
 paul@1039     70 
|| A mapping from user identities to group identifiers indicating the sharing
 
 paul@1039     71 
.. of a quota across a number of users
 
 paul@1039     72 
==
 
 paul@1039     73 
`limits`
 
 paul@1039     74 
|| A mapping from user identities or group identifiers to quota limits
 
 paul@1039     75 
}}}}
 
 paul@988     76 
 
 paul@988     77 
== Store Structure ==
 
 paul@988     78 
 
 paul@1039     79 
Within the store directory are a collection of user-specific subdirectories
 
 paul@1039     80 
acting as each user's own store directory containing various files and further
 
 paul@1039     81 
subdirectories.
 
 paul@1039     82 
 
 paul@988     83 
The store directory for each user is considered in isolation from all other
 
 paul@1039     84 
users' directories: imip-agent ''does not'' go looking for information belonging
 
 paul@1039     85 
to other users when processing information on behalf of a particular user.
 
 paul@988     86 
 
 paul@1039     87 
The following entries are defined within a user's own store directory:
 
 paul@988     88 
 
 paul@988     89 
{{{{#!table
 
 paul@1039     90 
'''Entry''' || '''Purpose'''
 
 paul@988     91 
==
 
 paul@988     92 
`cancellations`
 
 paul@988     93 
|| Retains cancelled event details in `objects` and `recurrences` structures
 
 paul@988     94 
.. corresponding to those at the top level of the store from which the
 
 paul@988     95 
.. cancelled events originate:
 
 paul@988     96 
{{{
 
 paul@988     97 
cancellations/objects/UID
 
 paul@988     98 
cancellations/recurrences/UID/RECURRENCE-ID
 
 paul@988     99 
}}}
 
 paul@988    100 
==
 
 paul@988    101 
`counters`
 
 paul@988    102 
|| Retains counter-proposals for events in `objects` and `recurrences`
 
 paul@988    103 
.. structures corresponding to those at the top level of the store for which
 
 paul@988    104 
.. the counter-proposals are received, with a counter-proposal for each
 
 paul@988    105 
.. respondent being held for each object or recurrence involved:
 
 paul@988    106 
{{{
 
 paul@988    107 
counters/objects/UID/ATTENDEE
 
 paul@988    108 
counters/recurrences/UID/RECURRENCE-ID/ATTENDEE
 
 paul@988    109 
}}}
 
 paul@988    110 
==
 
 paul@988    111 
`freebusy`
 
 paul@988    112 
|| A file containing period descriptions in chronological order, one per line,
 
 paul@988    113 
.. indicating start and end datetimes (in UTC), unique identifier (`UID`),
 
 paul@988    114 
.. transparency, summary and organiser
 
 paul@988    115 
==
 
 paul@988    116 
`freebusy-offers`
 
 paul@988    117 
|| A file containing period descriptions in chronological order for
 
 paul@988    118 
.. scheduling offers made by counter-proposals sent by the user
 
 paul@988    119 
==
 
 paul@988    120 
`freebusy-other`
 
 paul@988    121 
|| A collection of files, one per user, each containing period descriptions
 
 paul@988    122 
.. received or deduced for that user in chronological order, structured similarly
 
 paul@988    123 
.. to the store user's own `freebusy` file
 
 paul@1039    124 
{{{
 
 paul@1039    125 
freebusy-other/USER
 
 paul@1039    126 
}}}
 
 paul@988    127 
==
 
 paul@988    128 
`freebusy-providers`
 
 paul@988    129 
|| A file containing details of [[../EventRecurrences|recurring events]] for which
 
 paul@988    130 
.. new free/busy records must be [[../CronIntegration|periodically generated]]
 
 paul@988    131 
.. because these events recur indefinitely
 
 paul@988    132 
==
 
 paul@988    133 
`objects`
 
 paul@988    134 
|| A collection of files, one per event, each bearing as its name the unique
 
 paul@988    135 
.. identifier (`UID`) of the event, with each file containing the event data:
 
 paul@988    136 
{{{
 
 paul@988    137 
objects/UID
 
 paul@988    138 
}}}
 
 paul@988    139 
==
 
 paul@988    140 
`recurrences`
 
 paul@988    141 
|| A collection of directories, one per "parent" event, each bearing as its name
 
 paul@988    142 
.. the unique identifier (`UID`) of the event, with each directory containing a
 
 paul@988    143 
.. collection of files, one per event recurrence, each bearing as its name the
 
 paul@988    144 
.. normalised recurrence identifier (`RECURRENCE-ID`) of the recurrence, with each
 
 paul@988    145 
.. file containing the data of the event recurrence:
 
 paul@988    146 
{{{
 
 paul@988    147 
recurrences/UID/RECURRENCE-ID
 
 paul@988    148 
}}}
 
 paul@988    149 
==
 
 paul@988    150 
`requests`
 
 paul@988    151 
|| A list of records, one per line, each consisting of a unique identifier (`UID`),
 
 paul@988    152 
.. normalised recurrence identifier (`RECURRENCE-ID`) if appropriate, and
 
 paul@988    153 
.. (optionally) a scheduling method, indicating the availability of an incoming
 
 paul@988    154 
.. scheduling request for handling by a user
 
 paul@988    155 
}}}}