syntax = "proto3";
package dht;
import "veilid.proto";

// DHTData - represents chunked blob data in the DHT
// Header in subkey 0 follows this structure
//
// stride = descriptor subkey count on first key - 1
// Subkeys 1..=stride on the first key are concatenated chunks
// Subkeys 0..stride on the 'keys' keys are concatenated chunks
//
// Keys must use writable schema in order to make this data mutable

message DHTData {
    // Other keys to concatenate
    // Uses the same writer as this DHTList with SMPL schema
    repeated veilid.TypedKey keys = 1;
    // Hash of reassembled data to verify contents
    veilid.TypedKey hash = 2;
    // Chunk size per subkey
    uint32 chunk = 3;
    // Total data size
    uint32 size = 4;
}

// DHTShortArray - represents a re-orderable collection of up to 256 individual elements
// Header in subkey 0 of first key follows this structure
//
// stride = descriptor subkey count on first key - 1
// Subkeys 1..=stride on the first key are individual elements
// Subkeys 0..stride on the 'keys' keys are also individual elements
//
// Keys must use writable schema in order to make this list mutable
message DHTShortArray {
    // Other keys to concatenate
    // Uses the same writer as this DHTList with SMPL schema
    repeated veilid.TypedKey keys = 1;
    
    // Item position index (uint8[256])
    // Actual item location is:
    //   idx = index[n] + 1 (offset for header at idx 0)
    //   key = idx / stride
    //   subkey = idx % stride
    bytes index = 2;
    // Free items are not represented in the list but can be
    // calculated through iteration
}

// DHTLog - represents an appendable/truncatable log collection of individual elements
// Header in subkey 0 of first key follows this structure
//
// stride = descriptor subkey count on first key - 1
// Subkeys 1..=stride on the first key are individual elements
// Subkeys 0..stride on the 'keys' keys are also individual elements
// 
// Keys must use writable schema in order to make this list mutable
message DHTLog {
    // Other keys to concatenate
    repeated veilid.TypedKey keys = 1;
    // Back link to another DHTLog further back
    veilid.TypedKey back = 2;
    // Count of subkeys in all keys in this DHTLog
    repeated uint32 subkey_counts = 3;
    // Total count of subkeys in all keys in this DHTLog including all backlogs
    uint32 total_subkeys = 4;
}

// DataReference
// Pointer to data somewhere in Veilid
// Abstraction over DHTData and BlockStore
message DataReference {
    oneof kind {
        veilid.TypedKey dht_data = 1;
        // TypedKey block = 2;
    }
}

// A pointer to an child DHT record
message OwnedDHTRecordPointer {
    // DHT Record key
    veilid.TypedKey record_key = 1;
    // DHT record owner key
    veilid.KeyPair owner = 2;
}
