lib/trav3.rb in trav3-0.2.2 vs lib/trav3.rb in trav3-0.2.3
- old
+ new
@@ -4,16 +4,17 @@
require 'trav3/version'
require 'trav3/pagination'
require 'trav3/options'
require 'trav3/headers'
require 'trav3/result'
+require 'trav3/delete'
require 'trav3/post'
require 'trav3/get'
# Trav3 project namespace
module Trav3
- API_ROOT = 'https://api.travis-ci.org'.freeze
+ API_ROOT = 'https://api.travis-ci.org'
# An abstraction for the Travis CI v3 API
#
# @author Daniel P. Clark https://6ftdan.com
# @!attribute [r] api_endpoint
@@ -31,11 +32,11 @@
# @param repo [String] github_username/repository_name
# @raise [InvalidRepository] if given input does not
# conform to valid repository identifier format
# @return [Travis]
def initialize(repo)
- raise InvalidRepository unless repo_slug_or_id? repo
+ validate_repo_format repo
@api_endpoint = API_ENDPOINT
@repo = sanitize_repo_name repo
initial_defaults
@@ -45,11 +46,11 @@
# Set as the API endpoint
# @param endpoint [String] name for value to set
# @return [self]
# rubocop:disable Lint/Void
def api_endpoint=(endpoint)
- raise InvalidAPIEndpoint unless /^https:\/\/api\.travis-ci\.(?:org|com)$/.match? endpoint
+ validate_api_endpoint endpoint
@api_endpoint = endpoint
self
end
@@ -134,11 +135,11 @@
# Example:GET /repo/rails%2Frails/branch/master
#
# @param name [String] the branch name for the current repository
# @return [Success, RequestError]
def branch(name)
- get("#{with_repo}/branch/#{name}#{opts}")
+ get("#{with_repo}/branch/#{name}")
end
# A list of branches.
#
# **If querying using the repository slug, it must be formatted using {http://www.w3schools.com/tags/ref_urlencode.asp standard URL encoding}, including any special characters.**
@@ -287,14 +288,25 @@
#
# Example: POST /build/86601346/restart
#
# @note POST requests require an authorization token set in the headers. See: {h}
#
- # @param id [String, Integer] the build id number
+ # @param build_id [String, Integer] the build id number
+ # @param option [Symbol] options for :cancel or :restart
+ # @raise [TypeError] if given build id is not a number
# @return [Success, RequestError]
- def build(id)
- get("#{without_repo}/build/#{id}")
+ def build(build_id, option = nil)
+ validate_number build_id
+
+ case option
+ when :cancel
+ post("#{without_repo}/build/#{build_id}/cancel")
+ when :restart
+ post("#{without_repo}/build/#{build_id}/restart")
+ else
+ get("#{without_repo}/build/#{build_id}")
+ end
end
# A list of builds.
#
# ## Attributes
@@ -470,16 +482,115 @@
# Example: GET /jobs?limit=5
#
# **Sortable by:** <code>id</code>, append <code>:desc</code> to any attribute to reverse order.
# The default value is id:desc.
#
- # @param id [String, Integer] the build id number
+ # @param build_id [String, Integer] the build id number
# @return [Success, RequestError]
- def build_jobs(id)
- get("#{without_repo}/build/#{id}/jobs")
+ def build_jobs(build_id)
+ get("#{without_repo}/build/#{build_id}/jobs")
end
+ # A list of caches.
+ #
+ # If querying using the repository slug, it must be formatted using {http://www.w3schools.com/tags/ref_urlencode.asp standard URL encoding}, including any special characters.
+ #
+ # ## Attributes
+ #
+ # Name Type Description
+ # branch String The branch the cache belongs to.
+ # match String The string to match against the cache name.
+ #
+ # ## Actions
+ #
+ # **Find**
+ #
+ # This returns all the caches for a repository.
+ #
+ # It's possible to filter by branch or by regexp match of a string to the cache name.
+ #
+ # ```bash
+ # curl \
+ # -H "Content-Type: application/json" \
+ # -H "Travis-API-Version: 3" \
+ # -H "Authorization: token xxxxxxxxxxxx" \
+ # https://api.travis-ci.com/repo/1234/caches?branch=master
+ # ```
+ #
+ # ```bash
+ # curl \
+ # -H "Content-Type: application/json" \
+ # -H "Travis-API-Version: 3" \
+ # -H "Authorization: token xxxxxxxxxxxx" \
+ # https://api.travis-ci.com/repo/1234/caches?match=linux
+ # ```
+ #
+ # GET <code>/repo/{repository.id}/caches</code>
+ #
+ # Template Variable Type Description
+ # repository.id Integer Value uniquely identifying the repository.
+ # Query Parameter Type Description
+ # branch [String] Alias for caches.branch.
+ # caches.branch [String] Filters caches by the branch the cache belongs to.
+ # caches.match [String] Filters caches by the string to match against the cache name.
+ # include [String] List of attributes to eager load.
+ # match [String] Alias for caches.match.
+ #
+ # Example: GET /repo/891/caches
+ #
+ # GET <code>/repo/{repository.slug}/caches</code>
+ #
+ # Template Variable Type Description
+ # repository.slug String Same as {repository.owner.name}/{repository.name}.
+ # Query Parameter Type Description
+ # branch [String] Alias for caches.branch.
+ # caches.branch [String] Filters caches by the branch the cache belongs to.
+ # caches.match [String] Filters caches by the string to match against the cache name.
+ # include [String] List of attributes to eager load.
+ # match [String] Alias for caches.match.
+ #
+ # Example: GET /repo/rails%2Frails/caches
+ #
+ # **Delete**
+ #
+ # This deletes all caches for a repository.
+ #
+ # As with `find` it's possible to delete by branch or by regexp match of a string to the cache name.
+ #
+ # ```bash
+ # curl -X DELETE \
+ # -H "Content-Type: application/json" \
+ # -H "Travis-API-Version: 3" \
+ # -H "Authorization: token xxxxxxxxxxxx" \
+ # https://api.travis-ci.com/repo/1234/caches?branch=master
+ # ```
+ #
+ # DELETE <code>/repo/{repository.id}/caches</code>
+ # Template Variable Type Description
+ # repository.id Integer Value uniquely identifying the repository.
+ #
+ # Example: DELETE /repo/891/caches
+ #
+ # DELETE <code>/repo/{repository.slug}/caches</code>
+ #
+ # Template Variable Type Description
+ # repository.slug String Same as {repository.owner.name}/{repository.name}.
+ #
+ # Example: DELETE /repo/rails%2Frails/caches
+ #
+ # @note DELETE requests require an authorization token set in the headers. See: {h}
+ #
+ # @param delete [Boolean] option for deleting cache(s)
+ # @return [Success, RequestError]
+ def caches(delete = false)
+ if delete
+ without_limit { delete("#{with_repo}/caches#{opts}") }
+ else
+ get("#{with_repo}/caches")
+ end
+ end
+
# An individual job.
#
# ## Attributes
#
# **Minimal Representation**
@@ -558,23 +669,23 @@
#
# Example: POST /job/86601347/debug
#
# @note POST requests require an authorization token set in the headers. See: {h}
#
- # @param id [String, Integer] the job id number
+ # @param job_id [String, Integer] the job id number
# @param option [Symbol] options for :cancel, :restart, or :debug
# @return [Success, RequestError]
- def job(id, option = nil)
+ def job(job_id, option = nil)
case option
when :cancel
- post("#{without_repo}/job/#{id}/cancel")
+ post("#{without_repo}/job/#{job_id}/cancel")
when :restart
- post("#{without_repo}/job/#{id}/restart")
+ post("#{without_repo}/job/#{job_id}/restart")
when :debug
- post("#{without_repo}/job/#{id}/debug")
+ post("#{without_repo}/job/#{job_id}/debug")
else
- get("#{without_repo}/job/#{id}")
+ get("#{without_repo}/job/#{job_id}")
end
end
# This validates the `.travis.yml` file and returns any warnings.
#
@@ -594,12 +705,11 @@
# Example:POST /lint
#
# @param yaml_content [String] the contents for the file `.travis.yml`
# @return [Success, RequestError]
def lint(yaml_content)
- raise TypeError, "String expected, #{yaml_content.class} given" unless \
- yaml_content.is_a? String
+ validate_string yaml_content
ct = headers.remove(:'Content-Type')
result = post("#{without_repo}/lint", body: yaml_content)
h('Content-Type': ct) if ct
result
@@ -678,21 +788,21 @@
#
# Example: DELETE /job/86601347/log
#
# @note DELETE is unimplemented
#
- # @param id [String, Integer] the job id number
+ # @param job_id [String, Integer] the job id number
# @param option [Symbol] options for :text or :delete
# @return [Success, String, RequestError]
- def log(id, option = nil)
+ def log(job_id, option = nil)
case option
when :text
- get("#{without_repo}/job/#{id}/log.txt", true)
+ get("#{without_repo}/job/#{job_id}/log.txt", true)
when :delete
raise Unimplemented
else
- get("#{without_repo}/job/#{id}/log")
+ get("#{without_repo}/job/#{job_id}/log")
end
end
# An individual organization.
#
@@ -742,11 +852,11 @@
#
# @param org_id [String, Integer] the organization id
# @raise [TypeError] if given organization id is not a number
# @return [Success, RequestError]
def organization(org_id)
- raise TypeError, 'Integer expected for organization id' unless /^\d+$/.match? org_id.to_s
+ validate_number org_id
get("#{without_repo}/org/#{org_id}")
end
# A list of organizations for the current user.
@@ -794,11 +904,11 @@
# @return [Success, RequestError]
def organizations
get("#{without_repo}/orgs")
end
- # This will be either a user or organization.
+ # This will be either a {https://developer.travis-ci.com/resource/user user} or {https://developer.travis-ci.com/resource/organization organization}.
#
# ## Attributes
#
# **Minimal Representation**
#
@@ -808,11 +918,11 @@
# id Integer Value uniquely identifying the owner.
# login String User or organization login set on GitHub.
#
# **Standard Representation**
#
- # Included when the resource is the main response of a request, or is eager loaded.
+ # Included when the resource is the main response of a request, or is {https://developer.travis-ci.com/eager-loading eager loaded}.
#
# Name Type Description
# id Integer Value uniquely identifying the owner.
# login String User or organization login set on GitHub.
# name String User or organization name set on GitHub.
@@ -871,11 +981,11 @@
# Example: GET /owner/github_id/639823
#
# @param owner [String] username or github ID
# @return [Success, RequestError]
def owner(owner = username)
- if /^\d+$/.match? owner.to_s
+ if number? owner
get("#{without_repo}/owner/github_id/#{owner}")
else
get("#{without_repo}/owner/#{owner}")
end
end
@@ -1017,11 +1127,11 @@
# **Sortable by:** <code>id</code>, <code>github_id</code>, <code>owner_name</code>, <code>name</code>, <code>active</code>, <code>default_branch.last_build</code>, append <code>:desc</code> to any attribute to reverse order.
#
# @param owner [String] username or github ID
# @return [Success, RequestError]
def repositories(owner = username)
- if /^\d+$/.match? owner.to_s
+ if number? owner
get("#{without_repo}/owner/github_id/#{owner}/repos#{opts}")
else
get("#{without_repo}/owner/#{owner}/repos#{opts}")
end
end
@@ -1159,11 +1269,11 @@
# @param action [String, Symbol] Optional argument for star/unstar/activate/deactivate
# @raise [InvalidRepository] if given input does not
# conform to valid repository identifier format
# @return [Success, RequestError]
def repository(repo = repository_name, action = nil)
- raise InvalidRepository unless repo_slug_or_id? repo
+ validate_repo_format repo
repo = sanitize_repo_name repo
action = '' unless %w[star unstar activate deavtivate].include? action.to_s
if action.empty?
@@ -1212,11 +1322,11 @@
#
# @param build_id [String, Integer] build id
# @raise [TypeError] if given build id is not a number
# @return [Success, RequestError]
def stages(build_id)
- raise TypeError, 'Integer expected for build id' unless /^\d+$/.match? build_id.to_s
+ validate_number build_id
get("#{without_repo}/build/#{build_id}/stages")
end
# An individual user.
@@ -1297,21 +1407,26 @@
# @param sync [Boolean] optional argument for syncing your Travis CI account with Github
# @raise [TypeError] if given user id is not a number
# @return [Success, RequestError]
def user(user_id = nil, sync = false)
return get("#{without_repo}/user") if !user_id && !sync
- raise TypeError, 'Integer expected for user id' unless /^\d+$/.match? user_id.to_s
+ validate_number user_id
+
if sync
get("#{without_repo}/user/#{user_id}/sync")
else
get("#{without_repo}/user/#{user_id}")
end
end
private # @private
+ def delete(url)
+ Trav3::DELETE.call(self, url)
+ end
+
def get(url, raw_reply = false)
Trav3::GET.call(self, url, raw_reply)
end
def initial_defaults
@@ -1319,22 +1434,42 @@
h('Content-Type': 'application/json')
h('Accept': 'application/json')
h('Travis-API-Version': 3)
end
+ def number?(input)
+ /^\d+$/.match? input.to_s
+ end
+
def opts
@options
end
def post(url, fields = {})
Trav3::POST.call(self, url, fields)
end
- def repo_slug_or_id?(repo)
- Regexp.new(/(^\d+$)|(^\w+(?:\/|%2F){1}\w+$)/).match? repo
+ def validate_api_endpoint(input)
+ raise InvalidAPIEndpoint unless /^https:\/\/api\.travis-ci\.(?:org|com)$/.match? input
end
+ def validate_number(input)
+ raise TypeError, "Integer expected, #{input.class} given" unless number? input
+ end
+
+ def validate_repo_format(input)
+ raise InvalidRepository unless repo_slug_or_id? input
+ end
+
+ def validate_string(input)
+ raise TypeError, "String expected, #{input.class} given" unless input.is_a? String
+ end
+
+ def repo_slug_or_id?(input)
+ Regexp.new(/(^\d+$)|(^\w+(?:\/|%2F){1}\w+$)/).match? input
+ end
+
def repository_name
@repo
end
def sanitize_repo_name(repo)
@@ -1349,9 +1484,16 @@
"#{api_endpoint}/repo/#{@repo}"
end
def without_repo
api_endpoint
+ end
+
+ def without_limit
+ limit = opts.remove(:limit)
+ result = yield
+ opts.build(limit: limit) if limit
+ result
end
end
end
# rubocop:enable Metrics/ClassLength