Skip to content

Commit 2ffb7c0

Browse files
HadrienGardeurchocolatkey
HadrienGardeur
and
chocolatkey
authored
Updated README for serve (#47)
Co-authored-by: Henry <chocolatkey@gmail.com>
1 parent 02b6b03 commit 2ffb7c0

2 files changed

Lines changed: 128 additions & 15 deletions

File tree

‎docs/manifest.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -121,7 +121,7 @@ Outputs are based on publications available from the [EPUB 3 Samples project](ht
121121
122122
### Moby Dick
123123
124-
#### Inferring metadata
124+
#### Extracting and inferring metadata
125125
126126
```sh
127127
readium manifest --infer-a11y=split moby-dick.epub | jq .metadata

‎docs/serve.md‎

Lines changed: 127 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,148 @@
11
# The `serve` command
22

3-
By default, the `serve` command will start an HTTP server listening by default on `http://localhost:15080`, serving all compatible files (EPUB, PDF, CBZ, etc.) found in a directory as Readium Web Publications.
3+
The `serve` command is designed to stream and parse packaged publications and serve them as [Web Publications](https://readium.org/webpub-manifest) over HTTP/HTTPS.
44

5-
## Examples
5+
## Serving files from a directory
66

7-
* Serve files from a directory.
7+
By default, this command will serve publications available in a given directory from the filesystem.
8+
9+
Since there's no default path, it requires the presence of a `--file-directory` flag and a path.
10+
11+
### Example
12+
13+
* Serving files from a directory.
814

915
```sh
10-
readium serve directory
16+
readium serve --file-directory ./publications
1117
```
1218

13-
## Listing files
19+
### Listing files
1420

1521
For debugging purposes, the server exposes a `/list.json` endpoint that
1622
returns a list of all the publications found in the directory along with their
17-
encoded paths. This `path` is calculated using Base64 to encode each filename.
23+
encoded paths.
24+
25+
This will be replaced by an OPDS 2.0 feed in a future release, using an optional flag.
26+
27+
## Using S3 or a compatible API
28+
29+
Many services provide an S3 compatible API. The `serve` command is fully compatible with these API, allowing implementers to stream and serve publications stored in multiple buckets.
30+
31+
### Example
32+
33+
* Streaming files from an S3 compatible API.
34+
35+
```sh
36+
readium serve -s s3 --s3-endpoint https://example.com/endpoint --s3-access-key {access-key} --s3-secret-key {secret-key}
37+
```
38+
39+
### Required flags
40+
41+
| Flag | Description |
42+
| ---- | ----------- |
43+
| `--s3-endpoint` | URL for the S3 service |
44+
| `--s3-access-key` | Access Key for the S3 service |
45+
| `--s3-secret-key` | Secret Key for the S3 service |
1846

19-
This will be replaced by an OPDS 2.0 feed in a future release.
47+
### Optional flags
2048

21-
The Readium Web Publication Manifest of each publication is available at `http://localhost:15080/{path}/manifest.json`
49+
| Flag | Description |
50+
| ---- | ----------- |
51+
| `--s3-region` | Region for the S3 service. Defaults to `auto`. |
2252

23-
## Streaming remote publications over HTTP/HTTPS
53+
## Using GCS
2454

25-
The `serve` command is also capable of streaming remote files over HTTP/HTTPS and serving them as Readium Web Publications, as long as the server supports byte range requests.
55+
In addition to S3, the `serve` command also supports GCS (Google Cloud Storage).
56+
57+
Unlike S3, support for GCS relies on configuration handled through [Application Default Credentials](https://cloud.google.com/docs/authentication/application-default-credentials) rather than flags when calling the Readium CLI. If running this project in e.g. [Google Cloud Run](https://cloud.google.com/run), the credentials will be automatically loaded.
58+
59+
### Example
60+
61+
* Streaming files from GCS.
62+
63+
```sh
64+
readium serve -s gs
65+
```
66+
67+
## Streaming over HTTP/HTTPS
68+
69+
The `serve` command is also capable of streaming remote files over HTTP/HTTPS as long as the remote server supports byte range requests.
70+
71+
### Example
72+
73+
* Streaming files over HTTP and HTTPS.
74+
75+
```sh
76+
readium serve -s http,https
77+
```
2678

2779
This feature is currently enabled by default, but will be moved behind a feature flag in future releases.
2880

29-
To stream a remote publication replace the `path` with a Base 64 encoded URL instead.
81+
## Supporting multiple schemes
82+
83+
As illustrated in the previous sections of this document, configuration for the `serve` commands relies primarily on a `-s`/`--scheme` flag that supports a list of comma separated values:
84+
85+
| Scheme | Value |
86+
| ------ | ----- |
87+
| Filesystem | `file` |
88+
| HTTP | `http` |
89+
| HTTPS | `https` |
90+
| S3 | `s3` |
91+
| Google Cloud Storage | `gs` |
92+
93+
### Example
94+
95+
* Serving files from both GCS and HTTPS.
96+
97+
```sh
98+
readium serve -s gs,https
99+
```
100+
101+
## Binding an address and a port
102+
103+
By default, the `serve` commands starts an HTTP server on `localhost` using `15080` as a port.
104+
105+
These settings can be overriden using dedicated flags:
106+
107+
| Flag | Description |
108+
| ---- | ----------- |
109+
| `-a` or `--address` | Address of the HTTP server. |
110+
| `-p` or `--port` | Port of the HTTP server. |
30111

31-
For example:
112+
113+
## Fetching a manifest for a publication
114+
115+
In its current version, the `serve` command relies on a single path from which all manifests can be fetched: `/{base64url-encoded-path-to-file}/manifest.json`.
116+
117+
Each scheme supports a dedicated URI scheme:
118+
119+
| Scheme | URI scheme | Path |
120+
| ------ | ---------- | ---- |
121+
| Filesystem | `file://` | Path to a given file relative to the path provided in `--file-directory`.
122+
| HTTP | `http://` | URL |
123+
| HTTPS | `https://` | URL |
124+
| S3 | `s3://` | Path to a bucket, followed by a path to a file (key) in that bucket: `s3://{bucket}/{path-to-file}` |
125+
| Google Cloud Storage | `gs://` | Path to a bucket, followed by a path to a file (key) in that bucket: `gs://{bucket}/{path-to-file}` |
126+
127+
Once calculated, the URI scheme and path to the file have to be [base64url](https://datatracker.ietf.org/doc/html/rfc4648#section-5) encoded in order to generate a path to a manifest.
128+
129+
### Example
130+
131+
```sh
132+
readium serve -s gs,https
133+
```
32134

33135
* I'd like to stream <https://github.com/IDPF/epub3-samples/releases/download/20230704/accessible_epub_3.epub>
34-
* Which can be Base 64 encoded to `aHR0cHM6Ly9naXRodWIuY29tL0lEUEYvZXB1YjMtc2FtcGxlcy9yZWxlYXNlcy9kb3dubG9hZC8yMDIzMDcwNC9hY2Nlc3NpYmxlX2VwdWJfMy5lcHVi`
35-
* As long as the HTTP server from the `serve` command is running, I can access the Readium Web Publication Manifest at <http://localhost:15080/aHR0cHM6Ly9naXRodWIuY29tL0lEUEYvZXB1YjMtc2FtcGxlcy9yZWxlYXNlcy9kb3dubG9hZC8yMDIzMDcwNC9hY2Nlc3NpYmxlX2VwdWJfMy5lcHVi/manifest.json>
136+
* Which can be base64url encoded to `aHR0cHM6Ly9naXRodWIuY29tL0lEUEYvZXB1YjMtc2FtcGxlcy9yZWxlYXNlcy9kb3dubG9hZC8yMDIzMDcwNC9hY2Nlc3NpYmxlX2VwdWJfMy5lcHVi`
137+
* The manifest for that file can be accessed at <http://localhost:15080/aHR0cHM6Ly9naXRodWIuY29tL0lEUEYvZXB1YjMtc2FtcGxlcy9yZWxlYXNlcy9kb3dubG9hZC8yMDIzMDcwNC9hY2Nlc3NpYmxlX2VwdWJfMy5lcHVi/manifest.json>
138+
139+
## Additional services
140+
141+
In addition to the Readium Web Publication Manifest, this commands also provides additional services that can be discovered through the `links` in each manifest.
142+
143+
In its current version, the CLI provides the following services:
144+
145+
* [Position List](https://github.com/readium/architecture/tree/master/models/locators/positions)
146+
* Content Iterator
147+
148+
We expect to deprecate the Content Iterator service in the near future.

0 commit comments

Comments
 (0)