ffl-python 0.1.4__py3-none-any.whl → 0.1.5__py3-none-any.whl

ffl/bin/ffl.com

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

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/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/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.dist-info → ffl_python-0.1.5.dist-info}/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,15 @@
+ffl/__init__.py,sha256=GQ8-MHqcrG1mT0Jkqdo1ifZdMp9j7YVOvsk8QP6o7so,1887
+ffl/_generated.py,sha256=y_o02NvGXOciWYmBzCjsh3Ro-ObtJQunWYAomPmh6ec,44072
+ffl/_runtime.py,sha256=hb4lQYWY51iupkBIXZk5Ok1aV2PJv6KoEdJKmcjmhrU,34800
+ffl/client.py,sha256=ZmpMNr0zDu9djxshdtkrkcwGTaNVZbdgxPrfw_1WuI8,10649
+ffl/errors.py,sha256=RarGTbHUzMYJ8ifYcwbQh3guNHHH8sPKPuxXgceLvtY,965
+ffl/events.py,sha256=WKX_2NaRrmVX9buxsR2JbT_m0deXJ6l54JJUN8p-i4A,9777
+ffl/models.py,sha256=t9ty_CSdBXJB0nfqH33gKc0OY1jYq-Ga8mLsiI7FK0Q,8008
+ffl/parsing.py,sha256=rc5BLmq5gybQCgczJHeCYyNrPo57WmecUI3OIHP8_Z0,4009
+ffl/py.typed,sha256=qzxecjP9nBZND4fnAxWaIqIc3-9Z7bDos33dUet8d9g,46
+ffl/bin/ffl.com,sha256=Fcq1bMn5qG-1rn9SGoVme5HLi7_JcEyRBdGnljTiQ5Y,48780381
+ffl_python-0.1.5.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+ffl_python-0.1.5.dist-info/METADATA,sha256=OU5PAMc43CzaRdXarUCGbmIusOAiNsYqVL6HFhiA7Kg,7964
+ffl_python-0.1.5.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+ffl_python-0.1.5.dist-info/top_level.txt,sha256=I3tRB8VSu6Bs5i_luGnIYh-dBWVtyqtLjpAfJqGtFMA,4
+ffl_python-0.1.5.dist-info/RECORD,,

ffl_python-0.1.4.dist-info/RECORD

@@ -1,15 +0,0 @@
-ffl/__init__.py,sha256=GQ8-MHqcrG1mT0Jkqdo1ifZdMp9j7YVOvsk8QP6o7so,1887
-ffl/_generated.py,sha256=y_o02NvGXOciWYmBzCjsh3Ro-ObtJQunWYAomPmh6ec,44072
-ffl/_runtime.py,sha256=hb4lQYWY51iupkBIXZk5Ok1aV2PJv6KoEdJKmcjmhrU,34800
-ffl/client.py,sha256=ZmpMNr0zDu9djxshdtkrkcwGTaNVZbdgxPrfw_1WuI8,10649
-ffl/errors.py,sha256=RarGTbHUzMYJ8ifYcwbQh3guNHHH8sPKPuxXgceLvtY,965
-ffl/events.py,sha256=V6NYG0Tfw8XR4YLF2tUqRWMhE6fRE-tnvENAoffeSV4,9263
-ffl/models.py,sha256=yqV2_HwgYJXS2FIzVxLycwU8_j0ORKzFXNlceonh52A,7975
-ffl/parsing.py,sha256=DPtgoMbbbKyeE0aqTY5iKpfRnUJBhpTnqmH3NVG6G8U,3930
-ffl/py.typed,sha256=qzxecjP9nBZND4fnAxWaIqIc3-9Z7bDos33dUet8d9g,46
-ffl/bin/ffl.com,sha256=DGFM-Lh6HnP96GsEkRokbdPKlCCBnP6KBejtwDFGc3s,51721850
-ffl_python-0.1.4.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-ffl_python-0.1.4.dist-info/METADATA,sha256=hean35OifKffdfYtKxv_HC9JdfvQ9-WLiOKYs98-t5k,6583
-ffl_python-0.1.4.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-ffl_python-0.1.4.dist-info/top_level.txt,sha256=I3tRB8VSu6Bs5i_luGnIYh-dBWVtyqtLjpAfJqGtFMA,4
-ffl_python-0.1.4.dist-info/RECORD,,