lambda-microvms 0.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: de35523913c4cd5c11fc48549081c7901db9fdacfef2a72618264885596bb838
+  data.tar.gz: 960ec7995dc496da3f358c6ad484eb0a420140afa727275b92e5eadf7201ce2b
+SHA512:
+  metadata.gz: 055d951f5d0a5dc948195eff437d7b67070faf74e5dba4eee65b583aa70fda29a0452d93ecbe4e311bf3e7f5f18054d999776c6c5294bc2c88b061c8a777c77c
+  data.tar.gz: 6948f65e7391fa14734dcd1f89757bfb6a1b2a04ee200566409de0851da3a80f41a7173607cbd6efa40a5bc31d09d1033237512eb145bf23358459871dd77da5

data/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 0.1.0 Unreleased
+
+- Initial Ruby development kit for AWS Lambda MicroVMs.
+- Client wrapper over `aws-sdk-lambda`.
+- Image, MicroVM, Endpoint, Waiter, and session helper APIs.
+- Project scaffolding via `lambda-microvms new NAME`.
+- Generated Ruby MicroVM projects include `aws_lambda_ric` for guest-side Lambda Runtime API integration.
+- Project configuration via `microvm.yml`.
+- Packaging helper via `lambda-microvms package`.
+- Deployment helper via `lambda-microvms deploy` using S3 artifact upload and MicroVM image creation.
+- Runtime helper via `lambda-microvms run`.
+- Project readiness checks via `lambda-microvms doctor`.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kenneth C. Demanawa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,179 @@
+# lambda-microvms
+
+[![Gem Version](https://badge.fury.io/rb/lambda-microvms.svg)](https://badge.fury.io/rb/lambda-microvms)
+[![CI](https://github.com/kanutocd/lambda-microvms/workflows/CI/badge.svg)](https://github.com/kanutocd/lambda-microvms/actions)
+[![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.
+
+`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.
+
+It gives Ruby developers a higher-level workflow:
+
+```text
+scaffold
+  ↓
+develop
+  ↓
+package
+  ↓
+deploy image
+  ↓
+run / suspend / resume / terminate
+```
+
+## Why `aws_lambda_ric` appears in generated projects
+
+Ruby MicroVM applications need a runtime inside the image. For non-AWS or OS-only Ruby container images, AWS documents the Ruby Runtime Interface Client (`aws_lambda_ric`) as the component that lets Ruby code interact with the Lambda Runtime API.
+
+`lambda-microvms` uses `aws_lambda_ric` as a **generated project dependency**, not as a host-side SDK dependency.
+
+```text
+Host side:
+  lambda-microvms
+  aws-sdk-lambda
+  aws-sdk-s3
+
+Guest side / inside generated image:
+  aws_lambda_ric
+  your Ruby handler
+```
+
+## Installation
+
+```ruby
+gem "lambda-microvms"
+```
+
+## Scaffold a Ruby MicroVM project
+
+```bash
+lambda-microvms new hello-worker
+cd hello-worker
+```
+
+Generated project:
+
+```text
+hello-worker/
+  Dockerfile
+  Gemfile
+  app.rb
+  microvm.yml
+  README.md
+  .env.example
+```
+
+The generated `Gemfile` includes:
+
+```ruby
+gem "aws_lambda_ric"
+```
+
+## Check readiness
+
+```bash
+lambda-microvms doctor
+```
+
+Checks Ruby, Docker, AWS CLI, project config, Dockerfile, deployment bucket, runtime role, and `aws_lambda_ric` presence.
+
+## Package
+
+```bash
+lambda-microvms package
+```
+
+Creates the source artifact configured by `microvm.yml`.
+
+## Deploy
+
+```bash
+lambda-microvms deploy
+```
+
+Deployment flow:
+
+```text
+zip project
+  ↓
+upload to S3
+  ↓
+create MicroVM image through aws-sdk-lambda
+```
+
+The exact AWS Lambda MicroVM API parameter names are still kept close to AWS naming. Put API-specific values under `image.create` in `microvm.yml`.
+
+## Run
+
+```bash
+lambda-microvms run
+```
+
+Runs the configured image ARN with the configured role ARN and runtime payload.
+
+## Ruby SDK usage
+
+```ruby
+require "lambda/microvms"
+
+client = Lambda::MicroVMs::Client.new(region: "us-east-1")
+
+image = client.image("arn:aws:lambda:us-east-1:123456789012:microvm-image:ruby-sandbox")
+
+vm = image.run(
+  role_arn: "arn:aws:iam::123456789012:role/lambda-microvm-runtime",
+  payload: { tenant_id: "tenant_123" }
+)
+
+vm.wait_until_running
+
+response = vm.post("/process", json: { hello: "world" })
+
+vm.suspend
+vm.resume
+vm.terminate
+```
+
+## Session helper
+
+```ruby
+Lambda::MicroVMs.session(
+  image_arn: "arn:aws:lambda:us-east-1:123456789012:microvm-image:ruby-sandbox",
+  role_arn: "arn:aws:iam::123456789012:role/lambda-microvm-runtime",
+  after: :suspend,
+  payload: { tenant_id: "tenant_123" }
+) do |vm|
+  vm.post("/process", json: { event_id: "evt_1" })
+end
+```
+
+Supported cleanup policies:
+
+```ruby
+after: :keep
+after: :suspend
+after: :terminate
+```
+
+## Architecture
+
+```text
+aws-sdk-lambda
+        │
+        ▼
+Lambda::MicroVMs::Client
+        │
+        ├── Image
+        ├── MicroVM
+        ├── Endpoint
+        ├── Session
+        ├── Scaffold
+        ├── Packager
+        └── Deployer
+```
+
+## 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.

data/exe/lambda-microvms

@@ -0,0 +1,102 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'lambda/microvms'
+
+module Lambda
+  module MicroVMs
+    # Minimal CLI for the Ruby Lambda MicroVM development kit.
+    class CLI
+      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 'help', nil then help
+        else
+          @err.puts "unknown command: #{command}"
+          help
+          1
+        end
+      rescue Error, ArgumentError, LoadError => e
+        @err.puts "error: #{e.message}"
+        1
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      private
+
+      def version
+        @out.puts VERSION
+        0
+      end
+
+      def new_project
+        name = @argv.shift || raise(ArgumentError, 'usage: lambda-microvms new NAME')
+        force = @argv.include?('--force')
+        Scaffold.new(name, force: force).create
+        @out.puts "created #{name}"
+        0
+      end
+
+      def project
+        @project ||= Project.load
+      end
+
+      def package
+        path = Packager.new(project).package
+        @out.puts path
+        0
+      end
+
+      def deploy
+        image = Deployer.new(project: project).deploy
+        @out.puts image.arn || image.data.inspect
+        0
+      end
+
+      def run_microvm
+        vm = Deployer.new(project: project).run
+        @out.puts vm.id || vm.data.inspect
+        0
+      end
+
+      def doctor
+        checks = Doctor.new(project: project).checks
+        checks.each do |check|
+          marker = check.ok ? 'PASS' : 'FAIL'
+          @out.puts "#{marker} #{check.name}: #{check.detail}"
+        end
+        checks.all?(&:ok) ? 0 : 1
+      end
+
+      def help
+        @out.puts <<~HELP
+          lambda-microvms #{VERSION}
+
+          Commands:
+            new NAME      Generate a Ruby Lambda MicroVM project using aws_lambda_ric
+            doctor        Check local project readiness
+            package       Create deployable source artifact
+            deploy        Package, upload to S3, and create a MicroVM image
+            run           Run the configured MicroVM image
+            version       Print version
+        HELP
+        0
+      end
+    end
+  end
+end
+
+exit Lambda::MicroVMs::CLI.new(ARGV).run

data/lib/lambda/microvms/client.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+begin
+  require 'aws-sdk-lambda'
+rescue LoadError
+  nil
+end
+
+module Lambda
+  module MicroVMs
+    # Ruby wrapper over Aws::Lambda::Client for Lambda MicroVM lifecycle operations.
+    class Client
+      attr_reader :sdk
+
+      def initialize(region: nil, profile: nil, sdk: nil, **)
+        @sdk = sdk || build_sdk(region:, profile:, **)
+      end
+
+      def image(arn)
+        Image.new(client: self, arn: arn)
+      end
+
+      def microvm(id_or_arn)
+        MicroVM.new(client: self, id: id_or_arn)
+      end
+
+      def create_image(**params)
+        response = call_sdk(:create_microvm_image, **params)
+        Image.from_response(client: self, response: response)
+      end
+
+      def get_image(**params)
+        response = call_sdk(:get_microvm_image, **params)
+        Image.from_response(client: self, response: response)
+      end
+
+      def delete_image(**params)
+        call_sdk(:delete_microvm_image, **params)
+      end
+
+      def run(**params)
+        response = call_sdk(:run_microvm, **params)
+        MicroVM.from_response(client: self, response: response)
+      end
+      alias run_microvm run
+
+      def get_microvm(**params)
+        response = call_sdk(:get_microvm, **params)
+        MicroVM.from_response(client: self, response: response)
+      end
+
+      def list_microvms(**params)
+        call_sdk(:list_microvms, **params)
+      end
+
+      def suspend_microvm(**params)
+        call_sdk(:suspend_microvm, **params)
+      end
+
+      def resume_microvm(**params)
+        call_sdk(:resume_microvm, **params)
+      end
+
+      def terminate_microvm(**params)
+        call_sdk(:terminate_microvm, **params)
+      end
+
+      def create_auth_token(**params)
+        call_sdk(:create_microvm_auth_token, **params)
+      end
+      alias create_microvm_auth_token create_auth_token
+
+      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)
+      end
+
+      private
+
+      def build_sdk(region:, profile:, **options)
+        raise LoadError, 'install aws-sdk-lambda to use Lambda::MicroVMs::Client' unless defined?(Aws::Lambda::Client)
+
+        args = options.dup
+        args[:region] = region if region
+        args[:profile] = profile if profile
+        Aws::Lambda::Client.new(**args)
+      end
+    end
+  end
+end

data/lib/lambda/microvms/deployer.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+begin
+  require 'aws-sdk-s3'
+rescue LoadError
+  nil
+end
+
+module Lambda
+  module MicroVMs
+    # Project-aware deployment helper: package, upload to S3, create MicroVM image.
+    class Deployer
+      attr_reader :project, :client, :s3
+
+      def initialize(project:, client: nil, s3: nil) # rubocop:disable Naming/MethodParameterName
+        @project = project
+        @client = client || Client.new(region: project.region, profile: project.profile)
+        @s3 = s3 || build_s3
+      end
+
+      def package
+        Packager.new(project).package
+      end
+
+      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'))
+        "s3://#{bucket}/#{key}"
+      end
+
+      def deploy
+        artifact = package
+        artifact_uri = upload(artifact)
+        client.create_image(**project.create_image_params(artifact_uri: artifact_uri))
+      end
+
+      def run
+        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)
+      end
+
+      private
+
+      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
+        Aws::S3::Client.new(**args)
+      end
+    end
+  end
+end

data/lib/lambda/microvms/doctor.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'English'
+module Lambda
+  module MicroVMs
+    # Performs lightweight local project readiness checks.
+    class Doctor
+      Check = Struct.new(:name, :ok, :detail, keyword_init: true)
+
+      attr_reader :project, :runner
+
+      def initialize(project:, runner: Kernel)
+        @project = project
+        @runner = runner
+      end
+
+      def checks
+        [
+          check('Ruby', RUBY_VERSION >= '3.2', RUBY_VERSION),
+          command_check('Docker', 'docker --version'),
+          command_check('AWS CLI', 'aws --version'),
+          file_check('microvm.yml', project.config_path),
+          file_check('Dockerfile', project.dockerfile),
+          config_check('role_arn', project.role_arn),
+          config_check('deployment.bucket', project.s3_bucket),
+          ric_check
+        ]
+      end
+
+      def ok?
+        checks.all?(&:ok)
+      end
+
+      private
+
+      def check(name, ok, detail) # rubocop:disable Naming/MethodParameterName
+        Check.new(name:, ok:, detail: detail.to_s)
+      end
+
+      def command_check(name, command)
+        output = `#{command} 2>&1`.strip
+        Check.new(name:, ok: $CHILD_STATUS.success?, detail: output)
+      rescue StandardError => e
+        Check.new(name:, ok: false, detail: e.message)
+      end
+
+      def file_check(name, path)
+        Check.new(name:, ok: File.exist?(path), detail: path)
+      end
+
+      def config_check(name, value)
+        Check.new(name:, ok: value && value != '', detail: value || 'missing')
+      end
+
+      def ric_check
+        gemfile = File.join(project.root, 'Gemfile')
+        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
+    end
+  end
+end

data/lib/lambda/microvms/endpoint.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+require 'uri'
+
+module Lambda
+  module MicroVMs
+    # HTTP client for a single Lambda MicroVM endpoint.
+    class Endpoint
+      attr_reader :url
+
+      def initialize(url:, token:, http: Net::HTTP)
+        @url = url
+        @token = token
+        @http = http
+      end
+
+      def get(path, headers: {})
+        request(Net::HTTP::Get, path, headers:)
+      end
+
+      def post(path, json: nil, body: nil, headers: {})
+        request(Net::HTTP::Post, path, json:, body:, headers:)
+      end
+
+      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:))
+        end
+
+        success = response.code.to_i.between?(200, 299)
+        unless success
+          raise EndpointError.new("MicroVM endpoint returned HTTP #{response.code}", status: response.code.to_i,
+                                                                                     body: response.body)
+        end
+
+        parse_response(response)
+      end
+
+      private
+
+      def build_uri(path)
+        base = URI(@url)
+        return base if path.nil? || path.empty? || path == '/'
+
+        joined = [base.path.sub(%r{/\z}, ''), path.sub(%r{\A/}, '')].reject(&:empty?).join('/')
+        base.path = "/#{joined}"
+        base
+      end
+
+      def parse_response(response)
+        content_type = response['Content-Type'].to_s
+        return JSON.parse(response.body) if content_type.include?('application/json') && !response.body.to_s.empty?
+
+        response.body
+      end
+
+      def build_request(klass, path, headers: {}, json: nil, body: nil)
+        uri = build_uri(path)
+        request = klass.new(uri)
+        headers = headers.merge('Authorization' => @token ? "Bearer #{@token}" : nil)
+        if json
+          headers['Content-Type'] ||= 'application/json'
+          request.body = JSON.generate(json)
+        elsif body
+          request.body = body
+        end
+        headers.each_pair.with_object(request) { |(key, value), req| req[key] = value }
+      end
+    end
+  end
+end

data/lib/lambda/microvms/error.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Lambda
+  module MicroVMs
+    # Base error for lambda-microvms.
+    class Error < StandardError; end
+
+    # Raised when an expected MicroVM lifecycle state is not reached in time.
+    class WaitTimeoutError < Error; end
+
+    # Raised when the configured AWS Lambda SDK client does not expose a needed operation.
+    class UnsupportedOperationError < Error; end
+
+    # Raised when project configuration is invalid or incomplete.
+    class ConfigurationError < Error; end
+
+    # Raised when an external command such as Docker fails.
+    class CommandError < Error; end
+
+    # Raised when a MicroVM endpoint call fails with a non-success response.
+    class EndpointError < Error
+      attr_reader :status, :body
+
+      def initialize(message, status:, body:)
+        @status = status
+        @body = body
+        super(message)
+      end
+    end
+  end
+end

data/lib/lambda/microvms/image.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Lambda
+  module MicroVMs
+    # Represents a Lambda MicroVM image/snapshot artifact.
+    class Image
+      attr_reader :client, :arn, :data
+
+      def self.from_response(client:, response:)
+        arn = Util.extract(response, :image_arn, :microvm_image_arn, :arn)
+        new(client: client, arn: arn, data: response)
+      end
+
+      def initialize(client:, arn:, data: nil)
+        @client = client
+        @arn = arn
+        @data = data
+      end
+
+      def refresh
+        fresh = client.get_image(image_arn: arn)
+        @data = fresh.data
+        self
+      end
+
+      def state
+        Util.normalize_state(Util.extract(@data, :state, :status, :image_state))
+      end
+
+      def ready?
+        %i[ready available active].include?(state)
+      end
+
+      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?
+        end
+        self
+      end
+
+      def run(role_arn:, payload: nil, **params)
+        request = params.merge(image_arn: arn, role_arn: role_arn)
+        request[:payload] = payload if payload
+        client.run(**request)
+      end
+    end
+  end
+end