API Design Strawmen & Codegen POC#28
Conversation
- Added tools/codegen.py to generate safe WIT bindings. - Added fastly_compute/exceptions.py to define the exception hierarchy. - Updated Makefile to include codegen target.
| manifest_version = 4 | ||
| service_id = "..." | ||
| name = "my-python-service" | ||
| language = "other" # Currently no native "python" support in CLI, so "other" + scripts |
There was a problem hiding this comment.
We'll add python prior to alpha. Update this to just say python now I think for design purposes -- we may just require a fastly cli fork or similar for previewing the developer experience until ready to land.
| [local_server] | ||
| # Viceroy integration | ||
| # The SDK build tool outputs to bin/main.wasm | ||
| bin = "bin/main.wasm" |
There was a problem hiding this comment.
Remove this section from the docs; not necessary.
|
|
||
| - **Initialization**: `uv init` | ||
| - **Adding Dependencies**: `uv add fastly-compute` | ||
| - **Build**: `fastly-py build` will detect `pyproject.toml` and use `uv sync` if needed to ensure the environment is ready. |
There was a problem hiding this comment.
Probably expand this section to have two forms:
- Manual init doing the steps described here.
- Based on a template which will reduce steps; propose we consider wsgi/flask for the basic example.
| ## Implementation Notes | ||
|
|
||
| 1. **Language Support**: Ideally, we work with the Fastly CLI team to get `language = "python"` supported natively, which would set up these defaults automatically. | ||
| 2. **Viceroy**: The `fastly compute serve` command runs Viceroy. Our build tool must ensure the artifact is compatible with the Viceroy version bundled with the CLI. |
There was a problem hiding this comment.
This is already the case with the current viceroy release, shouldn't be an issue. It just needs to support components 0.0.0+.
There was a problem hiding this comment.
Viceroy is not bundled with the CLI; the CLI downloads Viceroy binaries from the public 'releases' area of the Viceroy repository.
| ### Architecture | ||
|
|
||
| - **Language**: Rust | ||
| - **Distribution**: Standalone binary (via cargo install or downloadable releases). |
There was a problem hiding this comment.
This should be published on pypi.org, as uv is, so that it can be installed using normal Python package tooling. Users planning to use Python should not be required to install Rust unless it will be needed for other reasons for the build process.
There was a problem hiding this comment.
Good callout, I agree that this is what will make most sense; the fastly.toml build may end up being something like uv run or uv tool run (will need to sort through the tradeoffs there).
This is one of the ways in which componentize-py itself is distributed as well. Further down the road, we may have extra tooling or uv configuration to fetch from our own pypi mirror (or bytecode alliance) for getting wasi wheels. But that's not part of MVP, we're focusing on mostly pure python dependencies.
- Address feedback from kevin - Flesh out CLI tool more, packaging together with SDK code - Simplify `uv` interfacing with simplier `uv run build` with build moved into pyproject.toml (akin to npm integration). - Include directory structure considerations. - Some basic notes on building the package (maturin).
| class InspectOptions: | ||
| corp: Optional[str] = None | ||
| workspace: Optional[str] = None | ||
| override_client_ip: Optional[str | IPv4Address | IPv6Address] = None |
There was a problem hiding this comment.
Ideally, drop str version if feasible. Need to look at ip-address definition in the wit; if that has nuance, map this to our own SDK class probably.
There was a problem hiding this comment.
The ip-address definition is good. The LLM is being silly.
|
|
||
| @staticmethod | ||
| def inspect( | ||
| request: 'Request', |
There was a problem hiding this comment.
Getting the Request here presents an interesting problem when going through WSGI as I think we presently don't provide this. I don't think this is urgent @erikrose but something to consider when we look at this interface.
There was a problem hiding this comment.
I should add, as shown here this is just mirroring what the wit interface and stub requires.
|
Closing this, many details have been implemented and other are now captured in individual gh issues for feature add support for further discussion. Branch will remain around for now. |
3 participants
These changes are not intended for direct merge but meant as a way to discuss design ideas. Locally, I generated much of the proposals here using Gemini with a few iterations to get things closer to a point where I think we have key functionality covered.
That being said, I fully expect that both I and @erikrose will have feedback here. The [planning/todo.md] file is kind of an index for changes and tries to bucket ones that still may be riskier or deferred work (e.g. async support / asgi).
Finally, as part of fleshing out the exception handling desing (ala #19) I have a POC codegen script showing one approach. This will need more work but is my tool-assisted implementation of an alternative idea I had on how we might be able to consistently remap the variant we get from the SDK to a more fluent exception hierarchy.