Uploaded files are stored with Files cards: cards whose type is "File".

 

Creating or editing a File card will prompt you with a standard upload interface.

 

security

 

Most content managers do not check permissions on file downloads; if you know the url, you can get the file.  They may try to keep the url a secret, but the internet being what it is, that's not a terribly safe approach.

 

By contrast, Wagn checks card permissions on every user's initial download of every protected file. 

 

In technical terms, most systems expose directories of uploaded files directly to the webserver, so that the application isn't involved in any way in web requests.  That makes it pretty much impossible for the application to check permissions on the files.  Wagn, on the other hand, associates every file (including every image) with a card, and the read permissions on the card are equivalent to the read permissions on the file.  Once Wagn determines that the user has permission to view the file, it hands the process back to the server (via xsendfile), and the download begins.

 

performance

 

Won't all this extra permission checking slow things down?  The primary answer is that we keep things fast by only doing these checks once.  Wagn gives unique urls to each file and image revision and instructs browsers to use cached versions of those revisions after the first download.

 

We will also soon be implementing optimizations to insure that public files (those that can be read by "Anyone") will skip permission checking altogether.

 

urls / api

Web API
/<cardname>
/<cardname>.<ext>                    # accepts "rev" param specify revision number
/files/<card_id>/<action_id>.<ext>

Examples:
GET /my_paper                        # returns card (html page).  content is download link
GET /my_paper.pdf                    # returns file.  most recent revision.  browser cannot cache
GET /files/~67/12345.pdf             # this is what is linked to in card content.  returns file.  server tells browser to cache permanently.

 

 

file storage

files/:card_id/:action_id[-:size].:extension

• by default the files directory is in "local" before 1.13 and in the app root beginning with 1.13
• you can configure a custom files directory in wagn.yml with "attachment_storage_dir"
• the files should NOT be directly exposed to the webserver (eg, by putting it in the "public" directory); this would negate all the value of wagn's permission checking.
• :size only applies to images and can be any of the following: icon, small, medium, large, original

 

special views

 

All file cards have a "source" view that will provide a standard url for the card (see the third variant above).