bytescty

bytes-cty-type

A go-cty capsule type for immutable byte slices with optional MIME content types, plus functions for encoding and decoding.

Overview

This package provides a bytes type for use in HCL2 / cty expression evaluation contexts. A bytes value carries raw binary data and an optional content type string. It is represented as a cty object with a content_type attribute and an internal _capsule attribute for interface dispatch.

Extracted from vinculum, where it powers binary payloads in HTTP, serialization, and key-value store operations.

Types

bytescty.Bytes

type Bytes struct {
    Data        []byte
    ContentType string
}

bytescty.BytesCapsuleType

A cty capsule type wrapping *Bytes. Used internally as the _capsule attribute of bytes objects.

bytescty.BytesObjectType

A cty object type with attributes:

• content_type (string) — the MIME type
• _capsule (BytesCapsuleType) — the encapsulated bytes

Helper functions

bytescty.NewBytesCapsule(data []byte, contentType string) cty.Value
bytescty.BuildBytesObject(data []byte, contentType string) cty.Value
bytescty.GetBytesFromCapsule(val cty.Value) (*Bytes, error)
bytescty.GetBytesFromValue(val cty.Value) (*Bytes, error)

GetBytesFromValue accepts a raw capsule, a bytes object, or any cty object with a _capsule attribute containing a *Bytes — it delegates to rich-cty-types GetCapsuleFromValue.

Registration

import bytescty "github.com/tsarna/bytes-cty-type"

// Add all bytes functions to your eval context:
for name, fn := range bytescty.GetBytesFunctions() {
    funcs[name] = fn
}

rich-cty-types integration

The Bytes type implements the rich-cty-types Stringable and Lengthable interfaces:

• tostring(b) returns the raw bytes as a UTF-8 string.
• length(b) returns the byte length.

import (
    bytescty "github.com/tsarna/bytes-cty-type"
    richcty  "github.com/tsarna/rich-cty-types"
)

funcs := richcty.GetGenericFunctions()           // tostring, length, ...
for name, fn := range bytescty.GetBytesFunctions() {
    funcs[name] = fn
}

Functions

base64encode and base64decode deliberately shadow the HCL builtins of the same name, extending them rather than replacing them: one-argument base64decode still returns a string, so config written against the builtin keeps working.

Signature declarations

The table above is what these functions really accept. It is not what their cty metadata can say, and the gap is not small:

• Each takes an argument that is a union — a string, or a bytes value. cty has no union type, so its metadata can only say dynamic.
• bytes and base64decode each take one optional trailing argument. The only way cty offers to make an argument optional is to make it variadic, which erases its name, its type, and its arity.
• base64decode's return type depends on whether that argument is present — string with one argument, bytes with two — and a cty function has exactly one signature to say it in.

So externs.cty declares the real signatures, as functy //functy:extern declarations. The file is never compiled and declares nothing callable; it exists so that help(), generated documentation, and editor tooling can show what the cty metadata cannot.

Externs() returns it as opaque bytes — this package does not import functy and does not parse them:

parser.RegisterExterns(bytescty.Externs(), bytescty.ExternsFilename)

A host that is not a functy host can ignore it entirely; the cty Description on every function and parameter is still populated.

Examples

# Create bytes from a string
bytes("hello world")
bytes("hello", "text/plain")

# Access content type
bytes("img data", "image/png").content_type   # "image/png"

# Base64 round-trip
base64encode("hello")                          # "aGVsbG8="
base64decode("aGVsbG8=")                       # "hello" (string)
base64decode("aGVsbG8=", "text/plain")         # bytes object

# Re-wrap with different content type
bytes(existing_bytes, "application/json")

# With rich-cty-types generic functions
tostring(b)                                    # raw bytes as string
length(b)                                      # byte count

License

BSD 2-Clause — see LICENSE.