From 41ce0809ab49b8cab232b23cab0795bd09bda9d6 Mon Sep 17 00:00:00 2001
From: Kenneth Bingham <kenneth.bingham@netfoundry.io>
Date: Wed, 29 Jan 2025 03:41:40 -0500
Subject: [PATCH] document the proxy example

---
 sdk/python/examples/proxy/README.md | 48 +++++++++++++++++++++++++++++
 sdk/python/sdk/zrok/zrok/README.md  | 47 ----------------------------
 2 files changed, 48 insertions(+), 47 deletions(-)
 create mode 100644 sdk/python/examples/proxy/README.md
 delete mode 100644 sdk/python/sdk/zrok/zrok/README.md

diff --git a/sdk/python/examples/proxy/README.md b/sdk/python/examples/proxy/README.md
new file mode 100644
index 00000000..a5fff84f
--- /dev/null
+++ b/sdk/python/examples/proxy/README.md
@@ -0,0 +1,48 @@
+
+# zrok Python Proxy Example
+
+This demonstrates using the ProxyShare class to forward requests from the public frontend to a target URL.
+
+## Run the Example
+
+```bash
+LOG_LEVEL=INFO python ./proxy.py http://127.0.0.1:3000
+```
+
+Expected output:
+
+```txt
+2025-01-29 06:37:00,884 - __main__ - INFO - === Starting proxy server ===
+2025-01-29 06:37:00,884 - __main__ - INFO - Target URL: http://127.0.0.1:3000
+2025-01-29 06:37:01,252 - __main__ - INFO - Access proxy at: https://24x0pq7s6jr0.zrok.example.com:443
+2025-01-29 06:37:07,981 - zrok.proxy - INFO - Share 24x0pq7s6jr0 released
+```
+
+## Basic Usage
+
+```python
+from zrok.proxy import ProxyShare
+import zrok
+
+# Load the environment
+root = zrok.environment.root.Load()
+
+# Create a temporary proxy share (will be cleaned up on exit)
+proxy = ProxyShare.create(root=root, target="http://my-target-service")
+
+# Access the proxy's endpoints and token
+print(f"Access proxy at: {proxy.endpoints}")
+proxy.run()
+```
+
+## Creating a Reserved Proxy Share
+
+To create a share token that persists and can be reused, run the example `proxy.py --unique-name my-persistent-proxy`. If the unique name already exists it will be reused. Here's how it works:
+
+```python
+proxy = ProxyShare.create(
+    root=root,
+    target="http://127.0.0.1:3000",
+    unique_name="my-persistent-proxy"
+)
+```
diff --git a/sdk/python/sdk/zrok/zrok/README.md b/sdk/python/sdk/zrok/zrok/README.md
deleted file mode 100644
index 76b5fe8f..00000000
--- a/sdk/python/sdk/zrok/zrok/README.md
+++ /dev/null
@@ -1,47 +0,0 @@
-# Zrok Python SDK
-
-## Proxy Facility
-
-The SDK includes a proxy facility that makes it easy to create and manage proxy shares. This is particularly useful when you need to:
-
-1. Create an HTTP proxy with zrok
-2. Optionally reserve the proxy with a unique name for persistence
-3. Automatically handle cleanup of non-reserved shares
-
-### Basic Usage
-
-```python
-from zrok.proxy import ProxyShare
-import zrok
-
-# Load the environment
-root = zrok.environment.root.Load()
-
-# Create a temporary proxy share (will be cleaned up on exit)
-proxy = ProxyShare.create(root=root, target="http://my-target-service")
-
-# Access the proxy's endpoints and token
-print(f"Access proxy at: {proxy.endpoints}")
-print(f"Share token: {proxy.token}")
-```
-
-### Creating a Reserved Proxy Share
-
-To create a proxy share that persists and can be reused:
-
-```python
-# Create/retrieve a reserved proxy share with a unique name
-proxy = ProxyShare.create(
-    root=root,
-    target="http://my-target-service",
-    unique_name="my-persistent-proxy"
-)
-```
-
-When a `unique_name` is provided:
-
-1. If the zrok environment already has a share with that name, it will be reused
-2. If no share exists, a new reserved share will be created
-3. The share will be automatically cleaned up on exit if no `unique_name` is provided
-
-When a `unique_name` is not provided, the randomly generated share will be cleaned up on exit.