-
Notifications
You must be signed in to change notification settings - Fork 14
WebAppIntegration
v7files can be integrated into web applications (written in any language) to serve as a file storage backend. This works by running v7files in a mode that accepts HTTP POST requests that contain files to be uploaded on behalf of the web application.
Instead of the files being exposed via a WebDAV file system, they will then be completely under the control of application.
The connection between file contents managed by v7files and the application
that uses them is established via so-called "buckets". A bucket is a document
in the v7files.buckets collection that is created by the application and contains
control information how the bucket should work.
To enable the buckets service, configure a URL prefix as its endpoint
buckets.endpoints = upload/
Almost all other configuration is done via the individual buckets. Without a bucket the endpoint will not do anything.
To create a bucket, the application creates a MongoDB document
in the buckets collection (v7files.buckets).
The _id for that document is a String. It should not contain slashes and becomes part of the URL, right after the endpoint prefix configured above.
The other fields control how files can be uploaded and downloaded through this bucket.
Uploaded files (above a certain size threshold for inlining) are stored in the V7files content storage, just like the contents of WebDAV files. This results in a SHA hash by which they can then later be retrieved. Depending on the mode of operation (configured in the bucket), this SHA hash (along with other metadata such as the file name) is either stored in the bucket document itself, in some other collection or just passed along to the application.
The simplest way to uploads is to accept HTTP POST requests containing form-encoded parameters and file uploads coming directly from the end user's browser (not via the application server), and record them in the bucket document itself. We call this the "FormPost protocol".
FormPost mode is enabled for a bucket by setting the POST field to FormPost.
For every upload, an "upload document" is created and pushed onto the
FormPost.data array of the bucket. It contains the following fields:
-
parameters: The non-file form parameters sent with the request. -
files: The files uploaded with the request. Fields arefilenamefor the file name, andshaorinwith the file contents. -
_id: Every individual upload also gets a unique id (a MongoDB ObjectId). You can also get the upload timestamp from it.
After an upload (successful or not), the client browser is redirected to a URL
configured in the bucket (FormPost.redirect) where the application
server can process the uploaded data (the id of the nested document that holds this data is passed along).
FormPost is intended primarily as a temporary staging area for accepting user uploads that the application will then move to a more permanent location. It is recommended to create new buckets with long random ids on a per-user, per-transaction basis (and delete them afterwards). This way, access can be controlled by means of sharing the bucket id.
Files can also be downloaded again using a GET request against the bucket.
To enable this, set the GET field to FormPost as well.
The url is <endpoint>/<bucket>?sha=AAA...., where sha is the hex-encoded digest of the file.
A file with the specified digest must exist in the FormPost.data array, otherwise a 404 Not Found error response will be returned.
You can optionally also pass along the filename you want the download to have as the filename parameter in the GET request. Without it, the original upload file name will be used (in the case that the same file exists more than once in the bucket, one of the names will be chosen at random).
The FormPost protocol is very useful for direct uploads from browsers, but a little clumsy if you want to upload files from the application server. For this, you can issue PUT request in what we call the "EchoPut protocol".
EchoPut mode is enabled for a bucket by setting the PUT field to EchoPut.
In EchoPut mode, v7files stores the contents of the files, but does not keep track of anything else. Instead it returns a String with the hex-encoded SHA digest of the file just uploaded. It is up to the application server to save this somewhere.
You should not expose this endpoint to the outside world. All access must go through the application server.
Files can also be downloaded again using a GET request against the bucket.
To enable this, set the GET field to EchoPut as well.
The url is <endpoint>/<bucket>?sha=AAA...., where sha is the hex-encoded digest of the file.
The difference to FormPost mode is that this allows downloads of any file in the whole database, regardless if they have been uploaded through the bucket or not
(of which there is no record anyhow). The filename for the download will not have been recorded, either, so you can specify it as the filename parameter in the GET request.