49efdabede
This is based on work from @lunaris and @EronWright, to allow us to return better error messages from component providers. The basic idea here is to allow attaching more error details on the RPC layer, and turn errors into diagnostic *in the engine*, to avoid the need to do fix the error up in every SDK and pretty print it. GRPC allows us to attach error details to the returned error to help us with that. These details can be error details such as specified in the `error_details` proto that comes with grpc, but can also take any other shape. Currently we only support pretty printing select types from that proto, but this can be extended in the future. On the implementation side, Go has a pretty nice API to create these errors, which we can just let users use directly. For Python and NodeJS the API is not so nice for this, so we need to encapsulate the error into a special exception, and then turn that into a proper GRPC message, using the magic `grpc-status-details-bin` metadata field. For both Python and NodeJS I've only implemented one class for errors so far, as I'm interested in some feedback on the API design first. I'm wondering if we should just let users specify the fields as tuples, and then add them to the `error_details` proto? Very open to ideas here. Closes: https://github.com/pulumi/pulumi/pull/16132 --------- Co-authored-by: Will Jones <will@sacharissa.co.uk> Co-authored-by: Eron Wright <eron@pulumi.com> |
||
|---|---|---|
| .. | ||
| build-container | ||
| google/protobuf | ||
| pulumi | ||
| .checksum.txt | ||
| README.md | ||
| generate.sh | ||
| grpc_version.txt | ||
README.md
Protobuf and gRPC interfaces
This package contains Protobuf definitions for the various types, messages and interfaces that Pulumi components use to communicate. These definitions serve as the source of truth for several parts of the wider codebase.
Code generation
:::{note}
Code generated from Protobuf files is committed to the repository. If you change
one or more .proto files, you should run make build_proto to regenerate the
necessary stubs and commit the changes as part of the same piece of work.
:::
The gh-file:pulumi#proto/generate.sh script in this directory (called by the
build_proto target in the top-level gh-file:pulumi#Makefile) generates types
and gRPC clients for the languages supported in this repository (Go,
NodeJS/TypeScript and Python). Generated code is committed to the repository,
typically in proto directories at the relevant use sites (e.g.
gh-file:pulumi#sdk/nodejs/proto).
Documentation
We use the protoc-gen-doc
plugin to protoc to generate
Markdown documentation from the Protobuf files. This process is handled by the
gh-file:pulumi#docs/Makefile in the docs directory and uses the
gh-file:pulumi#docs/references/proto.md.tmpl template. Generated documentation ends
up in the docs/_generated directory (which is .gitignored), so e.g. this
index links to files in this folder.
Index
:::{toctree} :maxdepth: 1 :titlesonly:
/docs/_generated/proto/resource /docs/_generated/proto/provider /docs/_generated/proto/plugin /docs/_generated/proto/language /docs/_generated/proto/callback /docs/_generated/proto/loader /docs/_generated/proto/converter /docs/_generated/proto/analyzer /docs/_generated/proto/alias /docs/_generated/proto/engine /docs/_generated/proto/errors /docs/_generated/proto/source :::