search

cloudevents / sdk-go

Go SDK for CloudEvents
https://cloudevents.github.io/sdk-go/
Apache License 2.0
833 stars 219 forks source link

Would like to see a sample of how to use the new protobuf format. #705

Open n3wscott opened 3 years ago

n3wscott commented 3 years ago

We added protobuf format support but not a sample of how to use it.

See https://github.com/cloudevents/sdk-go/pull/662 https://github.com/cloudevents/sdk-go/pull/688

kconwayinvision commented 3 years ago

If you can outline the content you'd like to see and where in the docs you'd like to see it then I'll make a PR.

n3wscott commented 3 years ago

@kconwayinvision see the other samples here: https://github.com/cloudevents/sdk-go/tree/main/samples

I would perhaps add a protobuf example in the http folder? Just a simple example (perhaps, a copy of https://github.com/cloudevents/sdk-go/blob/main/samples/http/sender/main.go) for sending and receiving events (it is best to pair them to produce a simple demo).

Thanks!!

kconwayinvision commented 3 years ago

Here's a first draft: https://github.com/cloudevents/sdk-go/pull/712 .

kconwayinvision commented 3 years ago

I think this is mostly closed by https://github.com/cloudevents/sdk-go/pull/712.

From that PR thread, the only thing missing is an example of using the protobuf format for the envelope. I'm not able to create an example of that using the existing protocols because they either require JSON or define their own format that is specific to the protocol. For example, the HTTP transport encodes the envelope as HTTP headers and uses the request/response body to store the data attribute directly rather than writing a fully encoded envelope+data to the body.

I believe full use of the protobuf format for the envelope requires a new protocol definition in the spec that specifically makes use of it. For example, this could be a service interface defined in protobuf that receives and returns the CloudEvent protobuf structure directly. The example I gave in the PR discussion was:

service Protocol {
  rpc Send(CloudEvent) returns (Empty);
  rpc Request(CloudEvent) returns (CloudEvent);
}

This roughly matches the current client/server semantics of the Go SDK and could be wrapped in the generic client abstraction. That's effectively how I'm currently making use of both the format and encoding but it's not part of the current protobuf spec.