gorandoaws

README

gorandoaws

A Golang package for generating random (and hopefully unique) identifiers in Amazon Web Services.

The "Format" struct

The package exposes a collection of functions which return instances of the Format struct:

• DBInstanceIdentifier
• SecretClientRequestToken
• SecretName

The Format struct exposes the following functions:

• New() (string, error) generates and returns a randomly-generated value.
• NewWithOptions(NewOptions) (string, error) generates and returns a randomly-generated value with special options.
• IsValid(string) (bool, string) checks if the specified string is valid, and returns a validity flag along with a descriptive reason why (and if) the value is invalid.

The "Options" struct

New() will generate values with default options. To set special options, call NewWithOptions() and pass in an Options struct with one or more of these values set:

• Length describes the length of the value to generate.
• Prefix describes the left-wise prefix of the string to be generated.

DBInstanceIdentifier

DBInstanceIdentifier enables the creation and validation of RDS instance identifiers.

package main

import (
    "fmt"
    "github.com/cariad/gorandoaws"
)

func main() {
    id := gorandoaws.DBInstanceIdentifier()

    new, _ := id.New()
    fmt.Println(new)
    // r7h3-xungaxgyxsjlqbt-fvrnq39-rzz6w9ax5g-5805hzx42365azmor1yu5ol

    prefixed, _ := id.NewWithOptions(gorandoaws.NewOptions{Prefix: "myprefix-"})
    fmt.Println(prefixed)
    // myprefix-sidrh-21u8k1mg-zemii2zmg34mqxo5ra69rhtpw-2l7fibgegoejv

    valid, reason := id.IsValid("oopsahyphen-")
    fmt.Printf("%v, %s\n", valid, reason)
    // false, cannot end with "-"}

SecretClientRequestToken

SecretClientRequestToken enables the creation and validation of client request tokens for Secrets.

package main

import (
    "fmt"
    "github.com/cariad/gorandoaws"
)

func main() {
    token := gorandoaws.SecretClientRequestToken()

    new, _ := token.New()
    fmt.Println(new)
    // -fsAiOvJrx0ZAjBwfaqrGvbdkpOItBoB3Vxw5H0Zs1-YeakX9b-hg15TzTokf5ZK

    prefixed, _ := token.NewWithOptions(gorandoaws.NewOptions{Prefix: "myprefix-"})
    fmt.Println(prefixed)
    // myprefix-5-C1lUGkPmUWAxmnmsh0vXPJvRrDlPaHKQr1J92xJzij1-rWMDHweU4

    valid, reason := token.IsValid("asmalltokenimademyself")
    fmt.Printf("%v, %s\n", valid, reason)
    // false, length (22) must be between 32 and 64
}

SecretName

SecretName enables the creation and validation of Secret names.

package main

import (
    "fmt"
    "github.com/cariad/gorandoaws"
)

func main() {
    name := gorandoaws.SecretName()

    new, _ := name.New()
    fmt.Println(new)
    // 9fKqI2ysQxz8FCFg5NNJmbByWqvpX_YFlij0xJu512ri=gCY+52wnbdHBIIcmY6tptwaDhglC7cVG+r66r@5q4nK+K0rJTEvHggPfwQ0bZsdQLPlPiSPxZ42BgFzAbs9-liaADgtVqw9v4StxQA6sYA-B.Zmx3fKyklXP5XJXP5.9fv=bXAmXNfSupLB.UCVBTH4ohFbgdim+7bH9RBxKkkMWisVX6b3DjQY=uXm4KgxYBocHL=iRykV@tgLpZvN

    prefixed, _ := name.NewWithOptions(gorandoaws.NewOptions{Prefix: "myprefix-"})
    fmt.Println(prefixed)
    // myprefix-Q57kw53CnyRZoDE=8_+I3VFrDhV1v1MjsAWB=MFOqkX==1.UUgUAlSaIvtcdCBPm9QuG3XbY3v7npnlmgdsBurrXcOsyjyzujIRhUVq9w.h+9o8iPPduPmvmFWYrGAc4r3B6B=iYQ.WpnI006tWs7CbWzDtj4oEgrmuFn8QMJ5e-+ERC69WI6-C.iYJBmteng0dtN70Setdp0-1jwcwY3Bxp82rlFYizEjD6UtuxJNv2UljKHjY=Hft

    valid, reason := name.IsValid("oopsahyphenatedsixcharactersuffix-000000")
    fmt.Printf("%v, %s\n", valid, reason)
    // false, must not end with a hyphen followed by six characters
}

A note on uniqueness

The uniqueness of identifiers cannot be guaranteed. This package does not interact with AWS to verify identifiers.

To minimise the risk of clashing identifiers, the package creates very long identifiers wirh diverse pools. This minimises the risk of clashes, but does not remove it.

Acknowledgements

This project uses the following packages:

• github.com/cariad/gorando to generate random strings.
• github.com/cariad/gostringsplus to manipulate strings.

Licence, credit & sponsorship

This project is published under the MIT Licence.

You don't owe me anything in return, but as an indie freelance coder there are two things I'd appreciate:

• Credit. If your app or documentation has a credits page, please consider mentioning the projects you use.
• Cash. If you want and are able to support future development, please consider becoming a patron or buying me a coffee. Thank you!

Documentation

Index

• type Format
  • func DBInstanceIdentifier() Format
  • func SecretClientRequestToken() Format
  • func SecretName() Format
  • func (f Format) IsValid(value string) (bool, string)
  • func (f Format) New() (string, error)
  • func (f Format) NewWithOptions(no NewOptions) (string, error)
• type Length
  • func (l Length) IsValid(value string) (bool, string)
• type NewOptions
• type Rule
  • func MustNotContainTwoConsecutiveHyphens() Rule
  • func MustNotEndWithHyphenThenSixCharacters() Rule
  • func (r Rule) IsValid(value string) (bool, string)
• type Rules
  • func (r Rules) AreValid(value string) (bool, string)

Types

type Format

type Format struct {
	FirstCharPool   string
	MiddleCharsPool string
	FinalCharPool   string
	Length          Length
	Rules           Rules
}

Format describes the format of a value.

func DBInstanceIdentifier

func DBInstanceIdentifier() Format

DBInstanceIdentifier gets the format of an RDS instance identifier.

func SecretClientRequestToken

func SecretClientRequestToken() Format

SecretClientRequestToken gets the format of a Secret Client Request Token.

func SecretName

func SecretName() Format

SecretName gets the format of a Secret name.

func (Format) IsValid

func (f Format) IsValid(value string) (bool, string)

IsValid checks if a value is valid for a given format, then returns a validity flag and a descriptive message if it is not.

func (Format) New

func (f Format) New() (string, error)

New returns a new randomly-generated value.

func (Format) NewWithOptions

func (f Format) NewWithOptions(no NewOptions) (string, error)

NewWithOptions returns a new randomly-generated value with specific options.

type Length

type Length struct {
	Min int
	Max int
}

Length describes the length requirements of a value.

func (Length) IsValid

func (l Length) IsValid(value string) (bool, string)

IsValid checks if a value is within a length boundary and returns a validity flag and reason message if not.

type NewOptions

type NewOptions struct {
	// Length describes the requested length of the new value.
	Length int

	// Prefix describes the requested prefix of the new value.
	Prefix string
}

NewOptions describes a special request for a new value.

type Rule

type Rule struct {
	Expression string
	Message    string
}

Rule describes a regular expression which would cause a value's validation to fail.

func MustNotContainTwoConsecutiveHyphens

func MustNotContainTwoConsecutiveHyphens() Rule

MustNotContainTwoConsecutiveHyphens describes a rule which disallows values which contain two consecutive hyphens.

func MustNotEndWithHyphenThenSixCharacters

func MustNotEndWithHyphenThenSixCharacters() Rule

MustNotEndWithHyphenThenSixCharacters describes a rule which disallows values which end with a hyphen followed by six characters.

func (Rule) IsValid

func (r Rule) IsValid(value string) (bool, string)

IsValid checks if a value matches the given rule, and fails with a reason if it does.

type Rules

type Rules struct {
	Rules []Rule
}

Rules describes a collection of regular expressions which would cause a value's validation to fail.

func (Rules) AreValid

func (r Rules) AreValid(value string) (bool, string)

AreValid checks if a value matches any rules and fails with a reason if it does.