kotlinx-rpc-grpc-core/kotlinx.rpc.grpc/GrpcMetadata

GrpcMetadata

Available in a dev version: 0․11․0-grpc-186

How to configure

expect class GrpcMetadata(source)

Provides access to read and write metadata values to be exchanged during a gRPC call.

Metadata is an ordered map with case-insensitive keys that are ASCII strings. Each key can be associated with multiple values. Values can be either strings (for standard keys) or binary data (for keys ending with "-bin" suffix).

Key Requirements

Keys must contain only the following ASCII characters:

  • Digits: 0-9

  • Lowercase letters: a-z (uppercase letters are normalized to lowercase)

  • Special characters: -, _, .

Keys must not contain spaces or other special characters. Invalid keys will cause an IllegalArgumentException to be thrown. Binary keys must additionally end with the -bin suffix.

Value Requirements

ASCII string values must contain only:

  • ASCII visible characters (0x21-0x7E)

  • Space (0x20), but not at the beginning or end of the string

Non-ASCII characters in values are replaced with ? during encoding.

Thread Safety

This class is not thread-safe. Modifications made by one thread may not be visible to another thread concurrently reading the metadata.

Example usage

 val metadata = GrpcMetadata {
    append("custom-header", "value1")
    append("custom-header", "value2")
    appendBinary("custom-header-bin", byteArrayOf(1, 2, 3))
}

 val firstValue = metadata["custom-header"] // returns "value2" (last added)
 val allValues = metadata.getAll("custom-header") // returns ["value1", "value2"]
Content copied to clipboard
actual typealias GrpcMetadata = Metadata(source)

Provides access to read and write metadata values to be exchanged during a gRPC call.

Metadata is an ordered map with case-insensitive keys that are ASCII strings. Each key can be associated with multiple values. Values can be either strings (for standard keys) or binary data (for keys ending with "-bin" suffix).

Key Requirements

Keys must contain only the following ASCII characters:

  • Digits: 0-9

  • Lowercase letters: a-z (uppercase letters are normalized to lowercase)

  • Special characters: -, _, .

Keys must not contain spaces or other special characters. Invalid keys will cause an IllegalArgumentException to be thrown. Binary keys must additionally end with the -bin suffix.

Value Requirements

ASCII string values must contain only:

  • ASCII visible characters (0x21-0x7E)

  • Space (0x20), but not at the beginning or end of the string

Non-ASCII characters in values are replaced with ? during encoding.

Thread Safety

This class is not thread-safe. Modifications made by one thread may not be visible to another thread concurrently reading the metadata.

Example usage

 val metadata = GrpcMetadata {
    append("custom-header", "value1")
    append("custom-header", "value2")
    appendBinary("custom-header-bin", byteArrayOf(1, 2, 3))
}

 val firstValue = metadata["custom-header"] // returns "value2" (last added)
 val allValues = metadata.getAll("custom-header") // returns ["value1", "value2"]
Content copied to clipboard
actual class GrpcMetadata(source)

Provides access to read and write metadata values to be exchanged during a gRPC call.

Metadata is an ordered map with case-insensitive keys that are ASCII strings. Each key can be associated with multiple values. Values can be either strings (for standard keys) or binary data (for keys ending with "-bin" suffix).

Key Requirements

Keys must contain only the following ASCII characters:

  • Digits: 0-9

  • Lowercase letters: a-z (uppercase letters are normalized to lowercase)

  • Special characters: -, _, .

Keys must not contain spaces or other special characters. Invalid keys will cause an IllegalArgumentException to be thrown. Binary keys must additionally end with the -bin suffix.

Value Requirements

ASCII string values must contain only:

  • ASCII visible characters (0x21-0x7E)

  • Space (0x20), but not at the beginning or end of the string

Non-ASCII characters in values are replaced with ? during encoding.

Thread Safety

This class is not thread-safe. Modifications made by one thread may not be visible to another thread concurrently reading the metadata.

Example usage

 val metadata = GrpcMetadata {
    append("custom-header", "value1")
    append("custom-header", "value2")
    appendBinary("custom-header-bin", byteArrayOf(1, 2, 3))
}

 val firstValue = metadata["custom-header"] // returns "value2" (last added)
 val allValues = metadata.getAll("custom-header") // returns ["value1", "value2"]
Content copied to clipboard

Constructors

Link copied to clipboard
expect constructor()
constructor(raw: grpc_metadata_array)
actual constructor()

Functions

Link copied to clipboard
expect fun GrpcMetadata.append(key: String, value: String)

Appends a metadata entry with the given key and value.

expect fun <T> GrpcMetadata.append(key: GrpcMetadataKey<T>, value: T)

Appends a metadata entry with the given typed key and value.

actual fun GrpcMetadata.append(key: String, value: String)

Appends a metadata entry with the given key and value.

actual fun <T> GrpcMetadata.append(key: GrpcMetadataKey<T>, value: T)

Appends a metadata entry with the given typed key and value.

actual fun GrpcMetadata.append(key: String, value: String)

Appends a metadata entry with the given key and value.

actual fun <T> GrpcMetadata.append(key: GrpcMetadataKey<T>, value: T)

Appends a metadata entry with the given typed key and value.

Link copied to clipboard
expect fun GrpcMetadata.appendBinary(key: String, value: ByteArray)

Appends a binary metadata entry with the given key and value.

expect fun <T> GrpcMetadata.appendBinary(key: GrpcMetadataKey<T>, value: T)

Appends a binary metadata entry with the given typed key and value.

actual fun GrpcMetadata.appendBinary(key: String, value: ByteArray)

Appends a binary metadata entry with the given key and value.

actual fun <T> GrpcMetadata.appendBinary(key: GrpcMetadataKey<T>, value: T)

Appends a binary metadata entry with the given typed key and value.

actual fun GrpcMetadata.appendBinary(key: String, value: ByteArray)

Appends a binary metadata entry with the given key and value.

actual fun <T> GrpcMetadata.appendBinary(key: GrpcMetadataKey<T>, value: T)

Appends a binary metadata entry with the given typed key and value.

Link copied to clipboard
expect operator fun GrpcMetadata.contains(key: String): Boolean

Returns true if this metadata contains one or more values for the specified key.

actual operator fun GrpcMetadata.contains(key: String): Boolean

Returns true if this metadata contains one or more values for the specified key.

actual operator fun GrpcMetadata.contains(key: String): Boolean

Returns true if this metadata contains one or more values for the specified key.

Link copied to clipboard
fun GrpcMetadata.copy(): GrpcMetadata

Creates a copy of this metadata containing all entries.

Link copied to clipboard
expect operator fun GrpcMetadata.get(key: String): String?

Returns the last metadata entry added with the given key, or null if there are no entries.

expect operator fun <T> GrpcMetadata.get(key: GrpcMetadataKey<T>): T?

Returns the last metadata entry added with the given typed key, or null if there are no entries.

actual operator fun GrpcMetadata.get(key: String): String?

Returns the last metadata entry added with the given key, or null if there are no entries.

actual operator fun <T> GrpcMetadata.get(key: GrpcMetadataKey<T>): T?

Returns the last metadata entry added with the given typed key, or null if there are no entries.

actual operator fun GrpcMetadata.get(key: String): String?

Returns the last metadata entry added with the given key, or null if there are no entries.

actual operator fun <T> GrpcMetadata.get(key: GrpcMetadataKey<T>): T?

Returns the last metadata entry added with the given typed key, or null if there are no entries.

Link copied to clipboard
expect fun GrpcMetadata.getAll(key: String): List<String>

Returns all metadata entries with the given key, in the order they were added.

expect fun <T> GrpcMetadata.getAll(key: GrpcMetadataKey<T>): List<T>

Returns all metadata entries with the given typed key, in the order they were added.

actual fun GrpcMetadata.getAll(key: String): List<String>

Returns all metadata entries with the given key, in the order they were added.

actual fun <T> GrpcMetadata.getAll(key: GrpcMetadataKey<T>): List<T>

Returns all metadata entries with the given typed key, in the order they were added.

actual fun GrpcMetadata.getAll(key: String): List<String>

Returns all metadata entries with the given key, in the order they were added.

actual fun <T> GrpcMetadata.getAll(key: GrpcMetadataKey<T>): List<T>

Returns all metadata entries with the given typed key, in the order they were added.

Link copied to clipboard
expect fun GrpcMetadata.getAllBinary(key: String): List<ByteArray>

Returns all binary metadata entries with the given key, in the order they were added.

expect fun <T> GrpcMetadata.getAllBinary(key: GrpcMetadataKey<T>): List<T>

Returns all binary metadata entries with the given typed key, in the order they were added.

actual fun GrpcMetadata.getAllBinary(key: String): List<ByteArray>

Returns all binary metadata entries with the given key, in the order they were added.

actual fun <T> GrpcMetadata.getAllBinary(key: GrpcMetadataKey<T>): List<T>

Returns all binary metadata entries with the given typed key, in the order they were added.

actual fun GrpcMetadata.getAllBinary(key: String): List<ByteArray>

Returns all binary metadata entries with the given key, in the order they were added.

actual fun <T> GrpcMetadata.getAllBinary(key: GrpcMetadataKey<T>): List<T>

Returns all binary metadata entries with the given typed key, in the order they were added.

Link copied to clipboard
expect fun GrpcMetadata.getBinary(key: String): ByteArray?

Returns the last binary metadata entry added with the given key, or null if there are no entries.

expect fun <T> GrpcMetadata.getBinary(key: GrpcMetadataKey<T>): T?

Returns the last binary metadata entry added with the given typed key, or null if there are no entries.

actual fun GrpcMetadata.getBinary(key: String): ByteArray?

Returns the last binary metadata entry added with the given key, or null if there are no entries.

actual fun <T> GrpcMetadata.getBinary(key: GrpcMetadataKey<T>): T?

Returns the last binary metadata entry added with the given typed key, or null if there are no entries.

actual fun GrpcMetadata.getBinary(key: String): ByteArray?

Returns the last binary metadata entry added with the given key, or null if there are no entries.

actual fun <T> GrpcMetadata.getBinary(key: GrpcMetadataKey<T>): T?

Returns the last binary metadata entry added with the given typed key, or null if there are no entries.

Link copied to clipboard
expect fun GrpcMetadata.keys(): Set<String>

Returns an immutable set of all keys present in this metadata.

actual fun GrpcMetadata.keys(): Set<String>

Returns an immutable set of all keys present in this metadata.

actual fun GrpcMetadata.keys(): Set<String>

Returns an immutable set of all keys present in this metadata.

Link copied to clipboard
expect fun GrpcMetadata.merge(other: GrpcMetadata)

Merges all entries from other metadata into this metadata.

actual fun GrpcMetadata.merge(other: GrpcMetadata)

Merges all entries from other metadata into this metadata.

actual fun GrpcMetadata.merge(other: GrpcMetadata)

Merges all entries from other metadata into this metadata.

Link copied to clipboard
operator fun GrpcMetadata.plus(other: GrpcMetadata): GrpcMetadata

Creates a new metadata instance containing all entries from this metadata and other.

Link copied to clipboard
operator fun GrpcMetadata.plusAssign(other: GrpcMetadata)

Merges all entries from other metadata into this metadata using the += operator.

Link copied to clipboard
expect fun GrpcMetadata.remove(key: String, value: String): Boolean

Removes the first occurrence of the specified value for the given key.

expect fun <T> GrpcMetadata.remove(key: GrpcMetadataKey<T>, value: T): Boolean

Removes the first occurrence of the specified value for the given typed key.

actual fun GrpcMetadata.remove(key: String, value: String): Boolean

Removes the first occurrence of the specified value for the given key.

actual fun <T> GrpcMetadata.remove(key: GrpcMetadataKey<T>, value: T): Boolean

Removes the first occurrence of the specified value for the given typed key.

actual fun GrpcMetadata.remove(key: String, value: String): Boolean

Removes the first occurrence of the specified value for the given key.

actual fun <T> GrpcMetadata.remove(key: GrpcMetadataKey<T>, value: T): Boolean

Removes the first occurrence of the specified value for the given typed key.

Link copied to clipboard
expect fun GrpcMetadata.removeAll(key: String): List<String>

Removes all values for the given key and returns them.

expect fun <T> GrpcMetadata.removeAll(key: GrpcMetadataKey<T>): List<T>

Removes all values for the given typed key and returns them.

actual fun GrpcMetadata.removeAll(key: String): List<String>

Removes all values for the given key and returns them.

actual fun <T> GrpcMetadata.removeAll(key: GrpcMetadataKey<T>): List<T>

Removes all values for the given typed key and returns them.

actual fun GrpcMetadata.removeAll(key: String): List<String>

Removes all values for the given key and returns them.

actual fun <T> GrpcMetadata.removeAll(key: GrpcMetadataKey<T>): List<T>

Removes all values for the given typed key and returns them.

Link copied to clipboard
expect fun GrpcMetadata.removeAllBinary(key: String): List<ByteArray>

Removes all binary values for the given key and returns them.

expect fun <T> GrpcMetadata.removeAllBinary(key: GrpcMetadataKey<T>): List<T>
actual fun GrpcMetadata.removeAllBinary(key: String): List<ByteArray>

Removes all binary values for the given key and returns them.

actual fun <T> GrpcMetadata.removeAllBinary(key: GrpcMetadataKey<T>): List<T>
actual fun GrpcMetadata.removeAllBinary(key: String): List<ByteArray>

Removes all binary values for the given key and returns them.

actual fun <T> GrpcMetadata.removeAllBinary(key: GrpcMetadataKey<T>): List<T>
Link copied to clipboard
expect fun GrpcMetadata.removeBinary(key: String, value: ByteArray): Boolean

Removes the first occurrence of the specified binary value for the given key.

expect fun <T> GrpcMetadata.removeBinary(key: GrpcMetadataKey<T>, value: T): Boolean

Removes the first occurrence of the specified binary value for the given typed key.

actual fun GrpcMetadata.removeBinary(key: String, value: ByteArray): Boolean

Removes the first occurrence of the specified binary value for the given key.

actual fun <T> GrpcMetadata.removeBinary(key: GrpcMetadataKey<T>, value: T): Boolean

Removes the first occurrence of the specified binary value for the given typed key.

actual fun GrpcMetadata.removeBinary(key: String, value: ByteArray): Boolean

Removes the first occurrence of the specified binary value for the given key.

actual fun <T> GrpcMetadata.removeBinary(key: GrpcMetadataKey<T>, value: T): Boolean

Removes the first occurrence of the specified binary value for the given typed key.

Link copied to clipboard
open override fun toString(): String
Generated by Dokka
© 2026 JetBrains s.r.o and contributors. Apache License 2.0