daytona 0.202.0 → 0.204.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0d211705ef263fa492b31a4e32ffc3a1d6ff3dbd2429baa2fc03dcc60012672b
-  data.tar.gz: 803fc638b4d11ac3c2435621f565967888ac68e1278081f382ad9977ec26aa94
+  metadata.gz: b9262546e49c3718967e3a0300303d4a29307bf48e05d3858adbbd64ed3c5476
+  data.tar.gz: f7292a5cb930340df80595e497782a28fab1beb9bb3bbb5b8147a52ed8a4c952
 SHA512:
-  metadata.gz: a73eb35713a3d7bc507b9f5ef8290a2230c9accc2efd17dc2c6d6a9dc452ce1ac12d1453caba8c61e175743b488e22ad4876be8093a6208465c5071b33844b5e
-  data.tar.gz: dbf474763c6e4254eba6bd65d7892a756879fd22f10401eb3576fc1ccb4b89c4fe4beeaa45bb6e611de1346a5507134e6c11a8f028991159f6f6cd60b4592231
+  metadata.gz: 5ea724b9fd64d2efc919c764b7236b008e4eeda909b1796d0c05b91e31085cc379fe7a8215949ec1d0f8de40851a045edffd9aaabdfa13767d2346567876ef18
+  data.tar.gz: 44b45171c7a2d21e1060c52f85ef90a9379d10ddaeaf5bd4b66ecd3dd097ba6cfe1b67ec86e8feb00cdd96bd25853ef82e8bcd35b53db3e395fcc39b04199420

data/README.md

@@ -6,12 +6,20 @@ The SDK provides an interface for sandbox management, file system operations, Gi
 
 ## Installation
 
+Requires **Ruby >= 3.2**. Check your version with `ruby -v` before installing — on older versions the install fails with a Bundler/RubyGems resolver error rather than a clear message.
+
 Install the package using **gem**:
 
 ```bash
 gem install daytona
 ```
 
+or add it to your **Gemfile**:
+
+```ruby
+gem 'daytona'
+```
+
 ## Get API key
 
 Generate an API key from the [Daytona Dashboard ↗](https://app.daytona.io/dashboard/keys) to authenticate SDK requests and access Daytona services. For more information, see the [API keys](https://www.daytona.io/docs/en/api-keys/) documentation.
@@ -182,3 +190,45 @@ completions = lsp_server.completions(
   position: Daytona::LspServer::Position.new(line: 10, character: 15)
 )
 ```
+
+## List method return shapes
+
+Each `list` method returns a different shape depending on the resource. The table below shows the exact return type and how to access the elements.
+
+| Method | Return type | Shape | Access elements |
+| --- | --- | --- | --- |
+| `daytona.snapshot.list(page:, limit:)` | `Daytona::PaginatedResource` | Paginated wrapper | `result.items.each` |
+| `daytona.secret.list(cursor:, limit:, ...)` | `Daytona::ListSecretsResponse` | Cursor-paginated wrapper | `page.items.each` |
+| `daytona.volume.list` | `Array<Daytona::Volume>` | Bare array | iterate directly |
+| `daytona.list(query)` | `Enumerator<Daytona::Sandbox>` | Lazy enumerator | `.each { \|s\| ... }` |
+
+`PaginatedResource` and `ListSecretsResponse` are **wrapper objects**, not arrays. Calling `.each` or `.map` directly on them raises `NoMethodError`. Always go through `.items`:
+
+```ruby
+# snapshots — page-number pagination
+result = daytona.snapshot.list(page: 1, limit: 20)
+# result.items       => Array<Daytona::Snapshot>
+# result.total       => Float (total across all pages)
+# result.page        => Float (current page, 1-indexed)
+# result.total_pages => Float
+result.items.each { |snapshot| puts "#{snapshot.name} (#{snapshot.image_name})" }
+
+# secrets — cursor pagination
+cursor = nil
+loop do
+  page = daytona.secret.list(cursor: cursor, limit: 100)
+  # page.items       => Array<Daytona::Secret>
+  # page.total       => Float
+  # page.next_cursor => String | nil (nil = no more pages)
+  page.items.each { |secret| puts secret.name }
+  cursor = page.next_cursor
+  break if cursor.nil?
+end
+
+# volumes — bare array, iterate directly
+daytona.volume.list.each { |vol| puts vol.name }
+
+# sandboxes — lazy enumerator, fetches pages on demand
+query = Daytona::ListSandboxesQuery.new(labels: { 'env' => 'dev' })
+daytona.list(query).each { |sandbox| puts sandbox.id }
+```

data/lib/daytona/common/daytona.rb

@@ -56,6 +56,9 @@ module Daytona
     # @return [String, nil] Comma-separated list of allowed domains for the Sandbox
     attr_accessor :domain_allow_list
 
+    # @return [String, nil] Outbound proxy URL to route the Sandbox HTTP(S) traffic through
+    attr_accessor :outbound_proxy_url
+
     # @return [Integer, nil] Time to live in minutes (0 to disable)
     attr_accessor :ttl_minutes
 
@@ -86,6 +89,9 @@ module Daytona
     # @param network_block_all [Boolean, nil] Whether to block all network access for the Sandbox
     # @param network_allow_list [String, nil] Comma-separated list of allowed CIDR network addresses for the Sandbox
     # @param domain_allow_list [String, nil] Comma-separated list of allowed domains for the Sandbox
+    # @param outbound_proxy_url [String, nil] Outbound proxy URL to route the Sandbox HTTP(S) traffic through.
+    #   Applied via the HTTP(S)_PROXY environment variables; combine with domain_allow_list for
+    #   network-layer enforcement.
     # @param ttl_minutes [Integer, nil] Time to live in minutes (0 to disable)
     # @param ephemeral [Boolean, nil] Whether the Sandbox should be ephemeral
     # @param linked_sandbox [String, nil] ID or name of an existing Sandbox to link the new Sandbox to
@@ -106,6 +112,7 @@ module Daytona
       network_block_all: nil,
       network_allow_list: nil,
       domain_allow_list: nil,
+      outbound_proxy_url: nil,
       ephemeral: nil,
       linked_sandbox: nil
     )
@@ -125,6 +132,7 @@ module Daytona
       @network_block_all = network_block_all
       @network_allow_list = network_allow_list
       @domain_allow_list = domain_allow_list
+      @outbound_proxy_url = outbound_proxy_url
       @ephemeral = ephemeral
       @linked_sandbox = linked_sandbox
 
@@ -153,6 +161,7 @@ module Daytona
         network_block_all:,
         network_allow_list:,
         domain_allow_list:,
+        outbound_proxy_url:,
         ephemeral:,
         linked_sandbox:
       }.compact
@@ -207,6 +216,9 @@ module Daytona
     # @param network_block_all [Boolean, nil] Whether to block all network access for the Sandbox
     # @param network_allow_list [String, nil] Comma-separated list of allowed CIDR network addresses for the Sandbox
     # @param domain_allow_list [String, nil] Comma-separated list of allowed domains for the Sandbox
+    # @param outbound_proxy_url [String, nil] Outbound proxy URL to route the Sandbox HTTP(S) traffic through.
+    #   Applied via the HTTP(S)_PROXY environment variables; combine with domain_allow_list for
+    #   network-layer enforcement.
     # @param ephemeral [Boolean, nil] Whether the Sandbox should be ephemeral
     def initialize(image:, resources: nil, **args)
       @image = image
@@ -250,6 +262,9 @@ module Daytona
     # @param network_block_all [Boolean, nil] Whether to block all network access for the Sandbox
     # @param network_allow_list [String, nil] Comma-separated list of allowed CIDR network addresses for the Sandbox
     # @param domain_allow_list [String, nil] Comma-separated list of allowed domains for the Sandbox
+    # @param outbound_proxy_url [String, nil] Outbound proxy URL to route the Sandbox HTTP(S) traffic through.
+    #   Applied via the HTTP(S)_PROXY environment variables; combine with domain_allow_list for
+    #   network-layer enforcement.
     # @param ephemeral [Boolean, nil] Whether the Sandbox should be ephemeral
     def initialize(snapshot: nil, **args)
       @snapshot = snapshot

data/lib/daytona/common/snapshot.rb

@@ -43,6 +43,14 @@ module Daytona
   end
 
   class Snapshot
+    # Matches RFC 4122 UUIDs (versions 1-5) and the nil UUID - the same set the
+    # Daytona API recognizes as snapshot IDs. Anything else is treated as a name.
+    SNAPSHOT_ID_PATTERN = Regexp.new(
+      '\A(?:[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}' \
+      '|00000000-0000-0000-0000-000000000000)\z',
+      Regexp::IGNORECASE
+    ).freeze
+
     # @return [String] Unique identifier for the Snapshot
     attr_reader :id
 
@@ -94,6 +102,9 @@ module Daytona
     # @return [DaytonaApiClient::BuildInfo, nil] Build information for the snapshot
     attr_reader :build_info
 
+    # @return [String, nil] ID of the sandbox the Snapshot was created from
+    attr_reader :source_sandbox_id
+
     # @param snapshot_dto [DaytonaApiClient::SnapshotDto] The snapshot DTO from the API
     def initialize(snapshot_dto) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
       @id = snapshot_dto.id
@@ -113,6 +124,7 @@ module Daytona
       @updated_at = snapshot_dto.updated_at
       @last_used_at = snapshot_dto.last_used_at
       @build_info = snapshot_dto.build_info
+      @source_sandbox_id = snapshot_dto.source_sandbox_id
     end
 
     # Creates a Snapshot instance from a SnapshotDto
@@ -120,5 +132,11 @@ module Daytona
     # @param dto [DaytonaApiClient::SnapshotDto] The snapshot DTO from the API
     # @return [Daytona::Snapshot] The snapshot instance
     def self.from_dto(dto) = new(dto)
+
+    # Whether the given value looks like a Snapshot ID (a UUID) rather than a name.
+    #
+    # @param value [Object] value to test
+    # @return [Boolean] true when value is a UUID-shaped String
+    def self.id?(value) = value.is_a?(String) && SNAPSHOT_ID_PATTERN.match?(value)
   end
 end

data/lib/daytona/daytona.rb

@@ -289,6 +289,7 @@ module Daytona
         network_block_all: params.network_block_all,
         network_allow_list: params.network_allow_list,
         domain_allow_list: params.domain_allow_list,
+        outbound_proxy_url: params.outbound_proxy_url,
         linked_sandbox: params.linked_sandbox
       )
 

data/lib/daytona/sandbox.rb

@@ -88,6 +88,10 @@ module Daytona
     #   Not returned by list results; call #refresh on each item to populate.
     attr_reader :domain_allow_list
 
+    # @return [String, nil] Outbound proxy URL to route the sandbox HTTP(S) traffic through.
+    #   Not returned by list results; call #refresh on each item to populate.
+    attr_reader :outbound_proxy_url
+
     # @return [String] The target environment for the sandbox
     attr_reader :target
 
@@ -1109,6 +1113,7 @@ module Daytona
         @network_block_all = sandbox_dto.network_block_all
         @network_allow_list = sandbox_dto.network_allow_list
         @domain_allow_list = sandbox_dto.domain_allow_list
+        @outbound_proxy_url = sandbox_dto.outbound_proxy_url
         @volumes = sandbox_dto.volumes
         @build_info = sandbox_dto.build_info
         @backup_created_at = sandbox_dto.backup_created_at

data/lib/daytona/sdk/errors.rb

@@ -120,11 +120,19 @@ module Daytona
     class GitPushRejectedError < ConflictError; end
     class GitDirtyWorktreeError < ConflictError; end
     class GitMergeConflictError < ConflictError; end
+    class GitTransportFailedError < BadGatewayError; end
+    class GitRemoteRejectedError < UnprocessableEntityError; end
 
     # Daemon: filesystem
     class FileNotFoundError < NotFoundError; end
     class FileAccessDeniedError < ForbiddenError; end
 
+    # The supplied file path was rejected by the daemon (code `INVALID_FILE_PATH`).
+    class InvalidFilePathError < BadRequestError; end
+
+    # The daemon could not read the sandbox file (code `FILE_READ_FAILED`).
+    class FileReadFailedError < InternalServerError; end
+
     # Daemon: LSP
     class LspServerNotInitializedError < BadRequestError; end
 
@@ -171,10 +179,14 @@ module Daytona
       [SOURCE_DAEMON, 'GIT_PUSH_REJECTED'] => GitPushRejectedError,
       [SOURCE_DAEMON, 'GIT_DIRTY_WORKTREE'] => GitDirtyWorktreeError,
       [SOURCE_DAEMON, 'GIT_MERGE_CONFLICT'] => GitMergeConflictError,
+      [SOURCE_DAEMON, 'GIT_TRANSPORT_FAILED'] => GitTransportFailedError,
+      [SOURCE_DAEMON, 'GIT_REMOTE_REJECTED'] => GitRemoteRejectedError,
 
       # Daemon: filesystem
       [SOURCE_DAEMON, 'FILE_NOT_FOUND'] => FileNotFoundError,
       [SOURCE_DAEMON, 'FILE_ACCESS_DENIED'] => FileAccessDeniedError,
+      [SOURCE_DAEMON, 'INVALID_FILE_PATH'] => InvalidFilePathError,
+      [SOURCE_DAEMON, 'FILE_READ_FAILED'] => FileReadFailedError,
 
       # Daemon: LSP
       [SOURCE_DAEMON, 'LSP_SERVER_NOT_INITIALIZED'] => LspServerNotInitializedError,

data/lib/daytona/sdk/version.rb

@@ -5,6 +5,6 @@
 
 module Daytona
   module Sdk
-    VERSION = '0.202.0'
+    VERSION = '0.204.0'
   end
 end

data/lib/daytona/secret_service.rb

@@ -66,7 +66,8 @@ module Daytona
     #   cursor = nil
     #   loop do
     #     page = daytona.secret.list(cursor:, limit: 100)
-    #     page.items.each { |secret| puts secret.name }
+    #     puts "Fetched #{page.items.length} of #{page.total} secrets"
+    #     page.items.each { |secret| puts "#{secret.name} (#{secret.id})" }
     #     cursor = page.next_cursor
     #     break if cursor.nil?
     #   end

data/lib/daytona/snapshot_service.rb

@@ -26,19 +26,21 @@ module Daytona
     #
     # @param page [Integer, Nil]
     # @param limit [Integer, Nil]
+    # @param source_sandbox_id [String, Nil] Filter by the ID of the sandbox the snapshot was created from
     # @return [Daytona::PaginatedResource] Paginated list of all Snapshots
     # @raise [Daytona::Sdk::Error]
     #
     # @example
     #   daytona = Daytona::Daytona.new
-    #   response = daytona.snapshot.list(page: 1, limit: 10)
-    #   snapshots.items.each { |snapshot| puts "#{snapshot.name} (#{snapshot.image_name})" }
-    def list(page: nil, limit: nil)
+    #   page = daytona.snapshot.list(page: 2, limit: 10)
+    #   puts "Page #{page.page} of #{page.total_pages} (#{page.total} snapshots total)"
+    #   page.items.each { |snapshot| puts "#{snapshot.name} (#{snapshot.image_name})" }
+    def list(page: nil, limit: nil, source_sandbox_id: nil)
       raise Sdk::Error, 'page must be positive integer' if page && page < 1
 
       raise Sdk::Error, 'limit must be positive integer' if limit && limit < 1
 
-      response = snapshots_api.get_all_snapshots(page:, limit:)
+      response = snapshots_api.get_all_snapshots(page:, limit:, source_sandbox_id:)
       PaginatedResource.new(
         total: response.total,
         page: response.page,
@@ -49,7 +51,10 @@ module Daytona
 
     # Delete a Snapshot.
     #
-    # @param snapshot [Daytona::Snapshot] Snapshot to delete
+    # @param snapshot [Daytona::Snapshot, String] Snapshot to delete, or its ID or name.
+    #   Call cost: 1 API call for a Snapshot object or UUID string; 2 for a name
+    #   (resolve, then delete); up to 3 in the worst case for a UUID-formatted name
+    #   (the optimistic delete 404s, then resolve + delete).
     # @return [void]
     #
     # @example
@@ -57,11 +62,13 @@ module Daytona
     #   snapshot = daytona.snapshot.get("demo")
     #   daytona.snapshot.delete(snapshot)
     #   puts "Snapshot deleted"
-    def delete(snapshot) = snapshots_api.remove_snapshot(snapshot.id)
+    def delete(snapshot)
+      call_with_resolved_id(snapshot) { |id| snapshots_api.remove_snapshot(id) }
+    end
 
-    # Get a Snapshot by name.
+    # Get a Snapshot by ID or name.
     #
-    # @param name [String] Name of the Snapshot to get
+    # @param name [String] ID or name of the Snapshot to get
     # @return [Daytona::Snapshot] The Snapshot object
     #
     # @example
@@ -125,11 +132,15 @@ module Daytona
       Snapshot.from_dto(snapshot)
     end
 
-    # Activate a snapshot
+    # Activate a snapshot.
     #
-    # @param snapshot [Daytona::Snapshot] The snapshot instance
+    # @param snapshot [Daytona::Snapshot, String] The Snapshot instance, or its ID or name.
+    #   Call cost matches `delete`: 1 for an object or UUID string, 2 for a name,
+    #   up to 3 for a UUID-formatted name (optimistic 404 then resolve + activate).
     # @return [Daytona::Snapshot]
-    def activate(snapshot) = Snapshot.from_dto(snapshots_api.activate_snapshot(snapshot.id))
+    def activate(snapshot)
+      Snapshot.from_dto(call_with_resolved_id(snapshot) { |id| snapshots_api.activate_snapshot(id) })
+    end
 
     instrument :list, :delete, :get, :create, :activate, component: 'SnapshotService'
 
@@ -174,6 +185,30 @@ module Daytona
     # @return [Daytona::OtelState, nil]
     attr_reader :otel_state
 
+    # Invoke an ID-based Snapshot operation, resolving the given identifier with as
+    # few API calls as possible. Snapshot names may themselves be UUID-formatted, so
+    # a UUID-shaped string is first tried directly as an ID (single call) and only
+    # resolved through the API on a 404. Any other string costs one resolution call.
+    #
+    # @param snapshot [Daytona::Snapshot, String] Snapshot instance, ID, or name
+    # @yield [String] resolved Snapshot ID
+    # @yieldreturn [Object] operation result
+    # @return [Object] whatever the block returns
+    def call_with_resolved_id(snapshot)
+      return yield(snapshot.id) unless snapshot.is_a?(String)
+
+      if Snapshot.id?(snapshot)
+        begin
+          return yield(snapshot)
+        rescue DaytonaApiClient::ApiError => e
+          raise unless e.code == 404
+        end
+      end
+
+      resolved = snapshots_api.get_snapshot(snapshot)
+      yield(resolved.id)
+    end
+
     # Wait for snapshot to reach a terminal state (ACTIVE, ERROR, or BUILD_FAILED)
     # Optionally streams logs if on_logs callback is provided
     #

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: daytona
 version: !ruby/object:Gem::Version
-  version: 0.202.0
+  version: 0.204.0
 platform: ruby
 authors:
 - Daytona Platforms Inc.
@@ -85,42 +85,42 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.202.0
+        version: 0.204.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.202.0
+        version: 0.204.0
 - !ruby/object:Gem::Dependency
   name: daytona_api_client
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.202.0
+        version: 0.204.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.202.0
+        version: 0.204.0
 - !ruby/object:Gem::Dependency
   name: daytona_toolbox_api_client
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.202.0
+        version: 0.204.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.202.0
+        version: 0.204.0
 - !ruby/object:Gem::Dependency
   name: dotenv
   requirement: !ruby/object:Gem::Requirement
@@ -184,7 +184,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0.6'
 description: 'High-level Ruby SDK for Daytona: sandboxes, git, filesystem, LSP, process,
-  and object storage.'
+  and object storage. Requires Ruby >= 3.2.'
 email:
 - support@daytona.io
 executables: []