buildkit 1.6.1 → 1.6.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e0e8f1334155df0287e1c1ea8b99bd03234f10681f87bea60ddf471474952a9
-  data.tar.gz: 0cc70aa70b57a0f6754460257dbc127f936d11f6a35e01bcaa8cd9b677223078
+  metadata.gz: 6e44ba52bf1e6ebeb791cc1848cd06853bc84422d5e3a4a667dc478d33159fe6
+  data.tar.gz: a5e41995469ed1617f67a34c4a534bfcbf33dc4754fe117cbbf3fca9bceb1ec3
 SHA512:
-  metadata.gz: f48d7763085376ec590cb490ec8eca0c3b971aead37e3e9bc12e037627af4ff4122fdb242ebf20a3d4030c59f01ec7f4333078e8e33a4da097e628dccf91632e
-  data.tar.gz: 2f738d7d0437b8f6c2d37a68a240dfde0e37ac912de2bda9e74d8dba9e75f113b1c5c61705dddccd9cf050871afe3c8d622fdb17bb14e3a08757d002990f575c
+  metadata.gz: eeac7f5ea7ed18cc5f1fb1b9f7a4b4479693430a2aeff9c0a77845082cf7fe82877a65b2d5154ec53ca2adc3ce448f6f2edc059755f7d372d6ca0d8e8048c45b
+  data.tar.gz: da54f50f06508673aa93a8af9f29e709a23e7c5697f2e29a2149d525d19b2b7b30b3ef57e8322063ae4eb9b88f31e5d1821ed5db4b3595c45f55fed714095895

data/README.md

@@ -26,6 +26,8 @@ organization = client.organization('my-great-org')
 agents = organization.rels[:agents].get.data
 ```
 
+Identifier arguments (`org`, `pipeline`, `build`, `job`, `id`) are interpolated into the request path, so each must be a single URL path segment: letters, digits, `-`, `_`, `.`, `~`. Values containing `/`, `?`, `%`, or that are `.`, `..`, or empty raise `Buildkit::InvalidRouteSegment` (an `ArgumentError`) before any request is made. Validate or reject user-supplied identifiers at your application boundary rather than rescuing this error.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/buildkit/client/agents.rb

@@ -4,6 +4,8 @@ module Buildkit
   class Client
     # Methods for the Agents API
     #
+    # Identifier arguments must be single URL path segments; see {Buildkit::InvalidRouteSegment}.
+    #
     # @see https://buildkite.com/docs/api/agents
     module Agents
       # List agents
@@ -13,7 +15,7 @@ module Buildkit
       # @example
       #   Buildkit.agents('my-great-org')
       def agents(org, options = {})
-        get("/v2/organizations/#{org}/agents", options)
+        get("/v2/organizations/#{route_segment(org, :org)}/agents", options)
       end
 
       # Get an agent
@@ -25,7 +27,7 @@ module Buildkit
       # @example
       #   Buildkit.agent('my-great-org', '0b461f65-e7be-4c80-888a-ef11d81fd971')
       def agent(org, id, options = {})
-        get("/v2/organizations/#{org}/agents/#{id}", options)
+        get("/v2/organizations/#{route_segment(org, :org)}/agents/#{route_segment(id, :id)}", options)
       end
 
       # Stop an agent
@@ -36,7 +38,7 @@ module Buildkit
       # @example Stop an  agent
       #   Buildkit.stop_agent('my-great-org', '16940c91-f12d-4122-8154-0edf6c0978c2')
       def stop_agent(org, id, options = {})
-        put("/v2/organizations/#{org}/agents/#{id}/stop", options)
+        put("/v2/organizations/#{route_segment(org, :org)}/agents/#{route_segment(id, :id)}/stop", options)
       end
     end
   end

data/lib/buildkit/client/artifacts.rb

@@ -4,6 +4,8 @@ module Buildkit
   class Client
     # Methods for the Artifacts API
     #
+    # Identifier arguments must be single URL path segments; see {Buildkit::InvalidRouteSegment}.
+    #
     # @see https://buildkite.com/docs/api/artifacts
     module Artifacts
       # List all artifacts for a build
@@ -13,7 +15,8 @@ module Buildkit
       # @example
       #   Buildkit.artifacts('my-great-org', 'great-pipeline', 42)
       def artifacts(org, pipeline, build, options = {})
-        get("/v2/organizations/#{org}/pipelines/#{pipeline}/builds/#{build}/artifacts", options)
+        get("/v2/organizations/#{route_segment(org, :org)}/pipelines/#{route_segment(pipeline, :pipeline)}" \
+            "/builds/#{route_segment(build, :build)}/artifacts", options)
       end
 
       # List all artifacts for a job
@@ -23,7 +26,8 @@ module Buildkit
       # @example
       #   Buildkit.job_artifacts('my-great-org', 'great-pipeline', 42, '76365070-34d5-4104-8b91-952780f8029f')
       def job_artifacts(org, pipeline, build, job, options = {})
-        get("/v2/organizations/#{org}/pipelines/#{pipeline}/builds/#{build}/jobs/#{job}/artifacts", options)
+        get("/v2/organizations/#{route_segment(org, :org)}/pipelines/#{route_segment(pipeline, :pipeline)}" \
+            "/builds/#{route_segment(build, :build)}/jobs/#{route_segment(job, :job)}/artifacts", options)
       end
     end
   end

data/lib/buildkit/client/builds.rb

@@ -4,6 +4,8 @@ module Buildkit
   class Client
     # Methods for the Builds API
     #
+    # Identifier arguments must be single URL path segments; see {Buildkit::InvalidRouteSegment}.
+    #
     # @see https://buildkite.com/docs/api/builds
     module Builds
       # List all builds
@@ -24,7 +26,7 @@ module Buildkit
       # @example
       #   Buildkit.organization_builds('my-great-org'))
       def organization_builds(org, options = {})
-        get("/v2/organizations/#{org}/builds", options)
+        get("/v2/organizations/#{route_segment(org, :org)}/builds", options)
       end
 
       # List builds for a pipeline
@@ -36,7 +38,7 @@ module Buildkit
       # @example
       #   Buildkit.pipeline_builds('my-great-org', 'great-pipeline')
       def pipeline_builds(org, pipeline, options = {})
-        get("/v2/organizations/#{org}/pipelines/#{pipeline}/builds", options)
+        get(builds_path(org, pipeline), options)
       end
 
       # Get a build
@@ -49,7 +51,7 @@ module Buildkit
       # @example
       #   Buildkit.build('my-great-org', 'great-pipeline', 42)
       def build(org, pipeline, number, options = {})
-        get("/v2/organizations/#{org}/pipelines/#{pipeline}/builds/#{number}", options)
+        get("#{builds_path(org, pipeline)}/#{route_segment(number, :number)}", options)
       end
 
       # Rebuild a build
@@ -61,7 +63,7 @@ module Buildkit
       # @example
       #   Buildkit.rebuild('my-great-org', 'great-pipeline', 42)
       def rebuild(org, pipeline, number, options = {})
-        put("/v2/organizations/#{org}/pipelines/#{pipeline}/builds/#{number}/rebuild", options)
+        put("#{builds_path(org, pipeline)}/#{route_segment(number, :number)}/rebuild", options)
       end
 
       # Create a build
@@ -81,7 +83,7 @@ module Buildkit
       #   })
       #
       def create_build(org, pipeline, options = {})
-        post("/v2/organizations/#{org}/pipelines/#{pipeline}/builds", options)
+        post(builds_path(org, pipeline), options)
       end
 
       # Cancel a build
@@ -93,7 +95,13 @@ module Buildkit
       # @example
       #   Buildkit.cancel_build('my-great-org', 'great-pipeline', 42)
       def cancel_build(org, pipeline, number, options = {})
-        put("/v2/organizations/#{org}/pipelines/#{pipeline}/builds/#{number}/cancel", options)
+        put("#{builds_path(org, pipeline)}/#{route_segment(number, :number)}/cancel", options)
+      end
+
+      private
+
+      def builds_path(org, pipeline)
+        "/v2/organizations/#{route_segment(org, :org)}/pipelines/#{route_segment(pipeline, :pipeline)}/builds"
       end
     end
   end

data/lib/buildkit/client/jobs.rb

@@ -4,6 +4,8 @@ module Buildkit
   class Client
     # Methods for the Jobs API
     #
+    # Identifier arguments must be single URL path segments; see {Buildkit::InvalidRouteSegment}.
+    #
     # @see https://buildkite.com/docs/rest-api/jobs
     module Jobs
       # Retry a job
@@ -17,7 +19,7 @@ module Buildkit
       # @example
       #   Buildkit.retry_job('my-great-org', 'great-pipeline', 123, 'my-job-id')
       def retry_job(org, pipeline, build, job, options = {})
-        put("/v2/organizations/#{org}/pipelines/#{pipeline}/builds/#{build}/jobs/#{job}/retry", options)
+        put("#{job_path(org, pipeline, build, job)}/retry", options)
       end
 
       # Get a job's environment variables
@@ -31,7 +33,7 @@ module Buildkit
       # @example
       #   Buildkit.job_env('my-great-org', 'great-pipeline', 123, 'my-job-id')
       def job_env(org, pipeline, build, job, options = {})
-        get("/v2/organizations/#{org}/pipelines/#{pipeline}/builds/#{build}/jobs/#{job}/env", options)
+        get("#{job_path(org, pipeline, build, job)}/env", options)
       end
 
       # Get a job's log output
@@ -45,7 +47,7 @@ module Buildkit
       # @example
       #   Buildkit.job_log('my-great-org', 'great-pipeline', 123, 'my-job-id')
       def job_log(org, pipeline, build, job, options = {})
-        get("/v2/organizations/#{org}/pipelines/#{pipeline}/builds/#{build}/jobs/#{job}/log", options)
+        get("#{job_path(org, pipeline, build, job)}/log", options)
       end
 
       # Unblock a job
@@ -65,7 +67,14 @@ module Buildkit
       #     }
       #   })
       def unblock(org, pipeline, build, job, options = {})
-        put("/v2/organizations/#{org}/pipelines/#{pipeline}/builds/#{build}/jobs/#{job}/unblock", options)
+        put("#{job_path(org, pipeline, build, job)}/unblock", options)
+      end
+
+      private
+
+      def job_path(org, pipeline, build, job)
+        "/v2/organizations/#{route_segment(org, :org)}/pipelines/#{route_segment(pipeline, :pipeline)}" \
+          "/builds/#{route_segment(build, :build)}/jobs/#{route_segment(job, :job)}"
       end
     end
   end

data/lib/buildkit/client/organizations.rb

@@ -4,6 +4,8 @@ module Buildkit
   class Client
     # Methods for the Organizations API
     #
+    # Identifier arguments must be single URL path segments; see {Buildkit::InvalidRouteSegment}.
+    #
     # @see https://buildkite.com/docs/api/organizations
     module Organizations
       # List organizations
@@ -24,7 +26,7 @@ module Buildkit
       # @example
       #   Buildkit.organization('my-great-org')
       def organization(org, options = {})
-        get("/v2/organizations/#{org}", options)
+        get("/v2/organizations/#{route_segment(org, :org)}", options)
       end
     end
   end

data/lib/buildkit/client/pipelines.rb

@@ -4,6 +4,8 @@ module Buildkit
   class Client
     # Methods for the pipelines API
     #
+    # Identifier arguments must be single URL path segments; see {Buildkit::InvalidRouteSegment}.
+    #
     # @see https://buildkite.com/docs/api/pipelines
     module Pipelines
       # List pipelines
@@ -13,7 +15,7 @@ module Buildkit
       # @example
       #   Buildkit.pipelines('my-great-org')
       def pipelines(org, options = {})
-        get("/v2/organizations/#{org}/pipelines", options)
+        get(pipelines_path(org), options)
       end
 
       # Get a pipeline
@@ -25,7 +27,7 @@ module Buildkit
       # @example
       #   Buildkit.pipeline('my-great-org', 'great-pipeline')
       def pipeline(org, pipeline, options = {})
-        get("/v2/organizations/#{org}/pipelines/#{pipeline}", options)
+        get("#{pipelines_path(org)}/#{route_segment(pipeline, :pipeline)}", options)
       end
 
       # Create a pipeline
@@ -48,7 +50,7 @@ module Buildkit
       #   })
       #
       def create_pipeline(org, options = {})
-        post("/v2/organizations/#{org}/pipelines", options)
+        post(pipelines_path(org), options)
       end
 
       # Update a pipeline
@@ -63,7 +65,7 @@ module Buildkit
       #   })
       #
       def update_pipeline(org, pipeline, options = {})
-        patch("/v2/organizations/#{org}/pipelines/#{pipeline}", options)
+        patch("#{pipelines_path(org)}/#{route_segment(pipeline, :pipeline)}", options)
       end
 
       # Archive a pipeline
@@ -76,7 +78,7 @@ module Buildkit
       #   Buildkit.archive_pipeline('my-great-org', 'great-pipeline')
       #
       def archive_pipeline(org, pipeline)
-        post("/v2/organizations/#{org}/pipelines/#{pipeline}/archive")
+        post("#{pipelines_path(org)}/#{route_segment(pipeline, :pipeline)}/archive")
       end
 
       # Unarchive a pipeline
@@ -89,7 +91,7 @@ module Buildkit
       #   Buildkit.unarchive_pipeline('my-great-org', 'great-pipeline')
       #
       def unarchive_pipeline(org, pipeline)
-        post("/v2/organizations/#{org}/pipelines/#{pipeline}/unarchive")
+        post("#{pipelines_path(org)}/#{route_segment(pipeline, :pipeline)}/unarchive")
       end
 
       # Delete a pipeline
@@ -101,7 +103,13 @@ module Buildkit
       #   Buildkit.delete_pipeline('my-great-org', 'great-pipeline')
       #
       def delete_pipeline(org, pipeline)
-        delete("/v2/organizations/#{org}/pipelines/#{pipeline}")
+        delete("#{pipelines_path(org)}/#{route_segment(pipeline, :pipeline)}")
+      end
+
+      private
+
+      def pipelines_path(org)
+        "/v2/organizations/#{route_segment(org, :org)}/pipelines"
       end
     end
   end

data/lib/buildkit/client.rb

@@ -25,6 +25,11 @@ module Buildkit
     # Header keys that can be passed in options hash to {#get},{#head}
     CONVENIENCE_HEADERS = Set.new(%i[accept content_type])
 
+    # Characters permitted in a route identifier: RFC 3986 unreserved set.
+    # Buildkite identifiers are slugs ([a-z0-9-]), UUIDs, or integers, so this is
+    # not restrictive in practice; it rejects every path/query delimiter and `%`.
+    ROUTE_SEGMENT = /\A[A-Za-z0-9\-._~]+\z/.freeze
+
     # In Faraday 0.9, Faraday::Builder was renamed to Faraday::RackBuilder
     RACK_BUILDER_CLASS = defined?(Faraday::RackBuilder) ? Faraday::RackBuilder : Faraday::Builder
 
@@ -118,6 +123,25 @@ module Buildkit
 
     private
 
+    # Validate that a caller-supplied identifier is exactly one URL path segment.
+    #
+    # Named helpers interpolate identifiers between fixed route parts; a value
+    # containing `/`, `?` or a dot-segment would otherwise re-route the request
+    # to a different Buildkite action.
+    #
+    # @param value [String, Integer]
+    # @param name [Symbol] parameter name, for the error message
+    # @return [String]
+    # @raise [Buildkit::InvalidRouteSegment]
+    def route_segment(value, name)
+      segment = value.to_s
+      if segment.match?(ROUTE_SEGMENT) && segment != '.' && segment != '..'
+        segment
+      else
+        raise InvalidRouteSegment, "#{name} must be a single URL path segment, got #{value.inspect}"
+      end
+    end
+
     def request(method, path, data, options = {})
       if data.is_a?(Hash)
         options = extract_query_and_headers_from data

data/lib/buildkit/error.rb

@@ -166,4 +166,7 @@ module Buildkit
 
   # Raised when client fails to provide valid Content-Type
   class MissingContentType < ArgumentError; end
+
+  # Raised when a route identifier (org, pipeline, build, job, agent id) is not a single URL path segment
+  class InvalidRouteSegment < ArgumentError; end
 end

data/lib/buildkit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Buildkit
-  VERSION = '1.6.1'
+  VERSION = '1.6.2'
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: buildkit
 version: !ruby/object:Gem::Version
-  version: 1.6.1
+  version: 1.6.2
 platform: ruby
 authors:
 - Jean Boussier
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-09-20 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sawyer
@@ -38,7 +37,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description:
 email:
 - jean.boussier@shopify.com
 executables: []
@@ -78,7 +76,6 @@ licenses:
 - MIT
 metadata:
   allowed_push_host: https://rubygems.org
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -93,8 +90,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.18
-signing_key:
+rubygems_version: 4.0.21
 specification_version: 4
 summary: Ruby toolkit for working with the Buildkite API
 test_files: []