nightona 0.191.0

data/lib/nightona/nightona.rb

@@ -0,0 +1,336 @@
+# Copyright Daytona Platforms Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+# frozen_string_literal: true
+
+require 'json'
+require 'uri'
+
+module Nightona
+  class Nightona
+    include Instrumentation
+
+    # @return [Nightona::Config]
+    attr_reader :config
+
+    # @return [NightonaApiClient]
+    attr_reader :api_client
+
+    # @return [NightonaApiClient::SandboxApi]
+    attr_reader :sandbox_api
+
+    # @return [Nightona::VolumeService]
+    attr_reader :volume
+
+    # @return [NightonaApiClient::ObjectStorageApi]
+    attr_reader :object_storage_api
+
+    # @return [NightonaApiClient::SnapshotsApi]
+    attr_reader :snapshots_api
+
+    # @return [Nightona::SnapshotService]
+    attr_reader :snapshot
+
+    # @param config [Nightona::Config] Configuration options. Defaults to Nightona::Config.new
+    def initialize(config = Config.new)
+      @config = config
+      ensure_access_token_defined
+
+      otel_enabled = config.otel_enabled ||
+                     config._experimental&.dig('otel_enabled') ||
+                     config.read_env('NIGHTONA_OTEL_ENABLED') == 'true' ||
+                     config.read_env('NIGHTONA_EXPERIMENTAL_OTEL_ENABLED') == 'true'
+      @otel_state = (::Nightona.init_otel(Sdk::VERSION) if otel_enabled)
+
+      @api_client = build_api_client
+      @sandbox_api = NightonaApiClient::SandboxApi.new(api_client)
+      @config_api = NightonaApiClient::ConfigApi.new(api_client)
+      @volume = VolumeService.new(NightonaApiClient::VolumesApi.new(api_client), otel_state:)
+      @object_storage_api = NightonaApiClient::ObjectStorageApi.new(api_client)
+      @snapshots_api = NightonaApiClient::SnapshotsApi.new(api_client)
+      @snapshot = SnapshotService.new(snapshots_api:, object_storage_api:, default_region_id: config.target,
+                                      otel_state:)
+    end
+
+    # Shuts down OTel providers, flushing any pending telemetry data.
+    #
+    # @return [void]
+    def close
+      ::Nightona.shutdown_otel(@otel_state)
+      @otel_state = nil
+    end
+
+    # Creates a sandbox with the specified parameters
+    #
+    # @param params [Nightona::CreateSandboxFromSnapshotParams, Nightona::CreateSandboxFromImageParams, Nil] Sandbox creation parameters
+    # @return [Nightona::Sandbox] The created sandbox
+    # @raise [Nightona::Sdk::Error] If auto_stop_interval or auto_archive_interval is negative
+    def create(params = nil, on_snapshot_create_logs: nil)
+      if params.nil?
+        params = CreateSandboxFromSnapshotParams.new(language: CodeLanguage::PYTHON)
+      elsif params.language.nil?
+        params.language = CodeLanguage::PYTHON
+      end
+
+      unless CodeLanguage::ALL.include?(params.language.to_s.to_sym)
+        raise ArgumentError,
+              "Invalid #{CODE_TOOLBOX_LANGUAGE_LABEL}: #{params.language}. Supported languages: #{CodeLanguage::ALL.join(', ')}"
+      end
+
+      _create(params, on_snapshot_create_logs:)
+    end
+
+    # Deletes a Sandbox.
+    #
+    # @param sandbox [Nightona::Sandbox]
+    # @return [void]
+    def delete(sandbox) = sandbox.delete
+
+    # Gets a Sandbox by its ID.
+    #
+    # @param id [String]
+    # @return [Nightona::Sandbox]
+    def get(id)
+      sandbox_dto = sandbox_api.get_sandbox(id)
+      to_sandbox(sandbox_dto:)
+    end
+
+    # Iterates over Sandboxes matching the given query.
+    #
+    # @param query [Nightona::ListSandboxesQuery, nil] Optional filters, sorting, and per-page size.
+    # @return [Enumerator<Nightona::Sandbox>]
+    # @raise [Nightona::Sdk::Error]
+    #
+    # @example
+    #   nightona.list(Nightona::ListSandboxesQuery.new(labels: { 'env' => 'dev' })).each do |sandbox|
+    #     puts sandbox.id
+    #   end
+    def list(query = nil)
+      q = query || ListSandboxesQuery.new
+
+      Enumerator.new do |yielder|
+        cursor = nil
+        first_page = true
+        while first_page || cursor
+          first_page = false
+          response = fetch_sandbox_page(q, cursor)
+          response.items.each do |sandbox_dto|
+            yielder << to_sandbox(sandbox_dto: sandbox_dto)
+          end
+          cursor = response.next_cursor
+          break if cursor.nil? || (cursor.respond_to?(:empty?) && cursor.empty?)
+        end
+      end
+    end
+
+    # Starts a Sandbox and waits for it to be ready.
+    #
+    # @param sandbox [Nightona::Sandbox]
+    # @param timeout [Numeric] Maximum wait time in seconds (defaults to 60 s).
+    # @return [void]
+    def start(sandbox, timeout = Sandbox::DEFAULT_TIMEOUT) = sandbox.start(timeout)
+
+    # Stops a Sandbox and waits for it to be stopped.
+    #
+    # @param sandbox [Nightona::Sandbox]
+    # @param timeout [Numeric] Maximum wait time in seconds (defaults to 60 s).
+    # @return [void]
+    def stop(sandbox, timeout = Sandbox::DEFAULT_TIMEOUT) = sandbox.stop(timeout)
+
+    instrument :create, :delete, :get, :start, :stop, component: 'Nightona'
+
+    private
+
+    # @return [Nightona::OtelState, nil]
+    attr_reader :otel_state
+
+    # Fetches a single page of sandboxes. Each call produces one OTel span
+    # ("Nightona.list_fetch_page") so that paginated iteration emits N spans
+    # for N pages.
+    #
+    # @param q [Nightona::ListSandboxesQuery]
+    # @param cursor [String, nil]
+    # @return [NightonaApiClient::ListSandboxesResponse]
+    def fetch_sandbox_page(q, cursor)
+      opts = {
+        cursor: cursor,
+        limit: q.limit,
+        id: q.id,
+        name: q.name,
+        labels: q.labels ? JSON.dump(q.labels) : nil,
+        states: q.states,
+        snapshots: q.snapshots,
+        region_ids: q.targets,
+        min_cpu: q.min_cpu,
+        max_cpu: q.max_cpu,
+        min_memory_gi_b: q.min_memory_gib,
+        max_memory_gi_b: q.max_memory_gib,
+        min_disk_gi_b: q.min_disk_gib,
+        max_disk_gi_b: q.max_disk_gib,
+        is_public: q.is_public,
+        is_recoverable: q.is_recoverable,
+        created_at_after: q.created_at_after,
+        created_at_before: q.created_at_before,
+        last_event_after: q.last_activity_after,
+        last_event_before: q.last_activity_before,
+        sort: q.sort,
+        order: q.order
+      }.compact
+
+      sandbox_api.list_sandboxes(opts)
+    end
+
+    instrument :fetch_sandbox_page, component: 'Nightona.list'
+
+    # Creates a sandbox with the specified parameters
+    #
+    # @param params [Nightona::CreateSandboxFromSnapshotParams, Nightona::CreateSandboxFromImageParams] Sandbox creation parameters
+    # @param timeout [Numeric] Maximum wait time in seconds (defaults to 60 s).
+    # @param on_snapshot_create_logs [Proc]
+    # @return [Nightona::Sandbox] The created sandbox
+    # @raise [Nightona::Sdk::Error] If auto_stop_interval or auto_archive_interval is negative
+    def _create(params, timeout: 60, on_snapshot_create_logs: nil)
+      raise Sdk::Error, 'Timeout must be a non-negative number' if timeout.negative?
+
+      start_time = Time.now
+
+      raise Sdk::Error, 'auto_stop_interval must be a non-negative integer' if params.auto_stop_interval&.negative?
+
+      if params.auto_archive_interval&.negative?
+        raise Sdk::Error, 'auto_archive_interval must be a non-negative integer'
+      end
+
+      labels = params.labels&.dup || {}
+      labels[CODE_TOOLBOX_LANGUAGE_LABEL] = params.language.to_s if params.language
+
+      create_sandbox = NightonaApiClient::CreateSandbox.new(
+        user: params.os_user,
+        env: params.env_vars || {},
+        labels: labels,
+        public: params.public,
+        target: config.target,
+        auto_stop_interval: params.auto_stop_interval,
+        auto_archive_interval: params.auto_archive_interval,
+        auto_delete_interval: params.auto_delete_interval,
+        volumes: params.volumes,
+        network_block_all: params.network_block_all,
+        network_allow_list: params.network_allow_list,
+        domain_allow_list: params.domain_allow_list,
+        linked_sandbox: params.linked_sandbox
+      )
+
+      create_sandbox.snapshot = params.snapshot if params.respond_to?(:snapshot)
+
+      if params.respond_to?(:image) && params.image.is_a?(String)
+        create_sandbox.build_info = NightonaApiClient::CreateBuildInfo.new(
+          dockerfile_content: Image.base(params.image).dockerfile
+        )
+      elsif params.respond_to?(:image) && params.image.is_a?(Image)
+        create_sandbox.build_info = NightonaApiClient::CreateBuildInfo.new(
+          context_hashes: SnapshotService.process_image_context(object_storage_api, params.image),
+          dockerfile_content: params.image.dockerfile
+        )
+      end
+
+      if params.respond_to?(:resources)
+        create_sandbox.cpu = params.resources&.cpu
+        create_sandbox.memory = params.resources&.memory
+        create_sandbox.disk = params.resources&.disk
+        create_sandbox.gpu = params.resources&.gpu
+        if params.resources&.gpu_type
+          create_sandbox.gpu_type =
+            params.resources.gpu_type.is_a?(Array) ? params.resources.gpu_type : [params.resources.gpu_type]
+        end
+      end
+
+      response = sandbox_api.create_sandbox(create_sandbox)
+
+      if response.state == NightonaApiClient::SandboxState::PENDING_BUILD && on_snapshot_create_logs
+        # Wait for state to change from PENDING_BUILD before fetching logs
+        while response.state == NightonaApiClient::SandboxState::PENDING_BUILD
+          sleep(1)
+          response = sandbox_api.get_sandbox(response.id)
+        end
+
+        # Get build logs URL from API
+        build_logs_response = sandbox_api.get_build_logs_url(response.id)
+        uri = URI.parse("#{build_logs_response.url}?follow=true")
+
+        headers = {}
+        sandbox_api.api_client.update_params_for_auth!(headers, nil, ['bearer'])
+        Util.stream_async(uri:, headers:, on_chunk: on_snapshot_create_logs)
+      end
+
+      sandbox = to_sandbox(sandbox_dto: response)
+
+      if sandbox.state != NightonaApiClient::SandboxState::STARTED
+        sandbox.wait_for_sandbox_start([0.001, timeout - (Time.now - start_time)].max)
+      end
+
+      sandbox
+    end
+
+    # @return [void]
+    # @raise [Nightona::Sdk::Error]
+    def ensure_access_token_defined
+      return if config.api_key
+
+      unless config.jwt_token
+        raise Sdk::Error,
+              'Authentication credentials not found. Set NIGHTONA_API_KEY, or both NIGHTONA_JWT_TOKEN and ' \
+              'NIGHTONA_ORGANIZATION_ID. These can also be provided via Nightona::Config.'
+      end
+      return if config.organization_id
+
+      raise Sdk::Error,
+            'NIGHTONA_ORGANIZATION_ID is required when authenticating with NIGHTONA_JWT_TOKEN. ' \
+            'It can also be provided via Nightona::Config.'
+    end
+
+    # @return [NightonaApiClient::ApiClient]
+    def build_api_client
+      NightonaApiClient::ApiClient.new(api_client_config).tap do |client|
+        client.default_headers[HEADER_SOURCE] = SOURCE_RUBY
+        client.default_headers[HEADER_SDK_VERSION] = Sdk::VERSION
+        client.default_headers[HEADER_ORGANIZATION_ID] = config.organization_id if config.jwt_token
+        client.user_agent = "sdk-ruby/#{Sdk::VERSION}"
+      end
+    end
+
+    # @return [NightonaApiClient::Configuration]
+    def api_client_config
+      NightonaApiClient::Configuration.new.configure do |api_config|
+        uri = URI(config.api_url)
+        api_config.scheme = uri.scheme
+        api_config.host = uri.authority # Includes hostname:port
+        api_config.base_path = uri.path
+
+        api_config.access_token_getter = proc { config.api_key || config.jwt_token }
+        api_config
+      end
+    end
+
+    # @param sandbox_dto [NightonaApiClient::Sandbox, NightonaApiClient::SandboxListItem]
+    # @return [Nightona::Sandbox]
+    def to_sandbox(sandbox_dto:)
+      Sandbox.new(
+        sandbox_dto:,
+        config:,
+        sandbox_api:,
+        otel_state: @otel_state
+      )
+    end
+
+    SOURCE_RUBY = 'sdk-ruby'
+    private_constant :SOURCE_RUBY
+
+    HEADER_SOURCE = 'X-Nightona-Source'
+    private_constant :HEADER_SOURCE
+
+    HEADER_SDK_VERSION = 'X-Nightona-SDK-Version'
+    private_constant :HEADER_SDK_VERSION
+
+    HEADER_ORGANIZATION_ID = 'X-Nightona-Organization-ID'
+    private_constant :HEADER_ORGANIZATION_ID
+  end
+end

data/lib/nightona/object_storage.rb

@@ -0,0 +1,172 @@
+# Copyright Daytona Platforms Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+# frozen_string_literal: true
+
+require 'digest'
+require 'fileutils'
+require 'pathname'
+require 'tempfile'
+require 'zlib'
+require 'aws-sdk-s3'
+
+module Nightona
+  class ObjectStorage
+    # @return [String] The name of the S3 bucket used for object storage
+    attr_reader :bucket_name
+
+    # @return [Aws::S3::Client] The S3 client
+    attr_reader :s3_client
+
+    # Initialize ObjectStorage with S3-compatible credentials
+    #
+    # @param endpoint_url [String] The endpoint URL for the object storage service
+    # @param aws_access_key_id [String] The access key ID for the object storage service
+    # @param aws_secret_access_key [String] The secret access key for the object storage service
+    # @param aws_session_token [String] The session token for the object storage service
+    # @param bucket_name [String] The name of the bucket to use (defaults to "nightona-volume-builds")
+    # @param region [String] AWS region (defaults to us-east-1)
+    def initialize(endpoint_url:, aws_access_key_id:, aws_secret_access_key:, aws_session_token:, # rubocop:disable Metrics/ParameterLists
+                   bucket_name: DEFAULT_BUCKET_NAME, region: DEFAULT_REGION)
+      @bucket_name = bucket_name
+      @s3_client = Aws::S3::Client.new(
+        region:,
+        endpoint: endpoint_url,
+        access_key_id: aws_access_key_id,
+        secret_access_key: aws_secret_access_key,
+        session_token: aws_session_token
+      )
+    end
+
+    # Uploads a file to the object storage service
+    #
+    # @param path [String] The path to the file to upload
+    # @param organization_id [String] The organization ID to use
+    # @param archive_base_path [String, nil] The base path to use for the archive
+    # @return [String] The hash of the uploaded file
+    # @raise [Errno::ENOENT] If the path does not exist
+    def upload(path, organization_id, archive_base_path = nil)
+      raise Errno::ENOENT, "Path does not exist: #{path}" unless File.exist?(path)
+
+      path_hash = compute_hash_for_path_md5(path, archive_base_path)
+      s3_key = "#{organization_id}/#{path_hash}/context.tar"
+
+      return path_hash if file_exists_in_s3(s3_key)
+
+      upload_as_tar(s3_key, path, archive_base_path)
+
+      path_hash
+    end
+
+    # Compute the base path for an archive. Returns normalized path without the root
+    # (drive letter or leading slash).
+    #
+    # @param path_str [String] The path to compute the base path for
+    # @return [String] The base path for the given path
+    def self.compute_archive_base_path(path_str)
+      normalized_path = File.basename(path_str)
+
+      # Remove drive letter for Windows paths (e.g., C:)
+      path_without_drive = normalized_path.gsub(/^[A-Za-z]:/, '')
+
+      # Remove leading separators (both / and \)
+      path_without_drive.gsub(%r{^[/\\]+}, '')
+    end
+
+    private
+
+    # Computes the MD5 hash for a given path
+    #
+    # @param path_str [String] The path to compute the hash for
+    # @param archive_base_path [String, nil] The base path to use for the archive
+    # @return [String] The MD5 hash for the given path
+    def compute_hash_for_path_md5(path_str, archive_base_path = nil) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+      md5_hasher = Digest::MD5.new
+      abs_path_str = File.expand_path(path_str)
+
+      archive_base_path = self.class.compute_archive_base_path(path_str) if archive_base_path.nil?
+      md5_hasher.update(archive_base_path)
+
+      if File.file?(abs_path_str)
+        File.open(abs_path_str, 'rb') do |f|
+          while (chunk = f.read(8192))
+            md5_hasher.update(chunk)
+          end
+        end
+      else
+        Dir.glob(File.join(abs_path_str, '**', '*')).each do |file_path|
+          next unless File.file?(file_path)
+
+          rel_path = Pathname.new(file_path).relative_path_from(Pathname.new(abs_path_str)).to_s
+
+          md5_hasher.update(rel_path)
+
+          File.open(file_path, 'rb') do |f|
+            while (chunk = f.read(8192))
+              md5_hasher.update(chunk)
+            end
+          end
+        end
+
+        # Handle empty directories
+        Dir
+          .glob(File.join(abs_path_str, '**', '*'))
+          .select { |path| File.directory?(path) && Dir.empty?(path) }
+          .each do |empty_dir|
+            rel_dir = Pathname.new(empty_dir).relative_path_from(Pathname.new(abs_path_str)).to_s
+            md5_hasher.update(rel_dir)
+        end
+      end
+
+      md5_hasher.hexdigest
+    end
+
+    # Checks whether a specific object exists at the given path
+    #
+    # @param file_path [String] Full object path, e.g. "org/abcd123/context.tar"
+    # @return [Boolean] True if the object exists, False otherwise
+    def file_exists_in_s3(file_path)
+      s3_client.head_object(bucket: bucket_name, key: file_path)
+      true
+    rescue Aws::S3::Errors::NotFound
+      false
+    rescue StandardError => e
+      Sdk.logger.debug("Error checking file existence: #{e.message}")
+      false
+    end
+
+    # Uploads a file to the object storage service as a tar
+    #
+    # @param s3_key [String] The key to upload the file to
+    # @param source_path [String] The path to the file to upload
+    # @param archive_base_path [String, nil] The base path to use for the archive
+    def upload_as_tar(s3_key, source_path, archive_base_path = nil) # rubocop:disable Metrics/MethodLength
+      source_path = File.expand_path(source_path)
+
+      self.class.compute_archive_base_path(source_path) if archive_base_path.nil?
+
+      temp_file = Tempfile.new(['context', '.tar'])
+
+      begin
+        system('tar', '-cf', temp_file.path, '-C', File.dirname(source_path), File.basename(source_path))
+
+        File.open(temp_file.path, 'rb') do |file|
+          s3_client.put_object(
+            bucket: bucket_name,
+            key: s3_key,
+            body: file
+          )
+        end
+      ensure
+        temp_file.close
+        temp_file.unlink
+      end
+    end
+
+    DEFAULT_BUCKET_NAME = 'nightona-volume-builds'
+    private_constant :DEFAULT_BUCKET_NAME
+
+    DEFAULT_REGION = 'us-east-1'
+    private_constant :DEFAULT_REGION
+  end
+end

data/lib/nightona/otel.rb

@@ -0,0 +1,183 @@
+# Copyright Daytona Platforms Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+# frozen_string_literal: true
+
+module Nightona
+  # Holds OTel provider state for the SDK.
+  class OtelState
+    attr_reader :tracer_provider
+    attr_reader :meter_provider
+    attr_reader :tracer
+    attr_reader :meter
+
+    def initialize(tracer_provider:, meter_provider:, tracer:, meter:)
+      @tracer_provider = tracer_provider
+      @meter_provider = meter_provider
+      @tracer = tracer
+      @meter = meter
+      @histograms = {}
+      @histograms_mutex = Mutex.new
+    end
+
+    # Returns a cached histogram for the given metric name.
+    def histogram(name)
+      @histograms_mutex.synchronize do
+        @histograms[name] ||= meter.create_histogram(name, unit: 'ms')
+      end
+    end
+
+    def shutdown
+      tracer_provider.shutdown
+      meter_provider.shutdown
+    end
+  end
+
+  # Initializes OTel providers, sets globals, installs Typhoeus propagation.
+  # OTel gems are required lazily so they are never loaded when disabled.
+  #
+  # @param sdk_version [String]
+  # @return [OtelState]
+  def self.init_otel(sdk_version) # rubocop:disable Metrics/MethodLength
+    require 'opentelemetry-sdk'
+    require 'opentelemetry-metrics-sdk'
+    require 'opentelemetry-exporter-otlp'
+    require 'opentelemetry-exporter-otlp-metrics'
+
+    resource = OpenTelemetry::SDK::Resources::Resource.create(
+      'service.name' => 'nightona-ruby-sdk',
+      'service.version' => sdk_version
+    )
+
+    tracer_provider = OpenTelemetry::SDK::Trace::TracerProvider.new(resource:)
+    tracer_provider.add_span_processor(
+      OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
+        OpenTelemetry::Exporter::OTLP::Exporter.new
+      )
+    )
+    OpenTelemetry.tracer_provider = tracer_provider
+
+    meter_provider = OpenTelemetry::SDK::Metrics::MeterProvider.new(resource:)
+    meter_provider.add_metric_reader(
+      OpenTelemetry::SDK::Metrics::Export::PeriodicMetricReader.new(
+        exporter: OpenTelemetry::Exporter::OTLP::Metrics::MetricsExporter.new
+      )
+    )
+    OpenTelemetry.meter_provider = meter_provider
+
+    tracer = tracer_provider.tracer('nightona-ruby-sdk', sdk_version)
+    meter = meter_provider.meter('nightona-ruby-sdk')
+
+    # Install Typhoeus trace-context propagation
+    install_typhoeus_propagation
+
+    OtelState.new(tracer_provider:, meter_provider:, tracer:, meter:)
+  end
+
+  # Flushes and shuts down OTel providers.
+  def self.shutdown_otel(state)
+    state&.shutdown
+  end
+
+  # Wraps a block with OTel span creation and duration histogram recording.
+  # When otel_state is nil (OTel disabled), calls the block directly.
+  #
+  # @param otel_state [OtelState, nil]
+  # @param component [String]
+  # @param method_name [String]
+  # @return [Object] The block's return value
+  def self.with_instrumentation(otel_state, component, method_name, &block) # rubocop:disable Metrics/MethodLength
+    return block.call unless otel_state
+
+    span_name = "#{component}.#{method_name}"
+    metric_name = "#{to_snake_case(span_name)}_duration"
+    status = 'success'
+
+    otel_state.tracer.in_span(
+      span_name,
+      attributes: { 'component' => component, 'method' => method_name }
+    ) do |_span|
+      start_time = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+      begin
+        block.call
+      rescue StandardError => e
+        status = 'error'
+        raise e
+      ensure
+        duration_ms = (::Process.clock_gettime(::Process::CLOCK_MONOTONIC) - start_time) * 1000.0
+        otel_state.histogram(metric_name).record(
+          duration_ms,
+          attributes: { 'component' => component, 'method' => method_name, 'status' => status }
+        )
+      end
+    end
+  end
+
+  # Converts "ClassName.method_name" to "class_name_method_name".
+  def self.to_snake_case(str)
+    result = +''
+    str.each_char.with_index do |char, i|
+      if char == '.'
+        result << '_'
+      elsif char =~ /[A-Z]/ && i > 0 && str[i - 1] != '.'
+        result << '_' << char.downcase
+      else
+        result << char.downcase
+      end
+    end
+    result
+  end
+
+  # Installs Typhoeus.before callback for W3C trace-context propagation.
+  def self.install_typhoeus_propagation
+    return unless defined?(Typhoeus)
+
+    Typhoeus.before do |request|
+      headers = request.options[:headers] ||= {}
+      OpenTelemetry.propagation.inject(headers)
+      true
+    end
+  end
+
+  # Mixin that provides the `instrument` class macro for wrapping methods
+  # with OTel spans and metrics.
+  module Instrumentation
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      # Instruments the listed methods with OTel tracing/metrics.
+      # Must be called after all target methods are defined.
+      #
+      # @param method_names [Array<Symbol>] methods to instrument
+      # @param component [String] component name for span/metric attributes
+      def instrument(*method_names, component:) # rubocop:disable Metrics/MethodLength
+        method_names.each do |method_name|
+          original = instance_method(method_name)
+
+          # Detect original visibility
+          visibility = if private_method_defined?(method_name, false)
+                         :private
+                       elsif protected_method_defined?(method_name, false)
+                         :protected
+                       else
+                         :public
+                       end
+
+          define_method(method_name) do |*args, **kwargs, &blk|
+            ::Nightona.with_instrumentation(otel_state, component, method_name.to_s) do
+              original.bind_call(self, *args, **kwargs, &blk)
+            end
+          end
+
+          # Restore visibility
+          case visibility
+          when :private   then private method_name
+          when :protected then protected method_name
+          end
+        end
+      end
+    end
+  end
+end