OWIN SendFile Extension v0.3.0

 

Authors: The OWIN working group

Copyright: OWIN Contributors

License: Creative Commons Attribution 3.0 Unported License

Last Modified: 3 December 2012

Contents

1.       Introduction

2.       Definitions

3.       Detection

3.1.    Startup

3.2.    Per Request

4.       Delegate Signature

5.       Consumption

1.    Introduction

This document outlines the recommended patterns for consuming a server’s direct file transmission capabilities through the OWIN interface. It depends on OWIN v1.0.0 (but may work with other versions) and uses the extension key mechanics as outlined in CommonKeys.html.

2.    Definitions

SendFile – A server or platform feature that is capable of optimizing the copy of a files contents to the response output.

3.    Detection

In order for an application to use SendFile it MUST first detect support for the extension. 

3.1 Startup

At startup the server SHOULD specify in the Properties “server.Capabilities” dictionary if SendFile is supported (see the table below).  If the application does not see support for SendFile it MAY insert a middleware to add SendFile support.

Key Name

Description

“sendfile.Version”

The string value “1.0” indicating version 1.0 of the OWIN SendFile extension.

“sendfile.Support”

An IDictionary<string, object> containing feature details. This key and value do not need to be present if the dictionary would be empty.

“sendfile.Concurrency”

Placed in the sendfile.Support dictionary, the string value “Overlapped” indicates support for multiple outstanding async operations.

3.2 Per Request

The SendFile capable server or middleware adds the SendFileFunc to the environment dictionary for an application to utilize.

Key Name

Description

“sendfile.SendAsync”

The SendFileFunc provided by the server or middleware for the application to utilize.  See Delegate Signature.

4. Delegate Signature

The SendFile Func signature is as follows:

using SendFileFunc =

        Func

        <

            string, // File Name and path

            long, // Initial file offset

            long?, // Byte count, null for remainder of file

            CancellationToken, // Cancel

            Task // Complete

        >;  

5. Consumption

The server or middleware provides the SendFileFunc in the environment dictionary.  The consumer checks for its presence and invokes it once for each file range to be sent.  Before, after, or in between SendFile operations the consumer MAY also write to the response body stream.  If the consumer does write to the response body stream, they SHOULD flush the stream to ensure proper ordering with SendFileFunc invocations.  The server or middleware implementing SendFileFunc MUST NOT complete the corresponding Task until it is completely finished accessing the named file.  Once complete the application MUST be able to perform any normally allowed operations on the file including rename, modify, append, or delete.

Invoking the SendFileFunc SHOULD result in the response headers being sent if they have not already been, so the consumer MUST complete any necessary headers in advance, including range, content-length, transfer-encoding, etc..

Some implementations MAY permit SendFileFunc to be invoked multiple times before the prior operations have completed.  This capability is advertised with the key “sendFile.Concurrency” and value “Overrlapped”. When consuming this feature, the application must still wait for the synchronous SendFileFunc invocation to return a Task before initiating the next call.

Middleware that wish to replace, augment, or otherwise intercept SendFileFunc operations MAY do so by replacing the Func in the environment dictionary, possibly creating an invocation chain.

File names and paths SHOULD be absolute disk paths, e.g. “c:\myapp\myfile.ext”.  Routing middleware MAY assist in mapping relative URIs or disk paths to absolute disk paths.

When the given CancellationToken is triggered the server or middleware processing the file SHOULD promptly stop transmitting the file and cancel/fail the returned Task.  Canceling an incomplete file send is presumed fatal to overall request.  Additional Writes or SendFile calls should not be attempted if SendFile fails.