sdk-go

sdk-go copied to clipboard

The instructions in the README for this repo do not work as intended and instructions are not clear.

https://github.com/cloudevents/sdk-go#get-started

• go get github.com/cloudevents/sdk-go/[email protected]
  • Does not work if you do not have a go module. You need to go mod init example.com/test-sdk-go

https://github.com/cloudevents/sdk-go#send-your-first-cloudevent

(Not tested)

https://github.com/cloudevents/sdk-go#receive-your-first-cloudevent

• Code sample is broken up and not complete.
  • Does not include imports
  • Receiving is more common with CloudEvent than sending. Receiving should be the first example.
  • What is the filename? Say something like "Create a main.go file:"
  • Sample needs package and imports
    • Especially cloudevents "github.com/cloudevents/sdk-go/v2"
• Needs instructions on how to run this code. go run main.go?
• Sample does not work. Does not log any output, just hangs. Sending requests to localhost:8080 does not work.

---

All-in-all, I would expect a working sample of a very simple and common use-case, receiving a CloudEvent via HTTP.

The intent is not to teach go in the readme, I think someone who has used go even a little could get this to work, and if that fails there are several working samples using http and go mod.

Yes, some of these points are nits/nice-to-haves.

@n3wscott Are you not able to reproduce the issue of the sample not working?

Hey @n3wscott, I'd like to help our users have a better experience when using this SDK. I'm very thankful you've written the samples.

The majority of the samples like http/receiver you've mentioned have no comments or README instructions as is common with sample code. Some of our users are new to Go and CloudEvents, and I think there are some improvements we can make.

Here are some concrete ideas:

• What if we provided a more complete quickstart with a log on startup in the readme, so a user can copy-paste the sample and try out the SDK?

  ackage main
  
  mport (
  "context"
  "fmt"
  "log"
  
  cloudevents "github.com/cloudevents/sdk-go/v2"
  
  
  unc receive(event cloudevents.Event) {
  // do something with event.
  fmt.Printf("Received event:\n%s", event)
  
  
  unc main() {
  // The default client is HTTP.
  fmt.Println("Listening to CloudEvents...")
  c, err := cloudevents.NewDefaultClient()
  if err != nil {
  	log.Fatalf("failed to create client, %v", err)
  }
  log.Fatal(c.StartReceiver(context.Background(), receive))
  
  

  • And a simple command to test like go build && ./hello.
• What happens if a user sends a POST request with an invalid CloudEvent? It seems like the sample simply accepts the HTTP POST request with no output. Is that intended?
  • That seems like something we should document.
• I'm not sure how best to test the HTTP server locally. There seems to be no output with invalid CEs, so you must construct a curl request with a valid CE. It would be nice if there was a sample input and output you could try out the sample, or perhaps recommend the CE CLI.

What do you think?

• I think we already do much more advanced testing in the integration testing. It is a mixed bag when talking about a copy/pastable example in the readme.

• I am not sold on the value of the quickstart. There are more things you need to understand about go and go mod before this works. We had not been targeting this level of inexperience with the sdk.

• If a producer sends an invalid cloudevent, they will get an error on their side and the sdk receiver sees nothing.