Core Types - Cowrie

Overview

Cowrie Gen2 supports 9 core types that extend JSON with explicit numeric types and native binary data.

Type Constants

Type Tags (Wire Format)

const (
    TagNull       = 0x00
    TagFalse      = 0x01
    TagTrue       = 0x02
    TagInt64      = 0x03
    TagFloat64    = 0x04
    TagString     = 0x05
    TagArray      = 0x06
    TagObject     = 0x07
    TagBytes      = 0x08
    TagUint64     = 0x09
)

Type Enum

type Type uint8

const (
    TypeNull Type = iota
    TypeBool
    TypeInt64
    TypeUint64
    TypeFloat64
    TypeString
    TypeBytes
    TypeArray
    TypeObject
)

Type tags (wire format) differ from Type enum (API). For example, TagArray = 0x06 but TypeArray = 7.

Value Type

Value Struct

type Value struct {
    // Private fields
}

Represents an immutable Cowrie value of any type. Use constructors to create values.

Type Methods

Type

func (v *Value) Type() Type

Returns the type of this value. Example:

val := cowrie.Int64(42)
if val.Type() == cowrie.TypeInt64 {
    fmt.Println("Integer:", val.Int64())
}

IsNull

func (v *Value) IsNull() bool

Returns true if this value is null. Example:

if val.IsNull() {
    fmt.Println("Value is null")
}

Null

Constructor

func Null() *Value

Creates a null value. Wire format:

Tag: 0x00

Example:

val := cowrie.Null()
// Encodes to: 0x00

Bool

Constructor

func Bool(b bool) *Value

Creates a boolean value. Wire format:

Tag: 0x01 (false) or 0x02 (true)

Example:

val := cowrie.Bool(true)
if val.Type() == cowrie.TypeBool {
    fmt.Println("Bool:", val.Bool()) // true
}

Accessor

func (v *Value) Bool() bool

Returns the boolean value. Panics if not a bool.

Safe Accessors

func (v *Value) TryBool() (bool, bool)
func (v *Value) BoolOr(defaultVal bool) bool

Example:

if val, ok := v.TryBool(); ok {
    fmt.Println("Bool:", val)
}

b := v.BoolOr(false) // Returns false if not a bool

Int64

Constructor

func Int64(i int64) *Value

Creates a signed 64-bit integer value. Wire format:

Tag: 0x03
Value: zigzag-encoded varint

Zigzag encoding maps signed integers to unsigned for efficient varint encoding:

Example:

val := cowrie.Int64(-42)
data, _ := cowrie.Encode(val)
// Wire: 0x03 0x53 (tag + zigzag varint)

fmt.Println(val.Int64()) // -42

Accessor

func (v *Value) Int64() int64

Returns the int64 value. Panics if not an int64.

Safe Accessors

func (v *Value) TryInt64() (int64, bool)
func (v *Value) Int64Or(defaultVal int64) int64

Uint64

Constructor

func Uint64(u uint64) *Value

Creates an unsigned 64-bit integer value. Wire format:

Tag: 0x09
Value: varint

Example:

val := cowrie.Uint64(1234567890)
fmt.Println(val.Uint64()) // 1234567890

Accessor

func (v *Value) Uint64() uint64

Safe Accessors

func (v *Value) TryUint64() (uint64, bool)
func (v *Value) Uint64Or(defaultVal uint64) uint64

Float64

Constructor

func Float64(f float64) *Value

Creates a 64-bit floating point value. Wire format:

Tag: 0x04
Value: 8 bytes (IEEE 754 little-endian)

Example:

val := cowrie.Float64(3.14159)
fmt.Println(val.Float64()) // 3.14159

Accessor

func (v *Value) Float64() float64

Safe Accessors

func (v *Value) TryFloat64() (float64, bool)
func (v *Value) Float64Or(defaultVal float64) float64

String

Constructor

func String(s string) *Value

Creates a UTF-8 string value. Wire format:

Tag: 0x05
Length: varint (byte count)
Data: UTF-8 bytes

Example:

val := cowrie.String("Hello, 世界")
fmt.Println(val.String()) // "Hello, 世界"

Accessor

func (v *Value) String() string

Safe Accessors

func (v *Value) TryString() (string, bool)
func (v *Value) StringOr(defaultVal string) string

Bytes

Constructor

func Bytes(b []byte) *Value

Creates a binary data value. No base64 encoding required. Wire format:

Tag: 0x08
Length: varint (byte count)
Data: raw bytes

Example:

data := []byte{0xDE, 0xAD, 0xBE, 0xEF}
val := cowrie.Bytes(data)
fmt.Printf("%x\n", val.Bytes()) // "deadbeef"

Accessor

func (v *Value) Bytes() []byte

Safe Accessor

func (v *Value) TryBytes() ([]byte, bool)

Array

Constructor

func Array(items ...*Value) *Value

Creates an array of values. Elements can be heterogeneous. Wire format:

Tag: 0x06
Count: varint (element count)
Elements: encoded values

Example:

arr := cowrie.Array(
    cowrie.Int64(1),
    cowrie.String("two"),
    cowrie.Float64(3.0),
)

fmt.Println(arr.Len()) // 3
fmt.Println(arr.Index(1).String()) // "two"

Accessors

Len

func (v *Value) Len() int

Returns array length (or object member count, or 0 for other types).

Index

func (v *Value) Index(i int) *Value

Returns the i-th element. Panics if not an array or out of bounds.

IndexOr

func (v *Value) IndexOr(i int, defaultVal *Value) *Value

Returns the i-th element or defaultVal if out of bounds or not an array.

Array

func (v *Value) Array() []*Value

Returns all array elements. Panics if not an array.

TryArray

func (v *Value) TryArray() ([]*Value, bool)

Returns array elements and true, or (nil, false) if not an array.

Mutation

Append

func (v *Value) Append(val *Value)

Appends a value to an array. Panics if not an array. Example:

arr := cowrie.Array()
arr.Append(cowrie.Int64(1))
arr.Append(cowrie.Int64(2))
fmt.Println(arr.Len()) // 2

Object

Member Type

type Member struct {
    Key   string
    Value *Value
}

Represents a key-value pair in an object.

Constructors

Object

func Object(members ...Member) *Value

Creates an object from members. Wire format:

Tag: 0x07
Count: varint (member count)
Members: (dictIndex:varint + value)*

Example:

obj := cowrie.Object(
    cowrie.Member{Key: "name", Value: cowrie.String("Alice")},
    cowrie.Member{Key: "age", Value: cowrie.Int64(30)},
)

name := obj.Get("name").String() // "Alice"

ObjectFromMap

func ObjectFromMap(m map[string]*Value) *Value

Creates an object from a map. Order is non-deterministic unless using EncodeOptions{Deterministic: true}. Example:

m := map[string]*Value{
    "x": cowrie.Float64(1.0),
    "y": cowrie.Float64(2.0),
}
obj := cowrie.ObjectFromMap(m)

Accessors

Get

func (v *Value) Get(key string) *Value

Returns the value for a key, or nil if not found. Panics if not an object.

GetOr

func (v *Value) GetOr(key string, defaultVal *Value) *Value

Returns the value for a key or defaultVal if not found or not an object.

Members

func (v *Value) Members() []Member

Returns all object members. Panics if not an object.

TryObject

func (v *Value) TryObject() ([]Member, bool)

Returns members and true, or (nil, false) if not an object. Example:

for _, m := range obj.Members() {
    fmt.Printf("%s: %v\n", m.Key, m.Value)
}

Mutation

Set

func (v *Value) Set(key string, val *Value)

Sets a key-value pair. Updates existing key or adds new member. Panics if not an object. Example:

obj := cowrie.Object()
obj.Set("x", cowrie.Int64(10))
obj.Set("x", cowrie.Int64(20)) // Updates existing
fmt.Println(obj.Get("x").Int64()) // 20

Dictionary Coding

Gen2 objects use dictionary coding for efficient key encoding: Before encoding:

array := cowrie.Array(
    cowrie.Object(
        cowrie.Member{Key: "id", Value: cowrie.Int64(1)},
        cowrie.Member{Key: "name", Value: cowrie.String("Alice")},
    ),
    cowrie.Object(
        cowrie.Member{Key: "id", Value: cowrie.Int64(2)},
        cowrie.Member{Key: "name", Value: cowrie.String("Bob")},
    ),
)

Wire format:

Dictionary: ["id", "name"]
Array: [
  Object: {0: 1, 1: "Alice"},
  Object: {0: 2, 1: "Bob"}
]

Size savings: ~70% reduction for repeated schemas.

Type Checking Patterns

Type Switch

switch val.Type() {
case cowrie.TypeNull:
    fmt.Println("null")
case cowrie.TypeBool:
    fmt.Println("bool:", val.Bool())
case cowrie.TypeInt64:
    fmt.Println("int64:", val.Int64())
case cowrie.TypeString:
    fmt.Println("string:", val.String())
case cowrie.TypeArray:
    for i := 0; i < val.Len(); i++ {
        processValue(val.Index(i))
    }
case cowrie.TypeObject:
    for _, m := range val.Members() {
        processField(m.Key, m.Value)
    }
}

Safe Access

// Try pattern (returns value and bool)
if s, ok := val.TryString(); ok {
    fmt.Println("String:", s)
}

// Or pattern (returns value or default)
count := val.GetOr("count", cowrie.Int64(0)).Int64()

Gen1 vs Gen2 Tag Differences

Gen1 and Gen2 use different tag values for several types. Always check for ‘SJ’ magic header to detect Gen2.

Tag	Gen1 Type	Gen2 Type
0x06	Bytes	Array
0x07	Array	Object
0x08	Object	Bytes

Format detection:

if len(data) >= 2 && data[0] == 'S' && data[1] == 'J' {
    // Gen2 format
    val, _ := cowrie.Decode(data)
} else {
    // Gen1 format
    val, _ := cowrie.DecodeGen1(data)
}

Gen1 API

Gen2 API

Graph API

ML API

Documentation Index

​Overview

​Type Constants

​Type Tags (Wire Format)

​Type Enum

​Value Type

​Value Struct

​Type Methods

​Type

​IsNull

​Null

​Constructor

​Bool

​Constructor

​Accessor

​Safe Accessors

​Int64

​Constructor

​Accessor

​Safe Accessors

​Uint64

​Constructor

​Accessor

​Safe Accessors

​Float64

​Constructor

​Accessor

​Safe Accessors

​String

​Constructor

​Accessor

​Safe Accessors

​Bytes

​Constructor

​Accessor

​Safe Accessor

​Array

​Constructor

​Accessors

​Len

​Index

​IndexOr

​Array

​TryArray

​Mutation

​Append

​Object

​Member Type

​Constructors

​Object

​ObjectFromMap

​Accessors

​Get

​GetOr

​Members

​TryObject

​Mutation

​Set

​Dictionary Coding

​Type Checking Patterns

​Type Switch

​Safe Access

​Gen1 vs Gen2 Tag Differences

​See Also

Build docs developers (and LLMs) love

Overview

Type Constants

Type Tags (Wire Format)

Type Enum

Value Type

Value Struct

Type Methods

Type

IsNull

Null

Constructor

Bool

Constructor

Accessor

Safe Accessors

Int64

Constructor

Accessor

Safe Accessors

Uint64

Constructor

Accessor

Safe Accessors

Float64

Constructor

Accessor

Safe Accessors

String

Constructor

Accessor

Safe Accessors

Bytes

Constructor

Accessor

Safe Accessor

Array

Constructor

Accessors

Len

Index

IndexOr

Array

TryArray

Mutation

Append

Object

Member Type

Constructors

Object

ObjectFromMap

Accessors

Get

GetOr

Members

TryObject

Mutation

Set

Dictionary Coding

Type Checking Patterns

Type Switch

Safe Access

Gen1 vs Gen2 Tag Differences

See Also