Skip to content

Commit

Permalink
Adjusting the readme to be for v2, rename ToEventMessage to ToMessage (
Browse files Browse the repository at this point in the history
…#386)

* Adjusting the readme to be for v2, rename ToEventMessage to ToMessage

Signed-off-by: Scott Nichols <snichols@vmware.com>

* point to the release-1.x.y branch for examples.

Signed-off-by: Scott Nichols <snichols@vmware.com>

* don't repeat yourself.

Signed-off-by: Scott Nichols <snichols@vmware.com>
  • Loading branch information
n3wscott authored Mar 16, 2020
1 parent 6017d94 commit 3e150c4
Show file tree
Hide file tree
Showing 9 changed files with 241 additions and 91 deletions.
170 changes: 89 additions & 81 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,130 +10,138 @@

This SDK is still considered work in progress.

**With v1.1.0:**
**For v1 of the SDK, see** [CloudEvents Go SDK v1](./README_v1.md).

[Master](https://github.com/cloudevents/sdk-go/tree/master) will now be the base
of the effort for v2.0.0 of this SDK and will contain breaking changes or
missing libraries.
**v2.0.0-preview2:**

Future work on v1.X.Y releases will branch off of
[release-1.y.z](https://github.com/cloudevents/sdk-go/tree/release-1.y.z). To
add a bugfix to a v1.X.Y release, please make a PR to that branch and we can do
releases as needed on the v1 SDK. No date for EOL on v1 support yet, that will
be determined by the progress on v2.
In _preview2_ we are focusing on the new Client interface:

The CloudEvents golang team is working hard to bring you v2.0.0 of the SDK.

**With v1.0.0:**
```go
type Client interface {
Send(ctx context.Context, event event.Event) error
Request(ctx context.Context, event event.Event) (*event.Event, error)
StartReceiver(ctx context.Context, fn interface{}) error
}
```

The API that exists under [`pkg/cloudevents`](./pkg/cloudevents) will follow
semver rules. This applies to the root [`./alias.go`](./alias.go) file as well.
Where a full `fn` looks like
`func(context.Context, event.Event) (*event.Event, transport.Result)`

Even though `pkg/cloudevents` is v1.0.0, there could still be minor bugs and
performance issues. We will continue to track and fix these issues as they come
up. Please file a pull request or issue if you experience problems.
For protocols that do not support responses, `StartReceiver` will throw an error
when attempting to set a receiver fn with that capability.

The API that exists under [`pkg/bindings`](./pkg/bindings) is a new API that
will become SDK v2.x, and will replace `pkg/cloudevents`. This area is still
under heavy development and will not be following the same semver rules as
`pkg/cloudevents`. If a release is required to ship changes to `pkg/bindings`, a
bug fix release will be issued (x.y.z+1).
For protocols that do not support responses from send (Requester interface),
`Client.Request` will throw an error.

We will target ~2 months of development to release v2 of this SDK with an end
date of March 27, 2020. You can read more about the plan for SDK v2 in the
[SDK v2 planning doc](./docs/SDK_v2.md).
**v2.0.0-preview1:**

This SDK current supports the following versions of CloudEvents:
In _preview1_ we are focusing on the new interfaces found in pkg/transport (will
be renamed to protocol):

- v1.0
- v0.3
- v0.2
- v0.1
- Sender, Send an event.
- Requester, Send an event and expect a response.
- Receiver, Receive an event.
- Responder, Receive an event and respond.

## Working with CloudEvents

Package [cloudevents](./pkg/cloudevents) provides primitives to work with
CloudEvents specification: https://github.com/cloudevents/spec.
_Note:_ Supported
[CloudEvents specification](https://github.com/cloudevents/spec): [0.3, 1.0].

Import this repo to get the `cloudevents` package:

```go
import "github.com/cloudevents/sdk-go"
import cloudevents "github.com/cloudevents/sdk-go"
```

Receiving a cloudevents.Event via the HTTP Transport:
To marshal a CloudEvent into JSON, use `event.Event` directly:

```go
func Receive(event cloudevents.Event) {
// do something with event.Context and event.Data (via event.DataAs(foo)
}
event := cloudevents.NewEvent()
event.SetSource("example/uri")
event.SetType("example.type")
event.SetData(cloudevents.ApplicationJSON, map[string]string{"hello": "world"})

bytes, err := json.Marshal(event)
```

To unmarshal JSON back into a CloudEvent:

```go
event := cloudevents.NewEvent()

err := json.Marshal(bytes, &event)
```

The aim of CloudEvents Specification is to define how to "bind" an event to a
particular protocol and back. This SDK wraps the protocol binding
implementations in a client to expose a simple `event.Event` based API.

An example of sending a cloudevents.Event via HTTP:

```go
func main() {
// The default client is HTTP.
c, err := cloudevents.NewDefaultClient()
if err != nil {
log.Fatalf("failed to create client, %v", err)
}
log.Fatal(c.StartReceiver(context.Background(), Receive));
}
```

Creating a minimal CloudEvent in version 1.0:
// Create an Event.
event := cloudevents.NewEvent()
event.SetSource("example/uri")
event.SetType("example.type")
event.SetData(cloudevents.ApplicationJSON, map[string]string{"hello": "world"})

```go
event := cloudevents.NewEvent()
event.SetID("ABC-123")
event.SetType("com.cloudevents.readme.sent")
event.SetSource("http://localhost:8080/")
event.SetData(data)
// Set a target.
ctx := cloudevents.ContextWithTarget(context.Background(), "http://localhost:8080/")

// Send that Event.
if err := c.Send(ctx, event); err != nil {
log.Fatalf("failed to send, %v", err)}
}
}
```

Sending a cloudevents.Event via the HTTP Transport with Binary v1.0 encoding:
An example of receiving a cloudevents.Event via HTTP:

```go
t, err := cloudevents.NewHTTPTransport(
cloudevents.WithTarget("http://localhost:8080/"),
cloudevents.WithEncoding(cloudevents.HTTPBinaryV1),
)
if err != nil {
panic("failed to create transport, " + err.Error())
func receive(event cloudevents.Event) {
// do something with event.
fmt.Printf("%s", event)
}

c, err := cloudevents.NewClient(t)
if err != nil {
panic("unable to create cloudevent client: " + err.Error())
}
if err := c.Send(ctx, event); err != nil {
panic("failed to send cloudevent: " + err.Error())
func main() {
// The default client is HTTP.
c, err := cloudevents.NewDefaultClient()
if err != nil {
log.Fatalf("failed to create client, %v", err)
}
log.Fatal(c.StartReceiver(context.Background(), receive));
}
```

Or, the transport can be set to produce CloudEvents using the selected encoding
but not change the provided event version, here the client is set to output
structured encoding:
Checkout the sample [sender](./cmd/samples/http/sender) and
[receiver](./cmd/samples/http/receiver) applications for working demo.

```go
t, err := cloudevents.NewHTTPTransport(
cloudevents.WithTarget("http://localhost:8080/"),
cloudevents.WithStructuredEncoding(),
)
```
It can be more performant to not parse an event all the way to the
`event.Event`. For this the package [binding](./pkg/binding) provides primitives
convert `event.Event` to `binding.Message`, and then bind an them onto a
[protocol](./pkg/protocol) implementation.

If you are using advanced transport features or have implemented your own
transport integration, provide it to a client so your integration does not
change:
For example, to convert an `event.Event` to a `binding.Message` and then create
an `http.Request`:

```go
t, err := cloudevents.NewHTTPTransport(
cloudevents.WithPort(8181),
cloudevents.WithPath("/events/")
)
// or a custom transport: t := &custom.MyTransport{Cool:opts}
msg := cloudevents.ToMessage(&event)

c, err := cloudevents.NewClient(t, opts...)
```
req, _ = nethttp.NewRequest("POST", "http://localhost", nil)
err = http.WriteRequest(context.TODO(), msg, req, nil)
// ...check error.

Checkout the sample [sender](./cmd/samples/http/sender) and
[receiver](./cmd/samples/http/receiver) applications for working demo.
// Then use req:
resp, err := http.DefaultClient.Do(req)
```

## Community

Expand Down
138 changes: 138 additions & 0 deletions README_v1.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,138 @@
# Go SDK for [CloudEvents](https://github.com/cloudevents/spec)

The Golong SDK v1 can be found on the `release-1.x.y` branch, or one of the
releases for v0, or v1 published releases.

**With v1.1.0:**

[Master](https://github.com/cloudevents/sdk-go/tree/master) will now be the base
of the effort for v2.0.0 of this SDK and will contain breaking changes or
missing libraries.

Future work on v1.X.Y releases will branch off of
[release-1.y.z](https://github.com/cloudevents/sdk-go/tree/release-1.y.z). To
add a bugfix to a v1.X.Y release, please make a PR to that branch and we can do
releases as needed on the v1 SDK. No date for EOL on v1 support yet, that will
be determined by the progress on v2.

The CloudEvents golang team is working hard to bring you v2.0.0 of the SDK.

**With v1.0.0:**

The API that exists under
[`pkg/cloudevents`](https://github.com/cloudevents/sdk-go/tree/release-1.y.z/pkg/cloudevents)
will follow semver rules. This applies to the root
[`./alias.go`](https://github.com/cloudevents/sdk-go/tree/release-1.y.z/alias.go)
file as well.

Even though `pkg/cloudevents` is v1.0.0, there could still be minor bugs and
performance issues. We will continue to track and fix these issues as they come
up. Please file a pull request or issue if you experience problems.

The API that exists under
[`pkg/bindings`](https://github.com/cloudevents/sdk-go/tree/release-1.y.z/pkg/bindings)
is a new API that will become SDK v2.x, and will replace `pkg/cloudevents`. This
area is still under heavy development and will not be following the same semver
rules as `pkg/cloudevents`. If a release is required to ship changes to
`pkg/bindings`, a bug fix release will be issued (x.y.z+1).

We will target ~2 months of development to release v2 of this SDK with an end
date of March 27, 2020. You can read more about the plan for SDK v2 in the
[SDK v2 planning doc](https://github.com/cloudevents/sdk-go/tree/release-1.y.z/docs/SDK_v2.md).

This SDK current supports the following versions of CloudEvents:

- v1.0
- v0.3
- v0.2
- v0.1

## Working with CloudEvents

Package
[cloudevents](https://github.com/cloudevents/sdk-go/tree/release-1.y.z/pkg/cloudevents)
provides primitives to work with CloudEvents specification:
https://github.com/cloudevents/spec.

Import this repo to get the `cloudevents` package:

```go
import "github.com/cloudevents/sdk-go"
```

Receiving a cloudevents.Event via the HTTP Transport:

```go
func Receive(event cloudevents.Event) {
// do something with event.Context and event.Data (via event.DataAs(foo)
}

func main() {
c, err := cloudevents.NewDefaultClient()
if err != nil {
log.Fatalf("failed to create client, %v", err)
}
log.Fatal(c.StartReceiver(context.Background(), Receive));
}
```

Creating a minimal CloudEvent in version 1.0:

```go
event := cloudevents.NewEvent()
event.SetID("ABC-123")
event.SetType("com.cloudevents.readme.sent")
event.SetSource("http://localhost:8080/")
event.SetData(data)
```

Sending a cloudevents.Event via the HTTP Transport with Binary v1.0 encoding:

```go
t, err := cloudevents.NewHTTPTransport(
cloudevents.WithTarget("http://localhost:8080/"),
cloudevents.WithEncoding(cloudevents.HTTPBinaryV1),
)
if err != nil {
panic("failed to create transport, " + err.Error())
}

c, err := cloudevents.NewClient(t)
if err != nil {
panic("unable to create cloudevent client: " + err.Error())
}
if err := c.Send(ctx, event); err != nil {
panic("failed to send cloudevent: " + err.Error())
}
```

Or, the transport can be set to produce CloudEvents using the selected encoding
but not change the provided event version, here the client is set to output
structured encoding:

```go
t, err := cloudevents.NewHTTPTransport(
cloudevents.WithTarget("http://localhost:8080/"),
cloudevents.WithStructuredEncoding(),
)
```

If you are using advanced transport features or have implemented your own
transport integration, provide it to a client so your integration does not
change:

```go
t, err := cloudevents.NewHTTPTransport(
cloudevents.WithPort(8181),
cloudevents.WithPath("/events/")
)
// or a custom transport: t := &custom.MyTransport{Cool:opts}

c, err := cloudevents.NewClient(t, opts...)
```

Checkout the sample
[sender](https://github.com/cloudevents/sdk-go/tree/release-1.y.z/cmd/samples/http/sender)
and
[receiver](https://github.com/cloudevents/sdk-go/tree/release-1.y.z/cmd/samples/http/receiver)
applications for working demo.
4 changes: 4 additions & 0 deletions alias.go
Original file line number Diff line number Diff line change
Expand Up @@ -97,6 +97,10 @@ var (

NewHTTPResponse = http.NewResult

// Message Creation

ToMessage = binding.ToMessage

// Tracing

EnableTracing = observability.EnableTracing
Expand Down
2 changes: 1 addition & 1 deletion pkg/binding/buffering/copy_message_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ func TestCopyMessage(t *testing.T) {
inputMessage = tt.message
} else {
e := tt.event.Clone()
inputMessage = binding.ToEventMessage(&e)
inputMessage = binding.ToMessage(&e)
}

t.Run(fmt.Sprintf("CopyMessage: %s", tt.name), func(t *testing.T) {
Expand Down
2 changes: 1 addition & 1 deletion pkg/binding/event_message.go
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ const (
// an Event message, you should copy it before
type EventMessage event.Event

func ToEventMessage(e *event.Event) Message {
func ToMessage(e *event.Event) Message {
return (*EventMessage)(e)
}

Expand Down
2 changes: 1 addition & 1 deletion pkg/binding/to_event_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,7 @@ func TestToEvent(t *testing.T) {
inputMessage = tt.message
} else {
e := tt.event.Clone()
inputMessage = binding.ToEventMessage(&e)
inputMessage = binding.ToMessage(&e)
}
got, err := binding.ToEvent(context.Background(), inputMessage, nil)
require.NoError(t, err)
Expand Down
Loading

0 comments on commit 3e150c4

Please sign in to comment.