gistfile1.txt

Assets V2
========

SDK
====

Async assets
--------------------

* Assets can be created without a synchronous file post
* File can be supplied after the fact
    * Files supplied post-creation go to ingest URL in a seperate request in >=1 post
* SDK can build ingest URLs (ingest.videojuicer.com/seed/asset_type/key)

Core API
=======

The ingest service supports server-side progress monitoring for current browsers and chunked posting and stitching for future browsers (starting with FF 3.6).

Creating a chunk-ingested asset...

* Create a _non-derived_ asset without file
* Assets like this report back an ingest key (possibly a UUID - anything random)
* continue to support direct posting for smaller files (synchronous workflow)
* new states: ingesting, ingested
 -- may wish to update state ingesting -> ingesting every time a chunk is received

Ingest Service (can't be part of core as it can't sit behind ELB)
* note this has to be a single service on a single instance - no load balancing
  -- possible JVM candidate (scala?)
* secret key handshake needed between core -> user -> ingest...
  -- panel has rights to create asset -> so _authorized_ consumers get an ingest key back
  -- ingest key is then provided back to ingest service (ingest URL) which can do a secure lookup on core
* runs a chunked posting service which will only actually employ chunking when the client supports FileReader
* when the client is chunking, each part is provided along with a file offset, for later re-stitching by the service
* note that no checksumming is strictly required here as each portion of data is being handled by the browser's own plumbing rather than routing through Flash
* receives final 'done' from the client and commences stitching / shuts down write credentials
* updates core with the source_uri that the ingest service is now ready to serve

State timeline
--------------------
create: pending
post to ingest service: ingesting
post 'completion' to ingest service: ingested
 -> back to normal -> to_acquire, acquiring, to_stow, stowing, ready


Panel 
=====

Upload workflow
------------------------

Javascript namespace
---------------------------------

AssetUpload - A single file upload which presents methods for getting progress and other state information, as well as starting/cancelling/resuming(?) an upload
AssetUploadController - The singleton class which maintains the stack of all active, failed and completed AssetUpload instances and provides logic for querying and displaying this state

AssetUploadStrategy - An abstract class that provides an interface for presenting a file selection field to the user, posting that data to the server, and retrieving the state for that AssetUpload. A single AssetUpload instance may use any strategy, but in practice we will configure the strategy for ALL AssetUpload instances when the application first loads by attempting to reference the FileReader class and catching the raised exception. An AssetUpload is instantiated with a JSON hash of asset properties for the asset we will be populating.

AssetUploadFileReaderStrategy - The new and shiny FileReader-based strategy.
AssetUploadIFrameStrategy - The old and busted hackety-hack iframe shite.
AssetUploadFlashStrategy - Something we will hopefully never have to build.

Fallback (when features not available in browser)
---------------------------------------------------------------------

* Use framed synchronous post and server-side progress reporting
* Each upload "job" contains a single file and is represented by an iframe containing something like:

    <iframe src="/assets/new?async=false&id=12"></iframe>
    which contains:
    <form action="uploader.lol" enctype="manypartslol" id="uploader">
        <input type="file" name="thefile" />
    </form>
    <script type="text/javascript">
        // some code that repeatedly polls server for progress data
        function pollLol() {
            jobState = // get job state from server as JSON
            var bytesLoaded = jobState["bytesLoaded"]
            var bytesTotal = jobState["bytesTotal"]
        }
        setInterval(pollLol, 500);
    </script>
    
* given the iframe has an id of upload_controller_12:
    * We can call $("#upload_controller_12").document.forms[0].submit(); to control the submit of the form

Each upload strategy is a module which provides methods for:

* Displaying a file selector element
* Posting the file to a URL
    // FileReader strategy: fileReader.post(url, etc. etc.)
    // IFrame strategy: $("theiframe").document.forms[0].submit();
* Retrieving the job's state and progress

Recovery from failure
-------------------------------