temporalio 0.3.0-x86_64-linux-musl → 0.5.0-x86_64-linux-musl

data/lib/temporalio/internal/client/implementation.rb

@@ -9,6 +9,7 @@ require 'temporalio/client/connection'
 require 'temporalio/client/interceptor'
 require 'temporalio/client/schedule'
 require 'temporalio/client/schedule_handle'
+require 'temporalio/client/with_start_workflow_operation'
 require 'temporalio/client/workflow_execution'
 require 'temporalio/client/workflow_execution_count'
 require 'temporalio/client/workflow_handle'
@@ -41,21 +42,18 @@ module Temporalio
         end
 
         def initialize(client)
-          super(nil)
+          super(nil) # steep:ignore
           @client = client
         end
 
         def start_workflow(input)
-          # TODO(cretz): Signal/update with start
           req = Api::WorkflowService::V1::StartWorkflowExecutionRequest.new(
             request_id: SecureRandom.uuid,
             namespace: @client.namespace,
-            workflow_type: Api::Common::V1::WorkflowType.new(
-              name: Workflow::Definition._workflow_type_from_workflow_parameter(input.workflow)
-            ),
+            workflow_type: Api::Common::V1::WorkflowType.new(name: input.workflow),
             workflow_id: input.workflow_id,
             task_queue: Api::TaskQueue::V1::TaskQueue.new(name: input.task_queue.to_s),
-            input: @client.data_converter.to_payloads(input.args),
+            input: @client.data_converter.to_payloads(input.args, hints: input.arg_hints),
             workflow_execution_timeout: ProtoUtils.seconds_to_duration(input.execution_timeout),
             workflow_run_timeout: ProtoUtils.seconds_to_duration(input.run_timeout),
             workflow_task_timeout: ProtoUtils.seconds_to_duration(input.task_timeout),
@@ -68,7 +66,12 @@ module Temporalio
             search_attributes: input.search_attributes&._to_proto,
             workflow_start_delay: ProtoUtils.seconds_to_duration(input.start_delay),
             request_eager_execution: input.request_eager_start,
-            header: ProtoUtils.headers_to_proto(input.headers, @client.data_converter)
+            user_metadata: ProtoUtils.to_user_metadata(
+              input.static_summary, input.static_details, @client.data_converter
+            ),
+            header: ProtoUtils.headers_to_proto(input.headers, @client.data_converter),
+            priority: input.priority._to_proto,
+            versioning_override: input.versioning_override&._to_proto
           )
 
           # Send request
@@ -100,29 +103,251 @@ module Temporalio
             id: input.workflow_id,
             run_id: nil,
             result_run_id: resp.run_id,
-            first_execution_run_id: resp.run_id
+            first_execution_run_id: resp.run_id,
+            result_hint: input.result_hint
           )
         end
 
-        def list_workflows(input)
-          Enumerator.new do |yielder|
-            req = Api::WorkflowService::V1::ListWorkflowExecutionsRequest.new(
-              namespace: @client.namespace,
-              query: input.query || ''
-            )
+        def start_update_with_start_workflow(input)
+          raise ArgumentError, 'Start operation is required' unless input.start_workflow_operation
+
+          if input.start_workflow_operation.options.id_conflict_policy == WorkflowIDConflictPolicy::UNSPECIFIED
+            raise ArgumentError, 'ID conflict policy is required in start operation'
+          end
+
+          # Try to mark used before using
+          input.start_workflow_operation._mark_used
+
+          # Build request
+          start_options = input.start_workflow_operation.options
+          start_req = _start_workflow_request_from_with_start_options(
+            Api::WorkflowService::V1::StartWorkflowExecutionRequest, start_options
+          )
+          req = Api::WorkflowService::V1::ExecuteMultiOperationRequest.new(
+            namespace: @client.namespace,
+            operations: [
+              Api::WorkflowService::V1::ExecuteMultiOperationRequest::Operation.new(start_workflow: start_req),
+              Api::WorkflowService::V1::ExecuteMultiOperationRequest::Operation.new(
+                update_workflow: Api::WorkflowService::V1::UpdateWorkflowExecutionRequest.new(
+                  namespace: @client.namespace,
+                  workflow_execution: Api::Common::V1::WorkflowExecution.new(
+                    workflow_id: start_options.id
+                  ),
+                  request: Api::Update::V1::Request.new(
+                    meta: Api::Update::V1::Meta.new(
+                      update_id: input.update_id,
+                      identity: @client.connection.identity
+                    ),
+                    input: Api::Update::V1::Input.new(
+                      name: input.update,
+                      args: @client.data_converter.to_payloads(input.args, hints: input.arg_hints),
+                      header: Internal::ProtoUtils.headers_to_proto(input.headers, @client.data_converter)
+                    )
+                  ),
+                  wait_policy: Api::Update::V1::WaitPolicy.new(
+                    lifecycle_stage: input.wait_for_stage
+                  )
+                )
+              )
+            ]
+          )
+
+          # Continually try to start until an exception occurs, the user-asked stage is reached, or the stage is
+          # accepted. But we will set the workflow handle as soon as we can.
+          # @type var update_resp: untyped
+          update_resp = nil
+          run_id = nil
+          begin
             loop do
-              resp = @client.workflow_service.list_workflow_executions(
-                req,
-                rpc_options: Implementation.with_default_rpc_options(input.rpc_options)
+              resp = @client.workflow_service.execute_multi_operation(
+                req, rpc_options: Implementation.with_default_rpc_options(input.rpc_options)
               )
-              resp.executions.each do |raw_info|
-                yielder << Temporalio::Client::WorkflowExecution.new(raw_info, @client.data_converter)
+              run_id = resp.responses.first.start_workflow.run_id
+              # Set workflow handle (no-op if already set)
+              input.start_workflow_operation._set_workflow_handle(
+                Temporalio::Client::WorkflowHandle.new(
+                  client: @client,
+                  id: start_options.id,
+                  run_id: nil,
+                  result_run_id: run_id,
+                  first_execution_run_id: run_id,
+                  result_hint: start_options.result_hint
+                )
+              )
+              update_resp = resp.responses.last.update_workflow
+
+              # We're only done if the response stage is at least accepted
+              if update_resp && Api::Enums::V1::UpdateWorkflowExecutionLifecycleStage.resolve(update_resp.stage) >=
+                                Temporalio::Client::WorkflowUpdateWaitStage::ACCEPTED
+                break
               end
-              break if resp.next_page_token.empty?
+            end
 
-              req.next_page_token = resp.next_page_token
+            # If the user wants to wait until completed, we must poll until outcome if not already there
+            if input.wait_for_stage == Temporalio::Client::WorkflowUpdateWaitStage::COMPLETED && update_resp.outcome
+              update_resp.outcome = @client._impl.poll_workflow_update(
+                Temporalio::Client::Interceptor::PollWorkflowUpdateInput.new(
+                  workflow_id: start_options.id,
+                  run_id:,
+                  update_id: input.update_id,
+                  rpc_options: input.rpc_options
+                )
+              )
+            end
+          rescue Error => e
+            # If this is a multi-operation failure, set exception to the first present, non-OK, non-aborted error
+            if e.is_a?(Error::RPCError)
+              multi_err = e.grpc_status.details&.first&.unpack(Api::ErrorDetails::V1::MultiOperationExecutionFailure)
+              if multi_err
+                non_aborted = multi_err.statuses.find do |s|
+                  # Exists, not-ok, not-aborted
+                  s && s.code != Error::RPCError::Code::OK &&
+                    !s.details&.first&.is(Api::Failure::V1::MultiOperationExecutionAborted)
+                end
+                if non_aborted
+                  e = Error::RPCError.new(
+                    non_aborted.message,
+                    code: non_aborted.code,
+                    raw_grpc_status: Api::Common::V1::GrpcStatus.new(
+                      code: non_aborted.code, message: non_aborted.message, details: non_aborted.details.to_a
+                    )
+                  )
+                end
+              end
+            end
+            if e.is_a?(Error::RPCError)
+              # Deadline exceeded or cancel is a special error type
+              if e.code == Error::RPCError::Code::DEADLINE_EXCEEDED || e.code == Error::RPCError::Code::CANCELED
+                e = Error::WorkflowUpdateRPCTimeoutOrCanceledError.new
+              elsif e.code == Error::RPCError::Code::ALREADY_EXISTS && e.grpc_status.details.first
+                # Unpack and set already started if that's the error
+                details = e.grpc_status.details.first.unpack(
+                  Api::ErrorDetails::V1::WorkflowExecutionAlreadyStartedFailure
+                )
+                if details
+                  e = Error::WorkflowAlreadyStartedError.new(
+                    workflow_id: start_options.id,
+                    workflow_type: start_req.workflow_type,
+                    run_id: details.run_id
+                  )
+                end
+              end
+            end
+            # Cancel is a special type
+            e = Error::WorkflowUpdateRPCTimeoutOrCanceledError.new if e.is_a?(Error::CanceledError)
+            # Before we raise here, we want to try to set the start operation exception (no-op if already set with a
+            # handle)
+            input.start_workflow_operation._set_workflow_handle(e)
+            raise e
+          end
+
+          # Return handle
+          Temporalio::Client::WorkflowUpdateHandle.new(
+            client: @client,
+            id: input.update_id,
+            workflow_id: start_options.id,
+            workflow_run_id: run_id,
+            known_outcome: update_resp.outcome,
+            result_hint: input.result_hint
+          )
+        end
+
+        def signal_with_start_workflow(input)
+          raise ArgumentError, 'Start operation is required' unless input.start_workflow_operation
+
+          # Try to mark used before using
+          input.start_workflow_operation._mark_used
+
+          # Build req
+          start_options = input.start_workflow_operation.options
+          req = _start_workflow_request_from_with_start_options(
+            Api::WorkflowService::V1::SignalWithStartWorkflowExecutionRequest, start_options
+          )
+          req.signal_name = input.signal
+          req.signal_input = @client.data_converter.to_payloads(input.args, hints: input.arg_hints)
+
+          # Send request
+          begin
+            resp = @client.workflow_service.signal_with_start_workflow_execution(
+              req,
+              rpc_options: Implementation.with_default_rpc_options(input.rpc_options)
+            )
+          rescue Error::RPCError => e
+            # Unpack and raise already started if that's the error, otherwise default raise
+            if e.code == Error::RPCError::Code::ALREADY_EXISTS && e.grpc_status.details.first
+              details = e.grpc_status.details.first.unpack(
+                Api::ErrorDetails::V1::WorkflowExecutionAlreadyStartedFailure
+              )
+              if details
+                e = Error::WorkflowAlreadyStartedError.new(
+                  workflow_id: req.workflow_id,
+                  workflow_type: req.workflow_type.name,
+                  run_id: details.run_id
+                )
+              end
             end
+            # Before we raise here, we want to the start operation exception
+            input.start_workflow_operation._set_workflow_handle(e)
+            raise e
           end
+
+          # Set handle and return handle
+          handle = Temporalio::Client::WorkflowHandle.new(
+            client: @client,
+            id: start_options.id,
+            run_id: nil,
+            result_run_id: resp.run_id,
+            first_execution_run_id: resp.run_id,
+            result_hint: start_options.result_hint
+          )
+          input.start_workflow_operation._set_workflow_handle(handle)
+          handle
+        end
+
+        def _start_workflow_request_from_with_start_options(klass, start_options)
+          klass.new(
+            request_id: SecureRandom.uuid,
+            namespace: @client.namespace,
+            workflow_type: Api::Common::V1::WorkflowType.new(name: start_options.workflow),
+            workflow_id: start_options.id,
+            task_queue: Api::TaskQueue::V1::TaskQueue.new(name: start_options.task_queue.to_s),
+            input: @client.data_converter.to_payloads(start_options.args, hints: start_options.arg_hints),
+            workflow_execution_timeout: ProtoUtils.seconds_to_duration(start_options.execution_timeout),
+            workflow_run_timeout: ProtoUtils.seconds_to_duration(start_options.run_timeout),
+            workflow_task_timeout: ProtoUtils.seconds_to_duration(start_options.task_timeout),
+            identity: @client.connection.identity,
+            workflow_id_reuse_policy: start_options.id_reuse_policy,
+            workflow_id_conflict_policy: start_options.id_conflict_policy,
+            retry_policy: start_options.retry_policy&._to_proto,
+            cron_schedule: start_options.cron_schedule,
+            memo: ProtoUtils.memo_to_proto(start_options.memo, @client.data_converter),
+            search_attributes: start_options.search_attributes&._to_proto,
+            workflow_start_delay: ProtoUtils.seconds_to_duration(start_options.start_delay),
+            user_metadata: ProtoUtils.to_user_metadata(
+              start_options.static_summary, start_options.static_details, @client.data_converter
+            ),
+            header: ProtoUtils.headers_to_proto(start_options.headers, @client.data_converter)
+          )
+        end
+
+        def list_workflow_page(input)
+          req = Api::WorkflowService::V1::ListWorkflowExecutionsRequest.new(
+            namespace: @client.namespace,
+            query: input.query || '',
+            next_page_token: input.next_page_token,
+            page_size: input.page_size
+          )
+          resp = @client.workflow_service.list_workflow_executions(
+            req,
+            rpc_options: Implementation.with_default_rpc_options(input.rpc_options)
+          )
+          executions = resp.executions.map do |raw_info|
+            Temporalio::Client::WorkflowExecution.new(raw_info, @client.data_converter)
+          end
+          Temporalio::Client::ListWorkflowPage.new(
+            executions: executions,
+            next_page_token: resp.next_page_token
+          )
         end
 
         def count_workflows(input)
@@ -191,8 +416,8 @@ module Temporalio
                 workflow_id: input.workflow_id,
                 run_id: input.run_id || ''
               ),
-              signal_name: Workflow::Definition::Signal._name_from_parameter(input.signal),
-              input: @client.data_converter.to_payloads(input.args),
+              signal_name: input.signal,
+              input: @client.data_converter.to_payloads(input.args, hints: input.arg_hints),
               header: Internal::ProtoUtils.headers_to_proto(input.headers, @client.data_converter),
               identity: @client.connection.identity,
               request_id: SecureRandom.uuid
@@ -212,8 +437,8 @@ module Temporalio
                   run_id: input.run_id || ''
                 ),
                 query: Api::Query::V1::WorkflowQuery.new(
-                  query_type: Workflow::Definition::Query._name_from_parameter(input.query),
-                  query_args: @client.data_converter.to_payloads(input.args),
+                  query_type: input.query,
+                  query_args: @client.data_converter.to_payloads(input.args, hints: input.arg_hints),
                   header: Internal::ProtoUtils.headers_to_proto(input.headers, @client.data_converter)
                 ),
                 query_reject_condition: input.reject_condition || 0
@@ -233,7 +458,7 @@ module Temporalio
             ))
           end
 
-          results = @client.data_converter.from_payloads(resp.query_result)
+          results = @client.data_converter.from_payloads(resp.query_result, hints: Array(input.result_hint))
           warn("Expected 0 or 1 query result, got #{results.size}") if results.size > 1
           results&.first
         end
@@ -255,8 +480,8 @@ module Temporalio
                 identity: @client.connection.identity
               ),
               input: Api::Update::V1::Input.new(
-                name: Workflow::Definition::Update._name_from_parameter(input.update),
-                args: @client.data_converter.to_payloads(input.args),
+                name: input.update,
+                args: @client.data_converter.to_payloads(input.args, hints: input.arg_hints),
                 header: Internal::ProtoUtils.headers_to_proto(input.headers, @client.data_converter)
               )
             ),
@@ -270,6 +495,10 @@ module Temporalio
           # the user cannot specify sooner than ACCEPTED)
           # @type var resp: untyped
           resp = nil
+          expected_stage = ProtoUtils.enum_to_int(Api::Enums::V1::UpdateWorkflowExecutionLifecycleStage,
+                                                  req.wait_policy.lifecycle_stage)
+          accepted_stage = ProtoUtils.enum_to_int(Api::Enums::V1::UpdateWorkflowExecutionLifecycleStage,
+                                                  Temporalio::Client::WorkflowUpdateWaitStage::ACCEPTED)
           loop do
             resp = @client.workflow_service.update_workflow_execution(
               req,
@@ -278,17 +507,17 @@ module Temporalio
 
             # We're only done if the response stage is after the requested stage
             # or the response stage is accepted
-            if resp.stage >= req.wait_policy.lifecycle_stage ||
-               resp.stage >= Temporalio::Client::WorkflowUpdateWaitStage::ACCEPTED
-              break
-            end
+            actual_stage = ProtoUtils.enum_to_int(Api::Enums::V1::UpdateWorkflowExecutionLifecycleStage, resp.stage)
+            break if actual_stage >= expected_stage || actual_stage >= accepted_stage
           rescue Error::RPCError => e
             # Deadline exceeded or cancel is a special error type
-            if e.code == Error::RPCError::Code::DEADLINE_EXCEEDED || e.code == Error::RPCError::Code::CANCELLED
+            if e.code == Error::RPCError::Code::DEADLINE_EXCEEDED || e.code == Error::RPCError::Code::CANCELED
               raise Error::WorkflowUpdateRPCTimeoutOrCanceledError
             end
 
             raise
+          rescue Error::CanceledError
+            raise Error::WorkflowUpdateRPCTimeoutOrCanceledError
           end
 
           # If the user wants to wait until completed, we must poll until outcome
@@ -309,7 +538,8 @@ module Temporalio
             id: input.update_id,
             workflow_id: input.workflow_id,
             workflow_run_id: input.run_id,
-            known_outcome: resp.outcome
+            known_outcome: resp.outcome,
+            result_hint: input.result_hint
           )
         end
 
@@ -338,7 +568,7 @@ module Temporalio
             return resp.outcome if resp.outcome
           rescue Error::RPCError => e
             # Deadline exceeded or cancel is a special error type
-            if e.code == Error::RPCError::Code::DEADLINE_EXCEEDED || e.code == Error::RPCError::Code::CANCELLED
+            if e.code == Error::RPCError::Code::DEADLINE_EXCEEDED || e.code == Error::RPCError::Code::CANCELED
               raise Error::WorkflowUpdateRPCTimeoutOrCanceledError
             end
 
@@ -584,7 +814,7 @@ module Temporalio
                        activity_id: input.task_token_or_id_reference.activity_id,
                        namespace: @client.namespace,
                        identity: @client.connection.identity,
-                       details: @client.data_converter.to_payloads(input.details)
+                       details: @client.data_converter.to_payloads(input.details, hints: input.detail_hints)
                      ),
                      rpc_options: Implementation.with_default_rpc_options(input.rpc_options)
                    )
@@ -594,7 +824,7 @@ module Temporalio
                        task_token: input.task_token_or_id_reference,
                        namespace: @client.namespace,
                        identity: @client.connection.identity,
-                       details: @client.data_converter.to_payloads(input.details)
+                       details: @client.data_converter.to_payloads(input.details, hints: input.detail_hints)
                      ),
                      rpc_options: Implementation.with_default_rpc_options(input.rpc_options)
                    )
@@ -613,7 +843,7 @@ module Temporalio
                 activity_id: input.task_token_or_id_reference.activity_id,
                 namespace: @client.namespace,
                 identity: @client.connection.identity,
-                result: @client.data_converter.to_payloads([input.result])
+                result: @client.data_converter.to_payloads([input.result], hints: Array(input.result_hint))
               ),
               rpc_options: Implementation.with_default_rpc_options(input.rpc_options)
             )
@@ -623,7 +853,7 @@ module Temporalio
                 task_token: input.task_token_or_id_reference,
                 namespace: @client.namespace,
                 identity: @client.connection.identity,
-                result: @client.data_converter.to_payloads([input.result])
+                result: @client.data_converter.to_payloads([input.result], hints: Array(input.result_hint))
               ),
               rpc_options: Implementation.with_default_rpc_options(input.rpc_options)
             )
@@ -632,6 +862,14 @@ module Temporalio
         end
 
         def fail_async_activity(input)
+          last_heartbeat_details = if input.last_heartbeat_details.empty?
+                                     nil
+                                   else
+                                     @client.data_converter.to_payloads(
+                                       input.last_heartbeat_details,
+                                       hints: input.last_heartbeat_detail_hints
+                                     )
+                                   end
           if input.task_token_or_id_reference.is_a?(Temporalio::Client::ActivityIDReference)
             @client.workflow_service.respond_activity_task_failed_by_id(
               Api::WorkflowService::V1::RespondActivityTaskFailedByIdRequest.new(
@@ -641,11 +879,7 @@ module Temporalio
                 namespace: @client.namespace,
                 identity: @client.connection.identity,
                 failure: @client.data_converter.to_failure(input.error),
-                last_heartbeat_details: if input.last_heartbeat_details.empty?
-                                          nil
-                                        else
-                                          @client.data_converter.to_payloads(input.last_heartbeat_details)
-                                        end
+                last_heartbeat_details:
               ),
               rpc_options: Implementation.with_default_rpc_options(input.rpc_options)
             )
@@ -656,11 +890,7 @@ module Temporalio
                 namespace: @client.namespace,
                 identity: @client.connection.identity,
                 failure: @client.data_converter.to_failure(input.error),
-                last_heartbeat_details: if input.last_heartbeat_details.empty?
-                                          nil
-                                        else
-                                          @client.data_converter.to_payloads(input.last_heartbeat_details)
-                                        end
+                last_heartbeat_details:
               ),
               rpc_options: Implementation.with_default_rpc_options(input.rpc_options)
             )
@@ -677,7 +907,7 @@ module Temporalio
                 activity_id: input.task_token_or_id_reference.activity_id,
                 namespace: @client.namespace,
                 identity: @client.connection.identity,
-                details: @client.data_converter.to_payloads(input.details)
+                details: @client.data_converter.to_payloads(input.details, hints: input.detail_hints)
               ),
               rpc_options: Implementation.with_default_rpc_options(input.rpc_options)
             )
@@ -687,7 +917,7 @@ module Temporalio
                 task_token: input.task_token_or_id_reference,
                 namespace: @client.namespace,
                 identity: @client.connection.identity,
-                details: @client.data_converter.to_payloads(input.details)
+                details: @client.data_converter.to_payloads(input.details, hints: input.detail_hints)
               ),
               rpc_options: Implementation.with_default_rpc_options(input.rpc_options)
             )

data/lib/temporalio/internal/proto_utils.rb

@@ -51,7 +51,7 @@ module Temporalio
       end
 
       def self.memo_from_proto(memo, converter)
-        return nil if memo.nil? || memo.fields.size.zero? # rubocop:disable Style/ZeroLengthPredicate Google Maps don't have empty
+        return nil if memo.nil? || memo.fields.size.zero? # rubocop:disable Style/ZeroLengthPredicate -- Google Maps don't have empty
 
         memo.fields.each_with_object({}) { |(key, val), h| h[key] = converter.from_payload(val) } # rubocop:disable Style/HashTransformValues
       end
@@ -73,7 +73,7 @@ module Temporalio
       end
 
       def self.headers_from_proto_map(headers, converter)
-        return nil if headers.nil? || headers.size.zero? # rubocop:disable Style/ZeroLengthPredicate Google Maps don't have empty
+        return nil if headers.nil? || headers.size.zero? # rubocop:disable Style/ZeroLengthPredicate -- Google Maps don't have empty
 
         headers.each_with_object({}) do |(key, val), h| # rubocop:disable Style/HashTransformValues
           # @type var h: Hash[String, Object?]
@@ -94,16 +94,48 @@ module Temporalio
         enum_val
       end
 
-      def self.convert_from_payload_array(converter, payloads)
+      def self.convert_from_payload_array(converter, payloads, hints:)
         return [] if payloads.empty?
 
-        converter.from_payloads(Api::Common::V1::Payloads.new(payloads:))
+        converter.from_payloads(Api::Common::V1::Payloads.new(payloads:), hints:)
       end
 
-      def self.convert_to_payload_array(converter, values)
+      def self.convert_to_payload_array(converter, values, hints:)
         return [] if values.empty?
 
-        converter.to_payloads(values).payloads.to_ary
+        converter.to_payloads(values, hints:).payloads.to_ary
+      end
+
+      def self.assert_non_reserved_name(name)
+        name = name&.to_s # In case it's a symbol or not present
+        return unless name
+        raise "'#{name}' cannot start with '__temporal_'" if name.start_with?('__temporal_')
+        # Might as well disable __stack_trace and __enhanced_stack_trace everywhere even though technically it's only
+        # reserved for queries
+        raise "'#{name}' name invalid" if name == '__stack_trace' || name == '__enhanced_stack_trace'
+      end
+
+      def self.reserved_name?(name)
+        name = name&.to_s # In case it's a symbol or not present
+        return false unless name
+
+        name.start_with?('__temporal_') || name == '__stack_trace' || name == '__enhanced_stack_trace'
+      end
+
+      def self.to_user_metadata(summary, details, converter)
+        return nil if (!summary || summary.empty?) && (!details || details.empty?)
+
+        metadata = Temporalio::Api::Sdk::V1::UserMetadata.new
+        metadata.summary = converter.to_payload(summary) if summary && !summary.empty?
+        metadata.details = converter.to_payload(details) if details && !details.empty?
+        metadata
+      end
+
+      def self.from_user_metadata(metadata, converter)
+        [
+          (converter.from_payload(metadata.summary) if metadata&.summary), #: String?
+          (converter.from_payload(metadata.details) if metadata&.details) #: String?
+        ]
       end
 
       class LazyMemo