GridFTP Google Drive DSI {#mainpage}
========================
This document describes the GridFTP DSI for the Google Drive API. A GridFTP server configured to use this DSI will provide each local user with access to their Google Drive folders and files.

## Installation

Install the package globus-gridftp-server-google-drive from the Globus respository.

For Red Hat-based systems:
```
  % sudo yum install globus-gridftp-server-google-drive
```
For Debian-based systems:
```
  % sudo apt-get install globus-gridftp-server-google-drive
```
## Configuration

The Google Drive DSI requires the following steps for configuration:

- Configure the GridFTP Server to Use the Google Drive DSI
- Configure the Google Drive DSI
- Restart the GridFTP server
- {Each User}: Authorize the GridFTP server to access Google Drive


### Configure the GridFTP Server to Use the Google Drive DSI

Create the file ```/etc/gridftp.d/gridftp-google-drive``` containing these lines:

```
 threads 2
 load_dsi_module google_drive
```

### Configure the Google Drive DSI ###

See the @ref config "Configuration File Documentation" document for details on the
configuration options for the file ```/etc/globus/globus-gridftp-server-google-drive.conf```

Note that the binary packages for the DSI contain reasonable default values.

### Restart the GridFTP server ###

```
    # service globus-gridftp-server restart
```

## Google Drive File Space

The Google Drive File space consists of a number of top-level folders:
- `/My Drive`
  - Files created by the current user. This is effectively the user's "Home Directory" on Google Drive, and is treated as `/~/` from the GridFTP server's perspective.
- `/Starred`
    - Files which have been "starred" by the user. Files and folders appear in this folder when the user clicks the star in the Google Drive web interface. Users can not directly create files in this directory via the DSI.
- `/Shared With Me`
    - Files which have been shared with the user by another Google user. Files and folders appear in this folder when another adds the current user to the ACL for that file or folder. Users can not directly create files in this directory via the DSI.
- `/Team Drives`
    - The children of this folder are Google Team Drives which have been shared with you. Unlike normal shared files, these *are not* included in the `/Shared With Me` folder.
- `/Trash`
    - Files which have been trashed but not completely deleted yet. This trash includes files that you own and deleted files in Team Drives.

### Filename Considerations

Google Drive allows objects to have arbitrary Unicode
names, including the '/' within a file name. It also allows
multiple file or directory objects with the same name to be present in a
directory.

When listing a directory that contains multiple objects with the same names,
they are *all* listed. However, the objects which have ambiguous names may
not be directly operated on.

The following transformations are done on file names which are generated
by the DSI in a file listing:
- Google Docs files have an application-specific extension appended to their
  names, as described below

For files containing the '/' character in the file name:
- '/' (anywhere in a file name) becomes '{slash}'
- '{slash}' (anywhere in a file name) becomes '{slash+}'
- '{slash+}' (anywhere in a file name) becomes '{slash++}'
- The pattern continues for additional + characters before the closing brace,
  where the encoded name includes one more + than the original Google Drive
  file name.

For files called '.' or '..':
- '.' (only if that is the entire file name) becomes '{dot}'
- '..' (only if that is the entire file name) becomes '{dotdot}'
- Note: These translations only occur if the entire file name is "." or "..".
  Those characters within a file name containing other characters are not
  modified.

For files called '{dot}', '{dot+}', '{dot++}', etc
- '{dot}  becomes '{dot+}'
- '{dot+}  becomes '{dot++}'
- This pattern continues for additional + characters before the closing brace,
  where the encoded name includes one more '+' character than the original
  Google Drive file name.
- Note: These tranlsations only occur if the entire file name matches the
  {dot+...} pattern. That pattern within a file name containing other characters
  is not modified.

For files called '{dotdot}', '{dotdot+}', '{dotdot++}', etc
- '{dotdot}  becomes '{dotdot+}'
- '{dotdot+}  becomes '{dotdot++}'
- This pattern continues for additional + characters before the closing brace,
  where the encoded name includes one more '+' character than the original
  Google Drive file name.
- Note: These tranlsations only occur if the entire file name matches the
  {dotdot+...} pattern. That pattern within a file name containing other
  characters is not modified.

The following transformations are done on components of file names which are
consumed by the DSI as parameters to file system operations:
- Names that end in a Google Docs extension have that removed before using
  the name to resolve the object id of the file.
- '{slash}' becomes '/'
- '{dot}' becomes '.'
- '{dotdot}' becomes '..'
- '{slash+}' becomes '{slash}'
- '{slash++}' becomes '{slash+}'
- The pattern continues for additional + characters before the closing brace,
  where the encoded name includes one fewer + than the original source file
  name.

Names that exactly match the pattern '{dot+}' with any number > 0 of +
characters are replaced with the same string with one fewer + characters.
Names that exactly match the pattern '{dotdot+}' with any number > 0 of +
characters are replaced with the same string with one fewer + characters.

## Google Docs Support

The DSI has some support for processing Google Docs files. In a file
listing, a Google Docs file has the following extension added:

<center>
| Mime Type                                  | Extension   |
|--------------------------------------------|-------------|
| `application/vnd.google-apps.document`     | `.gdoc`     |
| `application/vnd.google-apps.drawing`      | `.gdraw`    |
| `application/vnd.google-apps.presentation` | `.gslides`  |
| `application/vnd.google-apps.spreadsheet`  | `.gsheet `  |
| `application/vnd.google-apps.map`          | `.gmap`     |
</center>

When a GridFTP client attempts to retrieve a file of one of these types, the
DSI generates a JSON-formatted document stub (intended to be the same as) the
type generated by the Google Drive Desktop Application.

When a GridFTP client attempts to store a file with one of those extensions,
the DSI parses the data as a JSON-formatted document stub and copies the
Google Docs object it refers to the destination path.

Uploading something other than a JSON-formatted document stub, or a
JSON-formatted document stub that refers to a document that cannot be accessed
by the Google Drive user will fail.
