improve/add docs around events API

[#86811810]

Signed-off-by: Atul Kshirsagar <[email protected]>

client.go

@@ -24,6 +24,7 @@ var ErrSubscribedToClosedHub = errors.New("subscribed to closed hub")
 var ErrHubAlreadyClosed = errors.New("hub already closed")
 
 //go:generate counterfeiter -o fake_receptor/fake_client.go . Client
+
 type Client interface {
 	CreateTask(TaskCreateRequest) error
 	Tasks() ([]TaskResponse, error)

doc/api_lrps.md

@@ -114,4 +114,9 @@ Diego supports killing the ActualLRPs for a given `process_guid` at a given `ind
 DELETE /v1/actual_lrps/:process_guid/index/:index
 ```
 
+## Receiving events when Actual or Desired LRPs change
+
+To get server side event stream for changes to DesiredLRPs and ActualLRPs, see [Events](events.md).
+
+
 [back](README.md)

doc/events.md

@@ -0,0 +1,85 @@
+# Events
+
+```
+GET /v1/events
+```
+
+Following types of events are emitted when changes to desired LRP and actual LRP are done:
+
+## Desire LRP create event
+
+When a new desired LRP is created a `DesiredLRPCreatedEvent` is emitted. Below the desired lrp created event is described:
+
+```
+{
+  "desired_lrp": {...}
+}
+```
+
+The field value of `desired_lrp` will be a `DesiredLRPResponse`, which is described in the [LRP API](lrps.md).
+
+## Desired LRP change event
+
+When a desired LRP is changed a `DesiredLRPChangedEvent` is emitted. Below the desired lrp changed event is described:
+
+```
+{
+  "desired_lrp_before": {...},
+  "desired_lrp_after": {...},
+}
+```
+
+The field value of `desired_lrp_before` and `desired_lrp_after` will be a `DesiredLRPResponse`, which is described in the [LRP API](lrps.md).
+
+
+## Desired LRP remove event
+
+When a desired LRP is deleted a `DesiredLRPRemovedEvent` is emitted. Below the desired lrp deleted event is described:
+
+```
+{
+  "desired_lrp": {...}
+}
+```
+
+The field value of `desired_lrp` will be a `DesiredLRPResponse`, which is described in the [LRP API](lrps.md).
+
+
+## Actual LRP create event
+
+When a new actual LRP is created a `ActualLRPCreatedEvent` is emitted. Below the actual lrp created event is described:
+
+```
+{
+  "actual_lrp": {...}
+}
+```
+
+The field value of `actual_lrp` will be a `ActualLRPResponse`, which is described in the [LRP API](lrps.md).
+
+
+## Actual LRP change event
+
+When a actual LRP is changed a `ActualLRPChangedEvent` is emitted. Below the actual lrp changed event is described:
+
+```
+{
+  "actual_lrp_before": {...},
+  "actual_lrp_after": {...},
+}
+```
+
+The field value of `actual_lrp_before` and `actual_lrp_after` will be a `ActualLRPResponse`, which is described in the [LRP API](lrps.md).
+
+
+## Actual LRP remove event
+
+When a new actual LRP is deleted a `ActualLRPRemovedEvent` is emitted. Below the actual lrp deleted event is described:
+
+```
+{
+  "actual_lrp": {...}
+}
+```
+
+The field value of `actual_lrp` will be a `ActualLRPResponse`, which is described in the [LRP API](lrps.md).

event_source.go

@@ -50,12 +50,24 @@ func (e closeError) Error() string {
 }
 
 //go:generate counterfeiter -o fake_receptor/fake_event_source.go . EventSource
+
+// EventSource provides sequential access to a stream of events.
 type EventSource interface {
+	// Next reads the next event from the source. If the connection is lost, it
+	// automatically reconnects.
+	//
+	// If the end of the stream is reached cleanly (which should actually never
+	// happen), io.EOF is returned. If called after or during Close,
+	// ErrSourceClosed is returned.
 	Next() (Event, error)
+
+	// Close releases the underlying response, interrupts any in-flight Next, and
+	// prevents further calls to Next.
 	Close() error
 }
 
 //go:generate counterfeiter -o fake_receptor/fake_raw_event_source.go . RawEventSource
+
 type RawEventSource interface {
 	Next() (sse.Event, error)
 	Close() error