lambda-microvms 0.0.0

data/lib/lambda/microvms/microvm.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Lambda
+  module MicroVMs
+    # Represents one running, suspended, or terminated Lambda MicroVM session.
+    class MicroVM
+      attr_reader :client, :id, :data
+
+      def self.from_response(client:, response:)
+        id = Util.extract(response, :microvm_id, :microvm_arn, :id, :arn)
+        new(client: client, id: id, data: response)
+      end
+
+      def initialize(client:, id:, data: nil)
+        @client = client
+        @id = id
+        @data = data
+      end
+
+      def refresh
+        fresh = client.get_microvm(microvm_id: id)
+        @data = fresh.data
+        self
+      end
+
+      def state
+        Util.normalize_state(Util.extract(@data, :state, :status, :microvm_state))
+      end
+
+      def running?
+        state == :running
+      end
+
+      def suspended?
+        state == :suspended
+      end
+
+      def terminated?
+        state == :terminated
+      end
+
+      def pending?
+        state == :pending
+      end
+
+      def endpoint_url
+        endpoint = Util.extract(@data, :endpoint, :endpoint_url, :url)
+        return endpoint if endpoint.is_a?(String)
+
+        Util.extract(endpoint, :url, :endpoint_url) if endpoint
+      end
+
+      def auth_token(ports: nil, ttl_seconds: nil, **params)
+        request = params.merge(microvm_id: id)
+        request[:ports] = ports if ports
+        request[:ttl_seconds] = ttl_seconds if ttl_seconds
+        response = client.create_auth_token(**request)
+        Util.extract(response, :token, :auth_token, :microvm_auth_token)
+      end
+
+      def endpoint(token: nil, **token_params)
+        Endpoint.new(url: endpoint_url, token: token || auth_token(**token_params))
+      end
+
+      def get(path, token: nil, **)
+        endpoint(token: token).get(path, **)
+      end
+
+      def post(path, json: nil, body: nil, token: nil, **)
+        endpoint(token: token).post(path, json: json, body: body, **)
+      end
+
+      def suspend(**params)
+        client.suspend_microvm(**params, microvm_id: id)
+        self
+      end
+
+      def resume(**params)
+        response = client.resume_microvm(**params, microvm_id: id)
+        @data = response if response
+        self
+      end
+
+      def terminate(**params)
+        client.terminate_microvm(**params, microvm_id: id)
+        self
+      end
+
+      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?
+        end
+        self
+      end
+
+      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?
+        end
+        self
+      end
+
+      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?
+        end
+        self
+      end
+    end
+  end
+end

data/lib/lambda/microvms/packager.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'open3'
+require 'pathname'
+
+module Lambda
+  module MicroVMs
+    # Creates a deployable source artifact for Lambda MicroVM image creation.
+    class Packager
+      DEFAULT_EXCLUDES = ['.git/*', 'tmp/*', 'vendor/bundle/*', '*.gem'].freeze
+
+      attr_reader :project
+
+      def initialize(project)
+        @project = project
+      end
+
+      def package(output: project.artifact_path)
+        FileUtils.mkdir_p(File.dirname(output))
+        relative_output = begin
+          Pathname.new(output).relative_path_from(Pathname.new(project.root)).to_s
+        rescue StandardError
+          output
+        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)
+        raise CommandError, "zip failed: #{stderr.empty? ? stdout : stderr}" unless status.success?
+
+        output
+      end
+    end
+  end
+end

data/lib/lambda/microvms/project.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require 'fileutils'
+require 'tmpdir'
+
+module Lambda
+  module MicroVMs
+    # Reads lambda-microvms project configuration from microvm.yml.
+    class Project
+      DEFAULT_CONFIG = 'microvm.yml'
+
+      attr_reader :root, :config_path, :config
+
+      def self.load(path = DEFAULT_CONFIG)
+        config_path = File.expand_path(path)
+        root = File.dirname(config_path)
+        new(root: root, config_path: config_path,
+            config: YAML.safe_load_file(config_path, permitted_classes: [Symbol], aliases: true) || {})
+      end
+
+      def initialize(root:, config_path:, config:)
+        @root = root
+        @config_path = config_path
+        @config = stringify_keys(config)
+      end
+
+      def name = fetch('name', default: File.basename(root))
+
+      def region = fetch('region', default: ENV.fetch('AWS_REGION', nil))
+
+      def profile = fetch('profile', default: ENV.fetch('AWS_PROFILE', nil))
+
+      def role_arn = fetch('role_arn', 'role', default: nil)
+
+      def image_arn = fetch('image_arn', 'image.arn', default: nil)
+
+      def image_name = fetch('image.name', default: name)
+
+      def dockerfile = File.expand_path(fetch('build.dockerfile', default: 'Dockerfile'), root)
+
+      def build_context = File.expand_path(fetch('build.context', default: '.'), root)
+
+      def artifact_path = File.expand_path(fetch('build.artifact', default: "tmp/#{name}-microvm.zip"), root)
+
+      def s3_bucket = fetch('deployment.bucket', 's3.bucket', default: nil)
+
+      def s3_prefix = fetch('deployment.prefix', 's3.prefix', default: "lambda-microvms/#{name}")
+
+      def lifecycle_after = fetch('runtime.after', default: 'suspend').to_sym
+
+      def payload
+        fetch('runtime.payload', default: {}) || {}
+      end
+
+      def create_image_params(artifact_uri:)
+        params = fetch('image.create', default: {}) || {}
+        params = stringify_keys(params)
+        symbolized = params.to_h { |key, value| [key.to_sym, value] }
+        symbolized[:name] ||= image_name
+        symbolized[:code_artifact] ||= artifact_uri
+        symbolized
+      end
+
+      def run_params
+        params = stringify_keys(fetch('runtime.run', default: {}) || {})
+        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
+
+      def require!(field, value)
+        return value if value && value != ''
+
+        raise ConfigurationError, "missing required project configuration: #{field}"
+      end
+
+      private
+
+      def fetch(*paths, default:)
+        paths.each do |path|
+          current = @config
+          path.to_s.split('.').each do |part|
+            current = current[part] if current.respond_to?(:[])
+          end
+          return current unless current.nil?
+        end
+        default
+      end
+
+      def stringify_keys(value)
+        case value
+        when Hash
+          value.to_h { |key, child| [key.to_s, stringify_keys(child)] }
+        when Array
+          value.map { |child| stringify_keys(child) }
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/lambda/microvms/scaffold.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+module Lambda
+  module MicroVMs
+    # Generates Ruby Lambda MicroVM starter projects.
+    class Scaffold
+      attr_reader :name, :directory
+
+      def initialize(name, directory: name, force: false)
+        @name = name
+        @directory = directory
+        @force = force
+      end
+
+      def create
+        ensure_target!
+        FileUtils.mkdir_p(directory)
+        write('Gemfile', gemfile)
+        write('Dockerfile', dockerfile)
+        write('app.rb', app_rb)
+        write('microvm.yml', microvm_yml)
+        write('README.md', readme)
+        write('.env.example', env_example)
+        directory
+      end
+
+      private
+
+      def ensure_target!
+        return if @force || !File.exist?(directory) || Dir.empty?(directory)
+
+        raise ConfigurationError, "target directory is not empty: #{directory}"
+      end
+
+      def write(path, content)
+        File.write(File.join(directory, path), content)
+      end
+
+      def gemfile
+        <<~GEMFILE
+          source "https://rubygems.org"
+
+          gem "aws_lambda_ric"
+          gem "json"
+        GEMFILE
+      end
+
+      def dockerfile
+        <<~DOCKERFILE
+          FROM ruby:3.4-slim
+
+          ENV LAMBDA_TASK_ROOT=/var/task
+          WORKDIR ${LAMBDA_TASK_ROOT}
+
+          RUN apt-get update \\
+              && apt-get install -y --no-install-recommends build-essential \\
+              && rm -rf /var/lib/apt/lists/*
+
+          COPY Gemfile ${LAMBDA_TASK_ROOT}/Gemfile
+          RUN bundle install
+
+          COPY app.rb ${LAMBDA_TASK_ROOT}/app.rb
+
+          ENTRYPOINT ["bundle", "exec", "aws_lambda_ric"]
+          CMD ["app.App::Handler.process"]
+        DOCKERFILE
+      end
+
+      def app_rb
+        <<~RUBY
+          # frozen_string_literal: true
+
+          require "json"
+
+          module App
+            class Handler
+              def self.process(event:, context:)
+                {
+                  ok: true,
+                  message: "Hello from #{name}",
+                  event: event,
+                  request_id: context.respond_to?(:aws_request_id) ? context.aws_request_id : nil
+                }
+              end
+            end
+          end
+        RUBY
+      end
+
+      def microvm_yml
+        <<~YAML
+          name: #{name}
+          region: us-east-1
+
+          # Optional: AWS profile to use for CLI-driven commands.
+          # profile: default
+
+          # IAM role used when running the MicroVM.
+          role_arn: arn:aws:iam::123456789012:role/lambda-microvm-runtime
+
+          build:
+            dockerfile: Dockerfile
+            context: .
+            artifact: tmp/#{name}-microvm.zip
+
+          deployment:
+            bucket: replace-me-lambda-microvm-artifacts
+            prefix: lambda-microvms/#{name}
+
+          image:
+            name: #{name}
+            # arn: arn:aws:lambda:us-east-1:123456789012:microvm-image:#{name}
+            create:
+              # Keep this hash close to the AWS Lambda MicroVM create image API shape.
+              # lambda-microvms deploy injects code_artifact after S3 upload.
+              name: #{name}
+
+          runtime:
+            after: suspend
+            payload:
+              source: lambda-microvms
+        YAML
+      end
+
+      def readme
+        <<~README
+          # #{name}
+
+          Ruby AWS Lambda MicroVM application scaffold generated by `lambda-microvms`.
+
+          This project uses `aws_lambda_ric` inside the image so the Ruby handler can speak the Lambda Runtime API.
+
+          ## Local setup
+
+          ```bash
+          bundle install
+          ```
+
+          ## Build / deploy from the parent toolkit
+
+          ```bash
+          lambda-microvms doctor
+          lambda-microvms package
+          lambda-microvms deploy
+          lambda-microvms run
+          ```
+
+          Edit `microvm.yml` before deploying.
+        README
+      end
+
+      def env_example
+        <<~ENV
+          AWS_REGION=us-east-1
+          AWS_PROFILE=default
+        ENV
+      end
+    end
+  end
+end

data/lib/lambda/microvms/session.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Lambda
+  module MicroVMs
+    # Convenience API for run/use/cleanup MicroVM sessions.
+    module Session
+      module_function
+
+      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
+        yield vm
+      ensure
+        cleanup(vm, after) if vm
+      end
+
+      def cleanup(vm, after) # rubocop:disable Naming/MethodParameterName
+        case after
+        when :keep, nil
+          nil
+        when :suspend
+          vm.suspend
+        when :terminate
+          vm.terminate
+        else
+          raise ArgumentError, "unknown cleanup policy: #{after.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/lambda/microvms/util.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Lambda
+  module MicroVMs
+    # Internal helpers shared by resource objects.
+    module Util
+      module_function
+
+      def extract(value, *keys)
+        keys.each do |key|
+          if value.respond_to?(key)
+            result = value.public_send(key)
+            return result unless result.nil?
+          end
+
+          next unless value.respond_to?(:[])
+
+          begin
+            result = value[key]
+            return result unless result.nil?
+          rescue KeyError, TypeError
+            nil
+          end
+        end
+
+        nil
+      end
+
+      def normalize_state(value)
+        value.to_s.downcase.to_sym
+      end
+    end
+  end
+end

data/lib/lambda/microvms/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Lambda
+  module MicroVMs
+    VERSION = '0.0.0'
+  end
+end

data/lib/lambda/microvms/waiter.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Lambda
+  module MicroVMs
+    # Polls a resource until a desired lifecycle state is reached.
+    class Waiter
+      DEFAULT_DELAY = 1.0
+      DEFAULT_TIMEOUT = 60.0
+
+      def initialize(delay: DEFAULT_DELAY, timeout: DEFAULT_TIMEOUT, sleeper: Kernel)
+        @delay = delay
+        @timeout = timeout
+        @sleeper = sleeper
+      end
+
+      def wait(message: 'condition')
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + @timeout
+
+        loop do
+          value = yield
+          return value if value
+
+          now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          break if now >= deadline
+
+          @sleeper.sleep([@delay, deadline - now].min)
+        end
+
+        raise WaitTimeoutError, "timed out waiting for #{message}"
+      end
+    end
+  end
+end

data/lib/lambda/microvms.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative 'microvms/version'
+require_relative 'microvms/error'
+require_relative 'microvms/util'
+require_relative 'microvms/waiter'
+require_relative 'microvms/endpoint'
+require_relative 'microvms/client'
+require_relative 'microvms/image'
+require_relative 'microvms/microvm'
+require_relative 'microvms/session'
+require_relative 'microvms/project'
+require_relative 'microvms/scaffold'
+require_relative 'microvms/packager'
+require_relative 'microvms/deployer'
+require_relative 'microvms/doctor'
+
+module Lambda
+  # Idiomatic Ruby lifecycle helpers for AWS Lambda MicroVMs.
+  module MicroVMs
+    module_function
+
+    def session(...)
+      Session.session(...)
+    end
+  end
+end

data/sig/lambda/microvms.rbs

@@ -0,0 +1,153 @@
+module Lambda
+  module MicroVMs
+    VERSION: String
+
+    def self.session: (image_arn: String, role_arn: String, ?after: Symbol, ?client: Client, **untyped) { (MicroVM) -> untyped } -> untyped
+
+    class Error < StandardError
+    end
+
+    class WaitTimeoutError < Error
+    end
+
+    class UnsupportedOperationError < Error
+    end
+
+    class ConfigurationError < Error
+    end
+
+    class CommandError < Error
+    end
+
+    class EndpointError < Error
+      attr_reader status: Integer
+      attr_reader body: String?
+      def initialize: (String message, status: Integer, body: String?) -> void
+    end
+
+    class Client
+      attr_reader sdk: untyped
+      def initialize: (?region: String?, ?profile: String?, ?sdk: untyped, **untyped) -> void
+      def image: (String arn) -> Image
+      def microvm: (String id_or_arn) -> MicroVM
+      def create_image: (**untyped) -> Image
+      def get_image: (**untyped) -> Image
+      def delete_image: (**untyped) -> untyped
+      def run: (**untyped) -> MicroVM
+      def run_microvm: (**untyped) -> MicroVM
+      def get_microvm: (**untyped) -> MicroVM
+      def list_microvms: (**untyped) -> untyped
+      def suspend_microvm: (**untyped) -> untyped
+      def resume_microvm: (**untyped) -> untyped
+      def terminate_microvm: (**untyped) -> untyped
+      def create_auth_token: (**untyped) -> untyped
+      def create_microvm_auth_token: (**untyped) -> untyped
+      def call_sdk: (Symbol operation, **untyped) -> untyped
+    end
+
+    class Image
+      attr_reader client: Client
+      attr_reader arn: String?
+      attr_reader data: untyped
+      def self.from_response: (client: Client, response: untyped) -> Image
+      def initialize: (client: Client, arn: String?, ?data: untyped) -> void
+      def refresh: () -> Image
+      def state: () -> Symbol
+      def ready?: () -> bool
+      def wait_until_ready: (?delay: Numeric, ?timeout: Numeric) -> Image
+      def run: (role_arn: String, ?payload: untyped, **untyped) -> MicroVM
+    end
+
+    class MicroVM
+      attr_reader client: Client
+      attr_reader id: String?
+      attr_reader data: untyped
+      def self.from_response: (client: Client, response: untyped) -> MicroVM
+      def initialize: (client: Client, id: String?, ?data: untyped) -> void
+      def refresh: () -> MicroVM
+      def state: () -> Symbol
+      def running?: () -> bool
+      def suspended?: () -> bool
+      def terminated?: () -> bool
+      def pending?: () -> bool
+      def endpoint_url: () -> String?
+      def auth_token: (?ports: untyped, ?ttl_seconds: Integer?, **untyped) -> untyped
+      def endpoint: (?token: String?, **untyped) -> Endpoint
+      def get: (String path, ?token: String?, **untyped) -> untyped
+      def post: (String path, ?json: untyped, ?body: String?, ?token: String?, **untyped) -> untyped
+      def suspend: (**untyped) -> MicroVM
+      def resume: (**untyped) -> MicroVM
+      def terminate: (**untyped) -> MicroVM
+      def wait_until_running: (?delay: Numeric, ?timeout: Numeric) -> MicroVM
+      def wait_until_suspended: (?delay: Numeric, ?timeout: Numeric) -> MicroVM
+      def wait_until_terminated: (?delay: Numeric, ?timeout: Numeric) -> MicroVM
+    end
+
+    class Endpoint
+      attr_reader url: String
+      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
+    end
+
+    class Project
+      DEFAULT_CONFIG: String
+      attr_reader root: String
+      attr_reader config_path: String
+      attr_reader config: Hash[String, untyped]
+      def self.load: (?String path) -> Project
+      def initialize: (root: String, config_path: String, config: Hash[untyped, untyped]) -> void
+      def name: () -> String
+      def region: () -> String?
+      def profile: () -> String?
+      def role_arn: () -> String?
+      def image_arn: () -> String?
+      def image_name: () -> String
+      def dockerfile: () -> String
+      def build_context: () -> String
+      def artifact_path: () -> String
+      def s3_bucket: () -> String?
+      def s3_prefix: () -> String
+      def lifecycle_after: () -> Symbol
+      def payload: () -> Hash[String, untyped]
+      def create_image_params: (artifact_uri: String) -> Hash[Symbol, untyped]
+      def run_params: () -> Hash[Symbol, untyped]
+      def require!: (String field, untyped value) -> untyped
+    end
+
+    class Scaffold
+      attr_reader name: String
+      attr_reader directory: String
+      def initialize: (String name, ?directory: String, ?force: bool) -> void
+      def create: () -> String
+    end
+
+    class Packager
+      DEFAULT_EXCLUDES: Array[String]
+      attr_reader project: Project
+      def initialize: (Project project) -> void
+      def package: (?output: String) -> String
+    end
+
+    class Deployer
+      attr_reader project: Project
+      attr_reader client: Client
+      attr_reader s3: untyped
+      def initialize: (project: Project, ?client: untyped, ?s3: untyped) -> void
+      def package: () -> String
+      def upload: (String path) -> String
+      def deploy: () -> Image
+      def run: () -> MicroVM
+    end
+
+    class Doctor
+      Check: untyped
+      attr_reader project: Project
+      attr_reader runner: untyped
+      def initialize: (project: Project, ?runner: untyped) -> void
+      def checks: () -> Array[untyped]
+      def ok?: () -> bool
+    end
+  end
+end