volcano-sdk 0.32.6 → 0.33.0

data/lib/volcano/generated/lib/volcano-generated/models/update_sandbox_template_request.rb

@@ -0,0 +1,175 @@
+=begin
+#Volcano Hosting API
+
+#Public API for Volcano Hosting clients, SDKs, and CLI tooling (Port 8000).  This specification intentionally excludes first-party/internal APIs. See api/openapi-internal.yaml for non-public internal and Builder operations.
+
+The version of the OpenAPI document: 3.0.0
+Contact: support@volcano.dev
+Generated by: https://openapi-generator.tech
+Generator version: 7.17.0
+
+=end
+
+require 'date'
+require 'time'
+
+module Volcano::Generated
+  class UpdateSandboxTemplateRequest < ApiModelBase
+    attr_accessor :name
+
+    # Attribute mapping from ruby-style variable name to JSON key.
+    def self.attribute_map
+      {
+        :'name' => :'name'
+      }
+    end
+
+    # Returns attribute mapping this model knows about
+    def self.acceptable_attribute_map
+      attribute_map
+    end
+
+    # Returns all the JSON keys this model knows about
+    def self.acceptable_attributes
+      acceptable_attribute_map.values
+    end
+
+    # Attribute type mapping.
+    def self.openapi_types
+      {
+        :'name' => :'String'
+      }
+    end
+
+    # List of attributes with nullable: true
+    def self.openapi_nullable
+      Set.new([
+      ])
+    end
+
+    # Initializes the object
+    # @param [Hash] attributes Model attributes in the form of hash
+    def initialize(attributes = {})
+      if (!attributes.is_a?(Hash))
+        fail ArgumentError, "The input argument (attributes) must be a hash in `Volcano::Generated::UpdateSandboxTemplateRequest` initialize method"
+      end
+
+      # check to see if the attribute exists and convert string to symbol for hash key
+      acceptable_attribute_map = self.class.acceptable_attribute_map
+      attributes = attributes.each_with_object({}) { |(k, v), h|
+        if (!acceptable_attribute_map.key?(k.to_sym))
+          fail ArgumentError, "`#{k}` is not a valid attribute in `Volcano::Generated::UpdateSandboxTemplateRequest`. Please check the name to make sure it's valid. List of attributes: " + acceptable_attribute_map.keys.inspect
+        end
+        h[k.to_sym] = v
+      }
+
+      if attributes.key?(:'name')
+        self.name = attributes[:'name']
+      else
+        self.name = nil
+      end
+    end
+
+    # Show invalid properties with the reasons. Usually used together with valid?
+    # @return Array for valid properties with the reasons
+    def list_invalid_properties
+      warn '[DEPRECATED] the `list_invalid_properties` method is obsolete'
+      invalid_properties = Array.new
+      if @name.nil?
+        invalid_properties.push('invalid value for "name", name cannot be nil.')
+      end
+
+      pattern = Regexp.new(/^[a-z][a-z0-9-]{0,62}$/)
+      if @name !~ pattern
+        invalid_properties.push("invalid value for \"name\", must conform to the pattern #{pattern}.")
+      end
+
+      invalid_properties
+    end
+
+    # Check to see if the all the properties in the model are valid
+    # @return true if the model is valid
+    def valid?
+      warn '[DEPRECATED] the `valid?` method is obsolete'
+      return false if @name.nil?
+      return false if @name !~ Regexp.new(/^[a-z][a-z0-9-]{0,62}$/)
+      true
+    end
+
+    # Custom attribute writer method with validation
+    # @param [Object] name Value to be assigned
+    def name=(name)
+      if name.nil?
+        fail ArgumentError, 'name cannot be nil'
+      end
+
+      pattern = Regexp.new(/^[a-z][a-z0-9-]{0,62}$/)
+      if name !~ pattern
+        fail ArgumentError, "invalid value for \"name\", must conform to the pattern #{pattern}."
+      end
+
+      @name = name
+    end
+
+    # Checks equality by comparing each attribute.
+    # @param [Object] Object to be compared
+    def ==(o)
+      return true if self.equal?(o)
+      self.class == o.class &&
+          name == o.name
+    end
+
+    # @see the `==` method
+    # @param [Object] Object to be compared
+    def eql?(o)
+      self == o
+    end
+
+    # Calculates hash code according to all attributes.
+    # @return [Integer] Hash code
+    def hash
+      [name].hash
+    end
+
+    # Builds the object from hash
+    # @param [Hash] attributes Model attributes in the form of hash
+    # @return [Object] Returns the model itself
+    def self.build_from_hash(attributes)
+      return nil unless attributes.is_a?(Hash)
+      attributes = attributes.transform_keys(&:to_sym)
+      transformed_hash = {}
+      openapi_types.each_pair do |key, type|
+        if attributes.key?(attribute_map[key]) && attributes[attribute_map[key]].nil?
+          transformed_hash["#{key}"] = nil
+        elsif type =~ /\AArray<(.*)>/i
+          # check to ensure the input is an array given that the attribute
+          # is documented as an array but the input is not
+          if attributes[attribute_map[key]].is_a?(Array)
+            transformed_hash["#{key}"] = attributes[attribute_map[key]].map { |v| _deserialize($1, v) }
+          end
+        elsif !attributes[attribute_map[key]].nil?
+          transformed_hash["#{key}"] = _deserialize(type, attributes[attribute_map[key]])
+        end
+      end
+      new(transformed_hash)
+    end
+
+    # Returns the object in the form of hash
+    # @return [Hash] Returns the object in the form of hash
+    def to_hash
+      hash = {}
+      self.class.attribute_map.each_pair do |attr, param|
+        value = self.send(attr)
+        if value.nil?
+          is_nullable = self.class.openapi_nullable.include?(attr)
+          next if !is_nullable || (is_nullable && !instance_variable_defined?(:"@#{attr}"))
+        end
+
+        hash[param] = _to_hash(value)
+      end
+      hash
+    end
+
+  end
+
+end

data/lib/volcano/generated/lib/volcano-generated.rb

@@ -94,6 +94,8 @@ Volcano::Generated.autoload :CreateFrontendCustomDomainRequest, 'volcano-generat
 Volcano::Generated.autoload :CreateFunctionSchedulerRequest, 'volcano-generated/models/create_function_scheduler_request'
 Volcano::Generated.autoload :CreateOAuthConfigRequest, 'volcano-generated/models/create_o_auth_config_request'
 Volcano::Generated.autoload :CreateProjectRequest, 'volcano-generated/models/create_project_request'
+Volcano::Generated.autoload :CreateSandboxSessionRequest, 'volcano-generated/models/create_sandbox_session_request'
+Volcano::Generated.autoload :CreateSandboxTemplateRequest, 'volcano-generated/models/create_sandbox_template_request'
 Volcano::Generated.autoload :CreateServiceKeyRequest, 'volcano-generated/models/create_service_key_request'
 Volcano::Generated.autoload :CreateStorageBucketRequest, 'volcano-generated/models/create_storage_bucket_request'
 Volcano::Generated.autoload :CreateStoragePolicyRequest, 'volcano-generated/models/create_storage_policy_request'
@@ -324,6 +326,7 @@ Volcano::Generated.autoload :ProjectSourceExportOmission, 'volcano-generated/mod
 Volcano::Generated.autoload :ProjectSourceExportSkip, 'volcano-generated/models/project_source_export_skip'
 Volcano::Generated.autoload :ProjectSourceExportState, 'volcano-generated/models/project_source_export_state'
 Volcano::Generated.autoload :ProjectUsageResponse, 'volcano-generated/models/project_usage_response'
+Volcano::Generated.autoload :PublishSandboxPresetRequest, 'volcano-generated/models/publish_sandbox_preset_request'
 Volcano::Generated.autoload :RealtimeConfig, 'volcano-generated/models/realtime_config'
 Volcano::Generated.autoload :RealtimePlanLimits, 'volcano-generated/models/realtime_plan_limits'
 Volcano::Generated.autoload :RealtimeStats, 'volcano-generated/models/realtime_stats'
@@ -332,6 +335,27 @@ Volcano::Generated.autoload :ReplaceSharedVariablesRequest, 'volcano-generated/m
 Volcano::Generated.autoload :ResetDatabasePassword200Response, 'volcano-generated/models/reset_database_password200_response'
 Volcano::Generated.autoload :ResolveFunctionResponse, 'volcano-generated/models/resolve_function_response'
 Volcano::Generated.autoload :ResourceReference, 'volcano-generated/models/resource_reference'
+Volcano::Generated.autoload :SandboxAccess, 'volcano-generated/models/sandbox_access'
+Volcano::Generated.autoload :SandboxAccessRequest, 'volcano-generated/models/sandbox_access_request'
+Volcano::Generated.autoload :SandboxCapacity, 'volcano-generated/models/sandbox_capacity'
+Volcano::Generated.autoload :SandboxCapacityList, 'volcano-generated/models/sandbox_capacity_list'
+Volcano::Generated.autoload :SandboxCommandRequest, 'volcano-generated/models/sandbox_command_request'
+Volcano::Generated.autoload :SandboxCommandResult, 'volcano-generated/models/sandbox_command_result'
+Volcano::Generated.autoload :SandboxDeployment, 'volcano-generated/models/sandbox_deployment'
+Volcano::Generated.autoload :SandboxDeploymentPage, 'volcano-generated/models/sandbox_deployment_page'
+Volcano::Generated.autoload :SandboxExecutionRequest, 'volcano-generated/models/sandbox_execution_request'
+Volcano::Generated.autoload :SandboxExecutionResult, 'volcano-generated/models/sandbox_execution_result'
+Volcano::Generated.autoload :SandboxFileReadRequest, 'volcano-generated/models/sandbox_file_read_request'
+Volcano::Generated.autoload :SandboxFileResult, 'volcano-generated/models/sandbox_file_result'
+Volcano::Generated.autoload :SandboxFileWriteRequest, 'volcano-generated/models/sandbox_file_write_request'
+Volcano::Generated.autoload :SandboxPagination, 'volcano-generated/models/sandbox_pagination'
+Volcano::Generated.autoload :SandboxPreset, 'volcano-generated/models/sandbox_preset'
+Volcano::Generated.autoload :SandboxPresetList, 'volcano-generated/models/sandbox_preset_list'
+Volcano::Generated.autoload :SandboxSession, 'volcano-generated/models/sandbox_session'
+Volcano::Generated.autoload :SandboxSessionPage, 'volcano-generated/models/sandbox_session_page'
+Volcano::Generated.autoload :SandboxSubjectGrantRequest, 'volcano-generated/models/sandbox_subject_grant_request'
+Volcano::Generated.autoload :SandboxTemplate, 'volcano-generated/models/sandbox_template'
+Volcano::Generated.autoload :SandboxTemplatePage, 'volcano-generated/models/sandbox_template_page'
 Volcano::Generated.autoload :ScheduleRequest, 'volcano-generated/models/schedule_request'
 Volcano::Generated.autoload :ServiceKey, 'volcano-generated/models/service_key'
 Volcano::Generated.autoload :SetProjectGitProductionBranchRequest, 'volcano-generated/models/set_project_git_production_branch_request'
@@ -360,6 +384,7 @@ Volcano::Generated.autoload :UpdateOAuthConfigRequest, 'volcano-generated/models
 Volcano::Generated.autoload :UpdateProjectGitDeploySettingsRequest, 'volcano-generated/models/update_project_git_deploy_settings_request'
 Volcano::Generated.autoload :UpdateProjectRequest, 'volcano-generated/models/update_project_request'
 Volcano::Generated.autoload :UpdateRealtimeConfigRequest, 'volcano-generated/models/update_realtime_config_request'
+Volcano::Generated.autoload :UpdateSandboxTemplateRequest, 'volcano-generated/models/update_sandbox_template_request'
 Volcano::Generated.autoload :UpdateStorageBucketRequest, 'volcano-generated/models/update_storage_bucket_request'
 Volcano::Generated.autoload :UpdateVariableRequest, 'volcano-generated/models/update_variable_request'
 Volcano::Generated.autoload :UploadSessionPart, 'volcano-generated/models/upload_session_part'
@@ -388,6 +413,7 @@ Volcano::Generated.autoload :OAuthConfigurationApi, 'volcano-generated/api/o_aut
 Volcano::Generated.autoload :ProjectImportsApi, 'volcano-generated/api/project_imports_api'
 Volcano::Generated.autoload :ProjectsApi, 'volcano-generated/api/projects_api'
 Volcano::Generated.autoload :RealtimeApi, 'volcano-generated/api/realtime_api'
+Volcano::Generated.autoload :SandboxesApi, 'volcano-generated/api/sandboxes_api'
 Volcano::Generated.autoload :ServiceKeysApi, 'volcano-generated/api/service_keys_api'
 Volcano::Generated.autoload :StorageAdminApi, 'volcano-generated/api/storage_admin_api'
 Volcano::Generated.autoload :StorageBucketsApi, 'volcano-generated/api/storage_buckets_api'

data/lib/volcano/generated_transport.rb

@@ -29,6 +29,7 @@ module Volcano
   require_relative 'generated_transport_logs'
   require_relative 'generated_transport_functions'
   require_relative 'generated_transport_durable'
+  require_relative 'generated_transport_sandbox'
   require_relative 'generated_transport_storage'
   require_relative 'generated_transport_upload_sessions'
 

data/lib/volcano/generated_transport_sandbox.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Volcano
+  # Dispatch only the generated operations exposed by the Sandbox facade.
+  class GeneratedTransport
+    SANDBOX_OPERATIONS = {
+      list_sandbox_presets: lambda { |api, _request|
+        api.list_sandbox_presets_with_http_info(debug_return_type: 'Object')
+      },
+      create_sandbox_session: lambda { |api, request|
+        api.create_sandbox_session_with_http_info(request.resource_id, request.request_id, request.body,
+                                                  debug_return_type: 'Object')
+      },
+      execute_sandbox: lambda { |api, request|
+        api.execute_sandbox_with_http_info(request.resource_id, request.request_id, request.body,
+                                           debug_return_type: 'Object')
+      },
+      get_sandbox_session: lambda { |api, request|
+        api.get_sandbox_session_with_http_info(request.resource_id, debug_return_type: 'Object')
+      },
+      execute_sandbox_session: lambda { |api, request|
+        api.execute_sandbox_session_with_http_info(request.resource_id, request.request_id, request.body,
+                                                   debug_return_type: 'Object')
+      },
+      suspend_sandbox_session: lambda { |api, request|
+        api.suspend_sandbox_session_with_http_info(request.resource_id, debug_return_type: 'Object')
+      },
+      resume_sandbox_session: lambda { |api, request|
+        api.resume_sandbox_session_with_http_info(request.resource_id, debug_return_type: 'Object')
+      },
+      terminate_sandbox_session: lambda { |api, request|
+        api.terminate_sandbox_session_with_http_info(request.resource_id, debug_return_type: 'Object')
+      },
+      create_sandbox_session_access: lambda { |api, request|
+        api.create_sandbox_session_access_with_http_info(request.resource_id, request.body, debug_return_type: 'Object')
+      },
+      read_sandbox_session_file: lambda { |api, request|
+        api.read_sandbox_session_file_with_http_info(request.resource_id, request.body, debug_return_type: 'Object')
+      },
+      write_sandbox_session_file: lambda { |api, request|
+        api.write_sandbox_session_file_with_http_info(request.resource_id, request.body, debug_return_type: 'Object')
+      },
+      grant_sandbox_session: lambda { |api, request|
+        api.grant_sandbox_session_with_http_info(request.resource_id, request.subject_id, request.body,
+                                                 debug_return_type: 'Object')
+      },
+      revoke_sandbox_session: lambda { |api, request|
+        api.revoke_sandbox_session_with_http_info(request.resource_id, request.subject_id, debug_return_type: 'Object')
+      }
+    }.freeze
+    private_constant :SANDBOX_OPERATIONS
+
+    def sandbox_request(authorization:, request:)
+      invoke do
+        api = sandbox_api(authorization, request.timeout)
+        data, status, headers = SANDBOX_OPERATIONS.fetch(request.operation).call(api, request)
+        response(data, status, headers)
+      end
+    end
+
+    private
+
+    def sandbox_api(authorization, timeout)
+      configuration = generated_configuration(authorization)
+      configuration.timeout = [configuration.timeout, (timeout * 1_000).round].max
+      Generated::SandboxesApi.new(ApiClient.new(configuration))
+    end
+  end
+end

data/lib/volcano/sandbox_files.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'base64'
+
+module Volcano
+  # Byte-preserving files inside a Sandbox session.
+  class SandboxFiles
+    FILE_LIMIT = 8 * 1024 * 1024
+    private_constant :FILE_LIMIT
+
+    def initialize(requests, session_id)
+      @requests = requests
+      @session_id = session_id
+    end
+
+    def inspect = "#<Volcano::SandboxFiles session_id=#{@session_id.inspect}>"
+
+    def read(path)
+      response = @requests.call(request(:read_sandbox_session_file, { path: path }))
+      Base64.strict_decode64(SandboxResponse.text(Transport.json_object(response)['data']))
+    end
+
+    def write(path, data)
+      raise Error::ValidationError, 'Sandbox files are limited to 8 MiB' if data.bytesize > FILE_LIMIT
+
+      body = { path: path, data: Base64.strict_encode64(data) }
+      @requests.call(request(:write_sandbox_session_file, body), status: 204)
+      nil
+    end
+
+    private
+
+    def request(operation, body)
+      SandboxRequest.new(operation: operation, resource_id: @session_id, body: body)
+    end
+  end
+end

data/lib/volcano/sandbox_models.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Volcano
+  # Command output preserves nonzero exit codes as data.
+  SandboxCommandResult = Data.define(:stdout, :stderr, :exit_code, :timed_out, :stdout_truncated, :stderr_truncated)
+  # One-shot output is returned after confirmed guest reclamation.
+  SandboxExecutionResult = Data.define(:stdout, :stderr, :exit_code, :timed_out, :stdout_truncated,
+                                       :stderr_truncated, :session_id, :region, :duration_ms)
+  # A published preset and its available memory and regions.
+  SandboxPreset = Data.define(:id, :memory_mb, :regions)
+  # Expiring HTTP access credentials are redacted from inspection.
+  class SandboxAccess
+    attr_reader :url, :token, :expires_at
+
+    def initialize(url:, token:, expires_at:)
+      @url = url.dup.freeze
+      @token = token.dup.freeze
+      @expires_at = expires_at.dup.freeze
+      freeze
+    end
+
+    def inspect = "#<Volcano::SandboxAccess expires_at=#{expires_at.inspect}>"
+  end
+end

data/lib/volcano/sandbox_request.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'time'
+
+module Volcano
+  # Immutable addressing and payload for a generated Sandbox operation.
+  class SandboxRequest
+    def initialize(options)
+      @options = options.dup
+      body = options[:body]
+      @options[:body] = ImmutableRequestValue.capture(body) if body
+      @options.freeze
+      freeze
+    end
+
+    def operation = @options.fetch(:operation)
+    def resource_id = @options[:resource_id]
+    def subject_id = @options[:subject_id]
+    def body = @options[:body]
+    def request_id = @options[:request_id]
+    def timeout = @options.fetch(:timeout, 0)
+  end
+
+  # Shared validation and credentials for Sandbox facade operations.
+  class SandboxRequests
+    UUID = /\A[\da-f]{8}(?:-[\da-f]{4}){3}-[\da-f]{12}\z/i
+    USER_OPERATIONS = %i[get_sandbox_session execute_sandbox_session read_sandbox_session_file
+                         write_sandbox_session_file create_sandbox_session_access].freeze
+    private_constant :UUID, :USER_OPERATIONS
+
+    def initialize(client, transport, service_only: false)
+      @client = client
+      @transport = transport
+      @service_only = service_only
+    end
+
+    def service_scope = SandboxRequests.new(@client, @transport, service_only: true)
+
+    def call(request, status: 200)
+      response = if request.operation == :list_sandbox_presets
+                   dispatch(request, '')
+                 elsif user_request?(request)
+                   @client.session_request { |token| dispatch(request, token) }
+                 else
+                   dispatch(request, @client.service_token)
+                 end
+      Transport.body(response, status)
+    end
+
+    def self.expiry(value)
+      parsed = value.is_a?(Time) ? value : Time.iso8601(value)
+      parsed.getutc.iso8601
+    rescue ArgumentError
+      raise Error::ValidationError, 'Sandbox grant expiry must be a Time or ISO8601 timestamp'
+    end
+
+    def self.identifier(value)
+      return value.dup.freeze if value.is_a?(String) && UUID.match?(value)
+
+      raise Error::ValidationError, 'Sandbox resource and request IDs must be UUIDs'
+    end
+
+    def self.request_id(options)
+      identifier(options.fetch(:request_id) { SecureRandom.uuid })
+    end
+
+    def self.selector(options)
+      if options.key?(:preset) == options.key?(:sandbox_id)
+        raise Error::ValidationError, 'Choose exactly one preset or sandbox_id'
+      end
+
+      result = options.slice(:region, :preset, :sandbox_id, :memory_mb)
+      result[:sandbox_id] = identifier(result[:sandbox_id]) if result.key?(:sandbox_id)
+      result
+    end
+
+    def self.command(command, options)
+      options.slice(:timeout_seconds, :environment).merge(command: command)
+    end
+
+    private
+
+    def user_request?(request)
+      !@service_only && USER_OPERATIONS.include?(request.operation) && !@client.current_session.nil?
+    end
+
+    def dispatch(request, token)
+      Transport.invoke { @transport.sandbox_request(authorization: token, request: request) }
+    end
+  end
+end

data/lib/volcano/sandbox_response.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Volcano
+  # Validate wire values before exposing language-native Sandbox results.
+  module SandboxResponse
+    STATES = %w[starting running suspending suspended resuming terminating terminated unknown].freeze
+    private_constant :STATES
+
+    def self.text(value)
+      return value if value.is_a?(String)
+
+      raise TypeError, 'Invalid Sandbox text field'
+    end
+
+    def self.timestamp(value)
+      Time.iso8601(text(value)).freeze
+    rescue ArgumentError
+      raise TypeError, 'Invalid Sandbox timestamp'
+    end
+
+    def self.integer(value)
+      return value if value.is_a?(Integer)
+
+      raise TypeError, 'Invalid Sandbox integer field'
+    end
+
+    def self.flag(value)
+      return value if value.is_a?(TrueClass) || value.is_a?(FalseClass)
+
+      raise TypeError, 'Invalid Sandbox flag'
+    end
+
+    def self.state(value)
+      result = text(value)
+      return result.dup.freeze if STATES.include?(result)
+
+      raise TypeError, 'Invalid Sandbox state'
+    end
+
+    def self.command(value)
+      data = Transport.json_object(value)
+      SandboxCommandResult.new(
+        stdout: text(data['stdout']), stderr: text(data['stderr']), exit_code: integer(data['exit_code']),
+        timed_out: flag(data['timed_out']), stdout_truncated: flag(data['stdout_truncated']),
+        stderr_truncated: flag(data['stderr_truncated'])
+      )
+    end
+
+    def self.execution(value)
+      data = Transport.json_object(value)
+      SandboxExecutionResult.new(
+        **command(data).to_h, session_id: text(data['session_id']),
+                              region: text(data['region']), duration_ms: integer(data['duration_ms'])
+      )
+    end
+
+    def self.access(value)
+      data = Transport.json_object(value)
+      SandboxAccess.new(url: text(data['url']), token: text(data['token']), expires_at: timestamp(data['expires_at']))
+    end
+
+    def self.preset(value)
+      data = Transport.json_object(value)
+      regions = array(data['regions']).map { |region| text(region) }.freeze
+      SandboxPreset.new(id: text(data['id']), memory_mb: integer(data['memory_mb']), regions: regions)
+    end
+
+    def self.array(value)
+      return value if value.is_a?(Array)
+
+      raise TypeError, 'Invalid Sandbox list'
+    end
+  end
+end

data/lib/volcano/sandbox_session.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Volcano
+  # A session handle whose observed state changes only after validated responses.
+  class SandboxSession
+    attr_reader :id, :project_id, :region, :state, :expires_at, :files
+
+    def initialize(requests, value)
+      data = Transport.json_object(value)
+      @requests = requests
+      @id = SandboxRequests.identifier(data['id'])
+      @project_id = SandboxRequests.identifier(data['project_id'])
+      @region = SandboxResponse.text(data['region'])
+      assign_state(data)
+      @files = SandboxFiles.new(requests, @id)
+    end
+
+    def refresh = update(:get_sandbox_session)
+    def suspend = update(:suspend_sandbox_session, status: 202)
+    def resume = update(:resume_sandbox_session, status: 202)
+    def terminate = update(:terminate_sandbox_session, status: 202)
+
+    def inspect
+      "#<Volcano::SandboxSession id=#{@id.inspect} project_id=#{@project_id.inspect} " \
+        "region=#{@region.inspect} state=#{@state.inspect}>"
+    end
+
+    def exec(command, timeout_seconds: 60, environment: nil, request_id: nil)
+      options = { timeout_seconds: timeout_seconds, environment: environment, request_id: request_id }.compact
+      request = SandboxRequest.new(operation: :execute_sandbox_session, resource_id: @id,
+                                   body: SandboxRequests.command(command, options),
+                                   request_id: SandboxRequests.request_id(options),
+                                   timeout: SandboxResponse.integer(options.fetch(:timeout_seconds, 60)) + 120)
+      SandboxResponse.command(@requests.call(request))
+    end
+
+    def access(port)
+      request = SandboxRequest.new(operation: :create_sandbox_session_access, resource_id: @id, body: { port: port })
+      SandboxResponse.access(@requests.call(request))
+    end
+
+    def use
+      # @type var unwinding: bool
+      unwinding = true
+      result = yield self
+      unwinding = false
+      result
+    ensure
+      cleanup(unwinding) unless %w[terminating terminated].include?(@state)
+    end
+
+    private
+
+    def cleanup(unwinding)
+      terminate
+    rescue Error::NotFoundError
+      nil
+    rescue StandardError
+      raise unless unwinding
+    end
+
+    def update(operation, status: 200)
+      response = @requests.call(SandboxRequest.new(operation: operation, resource_id: @id), status: status)
+      data = Transport.json_object(response)
+      raise TypeError, 'Sandbox session identity changed' unless data['id'] == @id
+
+      assign_state(data)
+      self
+    end
+
+    def assign_state(data)
+      next_state = SandboxResponse.state(data['state'])
+      expiry = SandboxResponse.timestamp(data['expires_at'])
+      @state = next_state
+      @expires_at = expiry
+    end
+  end
+end