RackFiles specification

This feature allows storing arbitrary files (attachments) in the RackTables database. The files can be:

  • uploaded
  • downloaded
  • referenced
  • updated
  • deleted
  • linked

Referencing (attaching) is linking a file to some entity. For example, a digital picture can be attached to an object, one same PDF manual can be attached to any number of objects, a spreadsheet or diagram can be attached to a network or virtual service. This way, a file can be "used" 0 or more times anywhere on the database.

As long as the files have their own life, a new top-page "Files" will be added to the index page. The "Files" is a simple editor for the list of files. This editor would allow uploading a new file, deleting, and following to each file's details page. This "File" page would allow to re-upload the file, change "filename" and mime-type, manage links of the file (only allowing to delete links from here is acceptable), to download and to manage tags. Files can be tagged.

Each entity, which can be tagged (object, network, VS, RS pool, user, rack), should have two changes applied. First is to add "files" tab, which would allow picking a file from the list and attaching it to the current entity (allowing to delete existing records would also help). Second is to modify the "default" tab to list links to attached files (if any). Showing a thumbnail for gfx files would be cool, but isn't expected in the initial implementation.

database: things to do

The feature requires two new tables: one for the files and another for their links. This is much like the way tags are stored (TagTree and TagStorage SQL tables respectively). Additionally, the TagStorage must be ALTERed to allow new entity type ("file"). All changes shoud be reflected both in the installer scenario and in upgrade one. A traditional way to test if they concur is to dump the upgraded database and the freshly installed one. The dumps must produce no meaningful diffs. Now, on to the tables.

Files table. For the sake of security and backup consistency the binary data of all files is stored right in the table (no helper directories whatsoever). Then, each file should have:

  • filename (only for reference, not mandatory, not unique)
  • ctime, mtime and atime timestamps. ctime is set only once, when the record is first created. mtime is set each time the binary data is reuploaded. atime is set each time the file is downloaded.
  • id (unique integer key) like the key for any other entity
  • BLOB for the data

FileLinks table. Each reference is characterized by:

  • file id
  • entity type (object, user, rack, etc.)
  • entity id

An index is necessary in this table, which would make sure, that for each entity the list of files can be retrieved quickly. Another index for the file "name" would help in searching. List the changes to SQL in upgrade.php

code: things to do

There are two parts: the first is absolutely necessary for the initial implementation. The next one adds some finish to the feature to make everything work consistently.

part 1

New records should be added to the navigation.php to show the new page (with its tabs) and new "files" tabs on other pages. The index page should be modified to list the big icon for files. Get the files icon from the Crystal icon set, we are already using it. Add a set of functions in ophandler.php to handle user requests. Add a set of functions in database.php to actually work with the DB. Write some getEntityFiles() function to return data for "files" tab (a la loadTagsForEntity() one) The search function must be altered to include search results for the files. (look for the current code, which implements user search, and implement file search the same way). The file editor for any entity can (and should) be implemented by one single function, exactly the same way "tags" tab is currently implemented for everything.

part 2

Autotags. When a user is working with the object, there's an autotag pushed into context: {$id_NNNNN}. For files, similar autotag must be introduced: {$fileid_NNNNN}. This tag would be always present, when "file" page is operated. Additionally, it must be set, when "files" tab is operated for any entity. The "Files" page must have a tag filter on it, so a user can filter files displayed.