nexus_api 1.2.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 885db3d6a8d7a3b381b8a9a889ef2bbbbe5d746b14e430872815db135f25c879
-  data.tar.gz: 2408b1085fa8d62f5d506d113aad8d269b74e0a66564e1c9720ba6aaa2e4ccff
+  metadata.gz: ae2066e62934bcfeed3480aa351da4ad8053d258c762b4ed8cfc006a64eae7c3
+  data.tar.gz: 597ba898fabbf3efcb1c2ab22f0557875d33cb6af24fd8a9338cf7be4c83b942
 SHA512:
-  metadata.gz: 001d8efa8dbe403928908e11a88746a5cb5f6650120031b9992888bde1a8224d3c33812df0b59c5ccb229492329049dcdda1aa2829f7ec550488ce3c77cce3a6
-  data.tar.gz: ebd5b6c64759c57137c74a86584c4c51d15467ad8cea81154e72bb91a59fa30dc4f24a18729d444a7ac999d6b6dadcd944eed8a164cdbc120874539b0d489a4a
+  metadata.gz: 3015d930671ca0f18b89647f55a2fda2496c5ddd5c3df9540cd2d0012530a8ecf379f9aeaead6ab7a8a132e45c825cf89d25a78efb2b58b999343698a6d6531d
+  data.tar.gz: f217d6c26156c2dc7960ce5f393b211bdc560134ede1cb95658a7c0e4b54c4f6b02f8ff4e055f2d573c0082e487f223cd90018966ef97249d390e8d0c8ad386b

data/CHANGELOG.md

@@ -5,6 +5,38 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
+## [1.5.0](https://github.com/Cisco-AMP/nexus_api/compare/v1.4.1...v1.5.0) - 2020-06-10
+### Added
+- New methods around the `privileges` endpoint
+- New methods around the `roles` endpoint
+- New methods around the `users` endpoint
+- New `list_all_*` methods for endpoints that paginate so the user doesn't have to page through results themselves if they just want all the raw data
+
+
+## [1.4.1](https://github.com/Cisco-AMP/nexus_api/compare/v1.4.0...v1.4.1) - 2020-05-08
+### Changed
+- Error reporting to be more descriptive
+
+
+## [1.4.0](https://github.com/Cisco-AMP/nexus_api/compare/v1.3.0...v1.4.0) - 2020-05-05
+### Added
+- Optional `tag` parameter to `associate_tag()` and `delete_associated_tag()` methods
+
+### Changed 
+- Made `sha1` parameter optional for `associate_tag()` and `delete_associated_tag()` methods
+
+
+## [1.3.0](https://github.com/Cisco-AMP/nexus_api/compare/v1.2.1...v1.3.0) - 2020-04-30
+### Added
+- Optional source and general keyword match into staging endpoint method (`move_components_to()`)
+
+
+## [1.2.1](https://github.com/Cisco-AMP/nexus_api/compare/v1.2.0...v1.2.1) - 2020-04-29
+### Fixed
+- Correctly building request URLs when pagination is the only argument
+- `bin/nexus_api tag list` now using pagination
+
+
 ## [1.2.0](https://github.com/Cisco-AMP/nexus_api/compare/v1.1.0...v1.2.0) - 2020-04-24
 ### Added
 - `move_components_to` method for moving all components that match a given tag into a new destination

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    nexus_api (1.2.0)
+    nexus_api (1.5.0)
       bundler (~> 2)
       docker-api (~> 1.34.2)
       dotenv (~> 2.7.5)
@@ -34,7 +34,7 @@ GEM
     method_source (0.9.2)
     mime-types (3.3.1)
       mime-types-data (~> 3.2015)
-    mime-types-data (3.2019.1009)
+    mime-types-data (3.2020.0512)
     multi_json (1.14.1)
     netrc (0.11.0)
     pry (0.12.2)
@@ -84,4 +84,4 @@ DEPENDENCIES
   webmock (~> 3.8)
 
 BUNDLED WITH
-   2.0.2
+   2.1.4

data/README.md

@@ -59,21 +59,24 @@ api = NexusAPI::API.new(
   username: NEXUS_USERNAME,
   password: NEXUS_PASSWORD,
   hostname: NEXUS_HOSTNAME,
-  docker_pull_hostname: DOCKER_PUSH_HOSTNAME,  # Optional
-  docker_push_hostname: DOCKER_PULL_HOSTNAME,  # Optional
+  docker_pull_hostname: DOCKER_PULL_HOSTNAME,  # Optional
+  docker_push_hostname: DOCKER_PUSH_HOSTNAME,  # Optional
   config: "team_configs/#{CONFIG_NAME}",       # Optional
 )
 # NOTE: All Docker commands will fail if the docker hostnames are not initialized
 
 # You can query information through the list methods
-api.list_repositories
-api.list_repository_names
 api.list_assets(repository: REPOSITORY_NAME)
 api.list_asset(id: ASSET_ID)
 api.list_components(repository: REPOSITORY_NAME)
 api.list_component(id: ASSET_ID)
+api.list_privileges
+api.list_repositories
+api.list_repository_names
+api.list_roles
 api.list_scripts
 api.list_tags
+api.list_users
 
 # You can search for an asset by its name
 # Optionally, you can pass in additional fields to filter the results
@@ -90,7 +93,12 @@ api.search_asset(
 #  - list_components
 #  - list_tags
 #  - search_asset
-# You can use the following pattern to page through each method:
+# You can use the following methods to automatically gather data from all pages for you:
+#  - list_all_assets
+#  - list_all_components
+#  - list_all_tags
+#  - search_all_assets
+# Or you can use the following pattern to page through if additional processing is desired:
 set = Array.new.tap do |set|
   loop do
     set.concat(api.METHOD_YOU_WANT(ARGUMENTS, paginate: true))

data/lib/endpoints/assets.rb

@@ -6,6 +6,15 @@ module NexusAPI
       @connection.get_response(endpoint: "assets?repository=#{repository}", paginate: paginate)
     end
 
+    def list_all_assets(repository: nil)
+      assets = Array.new.tap do |assets|
+        loop do
+          assets.concat(list_assets(repository: repository, paginate: true))
+          break unless paginate?
+        end
+      end
+    end
+
     # GET /service/rest/v1/assets/{id}
     def list_asset(id:)
       @connection.get_response(endpoint: "assets/#{id}")

data/lib/endpoints/components.rb

@@ -6,6 +6,15 @@ module NexusAPI
       @connection.get_response(endpoint: "components?repository=#{repository}", paginate: paginate)
     end
 
+    def list_all_components(repository: nil)
+      components = Array.new.tap do |components|
+        loop do
+          components.concat(list_components(repository: repository, paginate: true))
+          break unless paginate?
+        end
+      end
+    end
+
     # POST /service/rest/v1/components
     def upload_maven_component(filename:, group_id:, artifact_id:, version:, repository: nil, tag: nil)
       repository ||= @team_config.maven_repository

data/lib/endpoints/privileges.rb

@@ -1,8 +1,20 @@
 module NexusAPI
   class API
     # GET /service/rest/beta/security/privileges
+    def list_privileges
+      @connection.get_response(endpoint: 'security/privileges', api_version: 'beta')
+    end
+
     # GET /service/rest/beta/security/privileges/{privilegeId}
+    def list_privilege(privilege_id:)
+      @connection.get_response(endpoint: "security/privileges/#{privilege_id}", api_version: 'beta')
+    end
+
     # DELETE /service/rest/beta/security/privileges/{privilegeId}
+    def delete_privilege(privilege_id:)
+      @connection.delete(endpoint: "security/privileges/#{privilege_id}", api_version: 'beta')
+    end
+
     # POST /service/rest/beta/security/privileges/application
     # PUT /service/rest/beta/security/privileges/application/{privilegeId}
     # POST /service/rest/beta/security/privileges/repository-admin
@@ -10,6 +22,21 @@ module NexusAPI
     # POST /service/rest/beta/security/privileges/repository-content-selector
     # PUT /service/rest/beta/security/privileges/repository-content-selector/{privilegeId}
     # POST /service/rest/beta/security/privileges/repository-view
+    def create_privilege_repository_view(name:, description: nil, actions: ['READ'], format: '*', repository: '*')
+      parameters = {
+        # The name is also used as the privilege_id
+        'name' => name,
+        'description' => description,
+        # READ, BROWSE, EDIT, ADD, DELETE, RUN, ASSOCIATE, DISASSOCIATE, ALL
+        'actions' => actions,
+        # The repository format (i.e 'nuget', 'npm') this privilege will grant access to (or * for all)
+        'format' => format,
+        # The name of the repository this privilege will grant access to (or * for all)
+        'repository' => repository
+      }
+      @connection.post(endpoint: 'security/privileges/repository-view', parameters: parameters, api_version: 'beta')
+    end
+
     # PUT /service/rest/beta/security/privileges/repository-view/{privilegeId}
     # POST /service/rest/beta/security/privileges/script
     # PUT /service/rest/beta/security/privileges/script/{privilegeId}

data/lib/endpoints/roles.rb

@@ -1,9 +1,31 @@
 module NexusAPI
   class API
     # GET /service/rest/beta/security/roles
+    def list_roles
+      @connection.get_response(endpoint: 'security/roles', api_version: 'beta')
+    end
+
     # POST /service/rest/beta/security/roles
+    def create_role(id:, name:, description: nil, privileges: [], roles: [])
+      parameters = {
+        'id' => id,
+        'name' => name,
+        'description' => description,
+        'privileges' => privileges,
+        'roles' => roles
+      }
+      @connection.post(endpoint: 'security/roles', parameters: parameters, api_version: 'beta')
+    end
+
     # GET /service/rest/beta/security/roles/{id}
+    def list_role(id:)
+      @connection.get_response(endpoint: "security/roles/#{id}?source=default", api_version: 'beta')
+    end
+
     # PUT /service/rest/beta/security/roles/{id}
     # DELETE /service/rest/beta/security/roles/{id}
+    def delete_role(id:)
+      @connection.delete(endpoint: "security/roles/#{id}", api_version: 'beta')
+    end
   end
 end

data/lib/endpoints/search.rb

@@ -13,6 +13,23 @@ module NexusAPI
       @connection.get_response(endpoint: endpoint, paginate: paginate)
     end
 
+    def search_all_assets(name:, format: nil, repository: nil, sha1: nil, version: nil)
+      results = Array.new.tap do |results|
+        loop do
+          results.concat(
+            search_asset(
+              name: name,
+              format: format,
+              repository: repository,
+              sha1: sha1,
+              version: version,
+              paginate: true
+            ))
+          break unless paginate?
+        end
+      end
+    end
+
     # GET /service/rest/v1/search/assets/download
   end
 end

data/lib/endpoints/staging.rb

@@ -2,8 +2,11 @@ module NexusAPI
   class API
     # POST /service/rest/v1/staging/delete
     # POST /service/rest/v1/staging/move/{destination}
-    def move_components_to(destination:, tag:)
-      @connection.post(endpoint: "staging/move/#{destination}?tag=#{tag}")
+    def move_components_to(destination:, tag:, source: nil, keyword: nil)
+      endpoint = "staging/move/#{destination}?tag=#{tag}"
+      endpoint += "&repository=#{source}" unless source.nil?
+      endpoint += "&q=#{keyword}" unless keyword.nil?
+      @connection.post(endpoint: endpoint)
     end
   end
 end

data/lib/endpoints/tags.rb

@@ -5,6 +5,15 @@ module NexusAPI
       @connection.get_response(endpoint: 'tags', paginate: paginate)
     end
 
+    def list_all_tags
+      tags = Array.new.tap do |tags|
+        loop do
+          tags.concat(list_tags(paginate: true))
+          break unless paginate?
+        end
+      end
+    end
+
     # POST /service/rest/v1/tags
     def create_tag(name:)
       parameters = JSON.dump({
@@ -21,24 +30,47 @@ module NexusAPI
     end
 
     # POST /service/rest/v1/tags/associate/{tagName}
-    def associate_tag(name:, sha1:, repository: nil)
+    def associate_tag(name:, sha1: nil, repository: nil, tag: nil)
       repository ||= @team_config.tag_repository
-      search_query =
-        "?"\
-        "wait=true&"\
-        "repository=#{repository}&"\
-        "sha1=#{sha1}"
+      if sha1.nil? && repository.nil? && tag.nil?
+        puts_error(__method__)
+        return false
+      end
+
+      search_query = "?wait=true"
+      search_query += "&sha1=#{sha1}" unless sha1.nil?
+      search_query += "&repository=#{repository}" unless repository.nil?
+      search_query += "&tag=#{tag}" unless tag.nil?
+
       @connection.post(endpoint: "tags/associate/#{name}" + search_query)
     end
 
     # DELETE /service/rest/v1/tags/associate/{tagName}
-    def delete_associated_tag(name:, sha1:, repository: nil)
+    def delete_associated_tag(name:, sha1: nil, repository: nil, tag: nil)
       repository ||= @team_config.tag_repository
-      search_query =
-        "?"\
-        "repository=#{repository}&"\
-        "sha1=#{sha1}"
-      @connection.delete(endpoint: "tags/associate/#{name}" + search_query)
+      parameters = {}
+      parameters['sha1'] = sha1 unless sha1.nil?
+      parameters['repository'] = repository unless repository.nil?
+      parameters['tag'] = tag unless tag.nil?
+      if parameters.empty?
+        puts_error(__method__)
+        return false
+      end
+
+      search_query = parameters.map do |parameter, value|
+        "#{parameter}=#{value}"
+      end.join("&")
+
+      @connection.delete(endpoint: "tags/associate/#{name}?" + search_query)
+    end
+
+
+    private
+
+    def puts_error(method)
+      puts "ERROR: NexusAPI::API::#{method}() requires AT LEAST one optional parameter to"
+      puts "       be set otherwise ALL assets in Nexus will be tagged. If this is desired"
+      puts "       please open an issue or a PR to add a new method to handle this case."
     end
   end
 end

data/lib/endpoints/users.rb

@@ -1,9 +1,30 @@
 module NexusAPI
   class API
     # GET /service/rest/beta/security/users
+    def list_users
+      @connection.get_response(endpoint: 'security/users', api_version: 'beta')
+    end
+
     # POST /service/rest/beta/security/users
+    def create_user(user_id:, first_name:, last_name:, email:, password:, roles:)
+      parameters = {
+        'userId' => user_id,
+        'firstName' => first_name,
+        'lastName' => last_name,
+        'emailAddress' => email,
+        'password' => password,
+        'status' => 'active',
+        'roles' => roles,
+      }
+      @connection.post(endpoint: 'security/users', parameters: parameters, api_version: 'beta')
+    end
+
     # PUT /service/rest/beta/security/users/{userId}
     # DELETE /service/rest/beta/security/users/{userId}
+    def delete_user(user_id:)
+      @connection.delete(endpoint: "security/users/#{user_id}", api_version: 'beta')
+    end
+
     # PUT /service/rest/beta/security/users/{userId}/change-password
     # DELETE /service/rest/beta/security/users/{userId}/user-token
   end

data/lib/nexus_api/cli_commands/list.rb

@@ -51,16 +51,31 @@ module NexusAPI
       print_paginating_set(action: :list_components, params: {repository: options[:repository]}, filter: 'name', proc: proc)
     end
 
+    desc 'privileges', 'Prints out a list of all privileges'
+    def privileges
+      print_set(action: :list_privileges, filter: 'name')
+    end
+
     desc 'repositories', 'Prints out a list of all repositories'
     def repositories
       print_set(action: :list_repositories, filter: 'name')
     end
 
+    desc 'roles', 'Prints out a list of all roles'
+    def roles
+      print_set(action: :list_roles, filter: 'name')
+    end
+
     desc 'status', 'Prints out if the Nexus server can respond to read and write requests'
     def status
       setup
       puts "Nexus can respond to read requests:  #{@api.status}"
       puts "Nexus can respond to write requests: #{@api.status_writable}"
     end
+
+    desc 'users', 'Prints out a list of all users'
+    def users
+      print_set(action: :list_users, filter: 'emailAddress')
+    end
   end
 end

data/lib/nexus_api/cli_commands/tag.rb

@@ -31,7 +31,7 @@ module NexusAPI
     desc 'list', 'Prints out a list of all tags'
     option :full, :aliases => '-f', :desc => 'Print full JSON output'
     def list
-      print_set(action: :list_tags, filter: 'name')
+      print_paginating_set(action: :list_tags, params: {}, filter: 'name')
     end
 
     desc 'remove', 'Removes a tag from an asset'

data/lib/nexus_api/docker_manager.rb

@@ -15,8 +15,8 @@ module NexusAPI
       return false unless docker_valid?
       image_name = image_name(@pull_host, image_name, tag)
       begin
-        image = @docker.pull_image(@username, @password, image_name)
-      rescue Docker::Error::NotFoundError => error
+        @docker.pull_image(@username, @password, image_name)
+      rescue Docker::Error::NotFoundError
         puts "ERROR: Failed to pull Docker image #{image_name}.\nDoes it exist in Nexus?"
         return false
       end

data/lib/nexus_api/nexus_connection.rb

@@ -88,7 +88,11 @@ module NexusAPI
 
     def handle(error)
       puts "ERROR: Request failed"
-      puts error.description if error.is_a?(RestClient::Response)
+      if error.is_a?(RestClient::Response)
+        puts error.description
+      else
+        puts error.to_s
+      end
     end
 
     def catch_connection_error
@@ -98,8 +102,12 @@ module NexusAPI
         return handle(error)
       rescue RestClient::Unauthorized => error
         return handle(error)
+      rescue RestClient::Exceptions::ReadTimeout => error
+        return handle(error)
       rescue RestClient::ExceptionWithResponse => error
         return handle(error.response)
+      rescue StandardError => error
+        return handle(error)
       end
     end
 
@@ -108,6 +116,7 @@ module NexusAPI
     end
 
     def send_request(connection_method, endpoint, parameters: '', headers: {}, api_version: 'v1')
+      parameters = parameters.to_json if headers['Content-Type'] == 'application/json'
       url = "https://#{@hostname}/service/rest/#{api_version}/#{endpoint}"
       catch_connection_error do
         RestClient::Request.execute(
@@ -120,10 +129,11 @@ module NexusAPI
     end
 
     def send_get(endpoint, paginate, headers, api_version)
+      url_marker = endpoint.include?('?') ? '&' : '?'
       # paginate answers is the user requesting pagination, paginate? answers does a continuation token exist
       # if an empty continuation token is included in the request we'll get an ArrayIndexOutOfBoundsException
-      endpoint += "&continuationToken=#{@continuation_token}" if paginate && paginate?
-      response = send_request(
+      endpoint += "#{url_marker}continuationToken=#{@continuation_token}" if paginate && paginate?
+      send_request(
         :get,
         endpoint,
         headers: headers,

data/lib/nexus_api/version.rb

@@ -1,4 +1,4 @@
 module NexusAPI
-  VERSION = '1.2.0'
+  VERSION = '1.5.0'
 end
 

data/lib/utilities/parameter_builder.rb

@@ -30,7 +30,7 @@ module NexusAPI
           'forceBasicAuth' => true,
           'httpPort' => port
         }
-      }.to_json
+      }
     end
 
     def self.maven_hosted(name, write_policy: ALLOW_ONCE, version_policy: RELEASE, layout_policy: STRICT)
@@ -46,7 +46,7 @@ module NexusAPI
           'versionPolicy' => version_policy,
           'layoutPolicy' => layout_policy
         }
-      }.to_json
+      }
     end
 
     def self.npm_hosted(name, write_policy: ALLOW_ONCE)
@@ -58,7 +58,7 @@ module NexusAPI
           'strictContentTypeValidation' => true,
           'writePolicy' => write_policy
         }
-      }.to_json
+      }
     end
 
     def self.pypi_hosted(name, write_policy: ALLOW_ONCE)
@@ -70,7 +70,7 @@ module NexusAPI
           'strictContentTypeValidation' => true,
           'writePolicy' => write_policy
         }
-      }.to_json
+      }
     end
 
     def self.yum_hosted(name, depth, write_policy: ALLOW_ONCE, deploy_policy: STRICT)
@@ -86,7 +86,7 @@ module NexusAPI
           'repodataDepth' => depth,
           'deployPolicy' => deploy_policy
         }
-      }.to_json
+      }
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nexus_api
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.5.0
 platform: ruby
 authors:
 - Francis Levesque