Chandler 0.6 Sharing Specification

Authors: Lisa Dusseault, Sheila Mooney , Mimi Yin Last edited: July 26, 2005 1:00 PM Creation date: April 13, 2005
Reviewers:

Overview

Goals and Objectives

In 0.6, Chandler will extend sharing in 4 major ways. 1) Support basic read-write AND read-only sharing on a per sharee basis. 2) Support read-only sharing with non-Chandler users via iCal. 3) Interoperate with the Cosmo and vanilla [stretch goal] CalDAV clients and 4) Prototype intelligent, per-attribute merging of simultaneous edits to a single shared item. Objectives 1 and 2 will be implemented by generating URL tickets, one for read-only sharing and a second for read-write sharing. All read-only sharees will access the share with the SAME read-only URL ticket. All read-write sharees will access the share with the SAME read-write URL. Publishing and subscribing to shares will be done out of band which means that in 0.6, users will not be provided with an integrated workflow to send out or receive sharing notifications. In 0.6, our primary goal is to ensure usable read-only and read-write sharing of calendars. We are committed to fixing any implementation or usability problems that may prevent us from reaching this goal.

This specification describes requirements for client-side functionality. However, there are also notes detailing server functionality so that we can see what minimum server functionality is required to support the client.

Sheila Mooney
Spec owner
Lisa Dusseault
Spec contributor
Morgen Sagen
Implementor: merge logic, GUI coordination and possibly implementation
Grant Baillie
Zanshin implementation: tickets, ETags, etc
Bryan Stearns
Possibly some GUI contribution if we reuse the current sharing detail view, review or polish

Background

What's already working in sharing in 0.5?

High Level Use Cases

These are the basic high-level use cases we will focus on supporting for 0.6.

1. A user publishes a read-only calendar share from Chandler to the Cosmo server.

2. A user publishes a read-write calendar share from Chandler to the Cosmo server.

3. A Chandler user subscribes to a read-only share published by another Chandler user via the Cosmo server.

4. A Chandler user subscribes to a read-write share published by another Chandler user via the Cosmo server.

5. For 0.6 we would like to handle some interoperability use cases such as:
    a. A user subscribes to any read-write or read-only calendar hosted in a Cosmo server in the correct format. This may have been published by another client such as Apple iCal.
    b. Subscribing to a Chandler calendar from Apple iCal using Cosmo server.
    c. [stretch] Publishing a Chandler calendar to a vanilla CalDAV server. This means publishing event data as individual ics files.
    d. [stretch] Subscribing to a Chandler calendar via a vanilla CalDAV server (if another CalDAV client were to come about in the 0.6 timeframe.)

[Sheila 07/25/05] Morgen would really like to handle (c) for 0.6 since it's not very difficult.

Definitions

Requirements

Security: This release does not require sharing to be completely secure. We will be using 1 URLs per ACL, per share (ie. read-only and read-write) and not handle issuing urls on a per sharee basis for per sharee ACLs in 0.6.

Interoperability: Chandler should interoperate with more than just one WebDAV server implementation, although we might work better with some WebDAV servers than with others. For 0.6, our primary use case is to support Cosmo, therefore only servers that support tickets are required. Depending on time contraints, if we wish to extend this for servers that do not support tickets, we can look at publishing a single share URL rather than 2 different ones.

Account Setup: We would like to provide the user with a streamlined way to set up a Cosmo account. But this is not required. Out-of-band account creation (ie. just like email) is acceptable for setting up sharing accounts in 0.6. We'll work on automated account creation in a later release.

Resharing: We will not restrict resharing in 0.6. Sharing URLs can be forwarded to anyone.

Unpublishing: Once a share has been published users should be able to unpublish it.

Permissions: Sharing does not need to be completely secure, but we would like to offer users the ability to share a single collection read-only with one set of sharees and read-write with a second set of sharees.

Synching: We have decided to stick with manual synching of shares for 0.6 However, users need to be able to:
    a) sync a particular share
    b) sync all shares
    c) sync email separately

Synching all shares only synchs those that have not been taken "offline".

Logging: We would like to support a simple logging mechanism for conflicts and merges. If possible we would also like to log changes as well. This will be something very simple for 0.6 with these conflicts and changes added to the Chandler log file. We will also have a test menu item where the user can run a report of the conflicts.

Event Sharing: This was deferred from 0.6.

Event Statuses and Alarms: In 0.6, sharers and sharees should be able to specify whether or not they want to share event status and/or alarms.

Assumptions

1. Sending and receiving sharing notifications will not be supported in Chandler for 0.6. Because email support will still be primitive in 0.6, we want to decouple the dependency of publishing and subscribing to shares from sending and receiving sharing notifications. Users will send and receive sharing notifications out of band, most likely via whatever email clients they user today. Chandler will provide affordances for copying the sharing URLs to the clipboard so that they can be pasted into the user's email client.

1. We will not track sharee sharing status (ie. who has successfully subscribed to your share, who encountered an error when they tried to subscribe.)

2. We will not issue tickets (aka set ACLs) on a per sharee basis. If the user-selected sharing server supports tickets, 2 urls (1 read-only, 1 read-write) will be issued and they can be sent to anybody. If the user-selected sharing server does not support tickets, 2 urls will be issued and they will only work for users who already have accounts on the same server.

3. A user does not have to have email accounts set up in order to publish or subscribe to a share.

4. Users can only publish a single collection to a single server in 0.6. There will be no UI provided for publishing the same collection to multiple servers simultanesouly. If users want to change the server that a collection is published to, they must first unpublish the collection on one server before they can publish the collection to a different server.

5. There will be no restrictions on resharing URLs in 0.6.

High-level Decisions

We will use URL-based tickets instead of ACLs to grant read-only or read-write access to shares. Sharees are granted read-only or read-write access depending on which URL they receive and / or use to access the share. We will not be setting ACLs on a per sharee basis, therefore, we do not need to support sharee account lookup.

For 0.6, we would like to move to a simple dialog based UI for publishing and subscribing to shares. We are aware that we will forsake some of the usability benefits of the sharing detail view for sending and receiving sharing notifications and managing shares. However we want to keep things simple and take the shortest path to achieving our 0.6 goals. We also want to make publishing and subscribing to shares independent of being able to successfully setup Chandler as an email client.

We will attempt to automatically merge simultaneously edited shared items on a per attribute basis. Smart merging will be required when two offline users (users A and B) attempt to change the same item. User A comes back online and synchs with the server. User B comes back online and synchs with the server. The server should detect a conflict: User B's version is NOT an edited version of User A's recently uploaded version. User A and User B's conflicting versions should be merged intelligently. The merge policy we will be using for 0.6 is that the server change wins. Using the previous example, User A would update their changes to the server first, then when User B syncs, they would have their edits overwritten by what User A updated. This way, User B can see that this data changes and retype their edits.

Terminology

We are proposing a few terminology changes for 0.6. 

Sharing Notification
Use this term instead of "Sharing invitation" to prevent confusion with event invitations.

Subscribing
Use this term to describe the process by which a share is downloaded using a URL entered manually or received via an out of band notification mechanism such as email. We want to eliminate the use of "accepting a share" since we are not tracking and managing sharess in 0.6.

Publishing
Use this term to describe the sharing initiation process, uploaded a share and generating read/write and readonly tickets.

User Interface/Interactions

High-level usability goals

The 0.5 publish and notification workflow was a one-step process that required the user to have email accounts (incoming and outgoing) setup and working. This presented a couple of barriers to sharing that are unacceptable in 0.6:

Thus, in 0.6, we will not require email accounts to be setup in order to publish or subscribe to shares.

How to share your personal calendar needs to be obvious to the user in 0.6.

Sharing a collection the first time


    When a user shares a collection, Chandler
Under the hood, Chandler

Subscribing to a shared collection, the first time

In order to subscribe to a share, sharees



Managing a shared collection from the Sharer's perspective


Once a user has shared a collection (either a source collection or a portion of a source collection), the user can manage the shared collection

Managing a shared collection from the Sharee's perspective



Receiving updates to a Share


As of right now, updates to shares are automatic and sharees are not provided with any notifications of changes to shares. Some candidates for change notifications:

Preserving Sharing Notification Via Email

We have already made the high-level decision that we will not expose the existing sharing management notification UI that was available in 0.5. We will think about bringing back this feature when our Chandler email functionality is more fully developed.


Receiving a Sharing Notification

In 0.5 users received sharing notifications in a special email with a link that automatically downloaded the shared collection added it to the sharee's sidebar. In 0.6, we will not support special sharing notification emails. Instead, sharees will receive sharing URLs out-of-band and enter them manually into the Subscribe dialog.

Restoring shares


If a users blows out their repository (which will be highly likely in the 0.6 timeframe), users need to be able to download previously published and subscribed to shares from whatever servers they were using. Ideally, we would like this to happen automatically, when the user sets up their sharing account information. Once the user re-enters their account info, Chandler could go out to the server and re-establish the published and subscribed to shares.


[Sheila] I would say this is a stretch goal for 0.6 but since we delete our repository frequently, it would be a big win if we can do it. Morgen has it on his list for now and we will see what we get done by M5.

Account Setup

The WebDAV account setup GUI will remain mostly unchanged from 0.5. However we will no longer pre-configure Chandler with a default account. Instead, Chandler will have no sharing accounts out of the box. The user must enter sharing account information on their own in order to share.

To make this easier, we will

Navigating Shares and the Sidebar

Shared collections appear in the sidebar with a sharing status icon to the right of the collection name.

In order to have the error icon appear, you must have synched this collection at least once first. If an error icon appears in the sidebar, it stays in this state until the user synchs this collection again successfully. Errors occurring when publishing or subscribing to a collection are not reflected in the sidebar. For more details, consult the Sidebar Spec.

Unpublishing a Share

Only sharer's can unpublish a share. Sharers can unpublish a share in any of 3 ways:

When users unpublish shares, an "Are you sure you want to do this" dialog should pop up: Other people may be subscribed to share this collection, are you sure you want to unpublish/delete it? Okay, Cancel.

Unsubscribing to a Share

Sharer's cannot unsubscribe to a Share, they can unpublish only. Sharees can unsubscribe from the Manage share dialog, they cannot unpublish the share. There should be 2 menu items under the collection menu for Unpublish and Unsubscribe. One of them will be greyed out accordingly depending on whether the particular collection selected has been published or subscribed to.

Menu items



    The following sharing related menu items appear under the Collection menu
If the selected collection is not shared:
If the selected collection is already shared:
If the user is the sharer:
If the user is a sharee:
Managing per-item, per user access priveleges in Resharing scenarios

UI Requirements

ACLS need to be kept track of on a per-sharing participant, per-item basis.

There are 3 possible states for every item:

  1. Read-only
  2. Read-write
  3. Not shared


There are two steps in determining the ACL of an item

  1. The ACL of the URL the sharee accessed the share with
  2. Does the sharee already possess the item through some other context (ie. via a different share or via a share they created themselves). If so, the higher, more liberal ACL always overrides (read-write) the lower, more narrow ACL (read-only).

Rules for determining read write or read only permissions for an item

For 0.6 we are not handling ACLs on a per-resource basis. For this reason, the read only and read write permissions of various shared and reshared items will not be ideal for 0.6. We have decided to use the following algorithm to determine the ACLs for a particular item.

1. If an item is unshared, all attributes are editable. This means for any Chandler user, that has not published or subscribed any shares, should be able to edit all information for an item.
2. For all shares for which I am NOT the sharer (subscriber only), then any attribute that is read write, should be editable. This means that if I subscribe to a share with read write privileges, I can edit the items.
3. For all subscribed shares for which the attribute in questions is not shared editable (read only), then these attributes are not editable. If I receive a read only share and drag this event to another collection, it remains read only. If I share this new collection out to User B as read write, then User B CAN edit this item although I cannot. We realize this is not the ideal behavior but until we have ACLs on a per resource basis, this limitation is ok.

These scenarios are futher expanded below.

1. User receives an item via a read-only share and then shares it out in a read-write share

If a user receives an item via a read-only share, they can add it to any of their other collections (shared or not shared).


If they add the read-only item to another collection which they are sharing read-write, the item maintains it's read-only-ness only for the sharer. Any sharees of this collection will be able to edit this item.

2. User receives an item via a read-write share and then shares it out in a read-only share

If a user receives an item via a read-write share and they add it to a collection they are sharing OUT, read-only, they should retain read-write access to the item. However, all sharees of the read-only share should only have read-only access to that item....IF the sharee does NOT already have or gain read-write access to the item via some other context.


Example: Caroline subscribes to the 543 Howard Street building maintenance calendar, read-write. She adds the  "Drill big hole between 4th and 5th floors" event to the Carpet cleaning calendar, which she created and shared read-only with the Custodial staff. Caroline maintains read-write access to the event. However, the Custodial staff receive the item, read-only.


But...the head of the Custodial staff ALSO happens to subscribe to the 543 Howard Street building maintenance calendar, read-write. As a result, he ALREADY has read-write access to the  "Drill big hole between 4th and 5th floors" even via the 543 Howard Street building maintenance calendar. Therefore, the head Custodian should NOT lose his read-write access to the event.

3. User receives an item via a read-only share and then receives the same item via a read-write share


If a user receives an item via a read-only share and then receives the same item via a different read-write share, the read-write-ness of the item inherited from the read-write share overrides the read-only-ness of the item inherited from the read-only share.


Example: In the mean time, Caroline, who has read-write access to the 543 Howard Street building maintenance calendar also decided that it would be a good idea to add the "Drill big hole between 4th and 5th floors" event to the KEI office calendar. Now the same event: "Drill big hole between 4th and 5th floors" has been added to the KEI office calendar, except this time with read-write priveleges. When Blue syncs her KEI calendar with the server, Carolines read-write priveleges on the event should override Blue's read-only priveleges. Blue should have read-write priveleges on the event in bothe KEI AND the 543 Howard Street building maintenance calendar.


4. User shares out an item and then receives it back via a different read-only share


If a user shares an item in a read-only share and then receives the same item back via a different read-only share, the read-only-ness of the item inherited from the read-only share is overwritten by the fact that the item was originally shared by the user.


Example: Blue creates the KEI Construction schedule calendar and shares it out either read-write or read-only (it doesn't matter in this case) with all of KEI. Caroline decides to add an event from the Construction calendar: "Fixing retardo doors that push and pull rather than slide" to the 543 Howard Street building maintenance calendar, which Blue subscribes to read-only. Because Blue originally created and shared the "Fixing retardo doors that push and pull rather than slide" event out to Caroline, the fact that she's now receiving the same event via a read-only share does NOT override her read-write access privilege to the event.

The basic rules are

  1. In the case of Inbound shares, given a choice, sharees always receive the items with the higher access level (read-write)
  2. In the case of Outbound shares, given a choice, sharees always receive the item with the lower access level (read-only)

Read-only shared collections and UI behaviors


Unstamping items in filtered shares

1. Adding items to a filtered share that do not meet the kind-based parameters set by the filter

Users are allowed to add items of any kind to a collection, regardless of whether the collection is  a filtered share. Items that do not meet the kind-based parameters set by the filter are simply not shared.

Example: June share her "My calendar" collection with Bug. Bug now has a "June" collection in his sidebar, but only the calendar portion of it is shared. Bug wants to add emails from June and tasks assigned to him by June to his June collection. Chandler will not prevent Bug from doing that. However, none of these email and task items will be shared with June unless Bug puts them on June's calendar.

2. Unstamping items in a filtered share such that they no longer meet the kind-based parameters set by the filter

If a user unstamps an item in a filtered share, such that the item no longer meets the kind-filter query parameters for the share, the item remains in the user's collection as an "unshared item" and is removed from the shared collection of all other sharing participants.

Example: June shares her "My calendar" collection with Bug. Bug decides for some odd reason to unstamp one of the events on June's calendar: "List of things to buy at the mall". The item now exists simply as a note in Bug's June collection. However, because it is no longer an event, and only the calendar portion of the June collection is being shared, the "List of things to buy at the mall" item gets removed from the server. As a result, the item is also removed from the June collection for all other subscribers (including June).

Marking items as private

If an item is marked as private before it has been shared, it should never be shared when this collection is published.

If an item is marked as private after it has been shared, it should be removed from the shared collection for everybody except for the person who marked it as private. We realize that this action causes the item to disappear from the server and it's possible for one read write sharer to mark someone else's item as private and have it disappear from their share. This is fine for 0.6 and we will popup a confirmation dialog to alert the user that this item will disappear for other sharers. A confirmation dialog should pop up: "Other people may be subscribed to share "such-and-such" item, are you sure you want to mark it as private? Okay, Cancel"

If an item in a shared collection is marked as private and we change it to public, the item simply get uploaded to the server the next time this user synchs.


Protocol Interactions

The protocol interactions are described at http://www.sharemation.com/~milele/public/dav/draft-ito-dav-ticket-00.txt. Chandler will implement a subset of that I-D. We will support only the MKTICKET request to create a ticket and not the DELTICKET request. We don't need to support the 'ticketdiscovery' property either if we simply remember the ticket in the response to the MKTICKET request.

Note that the defined protocol interactions require two round-trips for Chandler to create both a read-only ticket and a read-write ticket. This is acceptable.

Request Ticket

The MKTICKET request will be supported. The privilege field will be used but the timeout will always be infinite and the use limits will always be ""infinity".

The spec is incomplete -- it doesn't define how to do infinite timeouts, but this may be a "timeout" value of "infinity" similar to the use limit (we can test www.sharemation.com if we want to interoperate with Xythos WFS servers). Or we can omit the "timeout" element and this should default to "infinity".

Merging Changes

In 0.6 sharing, we will leverage the repository's view merging function to allow non-overlapping local/remote changes to be synchronized. The algorithm for using a separate repository view to deal with sharing is spelled out at this wiki page.

Changes to different attributes can be automatically merged -- the client simply uploads a new copy of the item with both attribute changes applied. Overlapping changes (conflicts) will be handled by logging the conflict in the client, and automatically choosing a local change over a remote change. In the future, conflict resolution could be presented to the user.

Tracking Sharing Patterns

Other work planned in 0.6 (and not specified here) includes an instrumentation framework -- a way to save and update counts, similar to log messages. Sharing will take advantage of this framework in order to track how sharing is used.

[Sheila 07/25/2005] I don't actually think we are going to be tracking all this. Morgen will be displaying a report of changes and conflicts but we are not planning on having any totals.

Tracking Sharing Changes

Is it possible to extend the instrumentation mechanism mentioned above to track changes made to shares?

Content Model Changes

In order to determine whether a given item is shared (and whether it is read-only) there will need to be additions to the content model; most likely we'll need bi-directional ref collections between Share and ContentItem to make it easy to see which Shares a given ContentItem participates in.

Specials Considerations

API Changes

Zanshin "createTicket" method on a Resource

Object: Resource

Method: CreateTicket

Parameters: permission flag (read-only vs. read-write)

Return value: Returns a URL for the resource with the requested ticket included in the URL?

QA/Test

GUI Testing: Ad-hoc

Interoperability Testing: Would be great to test with multiple WebDAV servers, including one that doesn't support tickets. In the case of a server not supporting tickets, we would provide only a single URL and not mark it as read-only or read-write (because we wouldn't know)

Server-side Collection/Resource Structure

In order to minimize the number of URLs the user has to manage for a shared ItemCollection, and to allow interoperability with other clients, the data stored on the server will be arranged as follows:

For example: 

~username/
   /collection-name/
      /af0418dc-bbe9-11d9-b9e2-00e018e1e422.ics
      /bf0418dc-bbe9-11d9-b9e2-00e018e1e422.ics
      /cf0418dc-bbe9-11d9-b9e2-00e018e1e422.ics
      /.chandler/
         /share.xml
         /af0418dc-bbe9-11d9-b9e2-00e018e1e422.xml
         /bf0418dc-bbe9-11d9-b9e2-00e018e1e422.xml
         /cf0418dc-bbe9-11d9-b9e2-00e018e1e422.xml
         /df0418dc-bbe9-11d9-b9e2-00e018e1e422.xml

Note, there may be more .xml files than .ics files since not all items will have CalendarEvent data associated with them.

Serialized Representation of Chandler Items

For interoperating with non-Chandler clients we will be using standardized file formats where applicable. For 0.6 this means using iCalendar format files published to the WebDAV/Cosmo server. However, for the Chandler-specific data we have more flexibility. For 0.5 we implemented an "Cloud XML" format which handles basic item sharing, but which needs improvement in the areas of representing complex data structures. For this reason a goal for 0.6 is to start using the already-existing "native repository XML" format (with some sharing-specific modifications) which will allow us to share any types of information that the repository supports. Since these files aren't meant for non-Chandler clients to consume, we could even use a binary format which the repository natively supports.

Deferred Features

Event Sharing: We would like to experiment with the ability to generate and share event URLs in 0.6. This feature is still in the proposal stage and has not been fully defined at this point. Once we have a better handle on the scope and schedule for the core 0.6 sharing features we will revisit what event sharing goals might be doable for this release.

History

Author Edit date Description
Lisa Dusseault April 13, 2005 First Draft
Sheila Mooney April 19, 2005 Second Draft
Sheila Mooney July 26, 2005 Final review edits