Adding timestamp end to events endpoint. Modifying api docs.

Docker-DCO-1.1-Signed-off-by: Isabel Jimenez <contact@isabeljimenez.com> (github: jimenez)

api/client/commands.go

@@ -1484,7 +1484,8 @@ func (cli *DockerCli) CmdCommit(args ...string) error {
 
 func (cli *DockerCli) CmdEvents(args ...string) error {
 	cmd := cli.Subcmd("events", "[OPTIONS]", "Get real time events from the server")
-	since := cmd.String([]string{"#since", "-since"}, "", "Show previously created events and then stream.")
+	since := cmd.String([]string{"#since", "-since"}, "", "Show all events created since timestamp")
+	until := cmd.String([]string{"-until"}, "", "Stream events until this timestamp")
 	if err := cmd.Parse(args); err != nil {
 		return nil
 	}
@@ -1493,22 +1494,27 @@ func (cli *DockerCli) CmdEvents(args ...string) error {
 		cmd.Usage()
 		return nil
 	}
-
-	v := url.Values{}
-	if *since != "" {
-		loc := time.FixedZone(time.Now().Zone())
+	var (
+		v   = url.Values{}
+		loc = time.FixedZone(time.Now().Zone())
+	)
+	var setTime = func(key, value string) {
 		format := "2006-01-02 15:04:05 -0700 MST"
-		if len(*since) < len(format) {
-			format = format[:len(*since)]
+		if len(value) < len(format) {
+			format = format[:len(value)]
 		}
-
-		if t, err := time.ParseInLocation(format, *since, loc); err == nil {
-			v.Set("since", strconv.FormatInt(t.Unix(), 10))
+		if t, err := time.ParseInLocation(format, value, loc); err == nil {
+			v.Set(key, strconv.FormatInt(t.Unix(), 10))
 		} else {
-			v.Set("since", *since)
+			v.Set(key, value)
 		}
 	}
-
+	if *since != "" {
+		setTime("since", *since)
+	}
+	if *until != "" {
+		setTime("until", *until)
+	}
 	if err := cli.stream("GET", "/events?"+v.Encode(), nil, cli.out, nil); err != nil {
 		return err
 	}

api/common.go

@@ -10,7 +10,7 @@ import (
 )
 
 const (
-	APIVERSION        version.Version = "1.10"
+	APIVERSION        version.Version = "1.11"
 	DEFAULTHTTPHOST                   = "127.0.0.1"
 	DEFAULTUNIXSOCKET                 = "/var/run/docker.sock"
 )

api/server/server.go

@@ -246,6 +246,7 @@ func getEvents(eng *engine.Engine, version version.Version, w http.ResponseWrite
 	var job = eng.Job("events", r.RemoteAddr)
 	streamJSON(job, w, true)
 	job.Setenv("since", r.Form.Get("since"))
+	job.Setenv("until", r.Form.Get("until"))
 	return job.Run()
 }
 

docs/sources/reference/api/docker_remote_api.rst

@@ -28,15 +28,30 @@ Docker Remote API
 2. Versions
 ===========
 
-The current version of the API is 1.10
+The current version of the API is 1.11
 
 Calling /images/<name>/insert is the same as calling
-/v1.10/images/<name>/insert
+/v1.11/images/<name>/insert
 
 You can still call an old version of the api using
-/v1.0/images/<name>/insert
+/v1.11/images/<name>/insert
 
 
+v1.11
+*****
+
+Full Documentation
+------------------
+
+:doc:`docker_remote_api_v1.11`
+
+What's new
+----------
+
+.. http:get:: /events
+
+   **New!** You can now use the ``-until`` parameter to close connection after timestamp.
+
 v1.10
 *****
 

docs/sources/reference/commandline/cli.rst

@@ -490,7 +490,9 @@ For example:
 
     Get real time events from the server
 
-    --since="": Show previously created events and then stream.
+    --since="": Show all events created since timestamp
+               (either seconds since epoch, or date string as below)
+    --until="": Show events created before timestamp
                (either seconds since epoch, or date string as below)
 
 .. _cli_events_example:

server/server.go

@@ -220,8 +220,10 @@ func (srv *Server) Events(job *engine.Job) engine.Status {
 	}
 
 	var (
-		from  = job.Args[0]
-		since = job.GetenvInt64("since")
+		from    = job.Args[0]
+		since   = job.GetenvInt64("since")
+		until   = job.GetenvInt64("until")
+		timeout = time.NewTimer(time.Unix(until, 0).Sub(time.Now()))
 	)
 	sendEvent := func(event *utils.JSONMessage) error {
 		b, err := json.Marshal(event)
@@ -250,9 +252,9 @@ func (srv *Server) Events(job *engine.Job) engine.Status {
 	srv.Unlock()
 	job.Stdout.Write(nil) // flush
 	if since != 0 {
-		// If since, send previous events that happened after the timestamp
+		// If since, send previous events that happened after the timestamp and until timestamp
 		for _, event := range srv.GetEvents() {
-			if event.Time >= since {
+			if event.Time >= since && (event.Time <= until || until == 0) {
 				err := sendEvent(&event)
 				if err != nil && err.Error() == "JSON error" {
 					continue
@@ -264,13 +266,23 @@ func (srv *Server) Events(job *engine.Job) engine.Status {
 			}
 		}
 	}
-	for event := range listener {
-		err := sendEvent(&event)
-		if err != nil && err.Error() == "JSON error" {
-			continue
-		}
-		if err != nil {
-			return job.Error(err)
+
+	// If no until, disable timeout
+	if until == 0 {
+		timeout.Stop()
+	}
+	for {
+		select {
+		case event := <-listener:
+			err := sendEvent(&event)
+			if err != nil && err.Error() == "JSON error" {
+				continue
+			}
+			if err != nil {
+				return job.Error(err)
+			}
+		case <-timeout.C:
+			return engine.StatusOK
 		}
 	}
 	return engine.StatusOK