i/prompting: add package for prompting common types/functions

interfaces/prompting/prompting.go

@@ -0,0 +1,161 @@
+// -*- Mode: Go; indent-tabs-mode: t -*-
+
+/*
+ * Copyright (C) 2024 Canonical Ltd
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License version 3 as
+ * published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+
+package prompting
+
+import (
+	"encoding/json"
+	"fmt"
+	"time"
+)
+
+// OutcomeType describes the outcome associated with a reply or rule.
+type OutcomeType string
+
+const (
+	// OutcomeUnset indicates that no outcome was specified, and should only
+	// be used while unmarshalling outcome fields marked as omitempty.
+	OutcomeUnset OutcomeType = ""
+	// OutcomeAllow indicates that a corresponding request should be allowed.
+	OutcomeAllow OutcomeType = "allow"
+	// OutcomeDeny indicates that a corresponding request should be denied.
+	OutcomeDeny OutcomeType = "deny"
+)
+
+func (outcome *OutcomeType) UnmarshalJSON(data []byte) error {
+	var s string
+	if err := json.Unmarshal(data, &s); err != nil {
+		return err
+	}
+	value := OutcomeType(s)
+	switch value {
+	case OutcomeAllow, OutcomeDeny:
+		*outcome = value
+	default:
+		return fmt.Errorf(`cannot have outcome other than %q or %q: %q`, OutcomeAllow, OutcomeDeny, value)
+	}
+	return nil
+}
+
+// IsAllow returns true if the outcome is OutcomeAllow, false if the outcome is
+// OutcomeDeny, or an error if it cannot be parsed.
+func (outcome OutcomeType) IsAllow() (bool, error) {
+	switch outcome {
+	case OutcomeAllow:
+		return true, nil
+	case OutcomeDeny:
+		return false, nil
+	default:
+		return false, fmt.Errorf(`internal error: invalid outcome: %q`, outcome)
+	}
+}
+
+// LifespanType describes the temporal scope for which a reply or rule applies.
+type LifespanType string
+
+const (
+	// LifespanUnset indicates that no lifespan was specified, and should only
+	// be used while unmarshalling lifespan fields marked as omitempty.
+	LifespanUnset LifespanType = ""
+	// LifespanForever indicates that the reply/rule should never expire.
+	LifespanForever LifespanType = "forever"
+	// LifespanSingle indicates that a reply should only apply once, and should
+	// not be used to create a rule.
+	LifespanSingle LifespanType = "single"
+	// LifespanTimespan indicates that a reply/rule should apply for a given
+	// duration or until a given expiration timestamp.
+	LifespanTimespan LifespanType = "timespan"
+	// TODO: add LifespanSession which expires after the user logs out
+	// LifespanSession  LifespanType = "session"
+)
+
+func (lifespan *LifespanType) UnmarshalJSON(data []byte) error {
+	var lifespanStr string
+	if err := json.Unmarshal(data, &lifespanStr); err != nil {
+		return err
+	}
+	value := LifespanType(lifespanStr)
+	switch value {
+	case LifespanForever, LifespanSingle, LifespanTimespan:
+		*lifespan = value
+	default:
+		return fmt.Errorf(`cannot have lifespan other than %q, %q, or %q: %q`, LifespanForever, LifespanSingle, LifespanTimespan, value)
+	}
+	return nil
+}
+
+// ValidateExpiration checks that the given expiration is valid for the
+// receiver lifespan.
+//
+// If the lifespan is LifespanTimespan, then expiration must be non-zero and be
+// after the given currTime. Otherwise, it must be zero. Returns an error if
+// any of the above are invalid.
+func (lifespan LifespanType) ValidateExpiration(expiration time.Time, currTime time.Time) error {
+	switch lifespan {
+	case LifespanForever, LifespanSingle:
+		if !expiration.IsZero() {
+			return fmt.Errorf(`cannot have specified expiration when lifespan is %q: %q`, lifespan, expiration)
+		}
+	case LifespanTimespan:
+		if expiration.IsZero() {
+			return fmt.Errorf(`cannot have unspecified expiration when lifespan is %q`, lifespan)
+		}
+		if currTime.After(expiration) {
+			return fmt.Errorf("cannot have expiration time in the past: %q", expiration)
+		}
+	default:
+		// Should not occur, since lifespan is validated when unmarshalled
+		return fmt.Errorf(`internal error: invalid lifespan: %q`, lifespan)
+	}
+	return nil
+}
+
+// ParseDuration checks that the given duration is valid for the receiver
+// lifespan and parses it into an expiration timestamp.
+//
+// If the lifespan is LifespanTimespan, then duration must be a string parsable
+// by time.ParseDuration(), representing the duration of time for which the rule
+// should be valid. Otherwise, it must be empty. Returns an error if any of the
+// above are invalid, otherwise computes the expiration time of the rule based
+// on the given currTime and the given duration and returns it.
+func (lifespan LifespanType) ParseDuration(duration string, currTime time.Time) (time.Time, error) {
+	var expiration time.Time
+	switch lifespan {
+	case LifespanForever, LifespanSingle:
+		if duration != "" {
+			return expiration, fmt.Errorf(`cannot have specified duration when lifespan is %q: %q`, lifespan, duration)
+		}
+	case LifespanTimespan:
+		if duration == "" {
+			return expiration, fmt.Errorf(`cannot have unspecified duration when lifespan is %q`, lifespan)
+		}
+		parsedDuration, err := time.ParseDuration(duration)
+		if err != nil {
+			return expiration, fmt.Errorf(`cannot parse duration: %w`, err)
+		}
+		if parsedDuration <= 0 {
+			return expiration, fmt.Errorf(`cannot have zero or negative duration: %q`, duration)
+		}
+		expiration = currTime.Add(parsedDuration)
+	default:
+		// Should not occur, since lifespan is validated when unmarshalled
+		return expiration, fmt.Errorf(`internal error: invalid lifespan: %q`, lifespan)
+	}
+	return expiration, nil
+}

interfaces/prompting/prompting_test.go

@@ -0,0 +1,218 @@
+// -*- Mode: Go; indent-tabs-mode: t -*-
+
+/*
+ * Copyright (C) 2024 Canonical Ltd
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License version 3 as
+ * published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+
+package prompting_test
+
+import (
+	"encoding/json"
+	"fmt"
+	"testing"
+	"time"
+
+	. "gopkg.in/check.v1"
+
+	"github.com/snapcore/snapd/dirs"
+	"github.com/snapcore/snapd/interfaces/prompting"
+)
+
+func Test(t *testing.T) { TestingT(t) }
+
+type promptingSuite struct {
+	tmpdir string
+}
+
+var _ = Suite(&promptingSuite{})
+
+func (s *promptingSuite) SetUpTest(c *C) {
+	s.tmpdir = c.MkDir()
+	dirs.SetRootDir(s.tmpdir)
+}
+
+func (s *promptingSuite) TestOutcomeIsAllow(c *C) {
+	result, err := prompting.OutcomeAllow.IsAllow()
+	c.Check(err, IsNil)
+	c.Check(result, Equals, true)
+	result, err = prompting.OutcomeDeny.IsAllow()
+	c.Check(err, IsNil)
+	c.Check(result, Equals, false)
+	_, err = prompting.OutcomeUnset.IsAllow()
+	c.Check(err, ErrorMatches, `internal error: invalid outcome.*`)
+	_, err = prompting.OutcomeType("foo").IsAllow()
+	c.Check(err, ErrorMatches, `internal error: invalid outcome.*`)
+}
+
+type fakeOutcomeWrapper struct {
+	Field1 prompting.OutcomeType `json:"field1"`
+	Field2 prompting.OutcomeType `json:"field2,omitempty"`
+}
+
+func (s *promptingSuite) TestUnmarshalOutcomeHappy(c *C) {
+	for _, outcome := range []prompting.OutcomeType{
+		prompting.OutcomeAllow,
+		prompting.OutcomeDeny,
+	} {
+		var fow1 fakeOutcomeWrapper
+		data := []byte(fmt.Sprintf(`{"field1": "%s", "field2": "%s"}`, outcome, outcome))
+		err := json.Unmarshal(data, &fow1)
+		c.Check(err, IsNil, Commentf("data: %v", string(data)))
+		c.Check(fow1.Field1, Equals, outcome, Commentf("data: %v", string(data)))
+		c.Check(fow1.Field2, Equals, outcome, Commentf("data: %v", string(data)))
+
+		var fow2 fakeOutcomeWrapper
+		data = []byte(fmt.Sprintf(`{"field1": "%s"}`, outcome))
+		err = json.Unmarshal(data, &fow2)
+		c.Check(err, IsNil, Commentf("data: %v", string(data)))
+		c.Check(fow2.Field1, Equals, outcome, Commentf("data: %v", string(data)))
+		c.Check(fow2.Field2, Equals, prompting.OutcomeUnset, Commentf("data: %v", string(data)))
+	}
+}
+
+func (s *promptingSuite) TestUnmarshalOutcomeUnhappy(c *C) {
+	for _, outcome := range []prompting.OutcomeType{
+		prompting.OutcomeUnset,
+		prompting.OutcomeType("foo"),
+	} {
+		var fow1 fakeOutcomeWrapper
+		data := []byte(fmt.Sprintf(`{"field1": "%s", "field2": "%s"}`, outcome, outcome))
+		err := json.Unmarshal(data, &fow1)
+		c.Check(err, ErrorMatches, `cannot have outcome other than.*`, Commentf("data: %v", string(data)))
+
+		var fow2 fakeOutcomeWrapper
+		data = []byte(fmt.Sprintf(`{"field1": "%s", "field2": "%s"}`, prompting.OutcomeAllow, outcome))
+		err = json.Unmarshal(data, &fow2)
+		c.Check(err, ErrorMatches, `cannot have outcome other than.*`, Commentf("data: %v", string(data)))
+	}
+}
+
+type fakeLifespanWrapper struct {
+	Field1 prompting.LifespanType `json:"field1"`
+	Field2 prompting.LifespanType `json:"field2,omitempty"`
+}
+
+func (s *promptingSuite) TestUnmarshalLifespanHappy(c *C) {
+	for _, lifespan := range []prompting.LifespanType{
+		prompting.LifespanForever,
+		prompting.LifespanSingle,
+		prompting.LifespanTimespan,
+	} {
+		var flw1 fakeLifespanWrapper
+		data := []byte(fmt.Sprintf(`{"field1": "%s", "field2": "%s"}`, lifespan, lifespan))
+		err := json.Unmarshal(data, &flw1)
+		c.Check(err, IsNil, Commentf("data: %v", string(data)))
+		c.Check(flw1.Field1, Equals, lifespan, Commentf("data: %v", string(data)))
+		c.Check(flw1.Field2, Equals, lifespan, Commentf("data: %v", string(data)))
+
+		var flw2 fakeLifespanWrapper
+		data = []byte(fmt.Sprintf(`{"field1": "%s"}`, lifespan))
+		err = json.Unmarshal(data, &flw2)
+		c.Check(err, IsNil, Commentf("data: %v", string(data)))
+		c.Check(flw2.Field1, Equals, lifespan, Commentf("data: %v", string(data)))
+		c.Check(flw2.Field2, Equals, prompting.LifespanUnset, Commentf("data: %v", string(data)))
+	}
+}
+
+func (s *promptingSuite) TestUnmarshalLifespanUnhappy(c *C) {
+	for _, lifespan := range []prompting.LifespanType{
+		prompting.LifespanUnset,
+		prompting.LifespanType("foo"),
+	} {
+		var flw1 fakeLifespanWrapper
+		data := []byte(fmt.Sprintf(`{"field1": "%s", "field2": "%s"}`, lifespan, lifespan))
+		err := json.Unmarshal(data, &flw1)
+		c.Check(err, ErrorMatches, `cannot have lifespan other than.*`, Commentf("data: %v", string(data)))
+
+		var flw2 fakeLifespanWrapper
+		data = []byte(fmt.Sprintf(`{"field1": "%s", "field2": "%s"}`, prompting.LifespanForever, lifespan))
+		err = json.Unmarshal(data, &flw2)
+		c.Check(err, ErrorMatches, `cannot have lifespan other than.*`, Commentf("data: %v", string(data)))
+	}
+}
+
+func (s *promptingSuite) TestValidateExpiration(c *C) {
+	var unsetExpiration time.Time
+	currTime := time.Now()
+	negativeExpiration := currTime.Add(-5 * time.Second)
+	validExpiration := currTime.Add(10 * time.Minute)
+
+	for _, lifespan := range []prompting.LifespanType{
+		prompting.LifespanForever,
+		prompting.LifespanSingle,
+	} {
+		err := lifespan.ValidateExpiration(unsetExpiration, currTime)
+		c.Check(err, IsNil)
+		for _, exp := range []time.Time{negativeExpiration, validExpiration} {
+			err = lifespan.ValidateExpiration(exp, currTime)
+			c.Check(err, ErrorMatches, `cannot have specified expiration when lifespan is.*`)
+		}
+	}
+
+	err := prompting.LifespanTimespan.ValidateExpiration(unsetExpiration, currTime)
+	c.Check(err, ErrorMatches, `cannot have unspecified expiration when lifespan is.*`)
+
+	err = prompting.LifespanTimespan.ValidateExpiration(negativeExpiration, currTime)
+	c.Check(err, ErrorMatches, `cannot have expiration time in the past.*`)
+
+	err = prompting.LifespanTimespan.ValidateExpiration(validExpiration, currTime)
+	c.Check(err, IsNil)
+}
+
+func (s *promptingSuite) TestParseDuration(c *C) {
+	unsetDuration := ""
+	invalidDuration := "foo"
+	negativeDuration := "-5s"
+	validDuration := "10m"
+	parsedValidDuration, err := time.ParseDuration(validDuration)
+	c.Assert(err, IsNil)
+	currTime := time.Now()
+
+	for _, lifespan := range []prompting.LifespanType{
+		prompting.LifespanForever,
+		prompting.LifespanSingle,
+	} {
+		expiration, err := lifespan.ParseDuration(unsetDuration, currTime)
+		c.Check(expiration.IsZero(), Equals, true)
+		c.Check(err, IsNil)
+		for _, dur := range []string{invalidDuration, negativeDuration, validDuration} {
+			expiration, err = lifespan.ParseDuration(dur, currTime)
+			c.Check(expiration.IsZero(), Equals, true)
+			c.Check(err, ErrorMatches, `cannot have specified duration when lifespan is.*`)
+		}
+	}
+
+	expiration, err := prompting.LifespanTimespan.ParseDuration(unsetDuration, currTime)
+	c.Check(expiration.IsZero(), Equals, true)
+	c.Check(err, ErrorMatches, `cannot have unspecified duration when lifespan is.*`)
+
+	expiration, err = prompting.LifespanTimespan.ParseDuration(invalidDuration, currTime)
+	c.Check(expiration.IsZero(), Equals, true)
+	c.Check(err, ErrorMatches, `cannot parse duration.*`)
+
+	expiration, err = prompting.LifespanTimespan.ParseDuration(negativeDuration, currTime)
+	c.Check(expiration.IsZero(), Equals, true)
+	c.Check(err, ErrorMatches, `cannot have zero or negative duration.*`)
+
+	expiration, err = prompting.LifespanTimespan.ParseDuration(validDuration, currTime)
+	c.Check(err, IsNil)
+	c.Check(expiration.After(time.Now()), Equals, true)
+	c.Check(expiration.Before(time.Now().Add(parsedValidDuration)), Equals, true)
+
+	expiration2, err := prompting.LifespanTimespan.ParseDuration(validDuration, currTime)
+	c.Check(err, IsNil)
+	c.Check(expiration2.Equal(expiration), Equals, true)
+}