hide

README

Hide IDs

Hide is a simple package to provide an ID type that is marshaled to/from a hash string. This prevents sending technical IDs to clients and converts them on the API layer. Hide uses hashids as its default hash function. But you can provide your own by implementing the Hash interface and configuring it using hide.UseHash.

Read our full article on Medium.

Installation

go get github.com/emvi/hide/v2

Example

Consider the following struct:

type User struct {
    Id       uint64  `json:"id"`
    Username string `json:"username"`
}

When marshaling this struct to JSON, the ID will be represented by a number:

{
    "id": 123,
    "username": "foobar"
}

In this case, you expose the technical user ID to your clients. By changing the type of the ID, you get a better result:

type User struct {
    Id       hide.ID `json:"id"`
    Username string  `json:"username"`
}

Notice that the uint64 ID got replaced by the hide.ID, which internally is represented as an uint64 as well, but implements the marshal interface. This allows you to cast between them and use hide.ID as a replacement. The resulting JSON changes to the following:

{
  "id": "beJarVNaQM",
  "username": "foobar"
}

If you send the new ID (which is a string now) back to the server and unmarshal it into the hide.ID type, you'll get the original technical ID back. It's also worth mentioning that a value of 0 is translated to null when an ID is marshaled to JSON or stored in a database.

View the full demo

Contribute

See CONTRIBUTING.md

License

MIT

Documentation

Index

• func ToString(id ID) (string, error)
• func UseHash(hasher Hash)
• type Hash
• type HashID
  • func NewHashID(salt string, minlen int) *HashID
  • func (hasher *HashID) Decode(data []byte) (ID, error)
  • func (hasher *HashID) Encode(id ID) ([]byte, error)
• type ID
  • func FromString(id string) (ID, error)
  • func (hideid ID) MarshalJSON() ([]byte, error)
  • func (hideid *ID) Scan(value interface{}) error
  • func (hideid *ID) UnmarshalJSON(data []byte) error
  • func (hideid ID) Value() (driver.Value, error)

Functions

func ToString

func ToString(id ID) (string, error)

ToString returns a new hash from given ID by using the hasher or an error if it couldn't encode the ID. If ID is 0, "null" will be returned.

func UseHash

func UseHash(hasher Hash)

UseHash sets the hide.Hash used to marshal/unmarshal hide.ID to/from JSON. hide.HashID is used by default.

Types

type Hash

type Hash interface {
	Encode(ID) ([]byte, error)
	Decode([]byte) (ID, error)
}

Hash is used to marshal/unmarshal hide.ID to/from JSON.

type HashID

type HashID struct {
	Salt      string
	MinLength int
}

HashID implements the hide.Hash interface and uses github.com/speps/go-hashids to encode and decode hashes.

func NewHashID

func NewHashID(salt string, minlen int) *HashID

NewHashID creates a new HashID with given salt and minimum hash length.

func (*HashID) Decode

func (hasher *HashID) Decode(data []byte) (ID, error)

Decode implements the hide.Hash interface.

func (*HashID) Encode

func (hasher *HashID) Encode(id ID) ([]byte, error)

Encode implements the hide.Hash interface.

type ID

type ID uint64

ID type that can be used as an replacement for uint64. It is converted to/from a hash value when marshalled to/from JSON. Value 0 is considered null.

func FromString

func FromString(id string) (ID, error)

FromString returns a new ID from given hash by using the hasher or an error if it couldn't decode the hash.

func (ID) MarshalJSON

func (hideid ID) MarshalJSON() ([]byte, error)

MarshalJSON implements the encoding json interface.

func (*ID) Scan

func (hideid *ID) Scan(value interface{}) error

Scan implements the Scanner interface.

func (*ID) UnmarshalJSON

func (hideid *ID) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the encoding json interface.

func (ID) Value

func (hideid ID) Value() (driver.Value, error)

Value implements the driver Valuer interface.