ffl-python 0.1.4__tar.gz → 0.1.5__tar.gz

{ffl_python-0.1.4 → ffl_python-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ffl-python
-Version: 0.1.4
+Version: 0.1.5
 Summary: Python binding for FastFileLink, backed by the portable ffl.com APE
 Author: ffl-python contributors
 License-Expression: Apache-2.0
@@ -20,13 +20,24 @@ Dynamic: license-file
 
 # ffl-python
 
-Python binding for FastFileLink. The package bundles the portable `ffl.com` APE and
-runs it behind a Python API; callers do not need to locate or install a separate FFL
-binary.
+`ffl-python` is the Python binding for the [FastFileLink](https://github.com/nuwainfo/ffl)
+CLI (FFL), which turns a file, folder, or stream into a browser-ready HTTPS link so the
+recipient can download it without installing anything. It prefers a direct QUIC/WebRTC P2P
+connection and falls back to a relayed/tunneled HTTPS link, with optional end-to-end
+encryption. See the FFL repository for the full protocol and CLI details.
 
-The low-level command grammar is generated by APEBind from `binding/ffl.apebind.yaml`.
-The public API in `src/ffl/client.py` is intentionally handwritten so FFL-specific
-library semantics stay explicit and reviewable.
+The package bundles the portable `ffl.com` APE and runs it behind a Python API, 
+powered by [APEBind](https://github.com/nuwainfo/apebind), 
+so callers do not need to locate or install a separate FFL 
+
+## Installation
+
+```bash
+pip install ffl-python
+```
+
+This installs the `ffl` package with the bundled `ffl.com` APE included -- no separate
+FFL install or PATH setup required.
 
 ## Development
 
@@ -42,14 +53,6 @@ python -m venv .venv
 # or: ./scripts/build.sh             # Linux/macOS
 ```
 
-The test directly imports `ffl`, shares a binary file, and downloads it through the
-bundled `ffl.com` APE. It requires working network access to FastFileLink. A wheel is a
-build artifact, not the source of truth.
-
-The integration suite covers ordinary, E2EE, relay, pickup-code, and public-key
-transfers; text, bytes, folders, multiple files, QR images, hooks, explicit ports, and
-session shutdown, and Basic Auth download.
-
 ## Share
 
 ```python
@@ -77,10 +80,6 @@ with ffl.share_text("hello", name="hello.txt") as session:
     print(session.link)
 ```
 
-Optional-value FFL flags use natural Python values. For example, `receipt=True` emits
-`--receipt` without a value, while `receipt="me@example.com"` emits the flag with the
-address.
-
 ### Stream a source without a temporary file
 
 `share_stream()` passes a binary file-like object directly to FFL stdin. It is useful
@@ -93,6 +92,25 @@ with open("backup.tar", "rb") as source:
         print(session.link)
 ```
 
+### Events
+
+`session.on(name, listener)` follows FFL's integrated events:
+
+| Semantic name | FFL event |
+| --- | --- |
+| `ready` | `/share/available` |
+| `started` | `/transfer/create` |
+| `progress` | `/transfer/progress` |
+| `completed` | `/transfer/complete` |
+| `failed` | `/transfer/fail` |
+
+HTTP, WebRTC, and direct P2P also emit their own events, such as
+`/download/complete`. Those stay on `session.on_raw()`. `completed` follows
+`/transfer/complete`, so one transfer notifies that listener once. Each accepted
+hook POST is answered with HTTP 200 and `{}`.
+
+The bundled `ffl.com` emits these names.
+
 ## Download
 
 ```python
@@ -154,9 +172,6 @@ print(result.public_key_path)
 print(result.private_key_path)
 ```
 
-`keygen()` has a 60-second process timeout and verifies that the key paths reported by
-FFL exist.
-
 ## Version and raw access
 
 ```python
@@ -167,44 +182,37 @@ result = ffl.raw(["download", "--help"])
 `raw()` is the escape hatch for new FFL options or commands that the semantic API has
 not adopted yet.
 
-## WSL2
-
-If an operation fails with `TLSError([0x6300])`, WSL may be routing the bundled
-`.com` APE through Windows interop. Run the following in WSL, then restart the WSL
-session:
-
-```bash
-sudo sh -c 'echo -1 > /proc/sys/fs/binfmt_misc/WSLInterop'
-```
-
-## Updating the FFL binding
-
-Install APEBind from its source project. When adopting a new `ffl.com`, first inspect the
-CLI into a raw discovery file:
-
-```bash
-./scripts/inspect.sh /path/to/ffl.com
-```
-
-This writes `binding/ffl.discovered.apebind.yaml` and automatically applies the hidden
-command seeds in `binding/ffl.commands.yaml`. Review the discovered-schema diff, then
-manually merge CLI changes into the canonical semantic contract
-`binding/ffl.apebind.yaml`. Automatic inspection never overwrites the semantic contract.
-
-After reviewing the semantic schema, regenerate the low-level binding:
-
-```bash
-./scripts/regenerate.sh /path/to/ffl.com
-# Windows: .\scripts\regenerate.ps1 D:\ffl.com
-```
-
-The script invokes APEBind into an isolated temporary project and replaces only these
-machine-owned files:
-
-- `src/ffl/_generated.py`
-- `src/ffl/_runtime.py`
-- `src/ffl/bin/ffl.com`
-- `src/ffl/py.typed`
-
-It deliberately does not overwrite `client.py`, `models.py`, parsing logic, tests, or the
-semantic schema.
+## Compared to magic-wormhole
+
+[magic-wormhole](https://github.com/magic-wormhole/magic-wormhole) is the other Python
+tool commonly reached for to move a file between two machines. Both are ad hoc,
+non-account-based transfers you can drive from Python, but they differ in shape:
+
+- **Binding vs. native library.** `ffl-python` is a subprocess wrapper around the
+  separate `ffl.com` CLI binary -- WebRTC/QUIC, NAT traversal, and relay/tunnel fallback
+  all happen in that external process. `wormhole` is a native, in-process Python package
+  (Twisted-based); no external binary is involved. In practice, though, wormhole's own
+  *file*-transfer path is also driven through its CLI machinery rather than a stable
+  public library call -- `wormhole.create()` covers generic message exchange, not file
+  transfer directly.
+- **Recipient experience.** An FFL share is an HTTPS link: the recipient opens it in a
+  browser and downloads, no install required. A wormhole transfer is a short code
+  (e.g. `7-crossbow-clockwork`) exchanged out-of-band; the recipient needs the
+  `wormhole` CLI installed to redeem it.
+- **Transport.** FFL tries a direct WebRTC/QUIC P2P connection first, falls back to a
+  plain P2P TCP connection, and falls back again to a relayed/tunneled HTTPS link if no
+  P2P path is reachable at all. wormhole's own transit protocol does direct TCP with a
+  relay fallback, with the connection authenticated by a SPAKE2 PAKE key derived from the
+  code.
+- **Security default.** wormhole is end-to-end encrypted on every transfer by
+  construction of the code exchange. FFL's end-to-end encryption is opt-in (`--e2ee`);
+  without it, data in transit is only as protected as the HTTPS connection to FFL's
+  relay/tunnel infrastructure.
+- **Feature surface.** FFL adds application-layer conveniences wormhole doesn't have: a
+  secondary pickup-code/public-key recipient check layered on top of the link,
+  receipt-confirmation emails, a pluggable choice of tunnel backend when P2P isn't
+  reachable (built-in `default`, plus Cloudflare, ngrok, Localtunnel, Loophole, Dev
+  Tunnel, Bore, or a self-hosted sish tunnel via `--preferred-tunnel`, with custom
+  tunnels configurable in `~/.fastfilelink/tunnels.json`), and general SOCKS5/HTTP
+  proxy configuration (wormhole only knows how to route through Tor, via `--tor`).
+  

ffl_python-0.1.5/README.md

@@ -0,0 +1,198 @@
+# ffl-python
+
+`ffl-python` is the Python binding for the [FastFileLink](https://github.com/nuwainfo/ffl)
+CLI (FFL), which turns a file, folder, or stream into a browser-ready HTTPS link so the
+recipient can download it without installing anything. It prefers a direct QUIC/WebRTC P2P
+connection and falls back to a relayed/tunneled HTTPS link, with optional end-to-end
+encryption. See the FFL repository for the full protocol and CLI details.
+
+The package bundles the portable `ffl.com` APE and runs it behind a Python API, 
+powered by [APEBind](https://github.com/nuwainfo/apebind), 
+so callers do not need to locate or install a separate FFL 
+
+## Installation
+
+```bash
+pip install ffl-python
+```
+
+This installs the `ffl` package with the bundled `ffl.com` APE included -- no separate
+FFL install or PATH setup required.
+
+## Development
+
+```bash
+python -m venv .venv
+.venv/Scripts/python -m pip install -e ".[dev]"   # Windows
+# or: .venv/bin/python -m pip install -e ".[dev]"
+
+.\scripts\test.ps1                 # Windows
+# or: ./scripts/test.sh              # Linux/macOS
+
+.\scripts\build.ps1                # Windows
+# or: ./scripts/build.sh             # Linux/macOS
+```
+
+## Share
+
+```python
+import ffl
+
+with ffl.share("release.zip", max_downloads=1, timeout_seconds=1800) as session:
+    print(session.link)
+```
+
+`share()` always requests a foreground FFL process and disables clipboard side effects,
+which gives library callers a deterministic `ShareSession` they can stop or keep alive.
+FFL's runtime-owned `--json` output is used internally to wait until `session.link` is
+ready.
+
+Multiple files are accepted directly:
+
+```python
+session = ffl.share(["one.txt", "two.txt"], name="files.zip")
+```
+
+Text and bytes helpers own their temporary file until the share session is closed:
+
+```python
+with ffl.share_text("hello", name="hello.txt") as session:
+    print(session.link)
+```
+
+### Stream a source without a temporary file
+
+`share_stream()` passes a binary file-like object directly to FFL stdin. It is useful
+for database dumps, generated artifacts, and other data that should not first be
+materialized as a separate temporary file:
+
+```python
+with open("backup.tar", "rb") as source:
+    with ffl.share_stream(source, name="backup.tar") as session:
+        print(session.link)
+```
+
+### Events
+
+`session.on(name, listener)` follows FFL's integrated events:
+
+| Semantic name | FFL event |
+| --- | --- |
+| `ready` | `/share/available` |
+| `started` | `/transfer/create` |
+| `progress` | `/transfer/progress` |
+| `completed` | `/transfer/complete` |
+| `failed` | `/transfer/fail` |
+
+HTTP, WebRTC, and direct P2P also emit their own events, such as
+`/download/complete`. Those stay on `session.on_raw()`. `completed` follows
+`/transfer/complete`, so one transfer notifies that listener once. Each accepted
+hook POST is answered with HTTP 200 and `{}`.
+
+The bundled `ffl.com` emits these names.
+
+## Download
+
+```python
+result = ffl.download("https://example.fastfilelink/...", output_path="download.bin")
+print(result.output_path)
+print(result.transfer_mode)
+```
+
+`download()` waits for the foreground FFL process to finish and returns a
+`DownloadResult`. For cancellation, progress, or caller-controlled timeouts, use
+`start_download()` and manage its `DownloadSession` explicitly.
+
+### Stream a download
+
+`download_stream()` exposes FFL stdout as binary chunks without buffering the whole
+file in memory:
+
+```python
+with ffl.download_stream("https://example.fastfilelink/...") as transfer:
+    with open("output.bin", "wb") as target:
+        for chunk in transfer.iter_bytes():
+            target.write(chunk)
+
+    result = transfer.wait()
+```
+
+Consume `iter_bytes()` through EOF before calling `wait()`. Calling `wait()` with
+unconsumed streamed stdout raises `RuntimeError`; this avoids silently discarding
+binary data or deadlocking when the child process fills its stdout pipe.
+
+## Authentication secrets
+
+For shares protected with HTTP Basic Auth, FFL supports `FFL_AUTH_PASSWORD`. Set it in
+the application environment and pass only `auth_user` to keep the password out of the
+FFL command line:
+
+```bash
+export FFL_AUTH_PASSWORD='use-your-secret-manager'
+```
+
+```powershell
+$env:FFL_AUTH_PASSWORD = 'use-your-secret-manager'
+```
+
+```python
+with ffl.share("release.zip", auth_user="deploy") as session:
+    print(session.link)
+```
+
+Do not also pass `auth_password=` when using this pattern: FFL gives the explicit CLI
+option precedence over `FFL_AUTH_PASSWORD`. The environment variable applies to the
+sharing side; pass download credentials explicitly when downloading a protected link.
+
+## Key generation
+
+```python
+result = ffl.keygen("alice")
+print(result.public_key_path)
+print(result.private_key_path)
+```
+
+## Version and raw access
+
+```python
+print(ffl.version())
+result = ffl.raw(["download", "--help"])
+```
+
+`raw()` is the escape hatch for new FFL options or commands that the semantic API has
+not adopted yet.
+
+## Compared to magic-wormhole
+
+[magic-wormhole](https://github.com/magic-wormhole/magic-wormhole) is the other Python
+tool commonly reached for to move a file between two machines. Both are ad hoc,
+non-account-based transfers you can drive from Python, but they differ in shape:
+
+- **Binding vs. native library.** `ffl-python` is a subprocess wrapper around the
+  separate `ffl.com` CLI binary -- WebRTC/QUIC, NAT traversal, and relay/tunnel fallback
+  all happen in that external process. `wormhole` is a native, in-process Python package
+  (Twisted-based); no external binary is involved. In practice, though, wormhole's own
+  *file*-transfer path is also driven through its CLI machinery rather than a stable
+  public library call -- `wormhole.create()` covers generic message exchange, not file
+  transfer directly.
+- **Recipient experience.** An FFL share is an HTTPS link: the recipient opens it in a
+  browser and downloads, no install required. A wormhole transfer is a short code
+  (e.g. `7-crossbow-clockwork`) exchanged out-of-band; the recipient needs the
+  `wormhole` CLI installed to redeem it.
+- **Transport.** FFL tries a direct WebRTC/QUIC P2P connection first, falls back to a
+  plain P2P TCP connection, and falls back again to a relayed/tunneled HTTPS link if no
+  P2P path is reachable at all. wormhole's own transit protocol does direct TCP with a
+  relay fallback, with the connection authenticated by a SPAKE2 PAKE key derived from the
+  code.
+- **Security default.** wormhole is end-to-end encrypted on every transfer by
+  construction of the code exchange. FFL's end-to-end encryption is opt-in (`--e2ee`);
+  without it, data in transit is only as protected as the HTTPS connection to FFL's
+  relay/tunnel infrastructure.
+- **Feature surface.** FFL adds application-layer conveniences wormhole doesn't have: a
+  secondary pickup-code/public-key recipient check layered on top of the link,
+  receipt-confirmation emails, a pluggable choice of tunnel backend when P2P isn't
+  reachable (built-in `default`, plus Cloudflare, ngrok, Localtunnel, Loophole, Dev
+  Tunnel, Bore, or a self-hosted sish tunnel via `--preferred-tunnel`, with custom
+  tunnels configurable in `~/.fastfilelink/tunnels.json`), and general SOCKS5/HTTP
+  proxy configuration (wormhole only knows how to route through Tor, via `--tor`).
+  

{ffl_python-0.1.4 → ffl_python-0.1.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ffl-python"
-version = "0.1.4"
+version = "0.1.5"
 description = "Python binding for FastFileLink, backed by the portable ffl.com APE"
 readme = "README.md"
 requires-python = ">=3.11"

ffl_python-0.1.5/src/ffl/bin/ffl.com

@@ -0,0 +1,4 @@
+[diffend] Oversized file quarantined before diffing.
+name: ffl_python-0.1.5/src/ffl/bin/ffl.com
+size: 48780381 bytes
+sha256: 15cab56cc9f9a86fb5ae7f521a85667b91cb8bbfc9704c9105d1a79634e24396

{ffl_python-0.1.4 → ffl_python-0.1.5}/src/ffl/events.py

@@ -31,11 +31,17 @@ from urllib.error import URLError
 from urllib.request import Request, urlopen
 
 
+# FFL posts one integrated /transfer/* event for every HTTP, WebRTC, and
+# direct P2P transfer. Semantic listeners bind to those names, plus
+# /share/available. Transport-specific events stay on the raw channel, so one
+# transfer notifies each semantic listener once.
+_HOOK_OK_BODY = b'{}'
 _SEMANTIC_EVENT_NAMES = {
-    '/hook/server/endpoints/register': 'ready',
-    '/hook/transfer/progress': 'progress',
-    '/hook/transfer/transport': 'transport',
-    '/hook/transfer/complete': 'completed',
+    '/share/available': 'ready',
+    '/transfer/create': 'started',
+    '/transfer/progress': 'progress',
+    '/transfer/complete': 'completed',
+    '/transfer/fail': 'failed',
 }
 
 
@@ -176,12 +182,15 @@ class FFLHookEventChannel:
                 try:
                     channel._publish(body)
                     published = True
-                    self.send_response(204)
+                    self.send_response(200)
+                    self.send_header('Content-Type', 'application/json')
+                    self.send_header('Content-Length', str(len(_HOOK_OK_BODY)))
+                    self.end_headers()
+                    self.wfile.write(_HOOK_OK_BODY)
                 except Exception as error:
                     channel._record_error(error)
                     self.send_response(500)
-                    
-                self.end_headers()
+                    self.end_headers()
 
                 if published and channel._forward_url is not None:
                     channel._forward_async(body)

{ffl_python-0.1.4 → ffl_python-0.1.5}/src/ffl/models.py

@@ -34,6 +34,8 @@ class TransferMode(IntEnum):
     WEBRTC_P2P = 2
     HTTP_FALLBACK = 3
     HTTP_DIRECT = 4
+    P2P_TCP = 5
+    P2P_QUIC = 6
 
 
 class ShareSession:

{ffl_python-0.1.4 → ffl_python-0.1.5}/src/ffl/parsing.py

@@ -42,12 +42,12 @@ class FFLResultParser:
 
     @classmethod
     def _detect_transfer_mode(cls, output: str) -> TransferMode:
-        if (
-            'P2P direct' in output
-            or 'P2P TCP' in output
-            or 'WebRTC P2P' in output
-        ):
+        if 'P2P direct' in output or 'WebRTC P2P' in output:
             return TransferMode.WEBRTC_P2P
+        if 'P2P UDP/QUIC' in output:
+            return TransferMode.P2P_QUIC
+        if 'P2P TCP' in output:
+            return TransferMode.P2P_TCP
         if 'HTTP fallback' in output:
             return TransferMode.HTTP_FALLBACK
         if (

{ffl_python-0.1.4 → ffl_python-0.1.5}/src/ffl_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ffl-python
-Version: 0.1.4
+Version: 0.1.5
 Summary: Python binding for FastFileLink, backed by the portable ffl.com APE
 Author: ffl-python contributors
 License-Expression: Apache-2.0
@@ -20,13 +20,24 @@ Dynamic: license-file
 
 # ffl-python
 
-Python binding for FastFileLink. The package bundles the portable `ffl.com` APE and
-runs it behind a Python API; callers do not need to locate or install a separate FFL
-binary.
+`ffl-python` is the Python binding for the [FastFileLink](https://github.com/nuwainfo/ffl)
+CLI (FFL), which turns a file, folder, or stream into a browser-ready HTTPS link so the
+recipient can download it without installing anything. It prefers a direct QUIC/WebRTC P2P
+connection and falls back to a relayed/tunneled HTTPS link, with optional end-to-end
+encryption. See the FFL repository for the full protocol and CLI details.
 
-The low-level command grammar is generated by APEBind from `binding/ffl.apebind.yaml`.
-The public API in `src/ffl/client.py` is intentionally handwritten so FFL-specific
-library semantics stay explicit and reviewable.
+The package bundles the portable `ffl.com` APE and runs it behind a Python API, 
+powered by [APEBind](https://github.com/nuwainfo/apebind), 
+so callers do not need to locate or install a separate FFL 
+
+## Installation
+
+```bash
+pip install ffl-python
+```
+
+This installs the `ffl` package with the bundled `ffl.com` APE included -- no separate
+FFL install or PATH setup required.
 
 ## Development
 
@@ -42,14 +53,6 @@ python -m venv .venv
 # or: ./scripts/build.sh             # Linux/macOS
 ```
 
-The test directly imports `ffl`, shares a binary file, and downloads it through the
-bundled `ffl.com` APE. It requires working network access to FastFileLink. A wheel is a
-build artifact, not the source of truth.
-
-The integration suite covers ordinary, E2EE, relay, pickup-code, and public-key
-transfers; text, bytes, folders, multiple files, QR images, hooks, explicit ports, and
-session shutdown, and Basic Auth download.
-
 ## Share
 
 ```python
@@ -77,10 +80,6 @@ with ffl.share_text("hello", name="hello.txt") as session:
     print(session.link)
 ```
 
-Optional-value FFL flags use natural Python values. For example, `receipt=True` emits
-`--receipt` without a value, while `receipt="me@example.com"` emits the flag with the
-address.
-
 ### Stream a source without a temporary file
 
 `share_stream()` passes a binary file-like object directly to FFL stdin. It is useful
@@ -93,6 +92,25 @@ with open("backup.tar", "rb") as source:
         print(session.link)
 ```
 
+### Events
+
+`session.on(name, listener)` follows FFL's integrated events:
+
+| Semantic name | FFL event |
+| --- | --- |
+| `ready` | `/share/available` |
+| `started` | `/transfer/create` |
+| `progress` | `/transfer/progress` |
+| `completed` | `/transfer/complete` |
+| `failed` | `/transfer/fail` |
+
+HTTP, WebRTC, and direct P2P also emit their own events, such as
+`/download/complete`. Those stay on `session.on_raw()`. `completed` follows
+`/transfer/complete`, so one transfer notifies that listener once. Each accepted
+hook POST is answered with HTTP 200 and `{}`.
+
+The bundled `ffl.com` emits these names.
+
 ## Download
 
 ```python
@@ -154,9 +172,6 @@ print(result.public_key_path)
 print(result.private_key_path)
 ```
 
-`keygen()` has a 60-second process timeout and verifies that the key paths reported by
-FFL exist.
-
 ## Version and raw access
 
 ```python
@@ -167,44 +182,37 @@ result = ffl.raw(["download", "--help"])
 `raw()` is the escape hatch for new FFL options or commands that the semantic API has
 not adopted yet.
 
-## WSL2
-
-If an operation fails with `TLSError([0x6300])`, WSL may be routing the bundled
-`.com` APE through Windows interop. Run the following in WSL, then restart the WSL
-session:
-
-```bash
-sudo sh -c 'echo -1 > /proc/sys/fs/binfmt_misc/WSLInterop'
-```
-
-## Updating the FFL binding
-
-Install APEBind from its source project. When adopting a new `ffl.com`, first inspect the
-CLI into a raw discovery file:
-
-```bash
-./scripts/inspect.sh /path/to/ffl.com
-```
-
-This writes `binding/ffl.discovered.apebind.yaml` and automatically applies the hidden
-command seeds in `binding/ffl.commands.yaml`. Review the discovered-schema diff, then
-manually merge CLI changes into the canonical semantic contract
-`binding/ffl.apebind.yaml`. Automatic inspection never overwrites the semantic contract.
-
-After reviewing the semantic schema, regenerate the low-level binding:
-
-```bash
-./scripts/regenerate.sh /path/to/ffl.com
-# Windows: .\scripts\regenerate.ps1 D:\ffl.com
-```
-
-The script invokes APEBind into an isolated temporary project and replaces only these
-machine-owned files:
-
-- `src/ffl/_generated.py`
-- `src/ffl/_runtime.py`
-- `src/ffl/bin/ffl.com`
-- `src/ffl/py.typed`
-
-It deliberately does not overwrite `client.py`, `models.py`, parsing logic, tests, or the
-semantic schema.
+## Compared to magic-wormhole
+
+[magic-wormhole](https://github.com/magic-wormhole/magic-wormhole) is the other Python
+tool commonly reached for to move a file between two machines. Both are ad hoc,
+non-account-based transfers you can drive from Python, but they differ in shape:
+
+- **Binding vs. native library.** `ffl-python` is a subprocess wrapper around the
+  separate `ffl.com` CLI binary -- WebRTC/QUIC, NAT traversal, and relay/tunnel fallback
+  all happen in that external process. `wormhole` is a native, in-process Python package
+  (Twisted-based); no external binary is involved. In practice, though, wormhole's own
+  *file*-transfer path is also driven through its CLI machinery rather than a stable
+  public library call -- `wormhole.create()` covers generic message exchange, not file
+  transfer directly.
+- **Recipient experience.** An FFL share is an HTTPS link: the recipient opens it in a
+  browser and downloads, no install required. A wormhole transfer is a short code
+  (e.g. `7-crossbow-clockwork`) exchanged out-of-band; the recipient needs the
+  `wormhole` CLI installed to redeem it.
+- **Transport.** FFL tries a direct WebRTC/QUIC P2P connection first, falls back to a
+  plain P2P TCP connection, and falls back again to a relayed/tunneled HTTPS link if no
+  P2P path is reachable at all. wormhole's own transit protocol does direct TCP with a
+  relay fallback, with the connection authenticated by a SPAKE2 PAKE key derived from the
+  code.
+- **Security default.** wormhole is end-to-end encrypted on every transfer by
+  construction of the code exchange. FFL's end-to-end encryption is opt-in (`--e2ee`);
+  without it, data in transit is only as protected as the HTTPS connection to FFL's
+  relay/tunnel infrastructure.
+- **Feature surface.** FFL adds application-layer conveniences wormhole doesn't have: a
+  secondary pickup-code/public-key recipient check layered on top of the link,
+  receipt-confirmation emails, a pluggable choice of tunnel backend when P2P isn't
+  reachable (built-in `default`, plus Cloudflare, ngrok, Localtunnel, Loophole, Dev
+  Tunnel, Bore, or a self-hosted sish tunnel via `--preferred-tunnel`, with custom
+  tunnels configurable in `~/.fastfilelink/tunnels.json`), and general SOCKS5/HTTP
+  proxy configuration (wormhole only knows how to route through Tor, via `--tor`).
+  

{ffl_python-0.1.4 → ffl_python-0.1.5}/tests/test_events.py

@@ -11,7 +11,7 @@ import pytest
 from ffl.events import FFLHookEventChannel
 
 
-def _event_body(index: int, name: str = '/hook/transfer/progress') -> bytes:
+def _event_body(index: int, name: str = '/transfer/progress') -> bytes:
     return json.dumps({'event': name, 'data': {'index': index}}).encode('utf-8')
 
 
@@ -20,7 +20,7 @@ def test_hook_history_is_bounded_and_exposes_semantic_event_names():
     try:
         channel._publish(_event_body(1))
         channel._publish(_event_body(2))
-        channel._publish(_event_body(3, '/hook/transfer/complete'))
+        channel._publish(_event_body(3, '/transfer/complete'))
 
         assert [event.data['index'] for event in channel.history] == [2, 3]
         assert channel.history[-1].semantic_name == 'completed'
@@ -36,6 +36,47 @@ def test_hook_history_is_bounded_and_exposes_semantic_event_names():
         channel.close()
 
 
+def test_integrated_transfer_events_map_once():
+    channel = FFLHookEventChannel()
+    try:
+        names = (
+            '/download/complete',
+            '/webrtc/transfer/complete',
+            '/p2p/transfer/complete',
+            '/hook/transfer/complete',
+            '/transfer/complete',
+            '/share/available',
+            '/transfer/create',
+            '/transfer/progress',
+            '/download/progress',
+            '/transfer/fail',
+        )
+        for index, name in enumerate(names, start=1):
+            channel._publish(_event_body(index, name))
+
+        def named(semantic):
+            return [
+                event.name for event in channel.history if event.semantic_name == semantic
+            ]
+
+        assert named('completed') == ['/transfer/complete']
+        assert named('progress') == ['/transfer/progress']
+        assert named('ready') == ['/share/available']
+        assert named('started') == ['/transfer/create']
+        assert named('failed') == ['/transfer/fail']
+
+        replayed = []
+        replayed_event = threading.Event()
+        channel.on_semantic(
+            'completed',
+            lambda event: (replayed.append(event.name), replayed_event.set()),
+        )
+        assert replayed_event.wait(timeout=1)
+        assert replayed == ['/transfer/complete']
+    finally:
+        channel.close()
+
+
 def test_live_event_iterator_preserves_events_after_history_eviction():
     channel = FFLHookEventChannel(event_history_limit=2)
     iterator = channel.events()
@@ -69,8 +110,12 @@ def test_hook_response_does_not_wait_for_forwarded_webhook():
         def do_POST(self) -> None:
             forwarded.set()
             release_forward.wait(timeout=5)
-            self.send_response(204)
+            body = b'{}'
+            self.send_response(200)
+            self.send_header('Content-Type', 'application/json')
+            self.send_header('Content-Length', str(len(body)))
             self.end_headers()
+            self.wfile.write(body)
 
         def log_message(self, format_string: str, *args) -> None:
             del format_string, args
@@ -84,7 +129,8 @@ def test_hook_response_does_not_wait_for_forwarded_webhook():
         started = time.monotonic()
         request = Request(channel.url, data=_event_body(1), method='POST')
         with urlopen(request, timeout=1) as response:
-            assert response.status == 204
+            assert response.status == 200
+            assert response.read() == b'{}'
 
         assert time.monotonic() - started < 0.5
         assert forwarded.wait(timeout=1)
@@ -114,7 +160,7 @@ def test_hook_response_does_not_wait_for_a_local_listener():
     release_listener = threading.Event()
     channel = FFLHookEventChannel()
     channel.on(
-        '/hook/transfer/progress',
+        '/transfer/progress',
         lambda event: (listener_started.set(), release_listener.wait(timeout=5)),
     )
 
@@ -122,7 +168,8 @@ def test_hook_response_does_not_wait_for_a_local_listener():
         started = time.monotonic()
         request = Request(channel.url, data=_event_body(1), method='POST')
         with urlopen(request, timeout=1) as response:
-            assert response.status == 204
+            assert response.status == 200
+            assert response.read() == b'{}'
 
         assert time.monotonic() - started < 0.5
         assert listener_started.wait(timeout=1)

{ffl_python-0.1.4 → ffl_python-0.1.5}/tests/test_hook.py

@@ -15,8 +15,12 @@ class _HookHandler(BaseHTTPRequestHandler):
         content_length = int(self.headers.get('Content-Length', '0'))
         self.__class__.requests.append((self.path, self.rfile.read(content_length)))
         self.__class__.received_event.set()
-        self.send_response(204)
+        body = b'{}'
+        self.send_response(200)
+        self.send_header('Content-Type', 'application/json')
+        self.send_header('Content-Length', str(len(body)))
         self.end_headers()
+        self.wfile.write(body)
 
     def log_message(self, format_string: str, *args) -> None:
         del format_string, args
@@ -50,6 +54,12 @@ def test_share_sends_events_to_hook_url(tmp_path: Path, monkeypatch):
                 if event.name == '/hook/server/endpoints/register'
             ]
             assert endpoint_events
+            completed = [
+                event.name
+                for event in session.event_history
+                if event.semantic_name == 'completed'
+            ]
+            assert completed == ['/transfer/complete']
             replayed = []
             session.on_raw('/hook/server/endpoints/register', replayed.append)
             assert replayed == endpoint_events

{ffl_python-0.1.4 → ffl_python-0.1.5}/tests/test_session.py

@@ -286,4 +286,30 @@ def test_download_parser_recognizes_p2p_tcp_output(tmp_path: Path):
 
     result = FFLResultParser.parse_download(process, None, tmp_path)
 
+    assert result.transfer_mode is ffl.TransferMode.P2P_TCP
+
+
+def test_download_parser_recognizes_p2p_quic_output(tmp_path: Path):
+    process = ffl.APEProcessResult(
+        ('download', 'https://example.test/file'),
+        0,
+        'Using P2P UDP/QUIC download\nDownloaded: file.bin',
+        '',
+    )
+
+    result = FFLResultParser.parse_download(process, None, tmp_path)
+
+    assert result.transfer_mode is ffl.TransferMode.P2P_QUIC
+
+
+def test_download_parser_recognizes_webrtc_p2p_output(tmp_path: Path):
+    process = ffl.APEProcessResult(
+        ('download', 'https://example.test/file'),
+        0,
+        'Using WebRTC P2P download\nDownloaded: file.bin',
+        '',
+    )
+
+    result = FFLResultParser.parse_download(process, None, tmp_path)
+
     assert result.transfer_mode is ffl.TransferMode.WEBRTC_P2P

ffl_python-0.1.4/README.md

@@ -1,190 +0,0 @@
-# ffl-python
-
-Python binding for FastFileLink. The package bundles the portable `ffl.com` APE and
-runs it behind a Python API; callers do not need to locate or install a separate FFL
-binary.
-
-The low-level command grammar is generated by APEBind from `binding/ffl.apebind.yaml`.
-The public API in `src/ffl/client.py` is intentionally handwritten so FFL-specific
-library semantics stay explicit and reviewable.
-
-## Development
-
-```bash
-python -m venv .venv
-.venv/Scripts/python -m pip install -e ".[dev]"   # Windows
-# or: .venv/bin/python -m pip install -e ".[dev]"
-
-.\scripts\test.ps1                 # Windows
-# or: ./scripts/test.sh              # Linux/macOS
-
-.\scripts\build.ps1                # Windows
-# or: ./scripts/build.sh             # Linux/macOS
-```
-
-The test directly imports `ffl`, shares a binary file, and downloads it through the
-bundled `ffl.com` APE. It requires working network access to FastFileLink. A wheel is a
-build artifact, not the source of truth.
-
-The integration suite covers ordinary, E2EE, relay, pickup-code, and public-key
-transfers; text, bytes, folders, multiple files, QR images, hooks, explicit ports, and
-session shutdown, and Basic Auth download.
-
-## Share
-
-```python
-import ffl
-
-with ffl.share("release.zip", max_downloads=1, timeout_seconds=1800) as session:
-    print(session.link)
-```
-
-`share()` always requests a foreground FFL process and disables clipboard side effects,
-which gives library callers a deterministic `ShareSession` they can stop or keep alive.
-FFL's runtime-owned `--json` output is used internally to wait until `session.link` is
-ready.
-
-Multiple files are accepted directly:
-
-```python
-session = ffl.share(["one.txt", "two.txt"], name="files.zip")
-```
-
-Text and bytes helpers own their temporary file until the share session is closed:
-
-```python
-with ffl.share_text("hello", name="hello.txt") as session:
-    print(session.link)
-```
-
-Optional-value FFL flags use natural Python values. For example, `receipt=True` emits
-`--receipt` without a value, while `receipt="me@example.com"` emits the flag with the
-address.
-
-### Stream a source without a temporary file
-
-`share_stream()` passes a binary file-like object directly to FFL stdin. It is useful
-for database dumps, generated artifacts, and other data that should not first be
-materialized as a separate temporary file:
-
-```python
-with open("backup.tar", "rb") as source:
-    with ffl.share_stream(source, name="backup.tar") as session:
-        print(session.link)
-```
-
-## Download
-
-```python
-result = ffl.download("https://example.fastfilelink/...", output_path="download.bin")
-print(result.output_path)
-print(result.transfer_mode)
-```
-
-`download()` waits for the foreground FFL process to finish and returns a
-`DownloadResult`. For cancellation, progress, or caller-controlled timeouts, use
-`start_download()` and manage its `DownloadSession` explicitly.
-
-### Stream a download
-
-`download_stream()` exposes FFL stdout as binary chunks without buffering the whole
-file in memory:
-
-```python
-with ffl.download_stream("https://example.fastfilelink/...") as transfer:
-    with open("output.bin", "wb") as target:
-        for chunk in transfer.iter_bytes():
-            target.write(chunk)
-
-    result = transfer.wait()
-```
-
-Consume `iter_bytes()` through EOF before calling `wait()`. Calling `wait()` with
-unconsumed streamed stdout raises `RuntimeError`; this avoids silently discarding
-binary data or deadlocking when the child process fills its stdout pipe.
-
-## Authentication secrets
-
-For shares protected with HTTP Basic Auth, FFL supports `FFL_AUTH_PASSWORD`. Set it in
-the application environment and pass only `auth_user` to keep the password out of the
-FFL command line:
-
-```bash
-export FFL_AUTH_PASSWORD='use-your-secret-manager'
-```
-
-```powershell
-$env:FFL_AUTH_PASSWORD = 'use-your-secret-manager'
-```
-
-```python
-with ffl.share("release.zip", auth_user="deploy") as session:
-    print(session.link)
-```
-
-Do not also pass `auth_password=` when using this pattern: FFL gives the explicit CLI
-option precedence over `FFL_AUTH_PASSWORD`. The environment variable applies to the
-sharing side; pass download credentials explicitly when downloading a protected link.
-
-## Key generation
-
-```python
-result = ffl.keygen("alice")
-print(result.public_key_path)
-print(result.private_key_path)
-```
-
-`keygen()` has a 60-second process timeout and verifies that the key paths reported by
-FFL exist.
-
-## Version and raw access
-
-```python
-print(ffl.version())
-result = ffl.raw(["download", "--help"])
-```
-
-`raw()` is the escape hatch for new FFL options or commands that the semantic API has
-not adopted yet.
-
-## WSL2
-
-If an operation fails with `TLSError([0x6300])`, WSL may be routing the bundled
-`.com` APE through Windows interop. Run the following in WSL, then restart the WSL
-session:
-
-```bash
-sudo sh -c 'echo -1 > /proc/sys/fs/binfmt_misc/WSLInterop'
-```
-
-## Updating the FFL binding
-
-Install APEBind from its source project. When adopting a new `ffl.com`, first inspect the
-CLI into a raw discovery file:
-
-```bash
-./scripts/inspect.sh /path/to/ffl.com
-```
-
-This writes `binding/ffl.discovered.apebind.yaml` and automatically applies the hidden
-command seeds in `binding/ffl.commands.yaml`. Review the discovered-schema diff, then
-manually merge CLI changes into the canonical semantic contract
-`binding/ffl.apebind.yaml`. Automatic inspection never overwrites the semantic contract.
-
-After reviewing the semantic schema, regenerate the low-level binding:
-
-```bash
-./scripts/regenerate.sh /path/to/ffl.com
-# Windows: .\scripts\regenerate.ps1 D:\ffl.com
-```
-
-The script invokes APEBind into an isolated temporary project and replaces only these
-machine-owned files:
-
-- `src/ffl/_generated.py`
-- `src/ffl/_runtime.py`
-- `src/ffl/bin/ffl.com`
-- `src/ffl/py.typed`
-
-It deliberately does not overwrite `client.py`, `models.py`, parsing logic, tests, or the
-semantic schema.

ffl_python-0.1.4/src/ffl/bin/ffl.com

@@ -1,4 +0,0 @@
-[diffend] Oversized file quarantined before diffing.
-name: ffl_python-0.1.4/src/ffl/bin/ffl.com
-size: 51721850 bytes
-sha256: 0c614cf8b87a1e73fde86b04911a246dd3ca9420819cfe8a05e8edc03146737b