gidx

Documentation

Overview

Package gidx creates and parses Infratographer-based Global IDs. These IDs are in the format of <resource type prefix>-<resource id> and are provided by the PrefixedID type. The IDs are intended to follow the Relay Global Object Identification Specification (https://relay.dev/graphql/objectidentification.htm), ensuring global uniqueness and the ability to resolve object types with only their IDs. The 7 character prefix includes the application and object type, allowing for easy identification of object types from the ID.

Prefixed IDs use a 7 character prefix, with the first 4 characters representing the application and the next 3 characters representing the object type. This allows for easy identification of the object type from the ID. For example, the instance-api application might use the 4 character prefix inst and have an object type of instance. The 3 character code for instance might be anc, resulting in a prefix of instanc. An instance ID might then look like instanc-myrandomidvalue.

Index

• Constants
• Variables
• type ErrInvalidID
  • func (e *ErrInvalidID) Error() string
• type PrefixedID
  • func MustNewID(prefix string) PrefixedID
  • func NewID(prefix string) (PrefixedID, error)
  • func Parse(str string) (PrefixedID, error)
  • func (p PrefixedID) MarshalGQL(w io.Writer)
  • func (p PrefixedID) Prefix() string
  • func (p *PrefixedID) Scan(v any) error
  • func (p *PrefixedID) UnmarshalGQL(v interface{}) error
  • func (p PrefixedID) Value() (driver.Value, error)

Constants

const (
	// PrefixPartLength is the number of characters expected in a prefix
	PrefixPartLength = 7
	// IDPartLength is the number of characters passed to nanoid when generating an ID value
	IDPartLength = 21
	// Parts represents how many parts of an ID there are
	Parts = 2
	// TotalLength is the length of a idx generated PrefixID
	TotalLength = PrefixPartLength + IDPartLength + Parts - 1
)

Variables

var (
	// ErrNilValue is returned when a nil value is provided
	ErrNilValue = errors.New("no value provided")

	// ErrUnsupportedType is returned when a value is provided of an unsupported type
	ErrUnsupportedType = errors.New("unsupported type")
)

Types

type ErrInvalidID

type ErrInvalidID struct {
	// contains filtered or unexported fields
}

ErrInvalidID is returned when a provided ID value is invalid

func (*ErrInvalidID) Error

func (e *ErrInvalidID) Error() string

type PrefixedID

type PrefixedID string

PrefixedID represents an ID that is formatted as prefix-id. PrefixedIDs are used to implement the relay spec for graphql, which required all IDs to be globally unique between objects and that you have the ability to resolve an object with only the id. Prefixed IDs make it possible by using a 7 characters long prefix with the first 4 characters representing the application the ID belongs to and the next 3 characters representing the object. This makes it possible to receive an ID and programatically tell you the object type the ID represents.

Examples scenario: instance-api uses the 4 character prefix of inst and has an object type of instance. The 3 character code for instance is anc, so combined the prefix is instanc, resulting an in instance having an id that looks like instanc-myrandomidvalue.

func MustNewID

func MustNewID(prefix string) PrefixedID

MustNewID wraps NewID and panics in the event of an error

func NewID

func NewID(prefix string) (PrefixedID, error)

NewID will return a new PrefixedID with the given prefix and a generated ID value. The ID value will be a 21 character nanoID value.

func Parse

func Parse(str string) (PrefixedID, error)

Parse reads in a string and returns a PrefixedID if the string is a properly formatted PrefixedID value

func (PrefixedID) MarshalGQL

func (p PrefixedID) MarshalGQL(w io.Writer)

MarshalGQL provides GraphQL marshaling so that PrefixedIDs can be returned in GraphQL results transparently. Only types that map to a string are supported.

func (PrefixedID) Prefix

func (p PrefixedID) Prefix() string

Prefix will return the Prefix value of an ID

func (*PrefixedID) Scan

func (p *PrefixedID) Scan(v any) error

Scan implements sql.Scanner so PrefixedIDs can be read from databases transparently. The value returned is not checked to ensure it's a properly formatted PrefixedID.

func (*PrefixedID) UnmarshalGQL

func (p *PrefixedID) UnmarshalGQL(v interface{}) error

UnmarshalGQL provides GraphQL unmarshaling so that PrefixedIDs can be parsed in GraphQL requests transparently. Only input types that map to a string are supported.

func (PrefixedID) Value

func (p PrefixedID) Value() (driver.Value, error)

Value implements sql.Valuer so that PrefixedIDs can be written to databases transparently. PrefixedIDs map to strings.