|
| 1 | +# Async Support for Firebase Functions Python |
| 2 | + |
| 3 | +## Overview |
| 4 | + |
| 5 | +This document outlines the design and implementation plan for adding async function support to firebase-functions-python. The goal is to leverage the new async capabilities in functions-framework while maintaining full backward compatibility with existing sync functions. |
| 6 | + |
| 7 | +## Background |
| 8 | + |
| 9 | +Functions-framework recently added async support via the `--asgi` flag, allowing async functions to be defined like: |
| 10 | + |
| 11 | +```python |
| 12 | +import functions_framework.aio |
| 13 | + |
| 14 | +@functions_framework.aio.http |
| 15 | +async def hello_async(request): # Starlette.Request |
| 16 | + await asyncio.sleep(1) |
| 17 | + return "Hello, async world!" |
| 18 | +``` |
| 19 | + |
| 20 | +## Design Goals |
| 21 | + |
| 22 | +1. **No code duplication** - Reuse existing decorators and logic |
| 23 | +2. **Backward compatibility** - All existing sync functions must continue to work |
| 24 | +3. **Unified API** - Users shouldn't need different decorators for sync vs async |
| 25 | +4. **Type safety** - Proper typing for both sync and async cases |
| 26 | +5. **Automatic detection** - The system should automatically detect and handle async functions |
| 27 | +6. **Universal support** - Async should work for ALL function types, not just HTTP |
| 28 | + |
| 29 | +## Function Types to Support |
| 30 | + |
| 31 | +Firebase Functions Python supports multiple trigger types that all need async support: |
| 32 | + |
| 33 | +### 1. HTTP Functions |
| 34 | +- `@https_fn.on_request()` - Raw HTTP requests |
| 35 | +- `@https_fn.on_call()` - Callable functions with auth/validation |
| 36 | + |
| 37 | +### 2. Firestore Functions |
| 38 | +- `@firestore_fn.on_document_created()` |
| 39 | +- `@firestore_fn.on_document_updated()` |
| 40 | +- `@firestore_fn.on_document_deleted()` |
| 41 | +- `@firestore_fn.on_document_written()` |
| 42 | + |
| 43 | +### 3. Realtime Database Functions |
| 44 | +- `@db_fn.on_value_created()` |
| 45 | +- `@db_fn.on_value_updated()` |
| 46 | +- `@db_fn.on_value_deleted()` |
| 47 | +- `@db_fn.on_value_written()` |
| 48 | + |
| 49 | +### 4. Cloud Storage Functions |
| 50 | +- `@storage_fn.on_object_archived()` |
| 51 | +- `@storage_fn.on_object_deleted()` |
| 52 | +- `@storage_fn.on_object_finalized()` |
| 53 | +- `@storage_fn.on_object_metadata_updated()` |
| 54 | + |
| 55 | +### 5. Pub/Sub Functions |
| 56 | +- `@pubsub_fn.on_message_published()` |
| 57 | + |
| 58 | +### 6. Scheduler Functions |
| 59 | +- `@scheduler_fn.on_schedule()` |
| 60 | + |
| 61 | +### 7. Task Queue Functions |
| 62 | +- `@tasks_fn.on_task_dispatched()` |
| 63 | + |
| 64 | +### 8. EventArc Functions |
| 65 | +- `@eventarc_fn.on_custom_event_published()` |
| 66 | + |
| 67 | +### 9. Remote Config Functions |
| 68 | +- `@remote_config_fn.on_config_updated()` |
| 69 | + |
| 70 | +### 10. Test Lab Functions |
| 71 | +- `@test_lab_fn.on_test_matrix_completed()` |
| 72 | + |
| 73 | +### 11. Alerts Functions |
| 74 | +- Various alert triggers for billing, crashlytics, performance, etc. |
| 75 | + |
| 76 | +### 12. Identity Functions |
| 77 | +- `@identity_fn.before_user_created()` |
| 78 | +- `@identity_fn.before_user_signed_in()` |
| 79 | + |
| 80 | +## Implementation Strategy |
| 81 | + |
| 82 | +### Phase 1: Core Infrastructure |
| 83 | + |
| 84 | +#### 1.1 Async Detection Mechanism |
| 85 | +- Add utility function to detect if a function is async using `inspect.iscoroutinefunction()` |
| 86 | +- This detection should happen at decoration time |
| 87 | + |
| 88 | +#### 1.2 Metadata Storage |
| 89 | +- Extend the `__firebase_endpoint__` attribute to include runtime mode information |
| 90 | +- Add a field to `ManifestEndpoint` to indicate async functions: |
| 91 | + ```python |
| 92 | + @dataclasses.dataclass(frozen=True) |
| 93 | + class ManifestEndpoint: |
| 94 | + # ... existing fields ... |
| 95 | + runtime_mode: Literal["sync", "async"] | None = "sync" |
| 96 | + ``` |
| 97 | + |
| 98 | +#### 1.3 Type System Updates |
| 99 | +- Create type unions to handle both sync and async cases |
| 100 | +- For HTTP functions: |
| 101 | + - Sync: `flask.Request` and `flask.Response` |
| 102 | + - Async: `starlette.requests.Request` and response types |
| 103 | +- For event functions: |
| 104 | + - Both sync and async will receive the same event objects |
| 105 | + - The difference is whether the handler is async |
| 106 | + |
| 107 | +### Phase 2: Decorator Updates |
| 108 | + |
| 109 | +#### 2.1 Universal Decorator Pattern |
| 110 | +Each decorator should follow this pattern: |
| 111 | + |
| 112 | +```python |
| 113 | +def on_some_event(**kwargs): |
| 114 | + def decorator(func): |
| 115 | + is_async = inspect.iscoroutinefunction(func) |
| 116 | + |
| 117 | + if is_async: |
| 118 | + # Set up async wrapper |
| 119 | + @functools.wraps(func) |
| 120 | + async def async_wrapper(*args, **kwargs): |
| 121 | + # Any necessary async setup |
| 122 | + return await func(*args, **kwargs) |
| 123 | + |
| 124 | + wrapped = async_wrapper |
| 125 | + runtime_mode = "async" |
| 126 | + else: |
| 127 | + # Use existing sync wrapper |
| 128 | + wrapped = existing_sync_wrapper(func) |
| 129 | + runtime_mode = "sync" |
| 130 | + |
| 131 | + # Set metadata |
| 132 | + endpoint = create_endpoint( |
| 133 | + # ... existing endpoint config ... |
| 134 | + runtime_mode=runtime_mode |
| 135 | + ) |
| 136 | + _util.set_func_endpoint_attr(wrapped, endpoint) |
| 137 | + |
| 138 | + return wrapped |
| 139 | + |
| 140 | + return decorator |
| 141 | +``` |
| 142 | + |
| 143 | +#### 2.2 HTTP Functions Special Handling |
| 144 | +HTTP functions need special care because the request type changes: |
| 145 | +- Sync: `flask.Request` |
| 146 | +- Async: `starlette.requests.Request` |
| 147 | + |
| 148 | +We'll need to handle this in the type system and potentially in request processing. |
| 149 | + |
| 150 | +### Phase 3: Manifest and Deployment |
| 151 | + |
| 152 | +#### 3.1 Manifest Generation |
| 153 | +- Update `serving.py` to include runtime mode in the manifest |
| 154 | +- The functions.yaml should indicate which functions need async runtime |
| 155 | + |
| 156 | +#### 3.2 Firebase CLI Integration |
| 157 | +- The CLI needs to read the runtime mode from the manifest |
| 158 | +- When deploying async functions, it should: |
| 159 | + - Set appropriate environment variables |
| 160 | + - Pass the `--asgi` flag to functions-framework |
| 161 | + - Potentially use different container configurations |
| 162 | + |
| 163 | +### Phase 4: Testing and Validation |
| 164 | + |
| 165 | +#### 4.1 Test Coverage |
| 166 | +- Add async versions of existing tests |
| 167 | +- Test mixed deployments (both sync and async functions) |
| 168 | +- Verify proper error handling in async contexts |
| 169 | +- Test timeout behavior for async functions |
| 170 | + |
| 171 | +#### 4.2 Example Updates |
| 172 | +- Update examples to show async usage |
| 173 | +- Create migration guide for converting sync to async |
| 174 | + |
| 175 | +## Example Usage |
| 176 | + |
| 177 | +### HTTP Functions |
| 178 | +```python |
| 179 | +# Sync (existing) |
| 180 | +@https_fn.on_request() |
| 181 | +def sync_http(request: Request) -> Response: |
| 182 | + return Response("Hello sync") |
| 183 | + |
| 184 | +# Async (new) |
| 185 | +@https_fn.on_request() |
| 186 | +async def async_http(request) -> Response: # Will be Starlette Request |
| 187 | + result = await some_async_api_call() |
| 188 | + return Response(f"Hello async: {result}") |
| 189 | +``` |
| 190 | + |
| 191 | +### Firestore Functions |
| 192 | +```python |
| 193 | +# Sync (existing) |
| 194 | +@firestore_fn.on_document_created(document="users/{userId}") |
| 195 | +def sync_user_created(event: Event[DocumentSnapshot]) -> None: |
| 196 | + print(f"User created: {event.data.id}") |
| 197 | + |
| 198 | +# Async (new) |
| 199 | +@firestore_fn.on_document_created(document="users/{userId}") |
| 200 | +async def async_user_created(event: Event[DocumentSnapshot]) -> None: |
| 201 | + await send_welcome_email(event.data.get("email")) |
| 202 | + await update_analytics(event.data.id) |
| 203 | +``` |
| 204 | + |
| 205 | +### Pub/Sub Functions |
| 206 | +```python |
| 207 | +# Async (new) |
| 208 | +@pubsub_fn.on_message_published(topic="process-queue") |
| 209 | +async def async_process_message(event: CloudEvent[MessagePublishedData]) -> None: |
| 210 | + message = event.data.message |
| 211 | + await process_job(message.data) |
| 212 | +``` |
| 213 | + |
| 214 | +## Benefits |
| 215 | + |
| 216 | +1. **Performance**: Async functions can handle I/O-bound operations more efficiently |
| 217 | +2. **Scalability**: Better resource utilization for functions that make external API calls |
| 218 | +3. **Modern Python**: Aligns with Python's async/await ecosystem |
| 219 | +4. **Flexibility**: Users can choose sync or async based on their needs |
| 220 | + |
| 221 | +## Considerations |
| 222 | + |
| 223 | +1. **Cold Start**: Need to verify async functions don't increase cold start times |
| 224 | +2. **Memory Usage**: Monitor if async runtime uses more memory |
| 225 | +3. **Debugging**: Ensure stack traces and error messages are clear for async functions |
| 226 | +4. **Timeouts**: Verify timeout behavior works correctly with async functions |
| 227 | + |
| 228 | +## Migration Path |
| 229 | + |
| 230 | +1. Start with HTTP functions as proof of concept |
| 231 | +2. Extend to event-triggered functions |
| 232 | +3. Update documentation and examples |
| 233 | +4. Release as minor version update (backward compatible) |
| 234 | + |
| 235 | +## Open Questions |
| 236 | + |
| 237 | +1. Should we support both Flask and Starlette response types for async HTTP functions? |
| 238 | +2. How should we handle async context managers and cleanup? |
| 239 | +3. Should we provide async versions of Firebase Admin SDK operations? |
| 240 | +4. What's the best way to handle errors in async functions? |
| 241 | + |
| 242 | +## Next Steps |
| 243 | + |
| 244 | +1. Prototype async support for HTTP functions |
| 245 | +2. Test with functions-framework in ASGI mode |
| 246 | +3. Design type system for handling both sync and async |
| 247 | +4. Update manifest generation |
| 248 | +5. Coordinate with Firebase CLI team for deployment support |
0 commit comments