Merge pull request juju#17562 from tlm/juju-5342-key-updater

juju#17562

This commit introduces a new type in the core package for representing machine id's. At the moment we seem to be using a combination of strings and uuid.

This follows a similar convention set up in other package to have a stronger type that conveys meaning to the user and gives an easy validation point for the domain layer.

My specific use case for introducing this is for a id type for the key updater so authorised keys can be fetched for a machine. At the moment this logic is ran off of tags but only applicable to machines. As part of this work I would like to change the story from keys for this entity to keys for this machine id.

## Checklist

- [x] Code style: imports ordered, good names, simple structure, etc
- [x] Comments saying why design decisions were made
- [x] Go unit tests, with comments saying what you're testing
- ~[ ] [Integration tests](https://github.com/juju/juju/tree/main/tests), with comments saying what you're testing~
- [x] [doc.go](https://discourse.charmhub.io/t/readme-in-packages/451) added or updated in changed packages

## QA steps

No use's of this yet. There are unit tests to assert logic. This PR is to introduce the idea before going further.

## Documentation changes

N/A

## Links

**Jira card:** JUJU-5342

core/machine/doc.go

@@ -0,0 +1,6 @@
+// Copyright 2024 Canonical Ltd.
+// Licensed under the AGPLv3, see LICENCE file for details.
+
+// Package machine provide core common types that all of Juju can use to reason
+// about machines in a model.
+package machine

core/machine/machine.go

@@ -0,0 +1,42 @@
+// Copyright 2024 Canonical Ltd.
+// Licensed under the AGPLv3, see LICENCE file for details.
+
+package machine
+
+import (
+	"fmt"
+
+	"github.com/juju/errors"
+
+	"github.com/juju/juju/internal/uuid"
+)
+
+// ID is a unique identifier for a machine.
+type ID string
+
+// NewId makes and returns a new machine [ID].
+func NewId() (ID, error) {
+	uuid, err := uuid.NewUUID()
+	if err != nil {
+		return "", fmt.Errorf("generating new machine id: %w", err)
+	}
+
+	return ID(uuid.String()), nil
+}
+
+// Validate returns an error if the [ID] is invalid. The error returned
+// satisfies [errors.NotValid].
+func (i ID) Validate() error {
+	if i == "" {
+		return fmt.Errorf("empty machine id%w", errors.Hide(errors.NotValid))
+	}
+	if !uuid.IsValidUUIDString(string(i)) {
+		return fmt.Errorf("invalid machine id: %q%w", i, errors.Hide(errors.NotValid))
+	}
+	return nil
+}
+
+// String returns the [ID] as a string.
+func (i ID) String() string {
+	return string(i)
+}

core/machine/machine_test.go

@@ -0,0 +1,50 @@
+// Copyright 2024 Canonical Ltd.
+// Licensed under the AGPLv3, see LICENCE file for details.
+
+package machine
+
+import (
+	"github.com/juju/errors"
+	jc "github.com/juju/testing/checkers"
+	gc "gopkg.in/check.v1"
+
+	"github.com/juju/juju/internal/uuid"
+)
+
+type machineSuite struct {
+}
+
+var _ = gc.Suite(&machineSuite{})
+
+// TestIdValidate is testing several good and not so good machine id's to check
+// that the validate method produces the correct result.
+func (*machineSuite) TestIdValidate(c *gc.C) {
+	tests := []struct {
+		id  string
+		err error
+	}{
+		{
+			id:  "",
+			err: errors.NotValid,
+		},
+		{
+			id:  "invalid",
+			err: errors.NotValid,
+		},
+		{
+			id: uuid.MustNewUUID().String(),
+		},
+	}
+
+	for i, test := range tests {
+		c.Logf("test %d: %q", i, test.id)
+		err := ID(test.id).Validate()
+
+		if test.err == nil {
+			c.Check(err, gc.IsNil)
+			continue
+		}
+
+		c.Check(err, jc.ErrorIs, test.err)
+	}
+}

core/machine/package_test.go

@@ -0,0 +1,14 @@
+// Copyright 2024 Canonical Ltd.
+// Licensed under the AGPLv3, see LICENCE file for details.
+
+package machine
+
+import (
+	"testing"
+
+	gc "gopkg.in/check.v1"
+)
+
+func TestPackage(t *testing.T) {
+	gc.TestingT(t)
+}