|
| 1 | + |
| 2 | + |
| 3 | +# About |
| 4 | + |
| 5 | +A HTTP 206 Partial Content handler to serve any readable stream partially in Express. |
| 6 | + |
| 7 | +Based on this blog post: https://www.codeproject.com/Articles/813480/HTTP-Partial-Content-In-Node-js. |
| 8 | + |
| 9 | +# Installation |
| 10 | + |
| 11 | +`yarn add express-partial-content` |
| 12 | + |
| 13 | +OR |
| 14 | + |
| 15 | +`npm install express-partial-content` |
| 16 | + |
| 17 | +> Note: `Express` package is a peer dependency for `express-partial-content` and must be present in dependencies of the host package. |
| 18 | +
|
| 19 | +# Usage |
| 20 | + |
| 21 | +From the `express-file-server` example: |
| 22 | + |
| 23 | +1. Implement a `ContentProvider` function which prepares and returns a `Content` object: |
| 24 | + |
| 25 | + import { promisify } from "util"; |
| 26 | + import fs from "fs"; |
| 27 | + import { Range, ContentDoesNotExistError, ContentProvider } from "express-partial-content"; |
| 28 | + import {logger} from "./logger"; |
| 29 | + |
| 30 | + const statAsync = promisify(fs.stat); |
| 31 | + const existsAsync = promisify(fs.exists); |
| 32 | + |
| 33 | + export const fileContentProvider: ContentProvider = async (req: Request) => { |
| 34 | + // Read file name from route params. |
| 35 | + const fileName = req.params.name; |
| 36 | + const file = `${__dirname}/files/${fileName}`; |
| 37 | + if (!(await existsAsync(file))) { |
| 38 | + throw new ContentDoesNotExistError(`File doesn't exist: ${file}`); |
| 39 | + } |
| 40 | + const stats = await statAsync(file); |
| 41 | + const totalSize = stats.size; |
| 42 | + const mimeType = "application/octet-stream"; |
| 43 | + const getStream = (range?: Range) => { |
| 44 | + if (!range) { |
| 45 | + // Request if for complete content. |
| 46 | + return fs.createReadStream(file); |
| 47 | + } |
| 48 | + // Partial content request. |
| 49 | + const { start, end } = range; |
| 50 | + logger.debug(`start: ${start}, end: ${end}`); |
| 51 | + return fs.createReadStream(file, { start, end }); |
| 52 | + }; |
| 53 | + return { |
| 54 | + fileName, |
| 55 | + totalSize, |
| 56 | + mimeType, |
| 57 | + getStream |
| 58 | + }; |
| 59 | + }; |
| 60 | + |
| 61 | +2. In your express code, use `createPartialContentHandler` factory method to generate an express handler for serving partial content for the route of your choice: |
| 62 | + |
| 63 | + import {createPartialContentHandler} from "express-partial-content"; |
| 64 | + import {logger} from "./logger"; |
| 65 | + |
| 66 | + const handler = createPartialContentHandler(fileContentProvider, logger); |
| 67 | + |
| 68 | + const app = express(); |
| 69 | + const port = 8080; |
| 70 | + |
| 71 | + // File name is a route param. |
| 72 | + app.get("/files/:name", handler); |
| 73 | + |
| 74 | + app.listen(port, () => { |
| 75 | + logger.debug("Server started!"); |
| 76 | + }); |
| 77 | + |
| 78 | +3. Run your server and use a multi-part/multi-connection download utility like [aria2c](https://aria2.github.io/) to test it: |
| 79 | + |
| 80 | + aria -x5 -k1M http://localhost:8080/files/readme.txt |
| 81 | + |
| 82 | +# Examples |
| 83 | + |
| 84 | +There one examples in the `src/examples` folder: |
| 85 | + |
| 86 | +1. `express-file-server`: Implements a file based `ContentProvider`. |
| 87 | + |
| 88 | +## Running the examples: |
| 89 | + |
| 90 | +1. `express-file-server`: Run the following commands, the server will listen on http://localhost:8080/. |
| 91 | + |
| 92 | + yarn build:dev |
| 93 | + yarn copy-assets |
| 94 | + yarn run:examples:file |
| 95 | + |
| 96 | +## Connecting to the running server: |
| 97 | + |
| 98 | +Browse to `https://localhost:8080/files/readme.txt` |
| 99 | + |
| 100 | +# Reference |
| 101 | + |
| 102 | +## createPartialContentHandler function: |
| 103 | + |
| 104 | +This is a factory method which generates a partial content handler for express routes. |
| 105 | + |
| 106 | +### Arguments: |
| 107 | + |
| 108 | +- `contentProvider`: An `async` function which returns a Promise resolved to a `Content` object (see below). |
| 109 | +- `logger`: Any logging implementation which has a `debug(message:string, extra: any)` method. Either `winston` or `bunyan` loggers should work. |
| 110 | + |
| 111 | +### Returns: |
| 112 | + |
| 113 | +- Express Route Handler: `createPartialContentHandler` returns an express handler which can be mapped to an Express route to serve partial content. |
| 114 | + |
| 115 | +## ContentProvider function: |
| 116 | + |
| 117 | +This function _needs to be implemented by you_. It's purpose is to fetch and return `Content` object containing necessary metadata and methods to stream the content partially. This method is invoked by the express handler (returned by `createPartialContentHandler`) on each request. |
| 118 | + |
| 119 | +### Arguments: |
| 120 | + |
| 121 | +- `Request`: It receives the `Request` object as it's only input. Use the information available in `Request` to find the requested content, e.g. through `Request.params` or query string, headers etc. |
| 122 | + |
| 123 | +### Returns: |
| 124 | + |
| 125 | +- `Promise<Content>`: See below. |
| 126 | + |
| 127 | +### Throws: |
| 128 | + |
| 129 | +- `ContentDoesNotExistError`: Throw this to indicate that the content doesn't exist. The generated express handler will return a 404 in this case. |
| 130 | + > Note: Any message provided to the `ContentDoesNotExistError` object is returned to the client. |
| 131 | +
|
| 132 | +## Content object: |
| 133 | + |
| 134 | +This object contains metadata and methods which describe the content. The `ContentProvider` method builds and returns it. |
| 135 | + |
| 136 | +### Properties: |
| 137 | + |
| 138 | +All the properties of this object are used to return content metadata to the client as various `Response` headers. |
| 139 | + |
| 140 | +- `fileName`: Used as the `Content-Disposition` header's `filename` value. |
| 141 | +- `mimeType`: Used as the `Content-Type` header value. |
| 142 | +- `totalSize`: Used as the `Content-Length` header value. |
| 143 | + |
| 144 | +### Methods: |
| 145 | + |
| 146 | +- `getStream(range?: Range)`: This method should return a readable stream initialized to the provided `range` (optional). You need to handle two cases: |
| 147 | + |
| 148 | + - range is `null`: When `range` is not-specified, the client is requesting the full content. In this case, return the stream as it is. |
| 149 | + - range is `{start, end}`: When client requests partial content, the `start` and `end` values will point to the corresponding byte positions (0 based and inclusive) of the content. You need to return stream limited to these positions. |
0 commit comments