Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Neumenon/cowrie/llms.txt

Use this file to discover all available pages before exploring further.

​
Go SDK

The Go implementation provides both Gen1 and Gen2 (v2) codecs with full type safety and high performance.

​
Installation

go get github.com/Neumenon/cowrie

​
Imports

import (
    "github.com/Neumenon/cowrie"  // Gen2 (default)
)

​
Basic Usage

​
Gen2: Encode & Decode

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

data, err := cowrie.Encode(val)
if err != nil {
    log.Fatal(err)
}

​
Gen1: Lightweight Encoding

import "github.com/Neumenon/cowrie/gen1"

// Encode any Go value
data, err := gen1.Encode(map[string]any{
    "name":   "Alice",
    "scores": []float64{0.1, 0.2, 0.3},
})

// Decode to any
result, err := gen1.Decode(data)
obj := result.(map[string]any)

​
Type System

​
Creating Values (Gen2)

// Scalars
nullVal := cowrie.Null()
boolVal := cowrie.Bool(true)
intVal := cowrie.Int64(42)
uintVal := cowrie.Uint64(100)
floatVal := cowrie.Float64(3.14)
strVal := cowrie.String("hello")
bytesVal := cowrie.Bytes([]byte{0x01, 0x02})

​
ML Types

// Tensor
data := []byte{...}  // raw tensor data
tensor := cowrie.Tensor(
    cowrie.DTypeFloat32,
    []uint64{384},  // shape
    data,
)

// Image
imageData := []byte{...}  // JPEG bytes
img := cowrie.Image(
    cowrie.ImageFormatJPEG,
    1920,  // width
    1080,  // height
    imageData,
)

// Audio
audioData := []byte{...}  // PCM samples
aud := cowrie.Audio(
    cowrie.AudioEncodingPCMInt16,
    44100,  // sample rate
    2,      // channels
    audioData,
)

​
Graph Types

// Node
node := cowrie.Node(
    "person_42",
    []string{"Person", "Employee"},
    map[string]any{
        "name": "Alice",
        "age":  30,
    },
)

// Edge
edge := cowrie.Edge(
    "person_42",
    "company_1",
    "WORKS_AT",
    map[string]any{
        "since": 2020,
    },
)

// Graph Shard
shard := cowrie.GraphShard(
    []cowrie.NodeData{...},
    []cowrie.EdgeData{...},
    map[string]any{"version": 1},
)

​
Reading Values

val, _ := cowrie.Decode(data)

switch val.Type() {
case cowrie.TypeString:
    str := val.String()
    fmt.Println(str)

case cowrie.TypeInt64:
    num := val.Int64()
    fmt.Println(num)

case cowrie.TypeArray:
    arr := val.Array()
    for _, item := range arr {
        // process item
    }

case cowrie.TypeObject:
    members := val.Members()
    for _, m := range members {
        fmt.Printf("%s: %v\n", m.Key, m.Value)
    }

case cowrie.TypeTensor:
    t := val.Tensor()
    fmt.Printf("DType: %d, Shape: %v\n", t.DType, t.Dims)
}

​
JSON Bridge

// Cowrie -> JSON
cowrieVal := cowrie.String("test")
jsonBytes, err := cowrie.ToJSON(cowrieVal)
if err != nil {
    log.Fatal(err)
}
fmt.Println(string(jsonBytes))  // "test"

​
Streaming

​
Gen1 Stream Decoder

import "github.com/Neumenon/cowrie/gen1"

dec := gen1.NewStreamDecoder(conn)
for {
    val, err := dec.Decode()
    if err == io.EOF {
        break
    }
    if err != nil {
        return err
    }
    process(val)
}

​
Gen2 IO Operations

val := cowrie.String("test")
err := cowrie.EncodeTo(writer, val)

​
Advanced Features

​
Encoding Options

opts := cowrie.EncodeOptions{
    Deterministic: true,  // Sort keys for reproducible output
    OmitNull:      true,  // Exclude null values from objects
}

val := cowrie.Object(
    cowrie.Member{Key: "name", Value: cowrie.String("Alice")},
    cowrie.Member{Key: "meta", Value: cowrie.Null()},
)

data, err := cowrie.EncodeWithOptions(val, opts)
// Result will not include "meta" field

​
Decoding Options

opts := cowrie.DecodeOptions{
    MaxDepth:     500,                // Limit nesting depth
    MaxArrayLen:  1_000_000,          // Limit array size
    MaxObjectLen: 100_000,            // Limit object fields
    MaxStringLen: 10_000_000,         // Limit string length
    MaxBytesLen:  100_000_000,        // Limit bytes/tensor data
    OnUnknownExt: cowrie.UnknownExtKeep,  // Preserve unknown extensions
}

val, err := cowrie.DecodeWithOptions(data, opts)

​
Type Conversion

// Convert Go types to Cowrie values
val := cowrie.FromAny(map[string]any{
    "name":  "Alice",
    "age":   30,
    "active": true,
})

// Convert Cowrie values back to Go types
goVal := cowrie.ToAny(val)
obj := goVal.(map[string]any)

​
Direct Go Any Encoding

For convenience, you can encode/decode Go any values directly without creating *Value objects: 
// Encode Go any directly
data, err := cowrie.EncodeAny(map[string]any{
    "name":  "Alice",
    "scores": []float64{1.0, 2.0, 3.0},
})

// Decode to Go any
result, err := cowrie.DecodeAny(data)
obj := result.(map[string]any)
With options: 
opts := cowrie.AnyOptions{
    Deterministic: true,
    OmitNull:      false,
}

data, err := cowrie.EncodeAnyWithOptions(value, opts)
EncodeAny internally calls FromAny to convert to *Value, then encodes. For performance-critical paths, consider using FromAny + Encode explicitly to reuse Value objects.

​
Error Handling

val, err := cowrie.Decode(data)
if err != nil {
    switch {
    case errors.Is(err, cowrie.ErrInvalidMagic):
        log.Println("Not a valid Cowrie file")
    case errors.Is(err, cowrie.ErrInvalidVersion):
        log.Println("Unsupported version")
    case errors.Is(err, cowrie.ErrDepthExceeded):
        log.Println("Data too deeply nested")
    case errors.Is(err, cowrie.ErrArrayTooLarge):
        log.Println("Array exceeds size limit")
    default:
        log.Printf("Decode error: %v", err)
    }
}

​
Performance Tips

  1. Reuse buffers: Use EncodeAppend to avoid allocations 
    buf := make([]byte, 0, 4096)
buf, err = cowrie.EncodeAppend(buf, val1)
buf, err = cowrie.EncodeAppend(buf, val2)
  2. Streaming for large data: Use EncodeTo and DecodeFrom for large payloads
  3. Security limits: Always use DecodeFromLimited for untrusted input
  4. Gen1 for simple data: Use Gen1 for lightweight JSON-compatible data

​
Package Reference

  • github.com/Neumenon/cowrie - Gen2 (Cowrie v2)
  • github.com/Neumenon/cowrie/gen1 - Gen1 (lightweight)
  • github.com/Neumenon/cowrie/graph - Graph utilities
  • github.com/Neumenon/cowrie/gnn - GNN helpers

Build docs developers (and LLMs) love

Get started for freeTalk to us