lambda-microvms 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 296c088486e240241e9e84b8932be4b07dd929aa4168b3b88d96347c5f6e9173
-  data.tar.gz: 8b3b9880d86869ef123247fb635d3a09bbc812bc6512ea6a45e6983c2414c04a
+  metadata.gz: c2278501b187e57ed03eacd396649c19e09bd5c6e07e890f5ce0403588c8f2fb
+  data.tar.gz: c8f240355cdc41e80e5d1d31a231e31cac3e6fd77d488f584e1027df0a47db0a
 SHA512:
-  metadata.gz: 114c31806d2c30c3682b9f33a79ddc2b3b114a5c4898f48f1fa07edf5ecf5e61bdd2cdc9d49150ca415715bb8e1a911335bd44a59f6277adb8e50ca424235a23
-  data.tar.gz: 713a3dabdfeac0e9dad4ea3212fa556295e6b77ee9929daf919ec56c6f01c8cce1e384220548a17fff6bb2e900ffe4903a21650edcfbe7929f7400b420c8eaee
+  metadata.gz: 22bc5c257c1650f571cdf560a4c32af34cd119341776cb42a707104620255bbd0e26091b4967acc88462ca873e8319c5109aa9ee46fa26ceb0634207c32526bd
+  data.tar.gz: 942370b040e49ece5f159226f0da4094f05b054c7636210150f2858d768c863e9deb3997d72dff212c707542812134a230850f2ebef06b8478c9af089c288f72

data/CHANGELOG.md

@@ -1,6 +1,15 @@
 # Changelog
 
-## 0.1.0 Unreleased
+## Unreleased
+
+## 0.2.0
+
+- Added `lambda-microvms sdk-contract` and doctor output for the experimental MicroVM SDK operation contract.
+- Added an adapter boundary for MicroVM SDK operations.
+- Added `Lambda::MicroVMs::FunctionClient` and `lambda-microvms function-invoke` for standard Lambda function APIs.
+- Made MicroVM deploy/run fail before packaging or uploading when the installed `aws-sdk-lambda` lacks MicroVM operations.
+
+## 0.1.0
 
 - Initial Ruby development kit for AWS Lambda MicroVMs.
 - Client wrapper over `aws-sdk-lambda`.

data/README.md

@@ -5,9 +5,9 @@
 [![Ruby Version](https://img.shields.io/badge/ruby-%3E%3D%203.2-ruby.svg)](https://www.ruby-lang.org/en/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-A Ruby development kit for AWS Lambda MicroVMs.
+A Ruby development kit for AWS Lambda MicroVM experiments and standard Lambda function workflows.
 
-`lambda-microvms` builds on the official `aws-sdk-lambda` gem. It provides Ruby resource objects, lifecycle helpers, endpoint calls, project scaffolding, packaging, and deployment commands for Lambda MicroVM applications.
+`lambda-microvms` builds on the official `aws-sdk-lambda` gem. It provides Ruby resource objects, lifecycle helpers, endpoint calls, project scaffolding, packaging, experimental MicroVM deployment commands, and a supported Lambda function client for APIs that exist today.
 
 It gives Ruby developers a higher-level workflow:
 
@@ -77,7 +77,15 @@ gem "aws_lambda_ric"
 lambda-microvms doctor
 ```
 
-Checks Ruby, Docker, AWS CLI, project config, Dockerfile, deployment bucket, runtime role, and `aws_lambda_ric` presence.
+Checks Ruby, Docker, AWS CLI, project config, Dockerfile, deployment bucket, runtime role, `aws_lambda_ric` presence, and whether the installed `aws-sdk-lambda` exposes the experimental MicroVM operation contract.
+
+## Check the MicroVM SDK contract
+
+```bash
+lambda-microvms sdk-contract
+```
+
+The public `aws-sdk-lambda` gem may not expose MicroVM lifecycle operations such as `create_microvm_image` or `run_microvm`. When those methods are missing, MicroVM `deploy` and `run` fail before packaging or uploading artifacts.
 
 ## Package
 
@@ -113,6 +121,30 @@ lambda-microvms run
 
 Runs the configured image ARN with the configured role ARN and runtime payload.
 
+## Standard Lambda function APIs
+
+The gem also includes a supported path for regular Lambda function APIs available in `aws-sdk-lambda` today.
+
+```ruby
+client = Lambda::MicroVMs::FunctionClient.new(region: "us-east-1")
+
+client.create_function(
+  name: "ruby-worker",
+  role_arn: "arn:aws:iam::123456789012:role/lambda-runtime",
+  handler: "app.Handler.process",
+  runtime: "ruby3.4",
+  zip_file: "tmp/function.zip"
+)
+
+result = client.invoke(function_name: "ruby-worker", payload: { hello: "world" })
+```
+
+You can also invoke an existing function from the CLI:
+
+```bash
+lambda-microvms function-invoke ruby-worker '{"hello":"world"}'
+```
+
 ## Ruby SDK usage
 
 ```ruby
@@ -169,6 +201,7 @@ Lambda::MicroVMs::Client
         ├── MicroVM
         ├── Endpoint
         ├── Session
+        ├── FunctionClient
         ├── Scaffold
         ├── Packager
         └── Deployer
@@ -176,5 +209,6 @@ 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
+MicroVM lifecycle support is experimental and contract-gated. The current public `aws-sdk-lambda` may not expose the MicroVM methods this gem wraps. Use `lambda-microvms sdk-contract` to verify your installed SDK.
+
+Standard Lambda function operations are available through `Lambda::MicroVMs::FunctionClient`.

data/exe/lambda-microvms

@@ -7,24 +7,33 @@ module Lambda
   module MicroVMs
     # Minimal CLI for the Ruby Lambda MicroVM development kit.
     class CLI
+      COMMANDS = {
+        'version' => :version,
+        '--version' => :version,
+        '-v' => :version,
+        'new' => :new_project,
+        'package' => :package,
+        'deploy' => :deploy,
+        'run' => :run_microvm,
+        'doctor' => :doctor,
+        'sdk-contract' => :sdk_contract,
+        'function-invoke' => :function_invoke,
+        'help' => :help
+      }.freeze
+
       def initialize(argv, out: $stdout, err: $stderr)
         @argv = argv
         @out = out
         @err = err
       end
 
-      # rubocop:disable Metrics/MethodLength
       def run
         command = @argv.shift
-        case command
-        when 'version', '--version', '-v' then version
-        when 'new' then new_project
-        when 'package' then package
-        when 'deploy' then deploy
-        when 'run' then run_microvm
-        when 'doctor' then doctor
-        when 'sdk-contract' then sdk_contract
-        when 'help', nil then help
+        action = COMMANDS[command]
+        if action
+          send(action)
+        elsif command.nil?
+          help
         else
           @err.puts "unknown command: #{command}"
           help
@@ -34,7 +43,6 @@ module Lambda
         @err.puts "error: #{e.message}"
         1
       end
-      # rubocop:enable Metrics/MethodLength
 
       private
 
@@ -93,6 +101,14 @@ module Lambda
         end
       end
 
+      def function_invoke
+        function_name = @argv.shift || raise(ArgumentError, 'usage: lambda-microvms function-invoke NAME [JSON]')
+        payload = @argv.empty? ? nil : JSON.parse(@argv.join(' '))
+        result = FunctionClient.new.invoke(function_name:, payload:)
+        @out.puts(result.is_a?(String) ? result : JSON.generate(result))
+        0
+      end
+
       def help
         @out.puts <<~HELP
           lambda-microvms #{VERSION}
@@ -104,6 +120,8 @@ module Lambda
             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
+            function-invoke NAME [JSON]
+                          Invoke a standard Lambda function with supported AWS APIs
             version       Print version
         HELP
         0

data/lib/lambda/microvms/adapters/microvm_sdk.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Lambda
+  module MicroVMs
+    # Internal adapter implementations for provider-specific SDK surfaces.
+    module Adapters
+      # Adapter for the experimental Lambda MicroVM SDK operation surface.
+      class MicroVMSdk
+        # SDK method names required by the experimental MicroVM lifecycle wrapper.
+        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(sdk)
+          @sdk = sdk
+        end
+
+        # Return MicroVM SDK operations missing from the wrapped SDK client.
+        #
+        # @return [Array<Symbol>] missing SDK operation names
+        def unsupported_operations
+          REQUIRED_OPERATIONS.reject { |operation| sdk.respond_to?(operation) }
+        end
+
+        # Check whether the wrapped SDK client exposes all MicroVM operations.
+        #
+        # @return [Boolean]
+        def supported?
+          unsupported_operations.empty?
+        end
+
+        # Dispatch a MicroVM operation to the wrapped 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(operation, **params)
+          unless sdk.respond_to?(operation)
+            raise UnsupportedOperationError, "Aws::Lambda::Client does not expose ##{operation}; run sdk-contract"
+          end
+
+          sdk.public_send(operation, **params)
+        end
+      end
+    end
+  end
+end

data/lib/lambda/microvms/client.rb

@@ -11,23 +11,13 @@ module Lambda
     # 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, **)
+      REQUIRED_OPERATIONS = Adapters::MicroVMSdk::REQUIRED_OPERATIONS
+
+      attr_reader :sdk, :adapter
+
+      def initialize(region: nil, profile: nil, sdk: nil, adapter: nil, **)
         @sdk = sdk || build_sdk(region: region, profile: profile, **)
+        @adapter = adapter || Adapters::MicroVMSdk.new(@sdk)
       end
 
       # Return wrapper operations missing from the given SDK client.
@@ -38,7 +28,7 @@ module Lambda
         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) }
+        Adapters::MicroVMSdk.new(sdk).unsupported_operations
       end
 
       # Check whether the given SDK client exposes all MicroVM operations.
@@ -158,11 +148,7 @@ module Lambda
       # @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"
-        end
-
-        @sdk.public_send(operation, **params)
+        adapter.call(operation, **params)
       end
 
       private

data/lib/lambda/microvms/deployer.rb

@@ -42,6 +42,7 @@ module Lambda
       #
       # @return [Image] created image resource
       def deploy
+        ensure_microvm_contract!
         artifact = package
         artifact_uri = upload(artifact)
         client.create_image(**project.create_image_params(artifact_uri: artifact_uri))
@@ -51,6 +52,7 @@ module Lambda
       #
       # @return [MicroVM] started MicroVM resource
       def run
+        ensure_microvm_contract!
         image_arn = project.require!('image.arn', project.image_arn)
         role_arn = project.require!('role_arn', project.role_arn)
         client.image(image_arn).run(**project.run_params, role_arn: role_arn)
@@ -64,6 +66,15 @@ module Lambda
         args = { region: project.region, profile: project.profile }.compact
         Aws::S3::Client.new(**args)
       end
+
+      def ensure_microvm_contract!
+        return unless client.respond_to?(:adapter)
+
+        missing = client.adapter.unsupported_operations
+        return if missing.empty?
+
+        raise UnsupportedOperationError, "Aws::Lambda::Client is missing MicroVM operations: #{missing.join(', ')}"
+      end
     end
   end
 end

data/lib/lambda/microvms/doctor.rb

@@ -27,7 +27,8 @@ module Lambda
           file_check('Dockerfile', project.dockerfile),
           config_check('role_arn', project.role_arn),
           config_check('deployment.bucket', project.s3_bucket),
-          ric_check
+          ric_check,
+          sdk_contract_check
         ]
       end
 
@@ -62,6 +63,13 @@ module Lambda
         ok = File.exist?(gemfile) && File.read(gemfile).include?('aws_lambda_ric')
         Check.new(name: 'aws_lambda_ric', ok: ok, detail: ok ? 'present in Gemfile' : 'missing from Gemfile')
       end
+
+      def sdk_contract_check
+        missing = Client.unsupported_operations
+        ok = missing.empty?
+        detail = ok ? 'MicroVM operations available' : "missing: #{missing.join(', ')}"
+        Check.new(name: 'aws-sdk-lambda MicroVM contract', ok: ok, detail: detail)
+      end
     end
   end
 end

data/lib/lambda/microvms/function_client.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Lambda
+  module MicroVMs
+    # Thin wrapper over stable Aws::Lambda::Client function APIs.
+    class FunctionClient
+      attr_reader :sdk
+
+      def initialize(region: nil, profile: nil, sdk: nil, **)
+        @sdk = sdk || build_sdk(region: region, profile: profile, **)
+      end
+
+      # Create a Lambda function from a zip file using supported AWS APIs.
+      #
+      # @param name [String] function name
+      # @param role_arn [String] IAM role ARN
+      # @param handler [String] handler name
+      # @param runtime [String] Lambda runtime identifier
+      # @param zip_file [String] path to deployment zip
+      # @param params [Hash] additional create_function parameters
+      # @return [Object] raw SDK response
+      def create_function(name:, role_arn:, handler:, runtime:, zip_file:, **params) # rubocop:disable Metrics/ParameterLists
+        sdk.create_function(
+          **params,
+          function_name: name,
+          role: role_arn,
+          handler: handler,
+          runtime: runtime,
+          code: { zip_file: File.binread(zip_file) }
+        )
+      end
+
+      # Update Lambda function code from a zip file.
+      #
+      # @param function_name [String] function name or ARN
+      # @param zip_file [String] path to deployment zip
+      # @param params [Hash] additional update_function_code parameters
+      # @return [Object] raw SDK response
+      def update_function_code(function_name:, zip_file:, **params)
+        sdk.update_function_code(**params, function_name: function_name, zip_file: File.binread(zip_file))
+      end
+
+      # Invoke a Lambda function and parse JSON payloads when possible.
+      #
+      # @param function_name [String] function name or ARN
+      # @param payload [Object] request payload
+      # @param params [Hash] additional invoke parameters
+      # @return [Object] parsed response payload or raw response body
+      def invoke(function_name:, payload: nil, **params)
+        response = sdk.invoke(**params, function_name: function_name, payload: encode_payload(payload))
+        parse_payload(response.payload)
+      end
+
+      private
+
+      def build_sdk(region:, profile:, **options)
+        unless defined?(Aws::Lambda::Client)
+          raise LoadError, 'install aws-sdk-lambda to use Lambda::MicroVMs::FunctionClient'
+        end
+
+        args = options.dup
+        args[:region] = region if region
+        args[:profile] = profile if profile
+        Aws::Lambda::Client.new(**args)
+      end
+
+      def encode_payload(payload)
+        case payload
+        when nil
+          nil
+        when String
+          payload
+        else
+          JSON.generate(payload)
+        end
+      end
+
+      def parse_payload(payload)
+        body = payload.respond_to?(:read) ? payload.read : payload.to_s
+        return nil if body.empty?
+
+        JSON.parse(body)
+      rescue JSON::ParserError
+        body
+      end
+    end
+  end
+end

data/lib/lambda/microvms/version.rb

@@ -3,6 +3,6 @@
 module Lambda
   module MicroVMs
     # Current gem version.
-    VERSION = '0.1.0'
+    VERSION = '0.2.0'
   end
 end

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'

data/sig/lambda/microvms.rbs

@@ -29,9 +29,10 @@ module Lambda
     class Client
       REQUIRED_OPERATIONS: Array[Symbol]
       attr_reader sdk: untyped
+      attr_reader adapter: Adapters::MicroVMSdk
       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 initialize: (?region: String?, ?profile: String?, ?sdk: untyped, ?adapter: Adapters::MicroVMSdk, **untyped) -> void
       def image: (String arn) -> Image
       def microvm: (String id_or_arn) -> MicroVM
       def create_image: (**untyped) -> Image
@@ -53,6 +54,31 @@ module Lambda
       def build_sdk: (region: String?, profile: String?, **untyped) -> untyped
     end
 
+    module Adapters
+      class MicroVMSdk
+        REQUIRED_OPERATIONS: Array[Symbol]
+        attr_reader sdk: untyped
+        def initialize: (untyped sdk) -> void
+        def unsupported_operations: () -> Array[Symbol]
+        def supported?: () -> bool
+        def call: (Symbol operation, **untyped) -> untyped
+      end
+    end
+
+    class FunctionClient
+      attr_reader sdk: untyped
+      def initialize: (?region: String?, ?profile: String?, ?sdk: untyped, **untyped) -> void
+      def create_function: (name: String, role_arn: String, handler: String, runtime: String, zip_file: String, **untyped) -> untyped
+      def update_function_code: (function_name: String, zip_file: String, **untyped) -> untyped
+      def invoke: (function_name: String, ?payload: untyped, **untyped) -> untyped
+
+      private
+
+      def build_sdk: (region: String?, profile: String?, **untyped) -> untyped
+      def encode_payload: (untyped payload) -> String?
+      def parse_payload: (untyped payload) -> untyped
+    end
+
     module Util
       def extract: (untyped value, *untyped keys) -> untyped
       def normalize_state: (untyped value) -> Symbol
@@ -198,6 +224,7 @@ module Lambda
       private
 
       def build_s3: () -> untyped
+      def ensure_microvm_contract!: () -> void
     end
 
     class Doctor
@@ -215,6 +242,7 @@ module Lambda
       def file_check: (String name, String path) -> untyped
       def config_check: (String name, untyped value) -> untyped
       def ric_check: () -> untyped
+      def sdk_contract_check: () -> untyped
     end
   end
 end
@@ -238,6 +266,9 @@ module FileUtils
 end
 
 module JSON
+  class ParserError < StandardError
+  end
+
   def self.parse: (String source) -> untyped
   def self.generate: (untyped value) -> String
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lambda-microvms
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Kenneth C. Demanawa
@@ -65,11 +65,13 @@ files:
 - README.md
 - exe/lambda-microvms
 - lib/lambda/microvms.rb
+- lib/lambda/microvms/adapters/microvm_sdk.rb
 - lib/lambda/microvms/client.rb
 - lib/lambda/microvms/deployer.rb
 - lib/lambda/microvms/doctor.rb
 - lib/lambda/microvms/endpoint.rb
 - lib/lambda/microvms/error.rb
+- lib/lambda/microvms/function_client.rb
 - lib/lambda/microvms/image.rb
 - lib/lambda/microvms/microvm.rb
 - lib/lambda/microvms/packager.rb