Skip to content

feat: allow human-readable IDs #57

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jason-lynch merged 1 commit into from
Jun 17, 2025
Merged

feat: allow human-readable IDs #57

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 34 additions & 24 deletions api/v1/design/api.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -146,9 +146,10 @@ var _ = g.Service("control-plane", func() {
g.Description("Returns information about a particular host in the cluster.")
g.Meta("openapi:summary", "Get host")
g.Payload(func() {
g.Attribute("host_id", g.String, func() {
g.Attribute("host_id", Identifier, func() {
g.Description("ID of the host to get.")
g.Format(g.FormatUUID)
g.Example("host-1")
g.Example("us-east-1")
g.Example("de3b1388-1f0c-42f1-a86c-59ab72f255ec")
})

Expand All @@ -170,9 +171,10 @@ var _ = g.Service("control-plane", func() {
g.Description("Removes a host from the cluster.")
g.Meta("openapi:summary", "Remove host")
g.Payload(func() {
g.Attribute("host_id", g.String, func() {
g.Attribute("host_id", Identifier, func() {
g.Description("ID of the host to remove.")
g.Format(g.FormatUUID)
g.Example("host-1")
g.Example("us-east-1")
g.Example("de3b1388-1f0c-42f1-a86c-59ab72f255ec")
})

Expand Down Expand Up @@ -226,9 +228,10 @@ var _ = g.Service("control-plane", func() {
g.Description("Returns information about a particular database in the cluster.")
g.Meta("openapi:summary", "Get database")
g.Payload(func() {
g.Attribute("database_id", g.String, func() {
g.Attribute("database_id", Identifier, func() {
g.Description("ID of the database to get.")
g.Format(g.FormatUUID)
g.Example("production")
g.Example("my-app")
g.Example("02f1a7db-fca8-4521-b57a-2a375c1ced51")
})

Expand All @@ -252,9 +255,10 @@ var _ = g.Service("control-plane", func() {
g.Description("Updates a database with the given specification.")
g.Meta("openapi:summary", "Update database")
g.Payload(func() {
g.Attribute("database_id", g.String, func() {
g.Attribute("database_id", Identifier, func() {
g.Description("ID of the database to update.")
g.Format(g.FormatUUID)
g.Example("production")
g.Example("my-app")
g.Example("02f1a7db-fca8-4521-b57a-2a375c1ced51")
})
g.Attribute("force_update", g.Boolean, func() {
Expand Down Expand Up @@ -286,9 +290,10 @@ var _ = g.Service("control-plane", func() {
g.Description("Deletes a database from the cluster.")
g.Meta("openapi:summary", "Delete database")
g.Payload(func() {
g.Attribute("database_id", g.String, func() {
g.Format(g.FormatUUID)
g.Attribute("database_id", Identifier, func() {
g.Description("ID of the database to delete.")
g.Example("production")
g.Example("my-app")
g.Example("02f1a7db-fca8-4521-b57a-2a375c1ced51")
})

Expand All @@ -312,9 +317,10 @@ var _ = g.Service("control-plane", func() {
g.Description("Initiates a backup for a database node.")
g.Meta("openapi:summary", "Backup database node")
g.Payload(func() {
g.Attribute("database_id", g.String, func() {
g.Format(g.FormatUUID)
g.Attribute("database_id", Identifier, func() {
g.Description("ID of the database to back up.")
g.Example("production")
g.Example("my-app")
g.Example("02f1a7db-fca8-4521-b57a-2a375c1ced51")
})
g.Attribute("node_name", g.String, func() {
Expand Down Expand Up @@ -345,14 +351,15 @@ var _ = g.Service("control-plane", func() {
g.Description("Lists all tasks for a database.")
g.Meta("openapi:summary", "List database tasks")
g.Payload(func() {
g.Attribute("database_id", g.String, func() {
g.Format(g.FormatUUID)
g.Attribute("database_id", Identifier, func() {
g.Description("ID of the database to list tasks for.")
g.Example("production")
g.Example("my-app")
g.Example("02f1a7db-fca8-4521-b57a-2a375c1ced51")
})
g.Attribute("after_task_id", g.String, func() {
g.Format(g.FormatUUID)
g.Description("ID of the task to start from.")
g.Format(g.FormatUUID)
g.Example("3c875a27-f6a6-4c1c-ba5f-6972fb1fc348")
})
g.Attribute("limit", g.Int, func() {
Expand Down Expand Up @@ -386,14 +393,15 @@ var _ = g.Service("control-plane", func() {
g.Description("Returns information about a particular task.")
g.Meta("openapi:summary", "Get database task")
g.Payload(func() {
g.Attribute("database_id", g.String, func() {
g.Format(g.FormatUUID)
g.Attribute("database_id", Identifier, func() {
g.Description("ID of the database the task belongs to.")
g.Example("production")
g.Example("my-app")
g.Example("02f1a7db-fca8-4521-b57a-2a375c1ced51")
})
g.Attribute("task_id", g.String, func() {
g.Format(g.FormatUUID)
g.Description("ID of the task to get.")
g.Format(g.FormatUUID)
g.Example("3c875a27-f6a6-4c1c-ba5f-6972fb1fc348")
})

Expand All @@ -415,19 +423,20 @@ var _ = g.Service("control-plane", func() {
g.Description("Returns the log of a particular task for a database.")
g.Meta("openapi:summary", "Get database task log")
g.Payload(func() {
g.Attribute("database_id", g.String, func() {
g.Format(g.FormatUUID)
g.Attribute("database_id", Identifier, func() {
g.Description("ID of the database to get task log for.")
g.Example("production")
g.Example("my-app")
g.Example("02f1a7db-fca8-4521-b57a-2a375c1ced51")
})
g.Attribute("task_id", g.String, func() {
g.Format(g.FormatUUID)
g.Description("ID of the task to get log for.")
g.Format(g.FormatUUID)
g.Example("3c875a27-f6a6-4c1c-ba5f-6972fb1fc348")
})
g.Attribute("after_entry_id", g.String, func() {
g.Format(g.FormatUUID)
g.Description("ID of the entry to start from.")
g.Format(g.FormatUUID)
g.Example("3c875a27-f6a6-4c1c-ba5f-6972fb1fc348")
})
g.Attribute("limit", g.Int, func() {
Expand Down Expand Up @@ -455,9 +464,10 @@ var _ = g.Service("control-plane", func() {
g.Description("Perform an in-place restore one or more nodes using the given restore configuration.")
g.Meta("openapi:summary", "Restore database")
g.Payload(func() {
g.Attribute("database_id", g.String, func() {
g.Format(g.FormatUUID)
g.Attribute("database_id", Identifier, func() {
g.Description("ID of the database to restore.")
g.Example("production")
g.Example("my-app")
g.Example("02f1a7db-fca8-4521-b57a-2a375c1ced51")
})
g.Attribute("request", RestoreDatabaseRequest)
Expand Down
18 changes: 10 additions & 8 deletions api/v1/design/cluster.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,14 +14,14 @@ var ClusterStatus = g.Type("ClusterStatus", func() {
})

var Cluster = g.Type("Cluster", func() {
g.Attribute("id", g.String, func() {
g.Format(g.FormatUUID)
g.Attribute("id", Identifier, func() {
g.Description("Unique identifier for the cluster.")
g.Example("production")
g.Example("a67cbb36-c3c3-49c9-8aac-f4a0438a883d")
})
g.Attribute("tenant_id", g.String, func() {
g.Format(g.FormatUUID)
g.Attribute("tenant_id", Identifier, func() {
g.Description("Unique identifier for the cluster's owner.")
g.Example("engineering")
g.Example("8210ec10-2dca-406c-ac4a-0661d2189954")
})
g.Attribute("status", ClusterStatus, func() {
Expand Down Expand Up @@ -54,9 +54,10 @@ var ClusterJoinRequest = g.Type("ClusterJoinRequest", func() {
g.Pattern(`^PGEDGE-[\w]{64}-[\w]{32}$`)
g.Example("PGEDGE-dd440afcf5de20ef8e8cf54f6cb9f125fd55f90e64faa94b906130b31235e730-41e975f41d7ea61058f2fe2572cb52dd")
})
g.Attribute("host_id", g.String, func() {
g.Format(g.FormatUUID)
g.Attribute("host_id", Identifier, func() {
g.Description("The unique identifier for the host that's joining the cluster.")
g.Example("host-1")
g.Example("us-east-1")
g.Example("de3b1388-1f0c-42f1-a86c-59ab72f255ec")
})
g.Attribute("hostname", g.String, func() {
Expand All @@ -76,8 +77,9 @@ var ClusterJoinRequest = g.Type("ClusterJoinRequest", func() {

var ClusterPeer = g.Type("ClusterPeer", func() {
g.Attribute("name", g.String, func() {
g.Format(g.FormatUUID)
g.Description("The name of the cluster member.")
g.Description("The name of the Etcd cluster member.")
g.Example("host-1")
g.Example("us-east-1")
g.Example("de3b1388-1f0c-42f1-a86c-59ab72f255ec")
})
g.Attribute("peer_url", g.String, func() {
Expand Down
21 changes: 21 additions & 0 deletions api/v1/design/common.go
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
package design

import (
g "goa.design/goa/v3/dsl"
)

// Allows IDs that are:
// - 1-63 characters
// - Contain only lower-cased letters and hyphens
// - Starts with a letter or number
// - Ends with a letter or number
// The handlers must also validate that there are no consecutive hyphens.
const idPattern = `^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$`

var Identifier = g.Type("Identifier", g.String, func() {
g.Description("A user-specified identifier. Must be 1-63 characters, contain only lower-cased letters and hyphens, start and end with a letter or number, and not contain consecutive hyphens.")
g.Pattern(idPattern)
g.Example("production")
g.Example("my-app")
g.Example("76f9b8c0-4958-11f0-a489-3bb29577c696")
})
44 changes: 23 additions & 21 deletions api/v1/design/database.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,9 @@ const (
cpuPattern = `^[0-9]+(\.[0-9]{1,3}|m)?$`
)

var HostIDs = g.ArrayOf(g.String, func() {
g.Format(g.FormatUUID)
var HostIDs = g.ArrayOf(Identifier, func() {
g.Example("host-1")
g.Example("us-east-1")
g.Example("de3b1388-1f0c-42f1-a86c-59ab72f255ec")
})

Expand Down Expand Up @@ -104,10 +105,9 @@ var DatabaseUserSpec = g.Type("DatabaseUserSpec", func() {
})

var BackupRepositorySpec = g.Type("BackupRepositorySpec", func() {
g.Attribute("id", g.String, func() {
g.Attribute("id", Identifier, func() {
g.Description("The unique identifier of this repository.")
g.MinLength(1)
g.MaxLength(64)
g.Example("my-app-1")
g.Example("f6b84a99-5e91-4203-be1e-131fe82e5984")
})
g.Attribute("type", g.String, func() {
Expand Down Expand Up @@ -246,10 +246,9 @@ var BackupConfigSpec = g.Type("BackupConfigSpec", func() {
})

var RestoreRepositorySpec = g.Type("RestoreRepositorySpec", func() {
g.Attribute("id", g.String, func() {
g.Attribute("id", Identifier, func() {
g.Description("The unique identifier of this repository.")
g.MinLength(1)
g.MaxLength(64)
g.Example("my-app-1")
g.Example("f6b84a99-5e91-4203-be1e-131fe82e5984")
})
g.Attribute("type", g.String, func() {
Expand Down Expand Up @@ -342,10 +341,11 @@ var RestoreRepositorySpec = g.Type("RestoreRepositorySpec", func() {
})

var RestoreConfigSpec = g.Type("RestoreConfigSpec", func() {
g.Attribute("source_database_id", g.String, func() {
g.Attribute("source_database_id", Identifier, func() {
g.Description("The ID of the database to restore this database from.")
g.Format(g.FormatUUID)
g.Example("6c8e43ee-26ea-47b8-a8f8-89897e0137bd")
g.Example("production")
g.Example("my-app")
g.Example("02f1a7db-fca8-4521-b57a-2a375c1ced51")
})
g.Attribute("source_node_name", g.String, func() {
g.Description("The name of the node to restore this database from.")
Expand Down Expand Up @@ -450,14 +450,15 @@ var DatabaseSpec = g.Type("DatabaseSpec", func() {

var Database = g.ResultType("Database", func() {
g.Attributes(func() {
g.Attribute("id", g.String, func() {
g.Format(g.FormatUUID)
g.Attribute("id", Identifier, func() {
g.Description("Unique identifier for the database.")
g.Example("production")
g.Example("my-app")
g.Example("02f1a7db-fca8-4521-b57a-2a375c1ced51")
})
g.Attribute("tenant_id", g.String, func() {
g.Format(g.FormatUUID)
g.Attribute("tenant_id", Identifier, func() {
g.Description("Unique identifier for the databases's owner.")
g.Example("engineering")
g.Example("8210ec10-2dca-406c-ac4a-0661d2189954")
})
g.Attribute("created_at", g.String, func() {
Expand Down Expand Up @@ -516,14 +517,15 @@ var Database = g.ResultType("Database", func() {
})

var CreateDatabaseRequest = g.Type("CreateDatabaseRequest", func() {
g.Attribute("id", g.String, func() {
g.Format(g.FormatUUID)
g.Attribute("id", Identifier, func() {
g.Description("Unique identifier for the database.")
g.Example("production")
g.Example("my-app")
g.Example("02f1a7db-fca8-4521-b57a-2a375c1ced51")
})
g.Attribute("tenant_id", g.String, func() {
g.Format(g.FormatUUID)
g.Attribute("tenant_id", Identifier, func() {
g.Description("Unique identifier for the databases's owner.")
g.Example("engineering")
g.Example("8210ec10-2dca-406c-ac4a-0661d2189954")
})
g.Attribute("spec", DatabaseSpec, func() {
Expand All @@ -545,9 +547,9 @@ var CreateDatabaseResponse = g.Type("CreateDatabaseResponse", func() {
})

var UpdateDatabaseRequest = g.Type("UpdateDatabaseRequest", func() {
g.Attribute("tenant_id", g.String, func() {
g.Format(g.FormatUUID)
g.Attribute("tenant_id", Identifier, func() {
g.Description("Unique identifier for the databases's owner.")
g.Example("engineering")
g.Example("8210ec10-2dca-406c-ac4a-0661d2189954")
})
g.Attribute("spec", DatabaseSpec, func() {
Expand Down
5 changes: 3 additions & 2 deletions api/v1/design/host.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,9 +75,10 @@ var HostCohort = g.Type("HostCohort", func() {
})

var Host = g.Type("Host", func() {
g.Attribute("id", g.String, func() {
g.Format(g.FormatUUID)
g.Attribute("id", Identifier, func() {
g.Description("Unique identifier for the host.")
g.Example("host-1")
g.Example("us-east-1")
g.Example("de3b1388-1f0c-42f1-a86c-59ab72f255ec")
})
g.Attribute("orchestrator", g.String, func() {
Expand Down
2 changes: 0 additions & 2 deletions api/v1/design/instance.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -96,12 +96,10 @@ var Instance = g.ResultType("Instance", func() {
g.Description("An instance of pgEdge Postgres running on a host.")
g.Attributes(func() {
g.Attribute("id", g.String, func() {
g.Format(g.FormatUUID)
g.Description("Unique identifier for the instance.")
g.Example("a67cbb36-c3c3-49c9-8aac-f4a0438a883d")
})
g.Attribute("host_id", g.String, func() {
g.Format(g.FormatUUID)
g.Description("The ID of the host this instance is running on.")
g.Example("de3b1388-1f0c-42f1-a86c-59ab72f255ec")
})
Expand Down
6 changes: 0 additions & 6 deletions api/v1/design/task.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,6 @@ var Task = g.Type("Task", func() {
g.Example("439eb515-e700-4740-b508-4a3f12ec4f83")
})
g.Attribute("database_id", g.String, func() {
g.Format(g.FormatUUID)
g.Description("The database ID of the task.")
g.Example("02f1a7db-fca8-4521-b57a-2a375c1ced51")
})
Expand All @@ -20,12 +19,10 @@ var Task = g.Type("Task", func() {
g.Example("n1")
})
g.Attribute("instance_id", g.String, func() {
g.Format(g.FormatUUID)
g.Description("The ID of the instance that the task is operating on.")
g.Example("3c875a27-f6a6-4c1c-ba5f-6972fb1fc348")
})
g.Attribute("host_id", g.String, func() {
g.Format(g.FormatUUID)
g.Description("The ID of the host that the task is running on.")
g.Example("2e52dcde-86d8-4f71-b58e-8dc3a10c936a")
})
Expand Down Expand Up @@ -83,12 +80,10 @@ var TaskLogEntry = g.Type("TaskLogEntry", func() {

var TaskLog = g.Type("TaskLog", func() {
g.Attribute("database_id", g.String, func() {
g.Format(g.FormatUUID)
g.Description("The database ID of the task log.")
g.Example("02f1a7db-fca8-4521-b57a-2a375c1ced51")
})
g.Attribute("task_id", g.String, func() {
g.Format(g.FormatUUID)
g.Description("The unique ID of the task log.")
g.Example("3c875a27-f6a6-4c1c-ba5f-6972fb1fc348")
})
Expand All @@ -98,7 +93,6 @@ var TaskLog = g.Type("TaskLog", func() {
g.Example("pending")
})
g.Attribute("last_entry_id", g.String, func() {
g.Format(g.FormatUUID)
g.Description("The ID of the last entry in the task log.")
g.Example("3c875a27-f6a6-4c1c-ba5f-6972fb1fc348")
})
Expand Down
Loading