ovstorage-user-read-bytes

Use when loading one bounded object into memory to parse, inspect, hash, or hand its bytes to another tool.

SKILL.md

GitHub

Read Bytes Safely

Goal: Load an object's contents into memory with a bounded size.

When to use this: You need the bytes of one object — to parse it, inspect it, hash it, or hand it to another tool. The object fits in memory.

For larger objects (multi-GB, or unknown size), use ovstorage-user-materialize to get a stable on-disk path instead — that lets you stream / mmap without buffering everything.

Recipe

max_bytes is required. Pick a cap large enough for the work but small enough to fail fast on accidental giants.

{
  "tool": "ovstorage_read",
  "arguments": {
    "address": "s3://my-bucket/data/report.json",
    "max_bytes": 1048576
  }
}

What success looks like

{
  "v": "0.1",
  "ok": true,
  "operation": "ovstorage_read",
  "result": {
    "data_base64": "ewogICJyZW...",
    "info": {
      "address": "s3://my-bucket/data/report.json",
      "size": 4231,
      "etag": "\"abc123\"",
      "version": null,
      "mtime_unix_nanos": 1718000000000000000
    }
  }
}

data_base64 is the object's bytes, base64-encoded (MCP results are JSON-shaped; binary data must be encoded). Decode in whatever language you're using.

Optional parameters

  • if_match — precondition. Pass the bare etag string (e.g. "abc123") from a prior stat to atomically verify the object hasn't changed. Mismatch surfaces as ObjectModified.
  • range_start + range_end — byte-range read (both inclusive). Useful when you only need a slice (e.g., the header of a large file).

When things go wrong

error.code Likely cause What to do
NotFound Address doesn't exist Confirm spelling; check ovstorage_list of the parent prefix
ResourceExhausted Object is larger than max_bytes Either raise max_bytes, narrow with range_start/range_end, or switch to ovstorage-user-materialize
PermissionDenied Credentials can't read this object Check ovstorage_doctor — connection's auth_state_kind
NoRoute No backend serves this address and no anonymous fallback is granted for its scheme See ovstorage-user-getting-started
ObjectModified if_match didn't match Re-stat to get current identity, then decide whether to retry
Transient Backend hiccup retryable: true — retry once or twice with backoff

See also