NodeJS / TypeScript Readium-2 "streamer"
NodeJS implementation (written in TypeScript) and HTTP micro-services (Express middleware) for https://github.com/readium/architecture/tree/master/streamer
- https://nodejs.org NodeJS >= 8, NPM >= 5 (check with command line
- OPTIONAL: https://yarnpkg.com Yarn >= 1.0 (check with command line
Command line install:
npm install r2-streamer-js
yarn add r2-streamer-js
...or manually add in your
Several ECMAScript flavours are provided out-of-the-box: ES5, ES6-2015, ES7-2016, ES8-2017:
(alternatively, GitHub mirror with semantic-versioning release tags: https://github.com/edrlab/r2-streamer-js-dist/tree/develop/dist/ )
require() statement for imports (NodeJS style).
More information about NodeJS compatibility:
The type definitions (aka "typings") are included as
*.d.ts files in
./node_modules/r2-streamer-js/dist/**, so this package can be used directly in a TypeScript project.
// from the index file;// ES5 import (assuming node_modules/r2-streamer-js/):;// ... or alternatively using a convenient path alias in the TypeScript config (+ WebPack etc.):;
A package-lock.json is provided (modern NPM replacement for
A yarn.lock file is currently not provided at the root of the source tree.
TravisCI builds are triggered automatically at every Git "push" in the
A test server app (not production-ready) is automatically deployed at Heroku, at every Git "push" in the
A mirror app is also deployed at Now.sh:
Both servers run NodeJS 8, and the apps are based on the ES8-2017 code transpiled from TypeScript.
HTTP CORS headers are served to allow cross-origin / remote API requests.
Version(s), Git revision(s)
NPM package (latest published):
Alternatively, GitHub mirror with semantic-versioning release tags:
Heroku app (latest deployed):
Now app (latest deployed):
Developer quick start
Command line steps (NPM, but similar with YARN):
git status(please ensure there are no local changes, especially in
package-lock.jsonand the dependency versions in
rm -rf node_modules(to start from a clean slate)
npm install, or alternatively
npm ci(both commands initialize the
node_modulestree of package dependencies, based on the strict
npm run build:all(invoke the main build script: clean, lint, compile)
ls dist(that's the build output which gets published as NPM package)
npm run server-debug -- PATH_TO_EPUB_OR_DIR " -1"(ES8-2017 dist, path is relative or absolute, -1 means no limits for HTTP header prefetch Links)
npm run start -- 99(ES6-2015 dist, default
./misc/epubsfolder, the 99 value overrides the default maximum number of HTTP header prefetch Links)
// ES5 import (assuming node_modules/r2-streamer-js/):;// ... or alternatively using a convenient path alias in the TypeScript config (+ WebPack etc.):;// Constructor parameter is optional:// disableDecryption: true// disableOPDS// disableReaders: true// disableRemotePubUrl: true to deactivateconst server =disableDecryption: false // deactivates the decryption of encrypted resources (Readium LCP).disableOPDS: true // deactivates the HTTP routes for the OPDS "micro services" (browser, converter)disableReaders: true // deactivates the built-in "readers" for ReadiumWebPubManifest (HTTP static host / route).disableRemotePubUrl: true // deactivates the HTTP route for loading a remote publication.maxPrefetchLinks: 5 // Link HTTP header, with rel = prefetch, see server.ts MAX_PREFETCH_LINKS (default = 10);// First parameter: port number, zero means default (3000),// unless specified via the environment variable `PORT` (process.env.PORT).// Tip: the NPM package `portfinder` can be used to automatically find an available port number.const url = await serverstart3000 false;// Second constructor parameter: if true, HTTPS instead of HTTP, using a randomly-generated self-signed certificate.// Also validates encrypted HTTP header during request-request cycles, so should only be used in runtime// contexts where the client side has access to the private encryption key (i.e. Electron app, see r2-navigator-js)console; // false// A client app that is capable of setting HTTP headers for every request originating from content webviews// can obtain the special encrypted header using this function:// (as used internally by the Electron-based `r2-navigator-js` component to secure the transport layer)const nameValuePair = server;console;console;//// Note that ports 80 and 443 (HTTPS) are always implicit (ommitted).console;// `serverInfo.urlScheme` ("http")// `serverInfo.urlHost` ("127.0.0.1")// `serverInfo.urlPort` (3000)console;// Calls `uncachePublications()` (see below)server;console; // false
To serve a
/robots.txt file that completely disables search robots:
// Call this before `server.start()`server;
To add custom HTTP routes:
// Call these before `server.start()`.// They are equivalent to `app.use()` and `app.get()`, where `app` is the underlying Express instance:server;server;
To register publications references (local filesystem paths) inside the internal server state (which is used to create the OPDS2 feed, see below):
// This can be called before or after `server.start()`:// the returned array contains URL routes to the ReadiumWebPubManifests,// e.g. `/pub/ID/manifest.json`, where `ID` is the base64 encoding of the registered path.// Note that the returned base64 URL path components are already URI-encoded (escaped).// (`=` and `/` are typically problematic edge-cases)const publicationURLs = server;// ...then:const publicationPaths = server; // ["/path/to/book.epub"]// ...and (calls `uncachePublication()`, see below):const publicationURLs = server;
To get the OPDS2 feed for the currently registered publications:
// This launches a potentially time-consuming Node process that scans (loads) each registered Publication,// and stores the generated OPDS2 feed inside a temporary filesystem location.// So this returns `undefined` at the first call, and the client must invoke the function again later.// Note that both `addPublications()` and `removePublications()` clear the OPDS2 feed entirely,// requiring its subsequent re-generation (full scan of registered publication paths).// (poor design, but at this stage really just an OPDS2 demo without real use-case)const opds2 = server;
To actually load+parse a publication reference (local filesystem path) into a ReadiumWebPubManifest Publication instance, stored in the server's state:
// The Publication object model is defined in `r2-shared-js`const publication = await server;// The above is basically a lazy-loader that checks the cache before loading+parsing a publication,// equivalent to:const publication = server;if !publicationpublication = ...; // load and parse "/path/to/book.epub"server;console; // true// see also:// (calls `publication.freeDestroy()` to cleanup allocated objects in the Publication,// particularly the file handle to the underlying zip/EPUB/CBZ file)server;server;
Note that HTTP/remote publications URLs can be loaded into the server's cache
and subsequently served by the streamer without prior registration via
However, publications from the local filesytem will only be served when registered,
even if they are cached (in other words, the HTTP route is disabled when the publication is non-registered).