lambda-microvms 0.0.0 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: de35523913c4cd5c11fc48549081c7901db9fdacfef2a72618264885596bb838
-  data.tar.gz: 960ec7995dc496da3f358c6ad484eb0a420140afa727275b92e5eadf7201ce2b
+  metadata.gz: 296c088486e240241e9e84b8932be4b07dd929aa4168b3b88d96347c5f6e9173
+  data.tar.gz: 8b3b9880d86869ef123247fb635d3a09bbc812bc6512ea6a45e6983c2414c04a
 SHA512:
-  metadata.gz: 055d951f5d0a5dc948195eff437d7b67070faf74e5dba4eee65b583aa70fda29a0452d93ecbe4e311bf3e7f5f18054d999776c6c5294bc2c88b061c8a777c77c
-  data.tar.gz: 6948f65e7391fa14734dcd1f89757bfb6a1b2a04ee200566409de0851da3a80f41a7173607cbd6efa40a5bc31d09d1033237512eb145bf23358459871dd77da5
+  metadata.gz: 114c31806d2c30c3682b9f33a79ddc2b3b114a5c4898f48f1fa07edf5ecf5e61bdd2cdc9d49150ca415715bb8e1a911335bd44a59f6277adb8e50ca424235a23
+  data.tar.gz: 713a3dabdfeac0e9dad4ea3212fa556295e6b77ee9929daf919ec56c6f01c8cce1e384220548a17fff6bb2e900ffe4903a21650edcfbe7929f7400b420c8eaee

data/README.md

@@ -177,3 +177,4 @@ Lambda::MicroVMs::Client
 ## Status
 
 This is an early implementation. Lambda MicroVMs is new, so generated AWS SDK operation shapes may evolve. Unsupported low-level operations raise `Lambda::MicroVMs::UnsupportedOperationError` with an upgrade hint.
+give

data/exe/lambda-microvms

@@ -23,6 +23,7 @@ module Lambda
         when 'deploy' then deploy
         when 'run' then run_microvm
         when 'doctor' then doctor
+        when 'sdk-contract' then sdk_contract
         when 'help', nil then help
         else
           @err.puts "unknown command: #{command}"
@@ -81,6 +82,17 @@ module Lambda
         checks.all?(&:ok) ? 0 : 1
       end
 
+      def sdk_contract
+        unsupported = Client.unsupported_operations
+        if unsupported.empty?
+          @out.puts 'Aws::Lambda::Client exposes all Lambda MicroVM operations'
+          0
+        else
+          @err.puts "missing Aws::Lambda::Client operations: #{unsupported.join(', ')}"
+          1
+        end
+      end
+
       def help
         @out.puts <<~HELP
           lambda-microvms #{VERSION}
@@ -91,6 +103,7 @@ module Lambda
             package       Create deployable source artifact
             deploy        Package, upload to S3, and create a MicroVM image
             run           Run the configured MicroVM image
+            sdk-contract  Check whether aws-sdk-lambda exposes MicroVM operations
             version       Print version
         HELP
         0

data/lib/lambda/microvms/client.rb

@@ -10,66 +10,153 @@ module Lambda
   module MicroVMs
     # Ruby wrapper over Aws::Lambda::Client for Lambda MicroVM lifecycle operations.
     class Client
+      # SDK methods this wrapper expects from Aws::Lambda::Client.
+      REQUIRED_OPERATIONS = %i[
+        create_microvm_image
+        get_microvm_image
+        delete_microvm_image
+        run_microvm
+        get_microvm
+        list_microvms
+        suspend_microvm
+        resume_microvm
+        terminate_microvm
+        create_microvm_auth_token
+      ].freeze
+
       attr_reader :sdk
 
       def initialize(region: nil, profile: nil, sdk: nil, **)
-        @sdk = sdk || build_sdk(region:, profile:, **)
+        @sdk = sdk || build_sdk(region: region, profile: profile, **)
+      end
+
+      # Return wrapper operations missing from the given SDK client.
+      #
+      # @param sdk [Object, nil] SDK client to inspect
+      # @return [Array<Symbol>] missing SDK operation names
+      def self.unsupported_operations(sdk = nil)
+        sdk ||= Aws::Lambda::Client.new(stub_responses: true) if defined?(Aws::Lambda::Client)
+        return REQUIRED_OPERATIONS unless sdk
+
+        REQUIRED_OPERATIONS.reject { |operation| sdk.respond_to?(operation) }
+      end
+
+      # Check whether the given SDK client exposes all MicroVM operations.
+      #
+      # @param sdk [Object, nil] SDK client to inspect
+      # @return [Boolean]
+      def self.sdk_contract_supported?(sdk = nil)
+        unsupported_operations(sdk).empty?
       end
 
+      # Build an image resource wrapper without fetching it.
+      #
+      # @param arn [String] MicroVM image ARN
+      # @return [Image] image resource wrapper
       def image(arn)
         Image.new(client: self, arn: arn)
       end
 
+      # Build a MicroVM resource wrapper without fetching it.
+      #
+      # @param id_or_arn [String] MicroVM id or ARN
+      # @return [MicroVM] MicroVM resource wrapper
       def microvm(id_or_arn)
         MicroVM.new(client: self, id: id_or_arn)
       end
 
+      # Create a MicroVM image through the Lambda SDK.
+      #
+      # @param params [Hash] SDK request parameters
+      # @return [Image] created image resource
       def create_image(**params)
         response = call_sdk(:create_microvm_image, **params)
         Image.from_response(client: self, response: response)
       end
 
+      # Fetch a MicroVM image and wrap the SDK response.
+      #
+      # @param params [Hash] SDK request parameters
+      # @return [Image] fetched image resource
       def get_image(**params)
         response = call_sdk(:get_microvm_image, **params)
         Image.from_response(client: self, response: response)
       end
 
+      # Delete a MicroVM image.
+      #
+      # @param params [Hash] SDK request parameters
+      # @return [Object] raw SDK response
       def delete_image(**params)
         call_sdk(:delete_microvm_image, **params)
       end
 
+      # Run a MicroVM from an image.
+      #
+      # @param params [Hash] SDK request parameters
+      # @return [MicroVM] started MicroVM resource
       def run(**params)
         response = call_sdk(:run_microvm, **params)
         MicroVM.from_response(client: self, response: response)
       end
       alias run_microvm run
 
+      # Fetch a MicroVM and wrap the SDK response.
+      #
+      # @param params [Hash] SDK request parameters
+      # @return [MicroVM] fetched MicroVM resource
       def get_microvm(**params)
         response = call_sdk(:get_microvm, **params)
         MicroVM.from_response(client: self, response: response)
       end
 
+      # List MicroVMs using the underlying Lambda SDK client.
+      #
+      # @param params [Hash] SDK request parameters
+      # @return [Object] raw SDK response
       def list_microvms(**params)
         call_sdk(:list_microvms, **params)
       end
 
+      # Suspend a MicroVM.
+      #
+      # @param params [Hash] SDK request parameters
+      # @return [Object] raw SDK response
       def suspend_microvm(**params)
         call_sdk(:suspend_microvm, **params)
       end
 
+      # Resume a suspended MicroVM.
+      #
+      # @param params [Hash] SDK request parameters
+      # @return [Object] raw SDK response
       def resume_microvm(**params)
         call_sdk(:resume_microvm, **params)
       end
 
+      # Terminate a MicroVM.
+      #
+      # @param params [Hash] SDK request parameters
+      # @return [Object] raw SDK response
       def terminate_microvm(**params)
         call_sdk(:terminate_microvm, **params)
       end
 
+      # Create an auth token for direct MicroVM endpoint access.
+      #
+      # @param params [Hash] SDK request parameters
+      # @return [Object] raw SDK response
       def create_auth_token(**params)
         call_sdk(:create_microvm_auth_token, **params)
       end
       alias create_microvm_auth_token create_auth_token
 
+      # Dispatch a supported operation to the underlying SDK client.
+      #
+      # @param operation [Symbol] SDK method name
+      # @param params [Hash] SDK request parameters
+      # @return [Object] raw SDK response
+      # @raise [UnsupportedOperationError] when the SDK does not expose the operation
       def call_sdk(operation, **params)
         unless @sdk.respond_to?(operation)
           raise UnsupportedOperationError, "Aws::Lambda::Client does not expose ##{operation}; upgrade aws-sdk-lambda"

data/lib/lambda/microvms/deployer.rb

@@ -15,28 +15,41 @@ module Lambda
       attr_reader :project, :client, :s3
 
       def initialize(project:, client: nil, s3: nil) # rubocop:disable Naming/MethodParameterName
-        @project = project
+        @project = project.validate!
         @client = client || Client.new(region: project.region, profile: project.profile)
         @s3 = s3 || build_s3
       end
 
+      # Package the project into a deployable zip artifact.
+      #
+      # @return [String] artifact path
       def package
         Packager.new(project).package
       end
 
+      # Upload an artifact to the configured S3 bucket and prefix.
+      #
+      # @param path [String] local artifact path
+      # @return [String] S3 URI
       def upload(path)
         bucket = project.require!('deployment.bucket', project.s3_bucket)
         key = [project.s3_prefix.sub(%r{/\z}, ''), File.basename(path)].join('/')
-        s3.put_object(bucket: bucket, key: key, body: File.open(path, 'rb'))
+        File.open(path, 'rb') { |body| s3.put_object(bucket: bucket, key: key, body: body) }
         "s3://#{bucket}/#{key}"
       end
 
+      # Package, upload, and create a MicroVM image.
+      #
+      # @return [Image] created image resource
       def deploy
         artifact = package
         artifact_uri = upload(artifact)
         client.create_image(**project.create_image_params(artifact_uri: artifact_uri))
       end
 
+      # Run the configured image with configured runtime parameters.
+      #
+      # @return [MicroVM] started MicroVM resource
       def run
         image_arn = project.require!('image.arn', project.image_arn)
         role_arn = project.require!('role_arn', project.role_arn)
@@ -48,9 +61,7 @@ module Lambda
       def build_s3
         raise LoadError, 'install aws-sdk-s3 to use deployment helpers' unless defined?(Aws::S3::Client)
 
-        args = {}
-        args[:region] = project.region if project.region
-        args[:profile] = project.profile if project.profile
+        args = { region: project.region, profile: project.profile }.compact
         Aws::S3::Client.new(**args)
       end
     end

data/lib/lambda/microvms/doctor.rb

@@ -5,6 +5,7 @@ module Lambda
   module MicroVMs
     # Performs lightweight local project readiness checks.
     class Doctor
+      # Result object for a single doctor check.
       Check = Struct.new(:name, :ok, :detail, keyword_init: true)
 
       attr_reader :project, :runner
@@ -14,6 +15,9 @@ module Lambda
         @runner = runner
       end
 
+      # Run all local readiness checks.
+      #
+      # @return [Array<Check>] check results
       def checks
         [
           check('Ruby', RUBY_VERSION >= '3.2', RUBY_VERSION),
@@ -49,7 +53,8 @@ module Lambda
       end
 
       def config_check(name, value)
-        Check.new(name:, ok: value && value != '', detail: value || 'missing')
+        ok = value && value.to_s.strip != ''
+        Check.new(name:, ok: ok, detail: ok ? value : 'missing')
       end
 
       def ric_check

data/lib/lambda/microvms/endpoint.rb

@@ -16,17 +16,39 @@ module Lambda
         @http = http
       end
 
+      # Send an authenticated GET request to the MicroVM endpoint.
+      #
+      # @param path [String] endpoint path
+      # @param headers [Hash] additional HTTP headers
+      # @return [Hash,String,nil] parsed JSON response or raw body
       def get(path, headers: {})
         request(Net::HTTP::Get, path, headers:)
       end
 
+      # Send an authenticated 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 headers [Hash] additional HTTP headers
+      # @return [Hash,String,nil] parsed JSON response or raw body
       def post(path, json: nil, body: nil, headers: {})
         request(Net::HTTP::Post, path, json:, body:, headers:)
       end
 
+      # Build and execute an authenticated HTTP request.
+      #
+      # @param klass [Class] Net::HTTP request class
+      # @param path [String] endpoint path
+      # @param json [Hash,Array,nil] JSON body to encode
+      # @param body [String,nil] raw request body
+      # @param headers [Hash] additional HTTP headers
+      # @return [Hash,String,nil] parsed JSON response or raw body
+      # @raise [EndpointError] when the endpoint returns a non-2xx status
       def request(klass, path, json: nil, body: nil, headers: {})
-        response = @http.start(uri.host, uri.port, use_ssl: uri.scheme == 'https') do |http|
-          http.request(build_request(klass, path, headers:, body:, json:))
+        req = build_request(klass, path, headers:, body:, json:)
+        response = @http.start(req.uri.host, req.uri.port, use_ssl: req.uri.scheme == 'https') do |http|
+          http.request(req)
         end
 
         success = response.code.to_i.between?(200, 299)
@@ -41,10 +63,10 @@ module Lambda
       private
 
       def build_uri(path)
-        base = URI(@url)
+        base = ::URI.parse(@url)
         return base if path.nil? || path.empty? || path == '/'
 
-        joined = [base.path.sub(%r{/\z}, ''), path.sub(%r{\A/}, '')].reject(&:empty?).join('/')
+        joined = [base.path.sub(%r{/\z}, ''), path.sub(%r{\A/}, '')].reject(&:empty?).join('/').sub(%r{\A/+}, '')
         base.path = "/#{joined}"
         base
       end

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.1.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

@@ -15,11 +15,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

data/sig/lambda/microvms.rbs

@@ -3,6 +3,7 @@ module Lambda
     VERSION: String
 
     def self.session: (image_arn: String, role_arn: String, ?after: Symbol, ?client: Client, **untyped) { (MicroVM) -> untyped } -> untyped
+    def session: (image_arn: String, role_arn: String, ?after: Symbol, ?client: Client, **untyped) { (MicroVM) -> untyped } -> untyped
 
     class Error < StandardError
     end
@@ -26,7 +27,10 @@ module Lambda
     end
 
     class Client
+      REQUIRED_OPERATIONS: Array[Symbol]
       attr_reader sdk: untyped
+      def self.unsupported_operations: (?untyped sdk) -> Array[Symbol]
+      def self.sdk_contract_supported?: (?untyped sdk) -> bool
       def initialize: (?region: String?, ?profile: String?, ?sdk: untyped, **untyped) -> void
       def image: (String arn) -> Image
       def microvm: (String id_or_arn) -> MicroVM
@@ -43,6 +47,31 @@ module Lambda
       def create_auth_token: (**untyped) -> untyped
       def create_microvm_auth_token: (**untyped) -> untyped
       def call_sdk: (Symbol operation, **untyped) -> untyped
+
+      private
+
+      def build_sdk: (region: String?, profile: String?, **untyped) -> untyped
+    end
+
+    module Util
+      def extract: (untyped value, *untyped keys) -> untyped
+      def normalize_state: (untyped value) -> Symbol
+      def self.extract: (untyped value, *untyped keys) -> untyped
+      def self.normalize_state: (untyped value) -> Symbol
+    end
+
+    class Waiter
+      DEFAULT_DELAY: Float
+      DEFAULT_TIMEOUT: Float
+      def initialize: (?delay: Numeric, ?timeout: Numeric, ?sleeper: untyped) -> void
+      def wait: (?message: String) { () -> untyped } -> untyped
+    end
+
+    module Session
+      def session: (image_arn: String, role_arn: String, ?after: Symbol?, ?client: Client, **untyped) { (MicroVM) -> untyped } -> untyped
+      def cleanup: (MicroVM vm, Symbol? after) -> untyped
+      def self.session: (image_arn: String, role_arn: String, ?after: Symbol?, ?client: Client, **untyped) { (MicroVM) -> untyped } -> untyped
+      def self.cleanup: (MicroVM vm, Symbol? after) -> untyped
     end
 
     class Image
@@ -88,7 +117,13 @@ module Lambda
       def initialize: (url: String, token: String?, ?http: untyped) -> void
       def get: (String path, ?headers: Hash[String, String]) -> untyped
       def post: (String path, ?json: untyped, ?body: String?, ?headers: Hash[String, String]) -> untyped
-      def request: (singleton(Net::HTTPGenericRequest) klass, String path, ?json: untyped, ?body: String?, ?headers: Hash[String, String]) -> untyped
+      def request: (untyped klass, String path, ?json: untyped, ?body: String?, ?headers: Hash[String, untyped]) -> untyped
+
+      private
+
+      def build_uri: (String? path) -> untyped
+      def parse_response: (untyped response) -> untyped
+      def build_request: (untyped klass, String path, ?headers: Hash[String, untyped], ?json: untyped, ?body: String?) -> untyped
     end
 
     class Project
@@ -113,7 +148,16 @@ module Lambda
       def payload: () -> Hash[String, untyped]
       def create_image_params: (artifact_uri: String) -> Hash[Symbol, untyped]
       def run_params: () -> Hash[Symbol, untyped]
+      def validate!: () -> Project
       def require!: (String field, untyped value) -> untyped
+
+      private
+
+      def validate_hash!: () -> void
+      def validate_lifecycle_after!: () -> void
+      def hash_config: (String path) -> Hash[untyped, untyped]
+      def fetch: (*String paths, default: untyped) -> untyped
+      def stringify_keys: (untyped value) -> untyped
     end
 
     class Scaffold
@@ -121,12 +165,23 @@ module Lambda
       attr_reader directory: String
       def initialize: (String name, ?directory: String, ?force: bool) -> void
       def create: () -> String
+
+      private
+
+      def ensure_target!: () -> void
+      def write: (String path, String content) -> untyped
+      def gemfile: () -> String
+      def dockerfile: () -> String
+      def app_rb: () -> String
+      def microvm_yml: () -> String
+      def readme: () -> String
+      def env_example: () -> String
     end
 
     class Packager
       DEFAULT_EXCLUDES: Array[String]
       attr_reader project: Project
-      def initialize: (Project project) -> void
+      def initialize: (Project project, ?runner: untyped) -> void
       def package: (?output: String) -> String
     end
 
@@ -139,6 +194,10 @@ module Lambda
       def upload: (String path) -> String
       def deploy: () -> Image
       def run: () -> MicroVM
+
+      private
+
+      def build_s3: () -> untyped
     end
 
     class Doctor
@@ -148,6 +207,63 @@ module Lambda
       def initialize: (project: Project, ?runner: untyped) -> void
       def checks: () -> Array[untyped]
       def ok?: () -> bool
+
+      private
+
+      def check: (String name, untyped ok, untyped detail) -> untyped
+      def command_check: (String name, String command) -> untyped
+      def file_check: (String name, String path) -> untyped
+      def config_check: (String name, untyped value) -> untyped
+      def ric_check: () -> untyped
+    end
+  end
+end
+
+module Aws
+  module Lambda
+    class Client
+      def initialize: (**untyped) -> void
+    end
+  end
+
+  module S3
+    class Client
+      def initialize: (**untyped) -> void
     end
   end
 end
+
+module FileUtils
+  def self.mkdir_p: (String | Array[String]) -> untyped
+end
+
+module JSON
+  def self.parse: (String source) -> untyped
+  def self.generate: (untyped value) -> String
+end
+
+module Net
+  class HTTP
+    def self.start: (String address, Integer port, ?use_ssl: bool) { (untyped) -> untyped } -> untyped
+
+    class Get
+    end
+
+    class Post
+    end
+  end
+end
+
+module Open3
+  def self.capture3: (*String command, ?chdir: String) -> [String, String, untyped]
+end
+
+module URI
+  def self.parse: (String uri) -> untyped
+end
+
+module YAML
+  def self.safe_load_file: (String filename, ?permitted_classes: Array[singleton(Symbol)], ?aliases: bool) -> untyped
+end
+
+$CHILD_STATUS: untyped

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: lambda-microvms
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.1.0
 platform: ruby
 authors:
 - Kenneth C. Demanawa
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-26 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: aws-sdk-lambda
@@ -91,7 +90,6 @@ metadata:
   source_code_uri: https://github.com/kanutocd/lambda-microvms
   changelog_uri: https://github.com/kanutocd/lambda-microvms/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -106,8 +104,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.19
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Idiomatic Ruby lifecycle client for AWS Lambda MicroVMs.
 test_files: []