Skip to content

armgit / BYOC

Public Imported from GitHub
0

One storage API for Google Drive, Nextcloud, and S3-compatible clouds, in TypeScript and Python.

docs: lead the README with the demo, and note that downloads stream

Ajay Ramineni04cd6c0238e8
diff --git a/README.md b/README.md
index 0944ba2..27afedf 100644
--- a/README.md
+++ b/README.md
@@ -11,10 +11,16 @@
[![CI](https://github.com/Ajayvarmaramineni/BYOC/actions/workflows/ci.yml/badge.svg)](https://github.com/Ajayvarmaramineni/BYOC/actions)
[![npm](https://img.shields.io/npm/v/@byoc/core?style=flat-square&label=%40byoc%2Fcore&color=CB3837&logo=npm)](https://www.npmjs.com/package/@byoc/core)
[![PyPI](https://img.shields.io/pypi/v/byoc-storage?style=flat-square&label=byoc-storage&color=3776AB&logo=pypi&logoColor=white)](https://pypi.org/project/byoc-storage/)
-[![Tests](https://img.shields.io/badge/Tests-822%20Passed-brightgreen?style=flat-square)](#testing-and-verification)
+[![Tests](https://img.shields.io/badge/Tests-868%20Passed-brightgreen?style=flat-square)](#testing-and-verification)
[![Types](https://img.shields.io/badge/Types-tsc%20strict%20%2B%20mypy%20strict-blue?style=flat-square)](#testing-and-verification)
[![License](https://img.shields.io/badge/License-Apache%202.0-orange?style=flat-square)](LICENSE)
+<br />
+
+<img src="./docs/assets/direct-upload.gif" alt="A 5.9 GB file uploads from the browser to the user's own cloud while the application server's log records zero bytes" width="100%" />
+
+<p><em>A 5.9&nbsp;GB file, uploaded in 7.9 seconds. The application server's log &mdash; on the right &mdash;<br />records two requests and <strong>zero bytes</strong>. <a href="./examples/direct-upload-demo">Run it yourself</a>.</em></p>
+
</div>
---
@@ -278,6 +284,10 @@ object key, so a client cannot redirect a grant to a different file.
> `false` — it authenticates every request with Basic credentials, so there is
> no URL a browser can be handed without also handing it the password.
+**[Run it yourself](./examples/direct-upload-demo)** — a page, a 90-line server,
+and a request log that stays at zero bytes while the file uploads. Points at a
+local MinIO by default, so it needs no cloud account.
+
---
## Files larger than memory
@@ -310,6 +320,11 @@ Google Drive needs a resumable session with a one-chunk lookahead, because it
accepts `bytes 0-N/*` while the total is unknown but demands the real total on
the final chunk.
+Downloads stream as well, so `StorageOutput.stream()` yields chunks rather than
+buffering the object first. That is what makes a migration bounded by the chunk
+size rather than by the largest file in it: a 300 MB transfer between providers
+holds 56 MB, in either direction.
+
Encryption streams too. `BYOC_E2EE_V3` authenticates independent frames, binding
the header, frame index and a final-frame marker as additional authenticated
data, so reordering, truncation and header swaps are all detected — and a large
@@ -452,9 +467,9 @@ FastAPI / Django / Next.js / Express
```
TypeScript 416 tests tsc --strict
-Python 406 tests mypy --strict, ruff
-Integration 42 tests live MinIO and WebDAV servers
-Interop 13 tests both SDKs, same live servers
+Python 452 tests mypy --strict, ruff
+Integration 43 tests live MinIO and WebDAV servers
+Interop 14 tests both SDKs, same live servers
```
Every adapter is exercised against a real server rather than a mock. Each of the following was a genuine bug caught that way and invisible to mocked tests:
diff --git a/python/README.md b/python/README.md
index a320ade..8f03907 100644
--- a/python/README.md
+++ b/python/README.md
@@ -2,7 +2,7 @@
[![PyPI](https://img.shields.io/pypi/v/byoc-storage?style=flat-square&color=3776AB&logo=pypi&logoColor=white)](https://pypi.org/project/byoc-storage/)
[![Python](https://img.shields.io/pypi/pyversions/byoc-storage?style=flat-square&color=3776AB)](https://pypi.org/project/byoc-storage/)
-[![Tests](https://img.shields.io/badge/Tests-406%20Passed-brightgreen?style=flat-square)](https://github.com/Ajayvarmaramineni/BYOC)
+[![Tests](https://img.shields.io/badge/Tests-452%20Passed-brightgreen?style=flat-square)](https://github.com/Ajayvarmaramineni/BYOC)
[![Types](https://img.shields.io/badge/mypy-strict-blue?style=flat-square)](https://github.com/Ajayvarmaramineni/BYOC)
[![License](https://img.shields.io/badge/License-Apache%202.0-orange?style=flat-square)](https://github.com/Ajayvarmaramineni/BYOC/blob/main/LICENSE)