lambda-microvms 0.0.0 → 0.2.0

data/lib/lambda/microvms/image.rb

@@ -6,6 +6,11 @@ module Lambda
     class Image
       attr_reader :client, :arn, :data
 
+      # Build an image resource from an SDK response.
+      #
+      # @param client [Client] lifecycle client
+      # @param response [Object] SDK response
+      # @return [Image] image resource
       def self.from_response(client:, response:)
         arn = Util.extract(response, :image_arn, :microvm_image_arn, :arn)
         new(client: client, arn: arn, data: response)
@@ -17,12 +22,18 @@ module Lambda
         @data = data
       end
 
+      # Refresh image data from the service.
+      #
+      # @return [self]
       def refresh
         fresh = client.get_image(image_arn: arn)
         @data = fresh.data
         self
       end
 
+      # Current normalized image state.
+      #
+      # @return [Symbol]
       def state
         Util.normalize_state(Util.extract(@data, :state, :status, :image_state))
       end
@@ -31,6 +42,11 @@ module Lambda
         %i[ready available active].include?(state)
       end
 
+      # Wait until the image reaches a ready-like state.
+      #
+      # @param delay [Numeric] polling delay in seconds
+      # @param timeout [Numeric] maximum wait in seconds
+      # @return [self]
       def wait_until_ready(delay: Waiter::DEFAULT_DELAY, timeout: Waiter::DEFAULT_TIMEOUT)
         Waiter.new(delay: delay, timeout: timeout).wait(message: "image #{arn} to be ready") do
           refresh.ready?
@@ -38,6 +54,12 @@ module Lambda
         self
       end
 
+      # Run a MicroVM from this image.
+      #
+      # @param role_arn [String] IAM role ARN used by the MicroVM runtime
+      # @param payload [Object,nil] optional runtime payload
+      # @param params [Hash] additional run parameters
+      # @return [MicroVM]
       def run(role_arn:, payload: nil, **params)
         request = params.merge(image_arn: arn, role_arn: role_arn)
         request[:payload] = payload if payload

data/lib/lambda/microvms/microvm.rb

@@ -6,6 +6,11 @@ module Lambda
     class MicroVM
       attr_reader :client, :id, :data
 
+      # Build a MicroVM resource from an SDK response.
+      #
+      # @param client [Client] lifecycle client
+      # @param response [Object] SDK response
+      # @return [MicroVM] MicroVM resource
       def self.from_response(client:, response:)
         id = Util.extract(response, :microvm_id, :microvm_arn, :id, :arn)
         new(client: client, id: id, data: response)
@@ -17,12 +22,18 @@ module Lambda
         @data = data
       end
 
+      # Refresh MicroVM data from the service.
+      #
+      # @return [self]
       def refresh
         fresh = client.get_microvm(microvm_id: id)
         @data = fresh.data
         self
       end
 
+      # Current normalized MicroVM state.
+      #
+      # @return [Symbol]
       def state
         Util.normalize_state(Util.extract(@data, :state, :status, :microvm_state))
       end
@@ -43,6 +54,9 @@ module Lambda
         state == :pending
       end
 
+      # Extract the direct endpoint URL from the current MicroVM data.
+      #
+      # @return [String, nil]
       def endpoint_url
         endpoint = Util.extract(@data, :endpoint, :endpoint_url, :url)
         return endpoint if endpoint.is_a?(String)
@@ -50,6 +64,12 @@ module Lambda
         Util.extract(endpoint, :url, :endpoint_url) if endpoint
       end
 
+      # Request an auth token for direct endpoint access.
+      #
+      # @param ports [Array<Integer>, nil] optional allowed ports
+      # @param ttl_seconds [Integer, nil] optional token lifetime
+      # @param params [Hash] additional token request parameters
+      # @return [String, nil] auth token value
       def auth_token(ports: nil, ttl_seconds: nil, **params)
         request = params.merge(microvm_id: id)
         request[:ports] = ports if ports
@@ -58,34 +78,71 @@ module Lambda
         Util.extract(response, :token, :auth_token, :microvm_auth_token)
       end
 
+      # Build an endpoint client for this MicroVM.
+      #
+      # @param token [String, nil] existing auth token
+      # @param token_params [Hash] parameters used when requesting a token
+      # @return [Endpoint]
       def endpoint(token: nil, **token_params)
-        Endpoint.new(url: endpoint_url, token: token || auth_token(**token_params))
+        url = endpoint_url
+        raise EndpointError.new('MicroVM endpoint URL is unavailable', status: 0, body: nil) unless url
+
+        Endpoint.new(url: url, token: token || auth_token(**token_params))
       end
 
+      # Send a GET request to the MicroVM endpoint.
+      #
+      # @param path [String] endpoint path
+      # @param token [String, nil] existing auth token
+      # @return [Hash,String,nil] endpoint response
       def get(path, token: nil, **)
         endpoint(token: token).get(path, **)
       end
 
+      # Send a POST request to the MicroVM endpoint.
+      #
+      # @param path [String] endpoint path
+      # @param json [Hash,Array,nil] JSON body to encode
+      # @param body [String,nil] raw request body
+      # @param token [String, nil] existing auth token
+      # @return [Hash,String,nil] endpoint response
       def post(path, json: nil, body: nil, token: nil, **)
         endpoint(token: token).post(path, json: json, body: body, **)
       end
 
+      # Suspend this MicroVM.
+      #
+      # @param params [Hash] additional suspend parameters
+      # @return [self]
       def suspend(**params)
         client.suspend_microvm(**params, microvm_id: id)
         self
       end
 
+      # Resume this MicroVM and update local data when the service returns a response.
+      #
+      # @param params [Hash] additional resume parameters
+      # @return [self]
       def resume(**params)
         response = client.resume_microvm(**params, microvm_id: id)
         @data = response if response
         self
       end
 
+      # Terminate this MicroVM.
+      #
+      # @param params [Hash] additional terminate parameters
+      # @return [self]
       def terminate(**params)
         client.terminate_microvm(**params, microvm_id: id)
         self
       end
 
+      # Wait until this MicroVM is running.
+      #
+      # @param delay [Numeric] polling delay in seconds
+      # @param timeout [Numeric] maximum wait in seconds
+      # @return [self]
       def wait_until_running(delay: Waiter::DEFAULT_DELAY, timeout: Waiter::DEFAULT_TIMEOUT)
         Waiter.new(delay: delay, timeout: timeout).wait(message: "MicroVM #{id} to be running") do
           refresh.running?
@@ -93,6 +150,11 @@ module Lambda
         self
       end
 
+      # Wait until this MicroVM is suspended.
+      #
+      # @param delay [Numeric] polling delay in seconds
+      # @param timeout [Numeric] maximum wait in seconds
+      # @return [self]
       def wait_until_suspended(delay: Waiter::DEFAULT_DELAY, timeout: Waiter::DEFAULT_TIMEOUT)
         Waiter.new(delay: delay, timeout: timeout).wait(message: "MicroVM #{id} to be suspended") do
           refresh.suspended?
@@ -100,6 +162,11 @@ module Lambda
         self
       end
 
+      # Wait until this MicroVM is terminated.
+      #
+      # @param delay [Numeric] polling delay in seconds
+      # @param timeout [Numeric] maximum wait in seconds
+      # @return [self]
       def wait_until_terminated(delay: Waiter::DEFAULT_DELAY, timeout: Waiter::DEFAULT_TIMEOUT)
         Waiter.new(delay: delay, timeout: timeout).wait(message: "MicroVM #{id} to be terminated") do
           refresh.terminated?

data/lib/lambda/microvms/packager.rb

@@ -8,14 +8,21 @@ module Lambda
   module MicroVMs
     # Creates a deployable source artifact for Lambda MicroVM image creation.
     class Packager
+      # Default zip exclusion patterns.
       DEFAULT_EXCLUDES = ['.git/*', 'tmp/*', 'vendor/bundle/*', '*.gem'].freeze
 
       attr_reader :project
 
-      def initialize(project)
+      def initialize(project, runner: Open3)
         @project = project
+        @runner = runner
       end
 
+      # Create the zip artifact for the configured project.
+      #
+      # @param output [String] output zip path
+      # @return [String] output path
+      # @raise [CommandError] when zip exits unsuccessfully
       def package(output: project.artifact_path)
         FileUtils.mkdir_p(File.dirname(output))
         relative_output = begin
@@ -25,7 +32,7 @@ module Lambda
         end
         excludes = DEFAULT_EXCLUDES + [relative_output]
         command = ['zip', '-q', '-r', output, '.'] + excludes.flat_map { |pattern| ['-x', pattern] }
-        stdout, stderr, status = Open3.capture3(*command, chdir: project.root)
+        stdout, stderr, status = @runner.capture3(*command, chdir: project.root)
         raise CommandError, "zip failed: #{stderr.empty? ? stdout : stderr}" unless status.success?
 
         output

data/lib/lambda/microvms/project.rb

@@ -8,10 +8,15 @@ module Lambda
   module MicroVMs
     # Reads lambda-microvms project configuration from microvm.yml.
     class Project
+      # Default project configuration file name.
       DEFAULT_CONFIG = 'microvm.yml'
 
       attr_reader :root, :config_path, :config
 
+      # Load a project configuration from disk.
+      #
+      # @param path [String] path to a YAML configuration file
+      # @return [Project] loaded project
       def self.load(path = DEFAULT_CONFIG)
         config_path = File.expand_path(path)
         root = File.dirname(config_path)
@@ -25,36 +30,79 @@ module Lambda
         @config = stringify_keys(config)
       end
 
+      # Project name.
+      #
+      # @return [String]
       def name = fetch('name', default: File.basename(root))
 
+      # AWS region from configuration or environment.
+      #
+      # @return [String, nil]
       def region = fetch('region', default: ENV.fetch('AWS_REGION', nil))
 
+      # AWS profile from configuration or environment.
+      #
+      # @return [String, nil]
       def profile = fetch('profile', default: ENV.fetch('AWS_PROFILE', nil))
 
+      # IAM role ARN used when running MicroVMs.
+      #
+      # @return [String, nil]
       def role_arn = fetch('role_arn', 'role', default: nil)
 
+      # Existing MicroVM image ARN.
+      #
+      # @return [String, nil]
       def image_arn = fetch('image_arn', 'image.arn', default: nil)
 
+      # Name used when creating a MicroVM image.
+      #
+      # @return [String]
       def image_name = fetch('image.name', default: name)
 
+      # Absolute path to the Dockerfile.
+      #
+      # @return [String]
       def dockerfile = File.expand_path(fetch('build.dockerfile', default: 'Dockerfile'), root)
 
+      # Absolute path to the build context.
+      #
+      # @return [String]
       def build_context = File.expand_path(fetch('build.context', default: '.'), root)
 
+      # Absolute path for the packaged artifact.
+      #
+      # @return [String]
       def artifact_path = File.expand_path(fetch('build.artifact', default: "tmp/#{name}-microvm.zip"), root)
 
+      # S3 bucket used for deployment artifacts.
+      #
+      # @return [String, nil]
       def s3_bucket = fetch('deployment.bucket', 's3.bucket', default: nil)
 
+      # S3 key prefix used for deployment artifacts.
+      #
+      # @return [String]
       def s3_prefix = fetch('deployment.prefix', 's3.prefix', default: "lambda-microvms/#{name}")
 
+      # Cleanup policy used after a session block.
+      #
+      # @return [Symbol]
       def lifecycle_after = fetch('runtime.after', default: 'suspend').to_sym
 
+      # Runtime payload configured for MicroVM runs.
+      #
+      # @return [Hash]
       def payload
-        fetch('runtime.payload', default: {}) || {}
+        hash_config('runtime.payload')
       end
 
+      # Build parameters for image creation with the artifact URI injected.
+      #
+      # @param artifact_uri [String] uploaded artifact URI
+      # @return [Hash] SDK-style create image parameters
       def create_image_params(artifact_uri:)
-        params = fetch('image.create', default: {}) || {}
+        params = hash_config('image.create')
         params = stringify_keys(params)
         symbolized = params.to_h { |key, value| [key.to_sym, value] }
         symbolized[:name] ||= image_name
@@ -62,22 +110,63 @@ module Lambda
         symbolized
       end
 
+      # Build parameters for running a MicroVM.
+      #
+      # @return [Hash] SDK-style run parameters
       def run_params
-        params = stringify_keys(fetch('runtime.run', default: {}) || {})
+        params = stringify_keys(hash_config('runtime.run'))
         symbolized = params.to_h { |key, value| [key.to_sym, value] }
         symbolized[:role_arn] ||= role_arn if role_arn
         symbolized[:payload] ||= payload unless payload.empty?
         symbolized
       end
 
+      # Validate project configuration sections used by deployment commands.
+      #
+      # @return [self]
+      # @raise [ConfigurationError] when a known section has an invalid shape
+      def validate!
+        validate_hash!
+        validate_lifecycle_after!
+        hash_config('image.create')
+        hash_config('runtime.payload')
+        hash_config('runtime.run')
+        self
+      end
+
+      # Return a required value or raise a configuration error.
+      #
+      # @param field [String] configuration field name used in the error
+      # @param value [Object] value to validate
+      # @return [Object] the validated value
+      # @raise [ConfigurationError] when the value is nil or empty
       def require!(field, value)
-        return value if value && value != ''
+        return value if value && value.to_s.strip != ''
 
         raise ConfigurationError, "missing required project configuration: #{field}"
       end
 
       private
 
+      def validate_hash!
+        return if @config.is_a?(Hash)
+
+        raise ConfigurationError, 'project configuration must be a YAML mapping'
+      end
+
+      def validate_lifecycle_after!
+        return if %i[keep suspend terminate].include?(lifecycle_after)
+
+        raise ConfigurationError, "unsupported runtime.after: #{lifecycle_after.inspect}"
+      end
+
+      def hash_config(path)
+        value = fetch(path, default: {}) || {}
+        return value if value.is_a?(Hash)
+
+        raise ConfigurationError, "#{path} must be a mapping"
+      end
+
       def fetch(*paths, default:)
         paths.each do |path|
           current = @config

data/lib/lambda/microvms/scaffold.rb

@@ -14,6 +14,9 @@ module Lambda
         @force = force
       end
 
+      # Create the scaffolded project files.
+      #
+      # @return [String] target directory
       def create
         ensure_target!
         FileUtils.mkdir_p(directory)

data/lib/lambda/microvms/session.rb

@@ -6,6 +6,15 @@ module Lambda
     module Session
       module_function
 
+      # Run a MicroVM, wait for it, yield it, and then clean it up.
+      #
+      # @param image_arn [String] MicroVM image ARN
+      # @param role_arn [String] IAM role ARN for the MicroVM runtime
+      # @param after [Symbol, nil] cleanup policy: :suspend, :terminate, :keep, or nil
+      # @param client [Client] lifecycle client
+      # @param run_options [Hash] additional run parameters
+      # @yieldparam vm [MicroVM] running MicroVM
+      # @return [Object] block result
       def session(image_arn:, role_arn:, after: :suspend, client: Client.new, **run_options)
         vm = client.image(image_arn).run(role_arn: role_arn, **run_options)
         vm.wait_until_running
@@ -14,6 +23,12 @@ module Lambda
         cleanup(vm, after) if vm
       end
 
+      # Apply a session cleanup policy to a MicroVM.
+      #
+      # @param vm [MicroVM] MicroVM to clean up
+      # @param after [Symbol, nil] cleanup policy
+      # @return [Object, nil] cleanup result
+      # @raise [ArgumentError] when the policy is unknown
       def cleanup(vm, after) # rubocop:disable Naming/MethodParameterName
         case after
         when :keep, nil

data/lib/lambda/microvms/util.rb

@@ -6,6 +6,11 @@ module Lambda
     module Util
       module_function
 
+      # Extract the first non-nil value from an object method or hash-like key.
+      #
+      # @param value [Object] response object, hash, or SDK structure
+      # @param keys [Array<Symbol,String>] candidate method or key names
+      # @return [Object, nil] the first extracted non-nil value
       def extract(value, *keys)
         keys.each do |key|
           if value.respond_to?(key)
@@ -26,6 +31,10 @@ module Lambda
         nil
       end
 
+      # Normalize a provider state value into a lowercase symbol.
+      #
+      # @param value [Object] state-like value
+      # @return [Symbol] normalized state
       def normalize_state(value)
         value.to_s.downcase.to_sym
       end

data/lib/lambda/microvms/version.rb

@@ -2,6 +2,7 @@
 
 module Lambda
   module MicroVMs
-    VERSION = '0.0.0'
+    # Current gem version.
+    VERSION = '0.2.0'
   end
 end

data/lib/lambda/microvms/waiter.rb

@@ -4,7 +4,9 @@ module Lambda
   module MicroVMs
     # Polls a resource until a desired lifecycle state is reached.
     class Waiter
+      # Default polling delay, in seconds.
       DEFAULT_DELAY = 1.0
+      # Default maximum wait time, in seconds.
       DEFAULT_TIMEOUT = 60.0
 
       def initialize(delay: DEFAULT_DELAY, timeout: DEFAULT_TIMEOUT, sleeper: Kernel)
@@ -13,6 +15,12 @@ module Lambda
         @sleeper = sleeper
       end
 
+      # Poll until the block returns a truthy value or the timeout expires.
+      #
+      # @param message [String] human-readable condition for timeout errors
+      # @yieldreturn [Object, false, nil] truthy value when the condition is satisfied
+      # @return [Object] the truthy block result
+      # @raise [WaitTimeoutError] if the timeout expires
       def wait(message: 'condition')
         deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + @timeout
 

data/lib/lambda/microvms.rb

@@ -5,7 +5,9 @@ require_relative 'microvms/error'
 require_relative 'microvms/util'
 require_relative 'microvms/waiter'
 require_relative 'microvms/endpoint'
+require_relative 'microvms/adapters/microvm_sdk'
 require_relative 'microvms/client'
+require_relative 'microvms/function_client'
 require_relative 'microvms/image'
 require_relative 'microvms/microvm'
 require_relative 'microvms/session'
@@ -15,11 +17,16 @@ require_relative 'microvms/packager'
 require_relative 'microvms/deployer'
 require_relative 'microvms/doctor'
 
+# Namespace for Lambda-related libraries.
 module Lambda
   # Idiomatic Ruby lifecycle helpers for AWS Lambda MicroVMs.
   module MicroVMs
     module_function
 
+    # Run a MicroVM from an image, yield it, and apply the requested cleanup policy.
+    #
+    # @see Lambda::MicroVMs::Session.session
+    # @return [Object] the block result
     def session(...)
       Session.session(...)
     end