@temporalio/core-bridge 1.14.2-canary-release-testing.0 → 1.16.0

package/sdk-core/crates/sdk-core-c-bridge/src/client.rs

@@ -14,21 +14,20 @@ use std::{
     time::Duration,
 };
 use temporalio_client::{
-    ClientKeepAliveOptions as CoreClientKeepAliveOptions, ClientOptions as CoreClientOptions,
-    ClientTlsOptions as CoreClientTlsOptions, CloudService, ConfiguredClient, HealthService,
-    OperatorService, RetryClient, RetryOptions, TemporalServiceClient, TestService,
-    TlsOptions as CoreTlsOptions, WorkflowService, callback_based, proxy::HttpConnectProxyOptions,
+    ClientKeepAliveOptions as CoreClientKeepAliveOptions, RetryOptions, callback_based,
+    grpc::{CloudService, HealthService, OperatorService, TestService, WorkflowService},
 };
 use tokio::sync::oneshot;
-use tonic::metadata::MetadataKey;
+use tonic::metadata::{MetadataKey, MetadataValue};
 use url::Url;
 
 #[repr(C)]
-pub struct ClientOptions {
+pub struct ConnectionOptions {
     pub target_url: ByteArrayRef,
     pub client_name: ByteArrayRef,
     pub client_version: ByteArrayRef,
     pub metadata: MetadataRef,
+    pub binary_metadata: MetadataRef,
     pub api_key: ByteArrayRef,
     pub identity: ByteArrayRef,
     pub tls_options: *const ClientTlsOptions,
@@ -79,21 +78,21 @@ pub struct ClientHttpConnectProxyOptions {
     pub password: ByteArrayRef,
 }
 
-type CoreClient = RetryClient<ConfiguredClient<TemporalServiceClient>>;
+type CoreConnection = temporalio_client::Connection;
 
-pub struct Client {
+pub struct Connection {
     pub(crate) runtime: Runtime,
-    pub(crate) core: CoreClient,
+    pub(crate) core: CoreConnection,
 }
 
 // Expected to outlive all async calls that use it
-unsafe impl Send for Client {}
-unsafe impl Sync for Client {}
+unsafe impl Send for Connection {}
+unsafe impl Sync for Connection {}
 
 /// If success or fail are not null, they must be manually freed when done.
 pub type ClientConnectCallback = unsafe extern "C" fn(
     user_data: *mut libc::c_void,
-    success: *mut Client,
+    success: *mut Connection,
     fail: *const ByteArray,
 );
 
@@ -102,14 +101,14 @@ pub type ClientConnectCallback = unsafe extern "C" fn(
 #[unsafe(no_mangle)]
 pub extern "C" fn temporal_core_client_connect(
     runtime: *mut Runtime,
-    options: *const ClientOptions,
+    options: *const ConnectionOptions,
     user_data: *mut libc::c_void,
     callback: ClientConnectCallback,
 ) {
     let runtime = unsafe { &mut *runtime };
     // Convert opts
     let options = unsafe { &*options };
-    let core_options: CoreClientOptions = match options.try_into() {
+    let mut connection_options: temporalio_client::ConnectionOptions = match options.try_into() {
         Ok(v) => v,
         Err(err) => {
             unsafe {
@@ -125,24 +124,22 @@ pub extern "C" fn temporal_core_client_connect(
         }
     };
     // Create override if present
-    let service_override = options.grpc_override_callback.map(|cb| {
-        create_callback_based_grpc_service(runtime, cb, options.grpc_override_callback_user_data)
-    });
+    if let Some(cb) = options.grpc_override_callback {
+        connection_options.service_override = Some(create_callback_based_grpc_service(
+            runtime,
+            cb,
+            options.grpc_override_callback_user_data,
+        ));
+    }
     // Spawn async call
     let user_data = UserDataHandle(user_data);
-    let core = runtime.core.clone();
+    connection_options.metrics_meter = runtime.core.telemetry().get_metric_meter();
     runtime.core.tokio_handle().spawn(async move {
-        match core_options
-            .connect_no_namespace_with_service_override(
-                core.telemetry().get_temporal_metric_meter(),
-                service_override,
-            )
-            .await
-        {
-            Ok(core) => {
-                let owned_client = Box::into_raw(Box::new(Client {
+        match temporalio_client::Connection::connect(connection_options).await {
+            Ok(connection) => {
+                let owned_client = Box::into_raw(Box::new(Connection {
                     runtime: runtime.clone(),
-                    core,
+                    core: connection,
                 }));
                 unsafe {
                     callback(user_data.into(), owned_client, std::ptr::null());
@@ -231,7 +228,7 @@ fn create_callback_based_grpc_service(
 }
 
 #[unsafe(no_mangle)]
-pub extern "C" fn temporal_core_client_free(client: *mut Client) {
+pub extern "C" fn temporal_core_client_free(client: *mut Connection) {
     unsafe {
         let _ = Box::from_raw(client);
     }
@@ -239,23 +236,33 @@ pub extern "C" fn temporal_core_client_free(client: *mut Client) {
 
 #[unsafe(no_mangle)]
 pub extern "C" fn temporal_core_client_update_metadata(
-    client: *mut Client,
-    metadata: ByteArrayRef,
+    client: *mut Connection,
+    metadata: MetadataRef,
 ) {
     let client = unsafe { &*client };
     let _result = client
         .core
-        .get_client()
         .set_headers(metadata.to_string_map_on_newlines());
 }
 
 #[unsafe(no_mangle)]
-pub extern "C" fn temporal_core_client_update_api_key(client: *mut Client, api_key: ByteArrayRef) {
+pub extern "C" fn temporal_core_client_update_binary_metadata(
+    client: *mut Connection,
+    metadata: MetadataRef,
+) {
     let client = unsafe { &*client };
-    client
+    let _result = client
         .core
-        .get_client()
-        .set_api_key(api_key.to_option_string());
+        .set_binary_headers(metadata.to_vec_map_on_newlines());
+}
+
+#[unsafe(no_mangle)]
+pub extern "C" fn temporal_core_client_update_api_key(
+    client: *mut Connection,
+    api_key: ByteArrayRef,
+) {
+    let client = unsafe { &*client };
+    client.core.set_api_key(api_key.to_option_string());
 }
 
 /// Callback that is invoked for every gRPC call if set on the client options.
@@ -271,6 +278,11 @@ pub type ClientGrpcOverrideCallback = Option<
     unsafe extern "C" fn(request: *mut ClientGrpcOverrideRequest, user_data: *mut libc::c_void),
 >;
 
+pub struct GrpcMetadataHolder {
+    pub data: Vec<ByteArrayRef>,
+    pub(super) _allocations: Vec<Vec<u8>>,
+}
+
 /// Representation of gRPC request for the callback.
 ///
 /// Note, temporal_core_client_grpc_override_request_respond is effectively the "free" call for
@@ -278,7 +290,7 @@ pub type ClientGrpcOverrideCallback = Option<
 /// call.
 pub struct ClientGrpcOverrideRequest {
     core: callback_based::GrpcRequest,
-    built_headers: OnceCell<String>,
+    built_headers: OnceCell<GrpcMetadataHolder>,
     response_sender: oneshot::Sender<Result<callback_based::GrpcSuccessResponse, tonic::Status>>,
 }
 
@@ -341,15 +353,24 @@ pub extern "C" fn temporal_core_client_grpc_override_request_headers(
     let req = unsafe { &*req };
     // Lazily create the headers on first access
     let headers = req.built_headers.get_or_init(|| {
-        req.core
+        let refs: Vec<Vec<u8>> = req
+            .core
             .headers
             .iter()
-            .filter_map(|(name, value)| value.to_str().ok().map(|val| (name.as_str(), val)))
-            .flat_map(|(k, v)| [k, v])
-            .collect::<Vec<_>>()
-            .join("\n")
+            .filter_map(|(name, value)| {
+                value.to_str().ok().map(|val| {
+                    let mut entry = format!("{name}\n").into_bytes();
+                    entry.extend(val.as_bytes());
+                    entry
+                })
+            })
+            .collect();
+        GrpcMetadataHolder {
+            data: refs.iter().map(ByteArrayRef::from).collect(),
+            _allocations: refs,
+        }
     });
-    headers.as_str().into()
+    headers.into()
 }
 
 /// Get a reference to the request protobuf bytes.
@@ -403,13 +424,13 @@ impl ClientGrpcOverrideResponse {
     }
 
     fn client_headers_from_metadata_ref(headers: MetadataRef) -> Result<http::HeaderMap, String> {
-        let key_values = headers.to_str_map_on_newlines();
+        let key_values = headers.to_vec_map_on_newlines();
         let mut header_map = http::HeaderMap::with_capacity(key_values.len());
         for (k, v) in key_values.into_iter() {
-            let name = http::HeaderName::try_from(k)
+            let name = http::HeaderName::try_from(&k)
                 .map_err(|e| format!("Invalid header name '{k}': {e}"))?;
-            let value = http::HeaderValue::from_str(v)
-                .map_err(|e| format!("Invalid header value '{v}': {e}"))?;
+            let value = http::HeaderValue::from_bytes(v.as_slice())
+                .map_err(|e| format!("Invalid header value '{v:?}': {e}"))?;
             header_map.insert(name, value);
         }
         Ok(header_map)
@@ -423,6 +444,7 @@ pub struct RpcCallOptions {
     pub req: ByteArrayRef,
     pub retry: bool,
     pub metadata: MetadataRef,
+    pub binary_metadata: MetadataRef,
     /// 0 means no timeout
     pub timeout_millis: u32,
     pub cancellation_token: *const CancellationToken,
@@ -471,7 +493,7 @@ macro_rules! service_call {
 /// Client, options, and user data must live through callback.
 #[unsafe(no_mangle)]
 pub extern "C" fn temporal_core_client_rpc_call(
-    client: *mut Client,
+    client: *mut Connection,
     options: *const RpcCallOptions,
     user_data: *mut libc::c_void,
     callback: ClientRpcCallCallback,
@@ -533,18 +555,24 @@ macro_rules! rpc_call_on_trait {
         if $call.retry {
             rpc_resp($trait::$call_name(&mut $client, rpc_req($call)?).await)
         } else {
-            rpc_resp($trait::$call_name(&mut $client.into_inner(), rpc_req($call)?).await)
+            // Disable retries for this call
+            *$client.retry_options_mut() = RetryOptions::no_retries();
+            rpc_resp($trait::$call_name(&mut $client, rpc_req($call)?).await)
         }
     };
 }
 
 async fn call_workflow_service(
-    client: &CoreClient,
+    client: &CoreConnection,
     call: &RpcCallOptions,
 ) -> anyhow::Result<Vec<u8>> {
     let rpc = call.rpc.to_str();
     let mut client = client.clone();
     match rpc {
+        "CountActivityExecutions" => {
+            rpc_call_on_trait!(client, call, WorkflowService, count_activity_executions)
+        }
+        "CountSchedules" => rpc_call_on_trait!(client, call, WorkflowService, count_schedules),
         "CountWorkflowExecutions" => {
             rpc_call_on_trait!(client, call, WorkflowService, count_workflow_executions)
         }
@@ -553,6 +581,9 @@ async fn call_workflow_service(
             rpc_call_on_trait!(client, call, WorkflowService, create_workflow_rule)
         }
         "DeleteSchedule" => rpc_call_on_trait!(client, call, WorkflowService, delete_schedule),
+        "DeleteActivityExecution" => {
+            rpc_call_on_trait!(client, call, WorkflowService, delete_activity_execution)
+        }
         "DeleteWorkerDeployment" => {
             rpc_call_on_trait!(client, call, WorkflowService, delete_worker_deployment)
         }
@@ -573,6 +604,9 @@ async fn call_workflow_service(
         "DeprecateNamespace" => {
             rpc_call_on_trait!(client, call, WorkflowService, deprecate_namespace)
         }
+        "DescribeActivityExecution" => {
+            rpc_call_on_trait!(client, call, WorkflowService, describe_activity_execution)
+        }
         "DescribeBatchOperation" => {
             rpc_call_on_trait!(client, call, WorkflowService, describe_batch_operation)
         }
@@ -651,6 +685,9 @@ async fn call_workflow_service(
                 get_workflow_execution_history_reverse
             )
         }
+        "ListActivityExecutions" => {
+            rpc_call_on_trait!(client, call, WorkflowService, list_activity_executions)
+        }
         "ListArchivedWorkflowExecutions" => {
             rpc_call_on_trait!(
                 client,
@@ -692,6 +729,12 @@ async fn call_workflow_service(
         }
         "PatchSchedule" => rpc_call_on_trait!(client, call, WorkflowService, patch_schedule),
         "PauseActivity" => rpc_call_on_trait!(client, call, WorkflowService, pause_activity),
+        "PauseWorkflowExecution" => {
+            rpc_call_on_trait!(client, call, WorkflowService, pause_workflow_execution)
+        }
+        "PollActivityExecution" => {
+            rpc_call_on_trait!(client, call, WorkflowService, poll_activity_execution)
+        }
         "PollActivityTaskQueue" => {
             rpc_call_on_trait!(client, call, WorkflowService, poll_activity_task_queue)
         }
@@ -728,6 +771,14 @@ async fn call_workflow_service(
         "RegisterNamespace" => {
             rpc_call_on_trait!(client, call, WorkflowService, register_namespace)
         }
+        "RequestCancelActivityExecution" => {
+            rpc_call_on_trait!(
+                client,
+                call,
+                WorkflowService,
+                request_cancel_activity_execution
+            )
+        }
         "RequestCancelWorkflowExecution" => {
             rpc_call_on_trait!(
                 client,
@@ -837,15 +888,21 @@ async fn call_workflow_service(
         "SignalWorkflowExecution" => {
             rpc_call_on_trait!(client, call, WorkflowService, signal_workflow_execution)
         }
-        "StartWorkflowExecution" => {
-            rpc_call_on_trait!(client, call, WorkflowService, start_workflow_execution)
+        "StartActivityExecution" => {
+            rpc_call_on_trait!(client, call, WorkflowService, start_activity_execution)
         }
         "StartBatchOperation" => {
             rpc_call_on_trait!(client, call, WorkflowService, start_batch_operation)
         }
+        "StartWorkflowExecution" => {
+            rpc_call_on_trait!(client, call, WorkflowService, start_workflow_execution)
+        }
         "StopBatchOperation" => {
             rpc_call_on_trait!(client, call, WorkflowService, stop_batch_operation)
         }
+        "TerminateActivityExecution" => {
+            rpc_call_on_trait!(client, call, WorkflowService, terminate_activity_execution)
+        }
         "TerminateWorkflowExecution" => {
             rpc_call_on_trait!(client, call, WorkflowService, terminate_workflow_execution)
         }
@@ -855,6 +912,9 @@ async fn call_workflow_service(
         "UnpauseActivity" => {
             rpc_call_on_trait!(client, call, WorkflowService, unpause_activity)
         }
+        "UnpauseWorkflowExecution" => {
+            rpc_call_on_trait!(client, call, WorkflowService, unpause_workflow_execution)
+        }
         "UpdateActivityOptions" => {
             rpc_call_on_trait!(client, call, WorkflowService, update_activity_options)
         }
@@ -904,7 +964,7 @@ async fn call_workflow_service(
 }
 
 async fn call_operator_service(
-    client: &CoreClient,
+    client: &CoreConnection,
     call: &RpcCallOptions,
 ) -> anyhow::Result<Vec<u8>> {
     let rpc = call.rpc.to_str();
@@ -944,7 +1004,10 @@ async fn call_operator_service(
     }
 }
 
-async fn call_cloud_service(client: &CoreClient, call: &RpcCallOptions) -> anyhow::Result<Vec<u8>> {
+async fn call_cloud_service(
+    client: &CoreConnection,
+    call: &RpcCallOptions,
+) -> anyhow::Result<Vec<u8>> {
     let rpc = call.rpc.to_str();
     let mut client = client.clone();
     match rpc {
@@ -1073,7 +1136,10 @@ async fn call_cloud_service(client: &CoreClient, call: &RpcCallOptions) -> anyho
     }
 }
 
-async fn call_test_service(client: &CoreClient, call: &RpcCallOptions) -> anyhow::Result<Vec<u8>> {
+async fn call_test_service(
+    client: &CoreConnection,
+    call: &RpcCallOptions,
+) -> anyhow::Result<Vec<u8>> {
     let rpc = call.rpc.to_str();
     let mut client = client.clone();
     match rpc {
@@ -1090,7 +1156,7 @@ async fn call_test_service(client: &CoreClient, call: &RpcCallOptions) -> anyhow
 }
 
 async fn call_health_service(
-    client: &CoreClient,
+    client: &CoreConnection,
     call: &RpcCallOptions,
 ) -> anyhow::Result<Vec<u8>> {
     let rpc = call.rpc.to_str();
@@ -1110,9 +1176,17 @@ fn rpc_req<P: prost::Message + Default>(
     let proto = P::decode(call.req.to_slice())?;
     let mut req = tonic::Request::new(proto);
     if call.metadata.size > 0 {
-        for (k, v) in call.metadata.to_str_map_on_newlines() {
+        for (k, v) in call.metadata.to_string_map_on_newlines() {
             req.metadata_mut()
-                .insert(MetadataKey::from_str(k)?, v.parse()?);
+                .insert(MetadataKey::from_str(k.as_str())?, v.parse()?);
+        }
+    }
+    if call.binary_metadata.size > 0 {
+        for (k, v) in call.binary_metadata.to_vec_map_on_newlines() {
+            req.metadata_mut().insert_bin(
+                MetadataKey::from_str(k.as_str())?,
+                MetadataValue::from_bytes(v.as_slice()),
+            );
         }
     }
     if call.timeout_millis > 0 {
@@ -1129,10 +1203,10 @@ where
     Ok(res?.get_ref().encode_to_vec())
 }
 
-impl TryFrom<&ClientOptions> for CoreClientOptions {
+impl TryFrom<&ConnectionOptions> for temporalio_client::ConnectionOptions {
     type Error = anyhow::Error;
 
-    fn try_from(opts: &ClientOptions) -> anyhow::Result<Self> {
+    fn try_from(opts: &ConnectionOptions) -> anyhow::Result<Self> {
         let tls_cfg = unsafe { opts.tls_options.as_ref() }
             .map(|c| c.try_into())
             .transpose()?;
@@ -1148,34 +1222,42 @@ impl TryFrom<&ClientOptions> for CoreClientOptions {
             Some(opts.metadata.to_string_map_on_newlines())
         };
 
+        let binary_headers = if opts.binary_metadata.size == 0 {
+            None
+        } else {
+            Some(opts.binary_metadata.to_vec_map_on_newlines())
+        };
+
         let api_key = opts.api_key.to_option_string();
 
         let http_connect_proxy =
             unsafe { opts.http_connect_proxy_options.as_ref() }.map(Into::into);
 
-        Ok(CoreClientOptions::builder()
-            .target_url(Url::parse(opts.target_url.to_str())?)
-            .client_name(opts.client_name.to_string())
-            .client_version(opts.client_version.to_string())
-            .identity(opts.identity.to_string())
-            .retry_options(
-                unsafe { opts.retry_options.as_ref() }
-                    .map_or(RetryOptions::default(), |c| c.into()),
-            )
-            .maybe_keep_alive(keep_alive.map(Some))
-            .maybe_headers(headers)
-            .maybe_api_key(api_key)
-            .maybe_http_connect_proxy(http_connect_proxy)
-            .maybe_tls_options(tls_cfg)
-            .build())
+        Ok(
+            temporalio_client::ConnectionOptions::new(Url::parse(opts.target_url.to_str())?)
+                .client_name(opts.client_name.to_string())
+                .client_version(opts.client_version.to_string())
+                .identity(opts.identity.to_string())
+                .retry_options(
+                    unsafe { opts.retry_options.as_ref() }
+                        .map_or(RetryOptions::default(), |c| c.into()),
+                )
+                .keep_alive(keep_alive)
+                .maybe_headers(headers)
+                .maybe_binary_headers(binary_headers)
+                .maybe_api_key(api_key)
+                .maybe_http_connect_proxy(http_connect_proxy)
+                .maybe_tls_options(tls_cfg)
+                .build(),
+        )
     }
 }
 
-impl TryFrom<&ClientTlsOptions> for CoreTlsOptions {
+impl TryFrom<&ClientTlsOptions> for temporalio_client::TlsOptions {
     type Error = anyhow::Error;
 
     fn try_from(opts: &ClientTlsOptions) -> anyhow::Result<Self> {
-        Ok(CoreTlsOptions {
+        Ok(temporalio_client::TlsOptions {
             server_root_ca_cert: opts.server_root_ca_cert.to_option_vec(),
             domain: opts.domain.to_option_string(),
             client_tls_options: match (
@@ -1183,10 +1265,12 @@ impl TryFrom<&ClientTlsOptions> for CoreTlsOptions {
                 opts.client_private_key.to_option_vec(),
             ) {
                 (None, None) => None,
-                (Some(client_cert), Some(client_private_key)) => Some(CoreClientTlsOptions {
-                    client_cert,
-                    client_private_key,
-                }),
+                (Some(client_cert), Some(client_private_key)) => {
+                    Some(temporalio_client::ClientTlsOptions {
+                        client_cert,
+                        client_private_key,
+                    })
+                }
                 _ => {
                     return Err(anyhow::anyhow!(
                         "Must have both client cert and private key or neither"
@@ -1197,9 +1281,9 @@ impl TryFrom<&ClientTlsOptions> for CoreTlsOptions {
     }
 }
 
-impl From<&ClientRetryOptions> for RetryOptions {
+impl From<&ClientRetryOptions> for temporalio_client::RetryOptions {
     fn from(opts: &ClientRetryOptions) -> Self {
-        RetryOptions {
+        temporalio_client::RetryOptions {
             initial_interval: Duration::from_millis(opts.initial_interval_millis),
             randomization_factor: opts.randomization_factor,
             multiplier: opts.multiplier,
@@ -1214,18 +1298,18 @@ impl From<&ClientRetryOptions> for RetryOptions {
     }
 }
 
-impl From<&ClientKeepAliveOptions> for CoreClientKeepAliveOptions {
+impl From<&ClientKeepAliveOptions> for temporalio_client::ClientKeepAliveOptions {
     fn from(opts: &ClientKeepAliveOptions) -> Self {
-        CoreClientKeepAliveOptions {
+        temporalio_client::ClientKeepAliveOptions {
             interval: Duration::from_millis(opts.interval_millis),
             timeout: Duration::from_millis(opts.timeout_millis),
         }
     }
 }
 
-impl From<&ClientHttpConnectProxyOptions> for HttpConnectProxyOptions {
+impl From<&ClientHttpConnectProxyOptions> for temporalio_client::proxy::HttpConnectProxyOptions {
     fn from(opts: &ClientHttpConnectProxyOptions) -> Self {
-        HttpConnectProxyOptions {
+        temporalio_client::proxy::HttpConnectProxyOptions {
             target_addr: opts.target_host.to_string(),
             basic_auth: if opts.username.size != 0 && opts.password.size != 0 {
                 Some((opts.username.to_string(), opts.password.to_string()))
@@ -1235,3 +1319,12 @@ impl From<&ClientHttpConnectProxyOptions> for HttpConnectProxyOptions {
         }
     }
 }
+
+impl From<&GrpcMetadataHolder> for MetadataRef {
+    fn from(value: &GrpcMetadataHolder) -> Self {
+        MetadataRef {
+            data: value.data.as_ptr(),
+            size: value.data.len(),
+        }
+    }
+}

package/sdk-core/crates/sdk-core-c-bridge/src/lib.rs

@@ -27,6 +27,8 @@ pub struct ByteArrayRef {
     pub size: libc::size_t,
 }
 
+unsafe impl Sync for ByteArrayRef {}
+
 impl ByteArrayRef {
     pub fn empty() -> ByteArrayRef {
         static EMPTY: &str = "";
@@ -98,6 +100,24 @@ impl ByteArrayRef {
             .map(|(k, v)| (k.to_string(), v.to_string()))
             .collect()
     }
+
+    pub fn to_option_str_key_value_pair(&self) -> Option<(&str, ByteArrayRef)> {
+        if let Some(index) = self.to_slice().iter().position(|&x| x == b'\n') {
+            let key_str = unsafe {
+                std::str::from_utf8_unchecked(std::slice::from_raw_parts(self.data, index))
+            };
+            let value = ByteArrayRef {
+                data: unsafe { self.data.add(index + 1) },
+                size: self.size - index - 1,
+            };
+            let _value_str = unsafe {
+                std::str::from_utf8_unchecked(std::slice::from_raw_parts(value.data, value.size))
+            };
+            Some((key_str, value))
+        } else {
+            None
+        }
+    }
 }
 
 impl From<&str> for ByteArrayRef {
@@ -118,6 +138,15 @@ impl From<&[u8]> for ByteArrayRef {
     }
 }
 
+impl From<&Vec<u8>> for ByteArrayRef {
+    fn from(value: &Vec<u8>) -> ByteArrayRef {
+        ByteArrayRef {
+            data: value.as_ptr(),
+            size: value.len(),
+        }
+    }
+}
+
 impl<T> From<Option<T>> for ByteArrayRef
 where
     T: Into<ByteArrayRef>,
@@ -134,19 +163,74 @@ pub struct ByteArrayRefArray {
 }
 
 impl ByteArrayRefArray {
+    pub fn empty() -> ByteArrayRefArray {
+        static EMPTY: &[ByteArrayRef] = &[];
+        EMPTY.into()
+    }
+
+    pub fn to_slice(&self) -> &[ByteArrayRef] {
+        unsafe { std::slice::from_raw_parts(self.data, self.size) }
+    }
+
     pub fn to_str_vec(&self) -> Vec<&str> {
         if self.size == 0 {
             vec![]
         } else {
-            let raw = unsafe { std::slice::from_raw_parts(self.data, self.size) };
-            raw.iter().map(ByteArrayRef::to_str).collect()
+            self.to_slice().iter().map(ByteArrayRef::to_str).collect()
+        }
+    }
+
+    fn to_bytearrayref_map_on_newlines(&self) -> HashMap<&str, ByteArrayRef> {
+        if self.size == 0 {
+            HashMap::new()
+        } else {
+            self.to_slice()
+                .iter()
+                .filter_map(ByteArrayRef::to_option_str_key_value_pair)
+                .collect()
         }
     }
+
+    pub fn to_string_map_on_newlines(&self) -> HashMap<String, String> {
+        self.to_bytearrayref_map_on_newlines()
+            .iter()
+            .map(|(k, v)| (k.to_string(), v.to_string()))
+            .collect()
+    }
+
+    pub fn to_vec_map_on_newlines(&self) -> HashMap<String, Vec<u8>> {
+        self.to_bytearrayref_map_on_newlines()
+            .iter()
+            .map(|(k, v)| (k.to_string(), v.to_vec()))
+            .collect()
+    }
 }
 
-/// Metadata is `<key1>\n<value1>\n<key2>\n<value2>`. Metadata keys or
-/// values cannot contain a newline within.
-pub type MetadataRef = ByteArrayRef;
+impl From<&[ByteArrayRef]> for ByteArrayRefArray {
+    fn from(value: &[ByteArrayRef]) -> ByteArrayRefArray {
+        ByteArrayRefArray {
+            data: value.as_ptr(),
+            size: value.len(),
+        }
+    }
+}
+
+impl<T> From<Option<T>> for ByteArrayRefArray
+where
+    T: Into<ByteArrayRefArray>,
+{
+    fn from(value: Option<T>) -> ByteArrayRefArray {
+        value.map(Into::into).unwrap_or(ByteArrayRefArray::empty())
+    }
+}
+
+/// Each ByteArrayRef is `<key>\n<value>`.
+/// Keys cannot contain a newline.
+pub type MetadataRef = ByteArrayRefArray;
+
+/// Data is `<key1>\n<value1>\n<key2>\n<value2>`.
+/// Keys and values cannot contain a newline within.
+pub type NewlineDelimitedMapRef = ByteArrayRef;
 
 #[repr(C)]
 pub struct ByteArray {