Quickstart

Get started with Cowrie in 5 minutes - encode and decode your first message

This quickstart will get you encoding and decoding data with Cowrie in just a few minutes. We’ll show examples for all supported languages.

For installation instructions, see the Installation guide.

Choose your variant

Cowrie has two variants - choose based on your use case:

• Gen1: Simple JSON APIs, real-time systems, embedded devices
• Gen2: ML pipelines, logs/events with repeated schemas, graph data

If you’re unsure, start with Gen1. You can always switch to Gen2 later if you need features like dictionary coding or ML types.

Gen1 quickstart

Gen1 provides a simple API for encoding and decoding JSON-like data.

Go

package main

import (
    "fmt"
    "github.com/Neumenon/cowrie/gen1"
)

func main() {
    // Encode a map to binary
    data, err := gen1.Encode(map[string]any{
        "name": "Alice",
        "age": 30,
        "scores": []float64{95.5, 87.2, 92.8},
    })
    if err != nil {
        panic(err)
    }
    
    fmt.Printf("Encoded %d bytes\n", len(data))
    
    // Decode back to native types
    result, err := gen1.Decode(data)
    if err != nil {
        panic(err)
    }
    
    // Access decoded data
    m := result.(map[string]any)
    fmt.Printf("Name: %s\n", m["name"])
    fmt.Printf("Age: %d\n", m["age"])
}

Gen2 quickstart

Gen2 provides a more powerful API with dictionary coding, compression, and ML types.

Go

package main

import (
    "fmt"
    "github.com/Neumenon/cowrie/gen2"
)

func main() {
    // Build a structured value
    val := gen2.Object(
        gen2.Member{Key: "name", Value: gen2.String("Alice")},
        gen2.Member{Key: "age", Value: gen2.Int64(30)},
        gen2.Member{Key: "active", Value: gen2.Bool(true)},
    )
    
    // Encode with dictionary coding
    data, err := gen2.Encode(val)
    if err != nil {
        panic(err)
    }
    
    fmt.Printf("Encoded %d bytes\n", len(data))
    
    // Decode back
    result, err := gen2.Decode(data)
    if err != nil {
        panic(err)
    }
    
    fmt.Printf("Decoded: %+v\n", result)
}

Working with numeric arrays

Both Gen1 and Gen2 automatically optimize homogeneous numeric arrays:

1. Create data with numeric arrays

   data = {
       "embedding": [0.1, 0.2, 0.3, 0.4, 0.5],
       "labels": [1, 0, 1, 1, 0]
   }
   
2. Encode with proto-tensors

   Arrays with 4+ elements of the same numeric type are automatically encoded as proto-tensors for efficiency:

   encoded = gen1.encode(data)  # Arrays stored as compact binary
   
3. Decode back to native arrays

   decoded = gen1.decode(encoded)
   print(decoded['embedding'])  # [0.1, 0.2, 0.3, 0.4, 0.5]
   

Proto-tensor encoding reduces array size by up to 30% compared to generic JSON arrays, with no API changes required.

Graph data example (Gen2)

Gen2 includes native graph types for GNN workloads:

Go

package main

import (
    "github.com/Neumenon/cowrie/gen2"
)

func main() {
    // Create a graph node
    node := gen2.Node(gen2.NodeConfig{
        ID:     "person_42",
        Labels: []string{"Person", "Employee"},
        Props: map[string]any{
            "name": "Alice",
            "age":  30,
        },
    })
    
    // Create an edge
    edge := gen2.Edge(gen2.EdgeConfig{
        From:     "person_42",
        To:       "company_1",
        EdgeType: "WORKS_AT",
        Props: map[string]any{
            "since": 2020,
        },
    })
    
    // Encode graph elements
    nodeData, _ := gen2.Encode(node)
    edgeData, _ := gen2.Encode(edge)
}

Compression (Gen2)

Gen2 supports optional compression with gzip or zstd:

Go

// Encode with gzip compression
options := gen2.EncodeOptions{
    Compress: true,
    CompressionType: gen2.CompressionGzip,
}
data, err := gen2.EncodeWithOptions(val, options)

Compression adds CPU overhead. Use it for large payloads where network bandwidth is the bottleneck.

Next steps

Installation

Complete installation guide for all languages

API Reference

Detailed API documentation and advanced features