Add docs for ASGI web apps

bioimage-io · May 7, 2024 · 0e6ed74 · 0e6ed74
1 parent 1be67a1
commit 0e6ed74
Show file tree

Hide file tree

Showing 2 changed files with 62 additions and 0 deletions.
diff --git a/docs/_sidebar.md b/docs/_sidebar.md
@@ -1,4 +1,5 @@
  * [Getting Started](/getting-started)
  * [ImJoy RPC V2](/imjoy-rpc)
  * [Serverless Functions](/serverless-functions)
+ * [Serve ASGI Web Apps](/asgi-apps)
  * [Development](/development)
diff --git a/docs/asgi-apps.md b/docs/asgi-apps.md
@@ -0,0 +1,61 @@
+## Serve ASGI Web Applications
+
+ASGI is a standard to create async web applications. With hypha, you can register a service which serves an ASGI application, e.g. a FastAPI app which serve a web page, or a web API.
+
+The following example shows how to use FastAPI to create a web application in the browser, e.g. https://imjoy-notebook.netlify.app/, and serve it through Hypha.
+
+```python
+import asyncio
+from imjoy_rpc.hypha import connect_to_server
+
+import micropip
+
+# This assumes you are in a Pyodide environment
+await micropip.install(["fastapi==0.70.0", "pyotritonclient==0.1.37", "numpy", "imageio", "Pillow", "matplotlib"])
+
+from fastapi import FastAPI
+from fastapi.responses import HTMLResponse
+
+# Connect to the Hypha server
+server_url = "https://ai.imjoy.io"
+server = await connect_to_server({"server_url": server_url})
+
+app = FastAPI()
+
+@app.get("/", response_class=HTMLResponse)
+async def root():
+    html_content = """
+    <html>
+        <head>
+            <title>Cat</title>
+        </head>
+        <body>
+            <img src="https://cataas.com/cat?type=square" alt="cat">
+        </body>
+    </html>
+    """
+    return HTMLResponse(content=html_content, status_code=200)
+
+@app.get("/api/v1/test")
+async def test():
+    return {"message": "Hello, it works!", "server_url": server_url}
+
+async def serve_fastapi(args):
+    scope = args["scope"]
+    print(f'{scope["client"]} - {scope["method"]} - {scope["path"]}')
+    await app(args["scope"], args["receive"], args["send"])
+
+svc_info = await server.register_service({
+    "id": "cellpose",
+    "name": "cellpose",
+    "type": "ASGI",
+    "serve": serve_fastapi,
+    "config":{
+        "visibility": "public"
+    }
+})
+
+print(f"Test it with the HTTP proxy: {server_url}/{server.config.workspace}/apps/{svc_info['id'].split(':')[1]}")
+```
+
+This will create a web page which you can view in the browser, and also an API endpoint at `/api/v1/test`.