feat(tasks): add a tasks.lastSuccess function

This patch adds a `lastSuccess` function that can be used to return the
last successful time a task ran. This patch only provides the interface,
and will error if called directly, and will be overridden/implemented
on the server first.

Fixes influxdata#3080

libflux/go/libflux/buildinfo.gen.go

@@ -41,7 +41,7 @@ var sourceHashes = map[string]string{
 	"libflux/src/core/scanner/unicode.rl":                                           "f923f3b385ddfa65c74427b11971785fc25ea806ca03d547045de808e16ef9a1",
 	"libflux/src/core/scanner/unicode.rl.COPYING":                                   "6cf2d5d26d52772ded8a5f0813f49f83dfa76006c5f398713be3854fe7bc4c7e",
 	"libflux/src/core/semantic/bootstrap.rs":                                        "6bc5eb694d5c2f439c02942ce55cee3dac5a10761d375e5276031522598fc2e0",
-	"libflux/src/core/semantic/builtins.rs":                                         "4ad03ce65a6dd746e63449e8d5d7a6f0c8fd2bb02d4d797b11a5ae613e85eda0",
+	"libflux/src/core/semantic/builtins.rs":                                         "1b9f4313bf472fe4f88f4777d29fec0094168b892b0db72d7b21d926e5e72bf9",
 	"libflux/src/core/semantic/check.rs":                                            "acb29602ee01f636818ba3522b3f110018abca3e7b4a6b75c29eec97856a324e",
 	"libflux/src/core/semantic/convert.rs":                                          "d4b1b98565c931742a2294ad7eadd864a11be4d5011e8e86240c5a7b645982b8",
 	"libflux/src/core/semantic/env.rs":                                              "e031d5b752d207a8f93bacd8515639e832735d5a85e90db76690aaeee8168127",

libflux/src/core/semantic/builtins.rs

@@ -138,6 +138,9 @@ pub fn builtins() -> Builtins<'static> {
             "influxdata/influxdb/secrets" => semantic_map! {
                 "get" => "(key: string) => string",
             },
+            "influxdata/influxdb/tasks" => semantic_map! {
+                "lastSuccess" => "(orTime: time) => time",
+            },
             "influxdata/influxdb/v1" => semantic_map! {
                 // exactly one of json and file must be specified
                 // https://github.com/influxdata/flux/issues/2250

stdlib/influxdata/influxdb/tasks/flux_gen.go

@@ -0,0 +1,181 @@
+// DO NOT EDIT: This file is autogenerated via the builtin command.
+
+package tasks
+
+import (
+	ast "github.com/influxdata/flux/ast"
+	parser "github.com/influxdata/flux/internal/parser"
+	runtime "github.com/influxdata/flux/runtime"
+)
+
+func init() {
+	runtime.RegisterPackage(pkgAST)
+}
+
+var pkgAST = &ast.Package{
+	BaseNode: ast.BaseNode{
+		Errors: nil,
+		Loc:    nil,
+	},
+	Files: []*ast.File{&ast.File{
+		BaseNode: ast.BaseNode{
+			Errors: nil,
+			Loc: &ast.SourceLocation{
+				End: ast.Position{
+					Column: 20,
+					Line:   7,
+				},
+				File:   "tasks.flux",
+				Source: "package tasks\n\noption lastSuccessTime = 0000-01-01T00:00:00Z\n\n// This is currently a noop, as its implementation is meant to be\n// overridden elsewhere.\nbuiltin lastSuccess",
+				Start: ast.Position{
+					Column: 1,
+					Line:   1,
+				},
+			},
+		},
+		Body: []ast.Statement{&ast.OptionStatement{
+			Assignment: &ast.VariableAssignment{
+				BaseNode: ast.BaseNode{
+					Errors: nil,
+					Loc: &ast.SourceLocation{
+						End: ast.Position{
+							Column: 46,
+							Line:   3,
+						},
+						File:   "tasks.flux",
+						Source: "lastSuccessTime = 0000-01-01T00:00:00Z",
+						Start: ast.Position{
+							Column: 8,
+							Line:   3,
+						},
+					},
+				},
+				ID: &ast.Identifier{
+					BaseNode: ast.BaseNode{
+						Errors: nil,
+						Loc: &ast.SourceLocation{
+							End: ast.Position{
+								Column: 23,
+								Line:   3,
+							},
+							File:   "tasks.flux",
+							Source: "lastSuccessTime",
+							Start: ast.Position{
+								Column: 8,
+								Line:   3,
+							},
+						},
+					},
+					Name: "lastSuccessTime",
+				},
+				Init: &ast.DateTimeLiteral{
+					BaseNode: ast.BaseNode{
+						Errors: nil,
+						Loc: &ast.SourceLocation{
+							End: ast.Position{
+								Column: 46,
+								Line:   3,
+							},
+							File:   "tasks.flux",
+							Source: "0000-01-01T00:00:00Z",
+							Start: ast.Position{
+								Column: 26,
+								Line:   3,
+							},
+						},
+					},
+					Value: parser.MustParseTime("0000-01-01T00:00:00Z"),
+				},
+			},
+			BaseNode: ast.BaseNode{
+				Errors: nil,
+				Loc: &ast.SourceLocation{
+					End: ast.Position{
+						Column: 46,
+						Line:   3,
+					},
+					File:   "tasks.flux",
+					Source: "option lastSuccessTime = 0000-01-01T00:00:00Z",
+					Start: ast.Position{
+						Column: 1,
+						Line:   3,
+					},
+				},
+			},
+		}, &ast.BuiltinStatement{
+			BaseNode: ast.BaseNode{
+				Errors: nil,
+				Loc: &ast.SourceLocation{
+					End: ast.Position{
+						Column: 20,
+						Line:   7,
+					},
+					File:   "tasks.flux",
+					Source: "builtin lastSuccess",
+					Start: ast.Position{
+						Column: 1,
+						Line:   7,
+					},
+				},
+			},
+			ID: &ast.Identifier{
+				BaseNode: ast.BaseNode{
+					Errors: nil,
+					Loc: &ast.SourceLocation{
+						End: ast.Position{
+							Column: 20,
+							Line:   7,
+						},
+						File:   "tasks.flux",
+						Source: "lastSuccess",
+						Start: ast.Position{
+							Column: 9,
+							Line:   7,
+						},
+					},
+				},
+				Name: "lastSuccess",
+			},
+		}},
+		Imports:  nil,
+		Metadata: "parser-type=rust",
+		Name:     "tasks.flux",
+		Package: &ast.PackageClause{
+			BaseNode: ast.BaseNode{
+				Errors: nil,
+				Loc: &ast.SourceLocation{
+					End: ast.Position{
+						Column: 14,
+						Line:   1,
+					},
+					File:   "tasks.flux",
+					Source: "package tasks",
+					Start: ast.Position{
+						Column: 1,
+						Line:   1,
+					},
+				},
+			},
+			Name: &ast.Identifier{
+				BaseNode: ast.BaseNode{
+					Errors: nil,
+					Loc: &ast.SourceLocation{
+						End: ast.Position{
+							Column: 14,
+							Line:   1,
+						},
+						File:   "tasks.flux",
+						Source: "tasks",
+						Start: ast.Position{
+							Column: 9,
+							Line:   1,
+						},
+					},
+				},
+				Name: "tasks",
+			},
+		},
+	}},
+	Package: "tasks",
+	Path:    "influxdata/influxdb/tasks",
+}

stdlib/influxdata/influxdb/tasks/lastSuccess_test.go

@@ -0,0 +1,34 @@
+package tasks_test
+
+import (
+	"context"
+	"testing"
+
+	"github.com/google/go-cmp/cmp"
+	"github.com/influxdata/flux"
+	"github.com/influxdata/flux/codes"
+	"github.com/influxdata/flux/dependencies/dependenciestest"
+	"github.com/influxdata/flux/stdlib/influxdata/influxdb/tasks"
+	"github.com/influxdata/flux/values"
+)
+
+func TestLastSuccess(t *testing.T) {
+	t.Run("lastSuccess test", func(t *testing.T) {
+		fluxArg := values.NewObjectWithValues(map[string]values.Value{"orTime": values.NewTime(100)})
+
+		_, got := tasks.LastSuccessFunction.Call(dependenciestest.Default().Inject(context.Background()), fluxArg)
+
+		if got == nil {
+			t.Fatal("lastSuccess should produce an error")
+		}
+
+		want := &flux.Error{
+			Code: codes.Unimplemented,
+			Msg:  "This function is not yet implemented.",
+		}
+
+		if !cmp.Equal(want, got) {
+			t.Fatalf("unexpected result -want/+got\n\n%s\n\n", cmp.Diff(want, got))
+		}
+	})
+}

stdlib/influxdata/influxdb/tasks/tasks.flux

@@ -0,0 +1,10 @@
+package tasks
+
+option lastSuccessTime = 0000-01-01T00:00:00Z
+
+// This is currently a noop, as its implementation is meant to be
+// overridden elsewhere.
+// As this function currently only returns an unimplemented error, and 
+// flux has no support for doing this natively, this function is a builtin.
+// When fully implemented, it should be able to be implemented in pure flux.
+builtin lastSuccess

stdlib/influxdata/influxdb/tasks/tasks.go

@@ -0,0 +1,37 @@
+package tasks
+
+import (
+	"context"
+
+	"github.com/influxdata/flux/codes"
+	"github.com/influxdata/flux/internal/errors"
+	"github.com/influxdata/flux/interpreter"
+	"github.com/influxdata/flux/runtime"
+	"github.com/influxdata/flux/values"
+)
+
+const LastSuccessKind = "lastSuccess"
+
+func init() {
+	runtime.RegisterPackageValue("influxdata/influxdb/tasks", LastSuccessKind, LastSuccessFunction)
+}
+
+// LastSuccessFunction is a function that calls LastSuccess.
+var LastSuccessFunction = makeLastSuccessFunc()
+
+func makeLastSuccessFunc() values.Function {
+	sig := runtime.MustLookupBuiltinType("influxdata/influxdb/tasks", "lastSuccess")
+	return values.NewFunction("lastSuccess", sig, LastSuccess, false)
+}
+
+// LastSuccess retrieves the last successful run of the task, or returns the value of the
+// orTime parameter if the task has never successfully run.
+func LastSuccess(ctx context.Context, args values.Object) (values.Value, error) {
+	fargs := interpreter.NewArguments(args)
+	_, err := fargs.GetRequired("orTime")
+	if err != nil {
+		return nil, err
+	}
+
+	return nil, errors.Newf(codes.Unimplemented, "This function is not yet implemented.")
+}

stdlib/packages.go

@@ -28,6 +28,7 @@ import (
 	_ "github.com/influxdata/flux/stdlib/influxdata/influxdb"
 	_ "github.com/influxdata/flux/stdlib/influxdata/influxdb/monitor"
 	_ "github.com/influxdata/flux/stdlib/influxdata/influxdb/secrets"
+	_ "github.com/influxdata/flux/stdlib/influxdata/influxdb/tasks"
 	_ "github.com/influxdata/flux/stdlib/influxdata/influxdb/v1"
 	_ "github.com/influxdata/flux/stdlib/internal/debug"
 	_ "github.com/influxdata/flux/stdlib/internal/gen"