From b728dbc80eba964a95f14d710662e578e804cab4 Mon Sep 17 00:00:00 2001 From: Mantas Date: Wed, 18 Nov 2026 10:08:55 +0200 Subject: [PATCH 01/11] refactor!: rewrite the client for 2.0 2.0 replaces the internals of the gem and most of its surface. What 1.x did through method_missing and a mutable client is explicit, immutable and checked here. The calls that changed are listed in the changelog and in the README's migration guide. The client. Client.new takes keyword arguments and validates them into a Config before any request is made, and an unknown option raises. A client is immutable: with and on_behalf_of return a new one, so a single instance is safe to share between threads. Credentials are redacted wherever a config, a transport or an error can be printed, and more than one authentication scheme is refused. The transport. Requests carry timeouts by default. A read is retried with backoff on connection failures, timeouts and the transient statuses, and a write is never repeated. No Faraday exception or object escapes: every failure is a ZammadAPI::Error with a class per status, and a response is a ZammadAPI::Response. get, post, put and delete reach any endpoint the gem does not model. A query is written the way Rails reads it back, so a search condition with nested groups reaches Zammad as it was given, and one a query string cannot carry is refused before it is sent. Collections. ListBase, ListAll and ListSearch give way to Collection, a lazy Enumerable that walks every page instead of stopping at the first hundred records, with order, page, in_batches, find_each, count and pluck. A page size is clamped to what the endpoint serves. Records. Dispatcher gives way to ResourceProxy, reached through plural readers such as client.tickets; the singular ones remain as deprecated aliases. A resource declares what its endpoint does, and a class of the caller's own works through client.resource. Records track their changes and send only those, answer false from save on a validation failure, support pattern matching, and reach the records they point at through record.related. The toolchain moves with the code that needs it: Ruby 3.4 for the `it` block parameter, faraday-retry, the RuboCop configuration without its todo file, and a Rakefile that separates the unit specs from the ones that need a live Zammad. Those live specs move from spec/zammad_api to spec/integration and are rewritten for the new API, and as they create and delete records they run only against the Zammad that TEST_URL names: there is no default. The specs under spec/unit are new and need no Zammad. The version is 2.0.0.alpha1. The Rakefile's steep and rbs_published tasks have nothing to check until the signatures arrive, two commits on. --- .gitignore | 4 +- .overcommit.yml | 50 +- .rspec | 1 + .rubocop.yml | 156 +- .rubocop_todo.yml | 35 - .ruby-version | 1 + .yardopts | 9 + Gemfile | 30 +- Gemfile.lock | 108 +- Rakefile | 66 +- bin/console | 8 + bin/setup | 6 + examples/example_http_token.rb | 59 - lib/zammad_api.rb | 20 +- lib/zammad_api/associations.rb | 143 ++ lib/zammad_api/attribute_access.rb | 311 ++++ lib/zammad_api/client.rb | 527 +++++- lib/zammad_api/collection.rb | 813 +++++++++ lib/zammad_api/config.rb | 508 ++++++ lib/zammad_api/deep_copy.rb | 83 + lib/zammad_api/dispatcher.rb | 12 - lib/zammad_api/duplicate_keys.rb | 49 + lib/zammad_api/errors.rb | 195 +- lib/zammad_api/json_helper.rb | 11 - lib/zammad_api/list_all.rb | 11 - lib/zammad_api/list_base.rb | 84 - lib/zammad_api/list_search.rb | 11 - lib/zammad_api/log.rb | 18 - lib/zammad_api/query_encoder.rb | 162 ++ lib/zammad_api/resource_proxy.rb | 611 +++++++ lib/zammad_api/resources.rb | 26 +- lib/zammad_api/resources/base.rb | 1003 +++++++++- lib/zammad_api/resources/group.rb | 14 +- lib/zammad_api/resources/organization.rb | 14 +- lib/zammad_api/resources/ticket.rb | 116 +- lib/zammad_api/resources/ticket_article.rb | 53 +- .../resources/ticket_article_attachment.rb | 58 +- lib/zammad_api/resources/ticket_priority.rb | 12 +- lib/zammad_api/resources/ticket_state.rb | 12 +- lib/zammad_api/resources/user.rb | 29 +- lib/zammad_api/response.rb | 170 ++ lib/zammad_api/transport.rb | 1153 +++++++++++- lib/zammad_api/version.rb | 4 +- script/live_target.rb | 37 + spec/integration/authentication_spec.rb | 29 + .../resources => integration}/group_spec.rb | 30 +- .../organization_spec.rb | 46 +- .../ticket_priority_spec.rb | 32 +- .../resources => integration}/ticket_spec.rb | 41 +- .../ticket_state_spec.rb | 34 +- .../resources => integration}/user_spec.rb | 50 +- spec/spec_helper.rb | 106 +- spec/support/bare_socket_adapter.rb | 46 + spec/support/client_helper.rb | 29 + spec/support/integration_helper.rb | 147 ++ .../zammad_api/associations/proxy_spec.rb | 433 +++++ spec/unit/zammad_api/attribute_access_spec.rb | 394 ++++ spec/unit/zammad_api/client_spec.rb | 1141 ++++++++++++ spec/unit/zammad_api/collection_spec.rb | 1306 +++++++++++++ spec/unit/zammad_api/config_spec.rb | 683 +++++++ spec/unit/zammad_api/query_encoder_spec.rb | 180 ++ spec/unit/zammad_api/resource_proxy_spec.rb | 1069 +++++++++++ spec/unit/zammad_api/resources/base_spec.rb | 1513 +++++++++++++++ .../ticket_article_attachment_spec.rb | 152 ++ spec/unit/zammad_api/resources/ticket_spec.rb | 216 +++ spec/unit/zammad_api/response_error_spec.rb | 197 ++ spec/unit/zammad_api/response_spec.rb | 158 ++ spec/unit/zammad_api/transport_spec.rb | 1614 +++++++++++++++++ spec/zammad_api/client_spec.rb | 110 -- spec/zammad_api/errors_spec.rb | 164 -- spec/zammad_api/json_helper_spec.rb | 21 - spec/zammad_api/resources/list_base_spec.rb | 7 - spec/zammad_api/transport_spec.rb | 80 - spec/zammad_api_spec.rb | 36 - zammad_api.gemspec | 71 +- 75 files changed, 15735 insertions(+), 1203 deletions(-) delete mode 100644 .rubocop_todo.yml create mode 100644 .ruby-version create mode 100644 .yardopts create mode 100755 bin/console create mode 100755 bin/setup delete mode 100755 examples/example_http_token.rb create mode 100644 lib/zammad_api/associations.rb create mode 100644 lib/zammad_api/attribute_access.rb create mode 100644 lib/zammad_api/collection.rb create mode 100644 lib/zammad_api/config.rb create mode 100644 lib/zammad_api/deep_copy.rb delete mode 100644 lib/zammad_api/dispatcher.rb create mode 100644 lib/zammad_api/duplicate_keys.rb delete mode 100644 lib/zammad_api/json_helper.rb delete mode 100644 lib/zammad_api/list_all.rb delete mode 100644 lib/zammad_api/list_base.rb delete mode 100644 lib/zammad_api/list_search.rb delete mode 100644 lib/zammad_api/log.rb create mode 100644 lib/zammad_api/query_encoder.rb create mode 100644 lib/zammad_api/resource_proxy.rb create mode 100644 lib/zammad_api/response.rb create mode 100644 script/live_target.rb create mode 100644 spec/integration/authentication_spec.rb rename spec/{zammad_api/resources => integration}/group_spec.rb (83%) rename spec/{zammad_api/resources => integration}/organization_spec.rb (80%) rename spec/{zammad_api/resources => integration}/ticket_priority_spec.rb (75%) rename spec/{zammad_api/resources => integration}/ticket_spec.rb (84%) rename spec/{zammad_api/resources => integration}/ticket_state_spec.rb (84%) rename spec/{zammad_api/resources => integration}/user_spec.rb (86%) create mode 100644 spec/support/bare_socket_adapter.rb create mode 100644 spec/support/client_helper.rb create mode 100644 spec/support/integration_helper.rb create mode 100644 spec/unit/zammad_api/associations/proxy_spec.rb create mode 100644 spec/unit/zammad_api/attribute_access_spec.rb create mode 100644 spec/unit/zammad_api/client_spec.rb create mode 100644 spec/unit/zammad_api/collection_spec.rb create mode 100644 spec/unit/zammad_api/config_spec.rb create mode 100644 spec/unit/zammad_api/query_encoder_spec.rb create mode 100644 spec/unit/zammad_api/resource_proxy_spec.rb create mode 100644 spec/unit/zammad_api/resources/base_spec.rb create mode 100644 spec/unit/zammad_api/resources/ticket_article_attachment_spec.rb create mode 100644 spec/unit/zammad_api/resources/ticket_spec.rb create mode 100644 spec/unit/zammad_api/response_error_spec.rb create mode 100644 spec/unit/zammad_api/response_spec.rb create mode 100644 spec/unit/zammad_api/transport_spec.rb delete mode 100644 spec/zammad_api/client_spec.rb delete mode 100644 spec/zammad_api/errors_spec.rb delete mode 100644 spec/zammad_api/json_helper_spec.rb delete mode 100644 spec/zammad_api/resources/list_base_spec.rb delete mode 100644 spec/zammad_api/transport_spec.rb delete mode 100644 spec/zammad_api_spec.rb diff --git a/.gitignore b/.gitignore index 002a2a1..bb396ef 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,6 @@ /.bundle/ -/.ruby-version -/.yardoc +/.steep/ +/.yardoc/ /_yardoc/ /coverage/ /doc/ diff --git a/.overcommit.yml b/.overcommit.yml index 8553cbe..740cb16 100644 --- a/.overcommit.yml +++ b/.overcommit.yml @@ -1,33 +1,23 @@ -# Use this file to configure the Overcommit hooks you wish to use. This will -# extend the default configuration defined in: -# https://github.com/sds/overcommit/blob/master/config/default.yml +# See https://github.com/sds/overcommit#configuration # -# At the topmost level of this YAML file is a key representing type of hook -# being run (e.g. pre-commit, commit-msg, etc.). Within each type you can -# customize each hook, such as whether to only run it on certain files (via -# `include`), whether to only display output if it fails (via `quiet`), etc. -# -# For a complete list of hooks, see: -# https://github.com/sds/overcommit/tree/master/lib/overcommit/hook -# -# For a complete list of options that you can use to customize hooks, see: -# https://github.com/sds/overcommit#configuration -# -# Uncomment the following lines to make the configuration take effect. +# Install with: bundle exec overcommit --install PreCommit: - RuboCop: - enabled: true - on_warn: fail # Treat all warnings as failures -# -# TrailingWhitespace: -# enabled: true -# exclude: -# - '**/db/structure.sql' # Ignore trailing whitespace in generated files -# -#PostCheckout: -# ALL: # Special hook name that customizes all hooks of this type -# quiet: true # Change all post-checkout hooks to only display output on failure -# -# IndexTags: -# enabled: true # Generate a tags file with `ctags` each time HEAD changes + RuboCop: + enabled: true + on_warn: fail # Treat all warnings as failures + command: ['bundle', 'exec', 'rubocop'] + + TrailingWhitespace: + enabled: true + + YamlSyntax: + enabled: true + + BundleCheck: + enabled: true + + RSpec: + enabled: true + description: 'Run the unit specs' + command: ['bundle', 'exec', 'rspec', 'spec/unit'] diff --git a/.rspec b/.rspec index 8c18f1a..7a2cc1a 100644 --- a/.rspec +++ b/.rspec @@ -1,2 +1,3 @@ +--require spec_helper --format documentation --color diff --git a/.rubocop.yml b/.rubocop.yml index 0ae18f9..f6254f4 100644 --- a/.rubocop.yml +++ b/.rubocop.yml @@ -1,117 +1,99 @@ -# Default enabled cops -# https://github.com/bbatsov/rubocop/blob/master/config/enabled.yml - plugins: - rubocop-performance - rubocop-rake - rubocop-rspec -inherit_from: - - .rubocop_todo.yml - AllCops: NewCops: enable Exclude: - - 'bin/rails' - - 'bin/rake' - - 'bin/spring' - - 'db/schema.rb' - - 'examples/**/*' - # Match the Ruby version specified in the gemspec. - TargetRubyVersion: 3.0 + - 'pkg/**/*' + - 'vendor/**/*' + # Keep in sync with required_ruby_version in the gemspec and the CI matrix. + TargetRubyVersion: 3.4 -# Zammad StyleGuide - -Style/FrozenStringLiteralComment: - Enabled: false +# --- Zammad style guide ----------------------------------------------------- Style/NegatedIf: - Description: >- - Favor unless over if for negative conditions - (or control flow or). - StyleGuide: 'https://github.com/bbatsov/ruby-style-guide#unless-for-negatives' + Description: 'Zammad prefers an explicit `if !x` over `unless x`.' Enabled: false Style/IfUnlessModifier: - Description: >- - Favor modifier if/unless usage when you have a - single-line body. - StyleGuide: 'https://github.com/bbatsov/ruby-style-guide#if-as-a-modifier' + Description: 'Zammad allows multi-line bodies for a single condition.' Enabled: false Style/TrailingCommaInArrayLiteral: - Description: 'Checks for trailing comma in array literals.' - StyleGuide: '#no-trailing-array-commas' Enabled: false Style/TrailingCommaInHashLiteral: - Description: 'Checks for trailing comma in hash literals.' Enabled: false Style/TrailingCommaInArguments: - Description: 'Checks for trailing comma in argument lists.' - StyleGuide: 'https://github.com/bbatsov/ruby-style-guide#no-trailing-array-commas' Enabled: false Layout/LeadingCommentSpace: - Description: 'Comments should start with a space.' - StyleGuide: 'https://github.com/bbatsov/ruby-style-guide#hash-space' Enabled: false Layout/HashAlignment: - Description: >- - Align the elements of a hash literal if they span more than - one line. Enabled: true EnforcedHashRocketStyle: table EnforcedColonStyle: table EnforcedLastArgumentHashStyle: always_inspect Style/ClassAndModuleChildren: - Description: 'Checks style of children classes and modules.' Enabled: false +Naming/PredicatePrefix: + # `has_many` is the established name for the declaration, and neither it nor + # the reader behind it is a predicate. + AllowedMethods: + - has_many + - has_many_target + Naming/MethodParameterName: - Description: >- - Checks for method parameter names that contain capital letters, - end in numbers, or do not meet a minimal length. - Enabled: true - AllowedNames: [id] + # `of` is ActiveRecord's name for a batch size, see Collection#in_batches. + AllowedNames: [id, to, of] Layout/MultilineMethodCallIndentation: - Description: >- - Checks the indentation of the method name part in method calls - that span more than one line. EnforcedStyle: indented Style/RescueStandardError: EnforcedStyle: implicit +Style/ArgumentsForwarding: + # Named parameters keep public signatures self-documenting for YARD/RBS. + UseAnonymousForwarding: false + +Naming/BlockForwarding: + EnforcedStyle: explicit + +Naming/PredicateMethod: + # Established names from the resource API. `save` reports whether the record + # was stored; the rest return true on success. + AllowedMethods: + - save + - save! + - update + - update! + - destroy + Style/Documentation: + Description: 'Public API documentation is enforced by review, not by this cop.' Enabled: false Style/PerlBackrefs: - Description: 'Avoid Perl-style regex back references.' - StyleGuide: 'https://github.com/bbatsov/ruby-style-guide#no-perl-regexp-last-matchers' Enabled: false Style/BlockComments: - # Keep block comments (=begin ... =end) to allow for easy copy-pasting of examples. - Description: 'Do not use block comments.' + Description: 'Block comments make examples easy to copy and paste.' Enabled: false Layout/LineLength: - Description: 'Limit lines to 80 characters.' - StyleGuide: 'https://github.com/bbatsov/ruby-style-guide#80-character-limits' Enabled: false Metrics/ClassLength: - Description: 'Avoid classes longer than 100 lines of code.' Enabled: false Metrics/MethodLength: - Description: 'Avoid methods longer than 10 lines of code.' - StyleGuide: 'https://github.com/bbatsov/ruby-style-guide#short-methods' Enabled: false Metrics/AbcSize: @@ -123,21 +105,61 @@ Metrics/CyclomaticComplexity: Metrics/PerceivedComplexity: Max: 12 +Metrics/ParameterLists: + # Config mirrors every supported option as a keyword argument. + Max: 16 + MaxOptionalParameters: 15 + +# Broken: "String".downcase == "strinG".downcase is not the same as +# "String".casecmp("strinG"), only as "String".casecmp("strinG") == 0. +Performance/Casecmp: + Enabled: false + +# --- Specs ------------------------------------------------------------------ + RSpec/ExampleLength: - inherit_mode: - merge: - - Exclude - CountAsOne: - - 'array' - - 'hash' - - 'heredoc' - Max: 25 + CountAsOne: ['array', 'hash', 'heredoc'] + Max: 12 + # Integration specs are end-to-end scenarios against a live Zammad. + Exclude: + - 'spec/integration/**/*' + +RSpec/MultipleExpectations: + Description: 'A few request assertions per example are clearer than splitting them.' + Max: 3 + Exclude: + - 'spec/integration/**/*' + +RSpec/DescribeMethod: + Exclude: + - 'spec/integration/**/*' RSpec/NestedGroups: - Max: 6 + Max: 4 -# Broken!!!! Generates broken code since "String".downcase == "strinG".downcase is not equals "String".casecmp("strinG") but "String".casecmp("strinG") == 0 !!! -Performance/Casecmp: - Description: 'Use `casecmp` rather than `downcase ==`.' - Reference: 'https://github.com/JuanitoFatas/fast-ruby#stringcasecmp-vs-stringdowncase---code' - Enabled: false +RSpec/SpecFilePathFormat: + # Integration specs are grouped by the Zammad object they exercise, not by + # the class under test. + Exclude: + - 'spec/integration/**/*' + +RSpec/DescribeClass: + Exclude: + - 'spec/integration/**/*' + +RSpec/BeforeAfterAll: + Exclude: + - 'spec/integration/**/*' + +RSpec/LeakyLocalVariable: + # The integration specs deliberately share a record across ordered examples: + # each one asserts on what the previous step left behind. The coupling is + # pinned by `config.order = :defined` and every example that reads the record + # goes through `established!`, so a partial run says what is missing rather + # than failing on nil. + Exclude: + - 'spec/integration/**/*' + +RSpec/NoExpectationExample: + Exclude: + - 'spec/integration/**/*' diff --git a/.rubocop_todo.yml b/.rubocop_todo.yml deleted file mode 100644 index 20ec1c6..0000000 --- a/.rubocop_todo.yml +++ /dev/null @@ -1,35 +0,0 @@ -Naming/PredicateMethod: - Enabled: false - -Style/MissingRespondToMissing: - Enabled: false - -Style/StringConcatenation: - Enabled: false - -Naming/AccessorMethodName: - Enabled: false - -RSpec/MultipleExpectations: - Enabled: false - -RSpec/ExampleLength: - Enabled: false - -RSpec/SpecFilePathFormat: - Enabled: false - -RSpec/NoExpectationExample: - Enabled: false - -RSpec/DescribeMethod: - Enabled: false - -RSpec/ContextWording: - Enabled: false - -RSpec/BeforeAfterAll: - Enabled: false - -RSpec/LeakyLocalVariable: - Enabled: false diff --git a/.ruby-version b/.ruby-version new file mode 100644 index 0000000..7919852 --- /dev/null +++ b/.ruby-version @@ -0,0 +1 @@ +4.0.9 diff --git a/.yardopts b/.yardopts new file mode 100644 index 0000000..04abe42 --- /dev/null +++ b/.yardopts @@ -0,0 +1,9 @@ +--markup markdown +--readme README.md +--output-dir doc +--no-private +--protected +lib/**/*.rb +- +CHANGELOG.md +LICENSE.md diff --git a/Gemfile b/Gemfile index 2d9e06b..2d37c5e 100644 --- a/Gemfile +++ b/Gemfile @@ -1,17 +1,25 @@ +# frozen_string_literal: true + source 'https://rubygems.org' -# runtime dependencies are defined in zammad_api.gemspec +# Runtime dependencies are defined in zammad_api.gemspec. gemspec -# development dependencies group :development, :test do - gem 'bundler', '>= 2.2.10' - gem 'overcommit' - gem 'rake' - gem 'rspec' - gem 'rubocop' - gem 'rubocop-performance' - gem 'rubocop-rake' - gem 'rubocop-rspec' - gem 'webmock' + gem 'overcommit', require: false + gem 'rake', require: false + gem 'rspec', '~> 3.13' + gem 'rubocop', require: false + gem 'rubocop-performance', require: false + gem 'rubocop-rake', require: false + gem 'rubocop-rspec', require: false + gem 'simplecov', '~> 1.3', require: false + gem 'webmock', '~> 3.26' + gem 'yard', require: false +end + +group :development do + # Static type checking against the signatures in sig/. + gem 'rbs', require: false + gem 'steep', require: false end diff --git a/Gemfile.lock b/Gemfile.lock index e8d29c5..9dc91ed 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -1,21 +1,24 @@ PATH remote: . specs: - zammad_api (1.3.1) - faraday (~> 2) + zammad_api (2.0.0.alpha1) + faraday (~> 2.9) + faraday-retry (~> 2.2) GEM remote: https://rubygems.org/ specs: - addressable (2.9.1) + addressable (2.9.2) public_suffix (>= 2.0.2, < 8.0) ast (2.4.3) bigdecimal (4.1.3) childprocess (5.1.0) logger (~> 1.5) + concurrent-ruby (1.3.8) crack (1.0.1) bigdecimal rexml + csv (3.3.7) diff-lcs (1.6.2) faraday (2.15.1) faraday-net_http (>= 2.0, < 3.6) @@ -23,11 +26,29 @@ GEM logger faraday-net_http (3.5.0) net-http (~> 0.5) - hashdiff (1.2.1) + faraday-retry (2.4.0) + faraday (~> 2.0) + ffi (1.17.4) + ffi (1.17.4-aarch64-linux-gnu) + ffi (1.17.4-aarch64-linux-musl) + ffi (1.17.4-arm-linux-gnu) + ffi (1.17.4-arm-linux-musl) + ffi (1.17.4-arm64-darwin) + ffi (1.17.4-x86-linux-gnu) + ffi (1.17.4-x86-linux-musl) + ffi (1.17.4-x86_64-darwin) + ffi (1.17.4-x86_64-linux-gnu) + ffi (1.17.4-x86_64-linux-musl) + fileutils (1.8.1) + hashdiff (1.2.2) iniparse (1.5.0) json (3.1.0) language_server-protocol (3.17.0.6) lint_roller (1.1.0) + listen (3.10.1) + logger + rb-fsevent (~> 0.10, >= 0.10.3) + rb-inotify (~> 0.9, >= 0.9.10) logger (1.7.0) net-http (0.10.0) net-protocol (>= 0.3.0) @@ -38,30 +59,45 @@ GEM childprocess (>= 5.0.0, < 6) iniparse (~> 1.4) rexml (>= 3.4.2) - parallel (1.28.0) + parallel (2.3.0) parser (3.3.13.0) ast (~> 2.4.1) racc - prism (1.9.0) - public_suffix (6.0.2) + prism (2.1.0) + prism (2.1.0-aarch64-linux-gnu) + prism (2.1.0-aarch64-linux-musl) + prism (2.1.0-arm-linux-gnu) + prism (2.1.0-arm-linux-musl) + prism (2.1.0-arm64-darwin) + prism (2.1.0-x86_64-darwin) + prism (2.1.0-x86_64-linux-gnu) + prism (2.1.0-x86_64-linux-musl) + public_suffix (7.0.5) racc (1.8.1) rainbow (3.1.1) rake (13.4.2) - regexp_parser (2.13.1) + rb-fsevent (0.11.2) + rb-inotify (0.11.1) + ffi (~> 1.0) + rbs (4.2.0) + logger + prism (>= 1.6.0) + tsort + regexp_parser (2.13.2) rexml (3.4.4) rspec (3.13.2) rspec-core (~> 3.13.0) rspec-expectations (~> 3.13.0) rspec-mocks (~> 3.13.0) - rspec-core (3.13.6) + rspec-core (3.13.7) rspec-support (~> 3.13.0) - rspec-expectations (3.13.5) + rspec-expectations (3.13.6) diff-lcs (>= 1.2.0, < 2.0) rspec-support (~> 3.13.0) - rspec-mocks (3.13.8) + rspec-mocks (3.13.9) diff-lcs (>= 1.2.0, < 2.0) rspec-support (~> 3.13.0) - rspec-support (3.13.7) + rspec-support (3.13.8) rubocop (1.92.2) json (>= 2.3) language_server-protocol (~> 3.17.0.2) @@ -73,9 +109,9 @@ GEM rubocop-ast (>= 1.49.0, < 2.0) ruby-progressbar (~> 1.7) unicode-display_width (>= 2.4.0, < 4.0) - rubocop-ast (1.50.0) + rubocop-ast (1.51.0) parser (>= 3.3.7.2) - prism (~> 1.7) + prism (>= 1.7) rubocop-performance (1.27.0) lint_roller (~> 1.1) rubocop (>= 1.89.0, < 2.0) @@ -88,7 +124,29 @@ GEM regexp_parser (>= 2.0) rubocop (~> 1.86, >= 1.86.2) ruby-progressbar (1.13.0) + securerandom (0.4.1) + simplecov (1.3.2) + steep (2.1.0) + concurrent-ruby (>= 1.1.10) + csv (>= 3.0.9) + fileutils (>= 1.1.0) + json (>= 2.1.0) + language_server-protocol (>= 3.17.0.4, < 4.0) + listen (~> 3.0) + logger (>= 1.3.0) + parser (>= 3.2) + prism (>= 0.25.0) + rainbow (>= 2.2.2, < 4.0) + rbs (~> 4.2) + securerandom (>= 0.1) + strscan (>= 1.0.0) + terminal-table (>= 2, < 5) + uri (>= 0.12.0) + strscan (3.1.8) + terminal-table (4.0.0) + unicode-display_width (>= 1.1.1, < 4) timeout (0.6.1) + tsort (0.2.0) unicode-display_width (3.3.0) unicode-emoji (~> 4.3) unicode-emoji (4.3.0) @@ -97,21 +155,35 @@ GEM addressable (>= 2.8.0) crack (>= 0.3.2) hashdiff (>= 0.4.0, < 2.0.0) + yard (0.9.45) PLATFORMS + aarch64-linux-gnu + aarch64-linux-musl + arm-linux-gnu + arm-linux-musl + arm64-darwin ruby + x86-linux-gnu + x86-linux-musl + x86_64-darwin + x86_64-linux-gnu + x86_64-linux-musl DEPENDENCIES - bundler (>= 2.2.10) overcommit rake - rspec + rbs + rspec (~> 3.13) rubocop rubocop-performance rubocop-rake rubocop-rspec - webmock + simplecov (~> 1.3) + steep + webmock (~> 3.26) + yard zammad_api! BUNDLED WITH - 2.6.9 + 4.0.20 diff --git a/Rakefile b/Rakefile index 4c774a2..756f246 100644 --- a/Rakefile +++ b/Rakefile @@ -1,6 +1,68 @@ +# frozen_string_literal: true + require 'bundler/gem_tasks' +require 'fileutils' require 'rspec/core/rake_task' +require 'rubocop/rake_task' +require_relative 'script/live_target' + +namespace :spec do + desc 'Run the unit specs (no Zammad instance required)' + RSpec::Core::RakeTask.new(:unit) do |task| + task.pattern = 'spec/unit/**/*_spec.rb' + end + + desc 'Run the integration specs against the Zammad that TEST_URL names' + RSpec::Core::RakeTask.new(integration: :live_target) do |task| + task.pattern = 'spec/integration/**/*_spec.rb' + end +end + +desc 'Run all specs' +task spec: [:live_target, 'spec:unit', 'spec:integration'] + +# The integration specs and check_connection create and delete records, so +# neither has a default for where. Asked here as well as in each of them, so +# that a task which was asked to run against a live Zammad says why it did +# not rather than passing over specs that were left out. +desc 'Check that TEST_URL names the Zammad to run the live checks against' +task :live_target do + abort LiveTarget.unset_message('This task') if LiveTarget.url.nil? +end + +desc 'Drive the Zammad that TEST_URL names end to end with this gem' +task check_connection: :live_target do + sh 'ruby script/check_connection.rb' +end + +RuboCop::RakeTask.new + +desc 'Type-check lib/ against the signatures in sig/' +task :steep do + sh 'bundle exec steep check' +end + +# sig/vendor stands in for dependencies that ship no signatures and is kept +# out of the gem, so the published set has to hold up without it. Naming a +# Faraday type in a published signature made `rbs validate` fail for every +# consumer, and nothing in this repo noticed, because sig/vendor is always +# on the load path here. +desc 'Check that the signatures the gem ships validate without sig/vendor' +task :rbs_published do + require 'tmpdir' -RSpec::Core::RakeTask.new(:spec) + Dir.mktmpdir do |dir| + published = Dir['sig/**/*.rbs'].grep_v(%r{\Asig/vendor/}) + published.each do |file| + target = File.join(dir, file) + FileUtils.mkdir_p(File.dirname(target)) + FileUtils.cp(file, target) + end + # `logger` is the only library the published signatures name, and it is a + # standard one RBS ships declarations for, so a consumer already has it. + sh "bundle exec rbs -r logger -I #{File.join(dir, 'sig')} validate" + end +end -task default: :spec +desc 'Run everything that does not need a Zammad instance' +task default: ['spec:unit', :rubocop, :steep, :rbs_published] diff --git a/bin/console b/bin/console new file mode 100755 index 0000000..dcbd7d1 --- /dev/null +++ b/bin/console @@ -0,0 +1,8 @@ +#!/usr/bin/env ruby +# frozen_string_literal: true + +require 'bundler/setup' +require 'zammad_api' +require 'irb' + +IRB.start(__FILE__) diff --git a/bin/setup b/bin/setup new file mode 100755 index 0000000..bc8f0ad --- /dev/null +++ b/bin/setup @@ -0,0 +1,6 @@ +#!/usr/bin/env bash +set -euo pipefail +IFS=$'\n\t' + +bundle install +bundle exec overcommit --install diff --git a/examples/example_http_token.rb b/examples/example_http_token.rb deleted file mode 100755 index 5cf5803..0000000 --- a/examples/example_http_token.rb +++ /dev/null @@ -1,59 +0,0 @@ -#!/usr/bin/env ruby - -$LOAD_PATH << './lib' -require 'rubygems' -require 'zammad_api' - -client = ZammadAPI::Client.new( - url: 'https://you.zammad.com/', - http_token: 'XXXX', -) - -# create ticket -ticket = client.ticket.new( - title: 'some new title', - state: 'new', - priority: '2 normal', - owner: '-', - customer: 'nicole.braun@zammad.org', - group: 'Users', - article: { - sender: 'Customer', - type: 'note', - subject: 'some subject', - content_type: 'text/plain', - body: "some body\nnext line", - } -) -ticket.save - -p '--------------------------------------------------------' -p "Ticket has been created: #{ticket.number} - #{ticket.title} at #{ticket.created_at}" -p " Attributes: #{ticket.attributes.inspect}" - -# get ticket -p '--------------------------------------------------------' -ticket = client.ticket.find(ticket.id) -p "Ticket found on server: #{ticket.number} - #{ticket.title} at #{ticket.created_at}" -p " Attributes: #{ticket.attributes.inspect}" - -# get articles of ticket -p '--------------------------------------------------------' -articles = ticket.articles -p "Total #{articles.length} articles" - -# create article -p '--------------------------------------------------------' -article = ticket.article( - type: 'note', - subject: 'some subject 2', - body: 'some body 2', -) -p "Article has been created: #{article.subject} at #{article.created_at}" -p " Attributes: #{article.attributes.inspect}" - -# get articles of ticket -p '--------------------------------------------------------' -articles = ticket.articles -p "Total #{articles.length} articles now" -p '--------------------------------------------------------' diff --git a/lib/zammad_api.rb b/lib/zammad_api.rb index 608477d..4e1a126 100644 --- a/lib/zammad_api.rb +++ b/lib/zammad_api.rb @@ -1,6 +1,20 @@ -require 'zammad_api/version' -require 'zammad_api/errors' -require 'zammad_api/client' +# frozen_string_literal: true +require_relative 'zammad_api/version' +require_relative 'zammad_api/errors' +require_relative 'zammad_api/deep_copy' +require_relative 'zammad_api/config' +require_relative 'zammad_api/response' +require_relative 'zammad_api/transport' +require_relative 'zammad_api/attribute_access' +require_relative 'zammad_api/associations' +require_relative 'zammad_api/collection' +require_relative 'zammad_api/resources' +require_relative 'zammad_api/resource_proxy' +require_relative 'zammad_api/client' + +# Ruby client for the Zammad API v1.0. +# +# @see Client module ZammadAPI end diff --git a/lib/zammad_api/associations.rb b/lib/zammad_api/associations.rb new file mode 100644 index 0000000..31fa295 --- /dev/null +++ b/lib/zammad_api/associations.rb @@ -0,0 +1,143 @@ +# frozen_string_literal: true + +require_relative 'errors' +require_relative 'transport' + +module ZammadAPI + # Readers for the records a record points at. + module Associations + # Fetches the records an association points at. + # + # Reached through +record.related+, never built directly. The readers live + # here rather than on the record itself because Zammad already expands an + # association into a name: +ticket.customer+ is the customer's login and + # +ticket.state+ is +"open"+, both free of charge. An association reader + # returns the whole record and costs a request, so it is worth telling the + # two apart at the call site. + # + # @example + # ticket = client.tickets.find(1) + # + # ticket.customer # => "customer@example.com", already loaded + # ticket.related.customer # => the User record, one request + # ticket.related.customer.email # => "customer@example.com" + # + # ticket.related.articles # => [TicketArticle, ...] + class Proxy + # @api private + # @param record [Resources::Base] + def initialize(record) + @record = record + @cache = {} + end + + def inspect + "#<#{Proxy.name} #{@record.class.name} id=#{@record.id.inspect} #{@record.class.associations.keys.join(', ')}>" + end + + private + + # Memoized: the record an id points at does not change under the caller, + # and an unmemoized reader would turn a loop over tickets into a request + # per ticket per mention. The record empties the memo through + # {#forget_targets} when what it was resolved from may no longer hold. + # + # What is resolved goes into the memo this call began with, not the one + # that is current once the request is back. They differ where the + # record was written to while the request was out - by a logger or a + # middleware of the caller's that reaches the record, or by another + # thread - and {#forget_targets} has swapped the memo for an empty one. + # Written to the current memo, the user fetched for `customer_id` 7 + # became the memoized answer for a record that by then says 9, and + # stayed it until the next write. + def belongs_to_target(name, class_name, foreign_key) + refuse_destroyed!(name) + memo = @cache + return memo[name] if memo.key?(name) + + id = @record[foreign_key] + # {Resources::Base.fetch_one} rather than a ResourceProxy built for the + # one call: {Client#setup} builds and freezes one proxy per resource so + # that callers get one proxy per resource, and a reader here that built + # a fresh one per association turned a walk over ten thousand tickets + # reading two associations each into twenty thousand objects that exist + # for a single method call. It is the read {ResourceProxy#find} makes + # too, so there is one of it rather than one here and one there. + memo[name] = id.nil? ? nil : resolve(class_name).fetch_one(@record.transport, id) + end + + # Deliberately not memoized: a list can grow while the record is held, + # and +ticket.related.articles+ after +ticket.add_article(...)+ has to show + # the article that was just added. + # + # The path proc is handed the escaped id rather than the record, so that + # a declaration cannot paste a raw id into a path. One that did resolved + # `related.articles` on a record carrying `id: "1/../../users"` onto the + # users endpoint, the same way an unescaped {Resources::Base#member_path} + # used to - and a proc is exactly where that is easy to forget. + def has_many_target(name, class_name, path) + refuse_destroyed!(name) + raise Error, "#{@record.class.name} has no id, so it has no #{name} to read; save it first" if @record.id.nil? + + target_class = resolve(class_name) + operation = "get #{name}" + + response = @record.transport.get( + path.call(Transport.escape_path_segment(@record.id)), + operation: operation, + resource_class: target_class, + query: { expand: true } + ) + records = response.decoded(:array, operation: operation, resource_class: target_class) + records.map { target_class.from_response(@record.transport, it) } + end + + # Drops every resolved target, so that the next read fetches it again. + # + # Called by the record, which keeps one proxy for as long as it lives + # and empties it on a save, a reload, a destroy and a write to a foreign + # key. It used to drop the proxy and build another on the next call to + # {Resources::Base#related}, which reached only the callers that asked + # again: `related = ticket.related`, the natural thing to write before + # reading two associations, kept the proxy that had been dropped, and + # after `ticket.customer_id = 9` or a reload `related.customer` went on + # answering with the user it had resolved before. A memo can only be + # emptied where it is held, so it is emptied here. + # + # Replaced rather than cleared, so that a lookup still on the wire has + # nowhere to put what it resolved from the value before: see + # {#belongs_to_target}. + def forget_targets + @cache = {} + end + + # Refuses to read through a record that was destroyed. + # + # {Resources::Base#related} asks the same question, but a proxy handed + # out before the destroy is already past that door: it answered from + # its memo, and `articles` requested the articles of a ticket that is + # gone. + def refuse_destroyed!(name) + return if !@record.destroyed? + + raise Error, "#{@record.class.name} #{@record.id} was destroyed, there is nothing to read #{name} from" + end + + # The target is named rather than referenced so that resources may point + # at each other without a load order between their files. The name comes + # from a declaration in code - this gem's, or a resource class a caller + # wrote - and never from data. + # + # A resource of this gem is named on its own, +'User'+, and wins: an + # application is likely to have a +User+ of its own at the top level, + # and that is not what a ticket's customer is. Any other name is read + # from the top level, so that a resource a caller declares can point at + # another of theirs: +belongs_to :role, class_name: 'Acme::Role'+. + def resolve(class_name) + return Resources.const_get(class_name, false) if Resources.const_defined?(class_name, false) + + Object.const_get(class_name) + end + end + end +end diff --git a/lib/zammad_api/attribute_access.rb b/lib/zammad_api/attribute_access.rb new file mode 100644 index 0000000..22e82d7 --- /dev/null +++ b/lib/zammad_api/attribute_access.rb @@ -0,0 +1,311 @@ +# frozen_string_literal: true + +require 'json' + +require_relative 'deep_copy' + +module ZammadAPI + # Read access to a Zammad record's attributes. + # + # Zammad objects can carry administrator-defined custom attributes, so the + # set of readable attributes is not known ahead of time and is resolved + # through +method_missing+. A reader for an attribute the record does not + # carry raises +NoMethodError+; {#[]}, {#fetch} with a default, and {#key?} + # are the readers for an attribute that may be absent. + # + # This also carries the object protocols a record is expected to answer: + # {#==} and {#hash} identify a record by its id and the Zammad it came + # from, {#deconstruct_keys} makes + # one matchable with +case/in+, and {#to_json} serializes its attributes. + module AttributeAccess + # Suffixes that mark a method call as a predicate or bang method rather + # than an attribute, so that typos like +save!+ still raise NoMethodError. + NON_ATTRIBUTE_SUFFIXES = %w[! ?].freeze + + # What a writer for an attribute is named: a plain identifier and an `=`. + # + # Ending in `=` is not enough, because Ruby's operators do too. `record[:x] + # = 1` reaches `method_missing` as `:[]=` and used to stage an attribute + # literally called `[]` whose value was the index - the write was lost, no + # error was raised, and the next `save` sent `{"[]": "x"}` to Zammad. + # `record <= 5` did the same for an attribute called `<`. + ATTRIBUTE_WRITER = /\A[a-zA-Z_]\w*=\z/ + private_constant :ATTRIBUTE_WRITER + + # All known attributes, deeply frozen. + # + # Writing through this hash would change what the record reports without + # staging a change, so the next +save+ would not send it. {#to_h} returns a + # copy that is safe to modify; an attribute writer is the way to stage one. + # + # @return [Hash{Symbol => Object}] + attr_reader :attributes + + # @param key [Symbol, String] + # @return [Object, nil] + def [](key) = attributes[key.to_sym] + + # Stages an attribute by name, the writer matching {#[]}. + # + # Defined rather than left to `method_missing`, which saw `:[]=` as a + # writer for an attribute called `[]` and staged the index as its value. + # A read-only record refuses this the way it refuses any other write, and + # {#respond_to?} says so before it is called. + # + # @param key [Symbol, String] + # @param value [Object] + # @return [Object] the staged value + # @raise [Error] when the attribute cannot be staged, such as +id+, or + # when the record was destroyed + # @raise [NoMethodError] when the record is read-only + def []=(key, value) + write_attribute(key.to_sym, value) + end + + # @param key [Symbol, String] + # @param default [Object] returned instead of raising + # @yieldparam key [Symbol] called instead of raising + # @return [Object] + # @raise [ArgumentError] when more than one fallback was given + # @raise [KeyError] when the attribute is absent and no fallback was given + def fetch(key, *default) + # Hash#fetch refuses a third argument, and so does this: collecting the + # fallback with a splat and reading `default.first` accepted + # `fetch(:a, :b, :c)` - a multi-key read that this has never been - and + # answered it with `:b`. A method whose whole point is that a missing + # attribute is an error has no business swallowing a mistyped call. + raise ArgumentError, "wrong number of arguments (given #{default.size + 1}, expected 1..2)" if default.size > 1 + + # Hash#fetch warns for this and then ignores the default, so this does + # too rather than silently picking one of the two fallbacks a caller + # cannot have meant to pass together. + # + # `uplevel` so that this reads like the warning it mirrors: Hash#fetch + # names the line that made the call, and a bare Kernel#warn named + # nothing at all - neither the call site nor the library it came from, + # which in an application with several such calls is everything the + # reader needs. Kernel#warn writes the `warning: ` prefix itself when + # given `uplevel`, so the message must not carry its own. + # + # Nothing here has to consult $VERBOSE. Kernel#warn is already silent + # when warnings are off, so `ruby -W0` and `$VERBOSE = nil` quiet this + # the same way they quiet Hash#fetch's own warning. + warn('block supersedes default value argument', uplevel: 1) if block_given? && !default.empty? + + symbol = key.to_sym + # An explicit &block argument cannot be resolved against Hash#fetch's + # overloads by the type checker, so the block is forwarded with yield. + # rubocop:disable-next Style/ExplicitBlockArgument + return attributes.fetch(symbol) { |missing| yield(missing) } if block_given? + return attributes.fetch(symbol, default.first) if !default.empty? + + attributes.fetch(symbol) + end + + # @return [Boolean] + def key?(key) = attributes.key?(key.to_sym) + + # @return [Hash{Symbol => Object}] a deep copy of all attributes, safe to + # modify + def to_h = deep_dup(attributes) + + # @return [Integer, nil] + def id = attributes[:id] + + # Enables Ruby pattern matching against a record's attributes. + # + # @example + # case client.tickets.find(1) + # in {state: 'closed'} + # nil + # in {state: String => state, priority: '3 high'} + # escalate(state) + # end + # + # @param keys [Array, nil] the keys the pattern asks for + # @return [Hash{Symbol => Object}] + def deconstruct_keys(keys) = keys.nil? ? attributes : attributes.slice(*keys) + + # Whether +other+ is the same Zammad record: the same class, carrying the + # same id, read from the same Zammad. + # + # The last of those is the URL the client was configured with. An id is + # only unique within one installation, and a script that reads two of + # them - a migration, a sync - holds ticket 1 of each: compared by class + # and id alone they were one record, so `uniq` dropped one of the two and + # a Hash keyed by record handed back the other instance's value. Two + # clients for one URL, or one client and its {Client#on_behalf_of} scope, + # still read the same record. + # + # A record with no id is equal only to itself, because two unsaved records + # are two records waiting to be created however alike their attributes + # are. That also means the first save of a record changes its {#hash}, so + # one used as a Hash key before being saved has to be rehashed after. + # + # @example + # client.tickets.find(1) == client.tickets.find(1) # => true + # [client.tickets.find(1), client.tickets.find(1)].uniq.size # => 1 + # + # @param other [Object] + # @return [Boolean] + def ==(other) + return true if equal?(other) + return false if !other.instance_of?(self.class) + + # The steep:ignore is for `installation`, which is protected: RBS has + # no word for that, so the signature declares it private. + !id.nil? && other.id == id && other.installation == installation # steep:ignore NoMethod + end + alias eql? == + + # Consistent with {#==}, so that records can be deduplicated with +uniq+, + # collected in a +Set+ and used as Hash keys. + # + # The class is part of the digest because an id is only unique within one + # kind of record: ticket 1 and user 1 are different records. The + # installation is part of it for the same reason one level up. + # + # @return [Integer] + def hash + id.nil? ? super : [self.class, installation, id].hash + end + + # The attributes, for a JSON encoder. + # + # Named the way ActiveSupport and its encoders expect, so that a record + # nested inside a structure being serialized renders as its attributes. + # + # @return [Hash{Symbol => Object}] + def as_json(*) = to_h + + # Without this, a record would serialize as its +to_s+, because that is + # what +Object#to_json+ falls back to. + # + # @example + # client.groups.find(1).to_json # => "{\"id\":1,\"name\":\"Support\"}" + # + # @param state [JSON::State, nil] passed by +JSON.generate+ when a record + # is nested in a structure it is serializing + # @return [String] the attributes as a JSON object + def to_json(state = nil) = to_h.to_json(state) + + def method_missing(name, *args) + identifier = name.to_s + return super if NON_ATTRIBUTE_SUFFIXES.any? { identifier.end_with?(it) } + return write_attribute(identifier.delete_suffix('=').to_sym, args.first) if ATTRIBUTE_WRITER.match?(identifier) + return attributes[name] if attributes.key?(name) + + # An attribute the record does not carry used to read as nil, which made + # `ticket.titel` a silent nil that flowed on into whatever was written + # with it - and left this module the one place in the gem that answers a + # question it cannot answer instead of saying so. It also put + # `respond_to?` and the call itself at odds: `respond_to?(:titel)` was + # false and `method(:titel)` raised NameError while `ticket.titel` + # worked, so generic code that asks before it calls - a serializer, a + # delegator, `try` - was told the reader did not exist. + # + # Built rather than left to `super`, so that the message can name what + # to reach for instead, while `name` and `receiver` stay what a bare + # NoMethodError would have carried. + # + # The steep:ignore is for `name`: NameError.new takes a Symbol there and + # NoMethodError#name answers with one, while the core signature + # describes the parameter as a String. + raise NoMethodError.new(unknown_attribute_message(name), name, args, receiver: self) # steep:ignore ArgumentTypeMismatch + end + + # `[]=` is a defined method, so `respond_to_missing?` never sees it and a + # read-only record answered true for the one writer it has while answering + # false for every named one - then raised NoMethodError when it was called. + # That is the invariant the writer branch below is conditional for: generic + # code asks before it writes, and a record that claims a writer it would + # refuse leads it straight into the exception it was checking to avoid. + # + # Compared as a String, because `respond_to?` takes either spelling and + # Ruby does not normalise the argument before it reaches here. Compared to + # the Symbol alone, `respond_to?('[]=')` fell through to the definition + # and answered true on a record that refuses every write - the same wrong + # answer this method exists to prevent, reached by the other spelling. + # rubocop:disable-next Style/OptionalBooleanParameter -- Ruby's own signature + def respond_to?(name, include_private = false) + return writable_attributes? if name.to_s == '[]=' + + super + end + + def respond_to_missing?(name, include_private = false) + identifier = name.to_s + return false if NON_ATTRIBUTE_SUFFIXES.any? { identifier.end_with?(it) } + # Not an unconditional true: a read-only record that claimed a writer and + # then raised NoMethodError when one was called would defeat the point of + # asking, and lead generic code - serializers, form binders, + # assign_attributes loops - straight into the exception it was checking + # to avoid. + return writable_attributes? && attribute_writable?(identifier.delete_suffix('=').to_sym) if ATTRIBUTE_WRITER.match?(identifier) + + attributes.key?(name) || super + end + + protected + + # Which Zammad this record was read from, for {#==} and {#hash}. + # + # Overridden by the records that hold a transport, with the URL it is + # configured for. That is the URL as it was written, not the host it + # resolves to, so two spellings of one instance count as two: nothing + # here can know better, and telling one installation apart from itself + # only costs a duplicate, where taking two for one loses a record. + # + # Protected, because it is asked of the other record and of nobody else. + # + # @return [String, nil] nil for a record that has no transport + def installation = nil + + private + + # Why an attribute is missing is worth saying, because the two reasons + # lead somewhere quite different: a name that is simply wrong, and a + # record Zammad served less of than it holds. The second is the same fact + # {Resources::Base#no_id_message} and {Resources::Base#write_attribute} + # are written around - Zammad reduces the object it serializes for a + # client whose user may not see the whole record - and it is not + # something the spelling of the call can show. + def unknown_attribute_message(name) + # Sorted by the name rather than by the key, because a key that could + # not become a Symbol is left as it arrived - {DeepCopy.symbolize} says + # so - and `[:name, 1].sort` raises, which would replace this message + # with an ArgumentError from inside the method that explains it. + carried = attributes.keys.sort_by(&:to_s).join(', ') + + "undefined attribute #{name} for #{self.class.name}. This record carries " \ + "#{attributes.empty? ? 'no attributes at all' : carried}. " \ + "Check the spelling, or read it with [#{name.inspect}] or fetch(#{name.inspect}, nil) where it may be absent. " \ + 'Zammad also serves a reduced object where the authenticated user may not see the whole record, so an ' \ + 'attribute the record has in Zammad can still be missing here - check what this client may read.' + end + + # Whether this record stages attribute writes, so that {#respond_to?} and + # calling a writer agree. + def writable_attributes? = false + + # Whether one particular attribute may be written. Overridden by records + # that refuse one: a record that claimed `id=` and then raised when it was + # called would defeat the point of asking, which is the whole reason the + # writer branch above is not an unconditional true. + def attribute_writable?(_key) = true + + # Overridden by writable records; read-only ones fall back to NoMethodError. + def write_attribute(key, _value) + raise NoMethodError, "#{self.class.name} attributes are read-only (tried to set #{key})" + end + + # Recursively converts string keys to symbols, including inside arrays, so + # that user supplied attributes behave the same as decoded responses, and + # freezes the result. See {DeepCopy} for why the walk lives there. + def frozen_attributes(value) = DeepCopy.frozen_copy(value, symbolize_keys: true) + + # The inverse of {#frozen_attributes}, for handing out a copy that callers + # may treat as their own. + def deep_dup(value) = DeepCopy.writable_copy(value) + end +end diff --git a/lib/zammad_api/client.rb b/lib/zammad_api/client.rb index b1d6c85..c3059c6 100644 --- a/lib/zammad_api/client.rb +++ b/lib/zammad_api/client.rb @@ -1,65 +1,512 @@ -require 'forwardable' +# frozen_string_literal: true -require 'zammad_api/log' -require 'zammad_api/transport' -require 'zammad_api/dispatcher' -require 'zammad_api/resources' +require_relative 'config' +require_relative 'errors' +require_relative 'resource_proxy' +require_relative 'resources' +require_relative 'transport' module ZammadAPI + # The entry point of this gem. + # + # @example Token authentication + # client = ZammadAPI::Client.new( + # url: 'https://zammad.example.com/', + # http_token: 'your-access-token' + # ) + # client.tickets.find(1).title + # + # @example Basic authentication with a custom timeout and logger + # client = ZammadAPI::Client.new( + # url: 'https://zammad.example.com/', + # user: 'user@example.com', + # password: 'secret', + # timeout: 10, + # logger: Logger.new($stdout) + # ) class Client - extend Forwardable + # Maps the reader methods of this client to their resource classes. + # + # Plural, because what a reader hands back stands for every record of + # its kind: a {ResourceProxy} is +Enumerable+ over all of them, so + # +client.tickets.each+ and +client.tickets.first(5)+ say what they do, + # where the singular the readers had in 1.x read as if it acted on one + # ticket. That name dates from when a proxy was only a dispatcher for + # +find+ and +create+. + RESOURCES = { + groups: Resources::Group, + organizations: Resources::Organization, + tickets: Resources::Ticket, + ticket_articles: Resources::TicketArticle, + ticket_priorities: Resources::TicketPriority, + ticket_states: Resources::TicketState, + users: Resources::User + }.freeze - def_delegators :@transport, :on_behalf_of, :on_behalf_of= + # The names the readers had in 1.x, mapped to the ones they have now. + # Each still works, as a deprecated alias - see {#resource}. + DEPRECATED_RESOURCES = { + group: :groups, + organization: :organizations, + ticket: :tickets, + ticket_article: :ticket_articles, + ticket_priority: :ticket_priorities, + ticket_state: :ticket_states, + user: :users + }.freeze - def initialize(config) - @config = config - @logger = ZammadAPI::Log.new(@config) - @transport = ZammadAPI::Transport.new(@config, @logger) - check_config + # Methods Ruby calls implicitly for type coercion. They must keep raising + # NoMethodError so that this object behaves normally in core operations. + CONVERSION_METHODS = %i[to_ary to_a to_hash to_str to_io to_proc coerce].freeze + + # @return [Config] the validated configuration, with credentials redacted + # from its +inspect+ output + attr_reader :config + + # @!method groups + # @return [ResourceProxy] proxy for {Resources::Group} + # @!method organizations + # @return [ResourceProxy] proxy for {Resources::Organization} + # @!method tickets + # @return [ResourceProxy] proxy for {Resources::Ticket} + # @!method ticket_articles + # @return [ResourceProxy] proxy for {Resources::TicketArticle} + # @!method ticket_priorities + # @return [ResourceProxy] proxy for {Resources::TicketPriority} + # @!method ticket_states + # @return [ResourceProxy] proxy for {Resources::TicketState} + # @!method users + # @return [ResourceProxy] proxy for {Resources::User} + RESOURCES.each do |name, resource_class| + define_method(name) { @resources.fetch(resource_class) } end - def perform_on_behalf_of(identifier) - self.on_behalf_of = identifier - yield.tap do |_| - self.on_behalf_of = nil + # @!method group + # @deprecated Use {#groups}. + # @return [ResourceProxy] + # @!method organization + # @deprecated Use {#organizations}. + # @return [ResourceProxy] + # @!method ticket + # @deprecated Use {#tickets}. + # @return [ResourceProxy] + # @!method ticket_article + # @deprecated Use {#ticket_articles}. + # @return [ResourceProxy] + # @!method ticket_priority + # @deprecated Use {#ticket_priorities}. + # @return [ResourceProxy] + # @!method ticket_state + # @deprecated Use {#ticket_states}. + # @return [ResourceProxy] + # @!method user + # @deprecated Use {#users}. + # @return [ResourceProxy] + DEPRECATED_RESOURCES.each do |old_name, name| + define_method(old_name) do + Client.warn_deprecated_resource(old_name, name) + @resources.fetch(RESOURCES.fetch(name)) end end - def method_missing(method, *_args) - method = modulize(method.to_s) - class_name = "ZammadAPI::Resources::#{method}" - begin - class_object = Kernel.const_get(class_name) - rescue - raise ResourceNotFoundError, "Resource for #{method} does not exist" + # Says that a reader was called by the name it had in 1.x. + # + # In Ruby's own +deprecated+ category, so it is silent unless the + # application asks for deprecation warnings - +ruby -W:deprecated+, or + # +Warning[:deprecated] = true+, which is what a test suite turns on - + # and a script that has not been migrated yet does not print a line per + # request in production. +uplevel+ names the line that made the call, + # past the two frames of this class in between. + # + # @api private + # @param old_name [Symbol] + # @param name [Symbol] + # @return [void] + def self.warn_deprecated_resource(old_name, name) + warn("ZammadAPI::Client##{old_name} is deprecated and will be removed in 3.0: use ##{name} instead", uplevel: 2, category: :deprecated) + end + + # Environment variables {.from_env} reads, mapped to the options they set. + ENV_OPTIONS = { + 'ZAMMAD_URL' => :url, + 'ZAMMAD_TOKEN' => :http_token, + 'ZAMMAD_HTTP_TOKEN' => :http_token, + 'ZAMMAD_OAUTH2_TOKEN' => :oauth2_token, + 'ZAMMAD_USER' => :user, + 'ZAMMAD_PASSWORD' => :password + }.freeze + + # Builds a client from the environment. + # + # Reads {ENV_OPTIONS}, so a script needs no configuration of its own. + # Anything passed in wins over the environment, and every other option + # keeps its default. That includes the way to authenticate: passing + # +user:+ and +password:+, or a token, replaces whichever credentials the + # environment holds rather than sitting beside them. An empty variable + # counts as unset, and +ZAMMAD_HTTP_TOKEN+ wins over +ZAMMAD_TOKEN+ if + # both are set. An environment that sets more than one way to + # authenticate - a token and a user with a password - is refused like + # any other configuration that does, unless an argument names the one to + # use. + # + # @example + # ZAMMAD_URL=https://zammad.example.com/ ZAMMAD_TOKEN=secret ruby report.rb + # + # client = ZammadAPI::Client.from_env + # client = ZammadAPI::Client.from_env(timeout: 300) # for one bulk job + # + # @param overrides [Hash] any option accepted by {Config} + # @return [Client] + # @raise [ConfigurationError] when neither the environment nor +overrides+ + # supply a URL and credentials + def self.from_env(**overrides) + from_environment = ENV_OPTIONS.filter_map do |name, option| + value = ENV.fetch(name, nil) + [option, value] if !value.to_s.empty? end - ZammadAPI::Dispatcher.new(@transport, class_object) + options = Config.merge_options(from_environment.to_h, overrides) + + raise ConfigurationError, "missing url: set ZAMMAD_URL or pass url: to #{name}.from_env" if options[:url].to_s.empty? + + new(**options) end - private + # Builds a client from a {Config} that is already validated and a + # transport that is already built. + # + # The public constructor turns options into a Config and a Config into a + # Transport, and building a Transport means building a Faraday stack: + # authentication, JSON, the retry middleware, adapter resolution. Anything + # holding a transport of its own - {Test} - threw all of that away one + # line later, and paid for it again for every stand-in a suite builds. + # This is the way in for those, and the reason there is no public + # `with_transport` to swap one in after the fact. + # + # @api private + # @param config [Config] an already validated configuration + # @param transport [Transport] anything with a {Transport} interface + # @return [Client] + def self.build(config, transport) + allocate.send(:setup, config, transport) + end + + # @param options [Hash] see {Config} for every supported option + # @option options [String] :url base URL of the Zammad instance + # @option options [String] :http_token access token + # @option options [String] :oauth2_token OAuth2 token + # @option options [String] :user login for basic authentication + # @option options [String] :password password for basic authentication + # @raise [ConfigurationError] when the options are incomplete or invalid, + # or name more than one way to authenticate + def initialize(**options) + config = Config.new(**options) + setup(config, Transport.new(config)) + end - def check_config - raise ConfigurationError, 'missing url in config' if !@config[:url] - raise ConfigurationError, 'config url needs to start with http:// or https://' if !%r{^(http|https)://}.match?(@config[:url]) + # The proxy for a resource, by name or by class. + # + # A name from 1.x - +:ticket+ for +:tickets+ - is still answered, with + # a deprecation warning. + # + # A class is the way to the parts of the API this gem does not model. + # {Resources::Base} is built to be subclassed - a path, and whatever the + # endpoint needs said about it - and a proxy for such a class gives its + # records everything the modelled ones have: pagination, +find_by+, + # change tracking, +save+. 1.x reached any subclass through +const_get+ + # on a name a caller supplied, and 2.0 closed that, which left raw + # requests as the only way to the rest of the API; this is the same + # reach, with the class handed over rather than looked up. + # + # @example A resource this gem does not model + # class Role < ZammadAPI::Resources::Base + # path 'api/v1/roles' + # end + # + # client.resource(Role).each { |role| puts role.name } + # client.resource(Role).find(2).update(note: 'Reviewed') + # + # @param name [Symbol, String, Class] a key of {RESOURCES}, or a subclass + # of {Resources::Base} + # @return [ResourceProxy] + # @raise [UnknownResourceError] when no resource has that name + # @raise [ArgumentError] for a class that is not a resource + # @raise [Error] for a resource class that declares no path + def resource(name) + return proxy_for(name) if name.is_a?(Class) - # check for token auth - return if @config[:http_token] && !@config[:http_token].empty? - return if @config[:oauth2_token] && !@config[:oauth2_token].empty? + key = name.to_sym - if !@config[:user] || @config[:user].empty? - raise ConfigurationError, 'missing user in config' + if !RESOURCES.key?(key) + current = DEPRECATED_RESOURCES.fetch(key) { raise UnknownResourceError, unknown_resource_message(name) } + Client.warn_deprecated_resource(key, current) + key = current end - return if @config[:password] && !@config[:password].empty? + @resources.fetch(RESOURCES.fetch(key)) + end + + # @return [Array] every resource name this client supports + def resource_names = RESOURCES.keys + + # The user these requests authenticate as, or the one {#on_behalf_of} + # scoped them to. + # + # @example Checking which account a token belongs to + # client.me.email # => "agent@example.com" + # + # @return [Resources::User] + # @raise [AuthenticationError] when the credentials are not valid + def me + response = @transport.get( + # Derived from the resource that declares the endpoint, not spelled + # out again: `member_path` exists for the same reason, and a path kept + # in two places is one that moves in one of them. Spelled out here, + # `client.users` would follow the users endpoint wherever it went and + # `client.me` would keep requesting the old one. + "#{Resources::User.resource_path}/me", + operation: 'find current user', + resource_class: Resources::User, + query: { expand: true } + ) + Resources::User.from_response( + @transport, + response.decoded(:object, operation: 'find current user', resource_class: Resources::User) + ) + end + + # The version of the Zammad instance, not of this gem — that is + # {ZammadAPI::VERSION}. + # + # Zammad serves it to administrators only: its VersionControllerPolicy + # permits +admin+ and nothing else. An agent's or a customer's + # credentials are answered with a 403, so to check that a client can + # reach Zammad at all, ask {#me}, which every account may. + # + # @example + # client.version # => "6.4.0" + # + # @return [String, nil] nil when the instance reported no version + # @raise [AuthorizationError] when the account is not an administrator + def version + response = @transport.get('api/v1/version', operation: 'get the Zammad version') + version = response.decoded(:object, operation: 'get the Zammad version')[:version] + version&.to_s + end + + # @!group Raw requests + + # Performs a +GET+ against any endpoint of the Zammad API. + # + # The resource classes cover a part of the API; these four methods reach + # the rest of it without giving up authentication, retries, credential + # redaction, JSON decoding or the error classes. + # + # +headers:+ is here because an escape hatch that cannot set one does not + # reach an endpoint that needs one. What it will not set is the two + # headers this client owns - see the +headers+ parameter below. + # + # @example An endpoint this gem does not model + # client.get('api/v1/roles').body + # # => [{id: 1, name: "Admin", ...}, ...] + # + # @example Reading a response header + # client.get('api/v1/tickets').headers['content-type'] + # + # @example An endpoint that needs a header of its own + # client.get('api/v1/tickets/1', headers: {'Accept-Language' => 'de-de'}) + # + # @param path [String] path relative to {Config#url}; a leading slash is + # ignored, so paths can be pasted from the Zammad documentation. An + # absolute URL is refused, so the client's credentials only ever go to + # the instance it was configured for. It is written the way a URL is: + # a space or a character outside ASCII has to be percent-encoded. + # @param query [Hash, nil] query string parameters + # @param headers [Hash, nil] request headers. Names are case-insensitive, + # and +Authorization+ and +From+ are refused: the first is what the + # client's credentials are for, the second is what {#on_behalf_of} sets. + # @return [Response] + # @raise [ResponseError] for any non-2xx response + # @raise [TransportError] when the request could not be completed + # @raise [ArgumentError] for a header this client sets itself, a value + # that is not text, a path that is an absolute URL, or one that cannot + # be read as a URL + def get(path, query: nil, headers: nil) = raw(:get, path, query: query, headers: headers) + + # Performs a +POST+ against any endpoint of the Zammad API. + # + # @example + # client.post('api/v1/tags/add', query: {object: 'Ticket', o_id: 1, item: 'urgent'}) + # + # @param path [String] path relative to {Config#url} + # @param query [Hash, nil] query string parameters + # @param body [Hash, Array, nil] request payload, encoded as JSON + # @param headers [Hash, nil] request headers + # @return [Response] + # @raise [ResponseError] for any non-2xx response + # @see #get + def post(path, query: nil, body: nil, headers: nil) = raw(:post, path, query: query, body: body, headers: headers) + + # Performs a +PUT+ against any endpoint of the Zammad API. + # + # @param path [String] path relative to {Config#url} + # @param query [Hash, nil] query string parameters + # @param body [Hash, Array, nil] request payload, encoded as JSON + # @param headers [Hash, nil] request headers + # @return [Response] + # @raise [ResponseError] for any non-2xx response + # @see #get + def put(path, query: nil, body: nil, headers: nil) = raw(:put, path, query: query, body: body, headers: headers) + + # Performs a +DELETE+ against any endpoint of the Zammad API. + # + # @param path [String] path relative to {Config#url} + # @param query [Hash, nil] query string parameters + # @param headers [Hash, nil] request headers + # @return [Response] + # @raise [ResponseError] for any non-2xx response + # @see #get + def delete(path, query: nil, headers: nil) = raw(:delete, path, query: query, headers: headers) + + # @!endgroup - raise ConfigurationError, 'missing password in config' + # Returns a new client with some configuration options changed. + # + # The options are re-validated, and any {#on_behalf_of} scope is carried + # over. The original client keeps its own connection and settings. + # + # Naming credentials replaces the ones this client has, whichever kind + # they were: +with(oauth2_token: 'x')+ on a client built with an access + # token authenticates with the OAuth2 token alone. + # + # The transport derives from the current one rather than being built from + # scratch, so a client wired to a stand-in stays wired to it. + # + # @example A longer timeout for one bulk job + # bulk = client.with(timeout: 300, retries: 5) + # bulk.tickets.all.each { |ticket| archive(ticket) } + # + # @param options [Hash] any option accepted by {Config} + # @return [Client] + # @raise [ConfigurationError] when the resulting options are invalid + def with(**options) + derived_config = config.with(**options) + dup.send(:setup, derived_config, @transport.with_config(derived_config)) end - def modulize(string) - string.gsub(/__(.?)/) { "::#{$1.upcase}" } - .gsub(%r{/(.?)}) { "::#{$1.upcase}" } - .gsub(/(?:_+|-+)([a-z])/) { $1.upcase } - .gsub(/(\A|\s)([a-z])/) { $1 + $2.upcase } + # Performs requests on behalf of another user. + # + # Returns a new client rather than mutating this one, so the original + # client is unaffected and both can be used concurrently. + # + # @example Scoped client + # support = client.on_behalf_of('agent@example.com') + # support.tickets.create(title: 'Help', group: 'Users', customer_id: 1) + # + # @example Block form + # client.on_behalf_of('agent@example.com') do |scoped| + # scoped.tickets.find(1) + # end + # + # An identifier that names nobody is refused. Zammad skips a +From+ + # header with nothing in it, and a nil sent none at all, so + # +client.on_behalf_of(current_user&.login)+ with nobody signed in + # handed back a client that looked scoped and was not: every request + # ran with the rights of the account the client authenticates as, and + # a list read through it held everything that account can see. No + # request failed, so nothing said the scope was missing. + # + # @param identifier [String, Integer] login, email address or user id + # @yieldparam scoped [Client] + # @return [Client] when no block is given, otherwise the block's value + # @raise [ArgumentError] for an identifier that is nil, empty or blank + def on_behalf_of(identifier) + # Nil is what a transport takes for no scope, so it is refused here. + # The rest is refused by the rule every transport is meant to apply, + # applied here as well: Client.build takes anything with a transport's + # interface, and one that stored what it was given would send an empty + # From header for `on_behalf_of('')`. + raise ArgumentError, Transport.blank_on_behalf_of_message(identifier) if identifier.nil? + + scoped = dup.send(:setup, config, @transport.with_on_behalf_of(Transport.stringify_on_behalf_of(identifier))) + return scoped if !block_given? + + yield scoped + end + + # The scope is shown where there is one, so that a client acting for + # another user does not print as the one it was derived from. + def inspect + scope = @transport.on_behalf_of + + "#<#{self.class.name} url=#{config.redacted_url.inspect} auth=#{config.authentication_scheme}#{" on_behalf_of=#{scope.inspect}" if scope}>" + end + + def method_missing(name, *args) + return super if CONVERSION_METHODS.include?(name) || name.to_s.end_with?('=', '!', '?') + + raise UnknownResourceError, unknown_resource_message(name) + end + + def respond_to_missing?(_name, _include_private = false) = false + + private + + def raw(method, path, query: nil, body: nil, headers: nil) + relative = Transport.relative_path(path) + + @transport.request( + method, + relative, + # Named by the path as it may be printed. The operation is in the + # message of every error the request raises, and a query string + # written into the path may carry a token. + operation: "#{method.to_s.upcase} #{Transport.redact_path(relative)}", + query: query, + body: body, + headers: headers + ) + end + + def unknown_resource_message(name) = "Unknown resource #{name}, available resources are: #{RESOURCES.keys.join(', ')}" + + # One of the proxies built with this client for a class it models, and a + # new one for any other resource class. A new one each time, rather than + # a memo: the client is frozen in everything but name once it is built - + # see {#setup} - and a proxy holds nothing but the transport and the + # class. + def proxy_for(resource_class) + raise ArgumentError, "resource takes the name of a resource or a subclass of #{Resources::Base.name}, and #{resource_class.inspect} is neither" if !(resource_class <= Resources::Base) + + @resources.fetch(resource_class) do + # Asked for now, so that a class without a path is reported by the + # call that named it rather than by its first request. + resource_class.resource_path + ResourceProxy.new(@transport, resource_class) + end + end + + # Everything a client is, in the one place all four ways of making one go + # through: {.new}, {.build}, {#with} and {#on_behalf_of}. Held apart, + # `build` restated `initialize`'s list of instance variables by hand, and + # the fourth one added to `initialize` would have left every client built + # for a test unset where it mattered. + # + # The proxies are built here rather than memoized on first use, because a + # client is documented - and used, in examples/concurrent_sync.rb - as + # immutable once built and safe to share between threads without locking. + # A memo populated by the first `client.tickets` in each worker is a write + # to shared state, and while CRuby's GVL makes it harmless, a contract + # that only holds on one implementation is not the contract that was + # written down. Building all seven up front costs an allocation each and + # keeps the object finished the moment it is handed back. + # + # @return [self] + def setup(config, transport) + @config = config + @transport = transport + @resources = RESOURCES.values.to_h { [it, ResourceProxy.new(transport, it)] }.freeze + + self end end end diff --git a/lib/zammad_api/collection.rb b/lib/zammad_api/collection.rb new file mode 100644 index 0000000..262b531 --- /dev/null +++ b/lib/zammad_api/collection.rb @@ -0,0 +1,813 @@ +# frozen_string_literal: true + +require_relative 'errors' + +module ZammadAPI + # A lazily fetched, automatically paginated list of records. + # + # Nothing is requested until the collection is iterated. {#order} and + # {#page} return new collections, so a collection can be built up in + # steps and shared without being disturbed. + # + # {#each} walks every page until the server runs out of records, so it is + # safe to iterate a collection larger than one page. {#first} reads one page + # sized for what it was asked for, and +lazy+, +detect+ and the rest of + # +Enumerable+ stop the walk as soon as they have enough, so neither has to + # download everything. + # + # @example Iterate every ticket + # client.tickets.all.each { |ticket| puts ticket.title } + # + # @example Narrow to matches, then stop after the first five + # client.tickets.search('state.name:open').first(5) + # + # @example Sorted by the server + # client.groups.order(:name).each { |group| puts group.name } + # + # @example Work in batches, e.g. for an import + # client.tickets.all.in_batches(of: 50) { |tickets| import(tickets) } + # + # @example One explicit page + # client.tickets.all.page(2, per_page: 50).to_a + class Collection + include Enumerable + + # The two directions a sort can run in, as Zammad spells them. + SORT_DIRECTIONS = %w[asc desc].freeze + private_constant :SORT_DIRECTIONS + + # What an attribute to sort by is named. Zammad takes several of them as + # one comma-separated parameter, so a name carrying a comma or a space + # would be read as something other than the one attribute it was. + SORT_ATTRIBUTE = /\A\w+\z/ + private_constant :SORT_ATTRIBUTE + + # @api private + # @param per_page [Integer, nil] records fetched per request, or nil for + # as many as the endpoint serves + # @param search [Boolean] whether this is a search endpoint, which + # differs from an index in two ways a collection has to know about: it + # reports the size of the whole result, alone for +only_total_count+ + # and beside a page for +with_total_count+, and it can serve a page + # short of its size, or with nothing on it, before the last one + # @param sortable [Boolean] whether this endpoint reads +sort_by+ and + # +order_by+ + # @param unsortable_hint [String] what to do instead where it does not + # @param widens [Boolean] whether a walk may ask for a larger page than + # +per_page+ once one has come back with nothing on it, which a read + # sized by {#first} may and a batch size a caller chose may not: see + # {#widened} + def initialize(transport:, resource_class:, path:, operation:, max_per_page:, sortable:, unsortable_hint:, query: {}, per_page: nil, page: nil, search: false, widens: false) + @transport = transport + @resource_class = resource_class + @path = path + @operation = operation + @query = query + @max_per_page = max_per_page + @sortable = sortable + @unsortable_hint = unsortable_hint + # As many as the endpoint serves, unless a call asks for another size. + # + # A fixed default of 100 was the earlier answer, and it cost a request + # for every 100 records where the endpoint would have served 1000: a + # walk of the user index spent ten times the round trips it needed, and + # each of those is a TLS handshake of its own under Faraday's default + # adapter. The endpoint's own cap is the one number that is right for + # every resource without a caller looking each of them up - it is + # already what {#clamp_per_page} measures against. + # + # What that costs is a larger page held at once - a thousand expanded + # users rather than a hundred. {#first} is what made that affordable: + # the cheap-looking call that only wants a record or two now sizes its + # own page instead of taking them off the front of this one. + @per_page = clamp_per_page(per_page || max_per_page) + @page = page + @search = search + @widens = widens + end + + # Yields every record, fetching further pages as needed. + # + # @yieldparam record [Resources::Base] + # @return [Enumerator] when no block is given + def each(&block) + return to_enum(:each) if !block + + in_batches { |records| records.each(&block) } + self + end + + # Yields every record, like {#each}, with the page size set inline. + # + # @param batch_size [Integer, nil] records fetched per request + # @yieldparam record [Resources::Base] + # @return [Enumerator] when no block is given + def find_each(batch_size: nil, &block) + return to_enum(:find_each, batch_size: batch_size) if !block + return with(per_page: page_size!(batch_size, 'batch_size')).find_each(&block) if batch_size + + each(&block) + end + + # Yields one array of records per page. + # + # A batch is one response: what a request returned is what the block gets, + # so +of+ is what sizes it. For groups of a size the API knows nothing + # about, slice the records instead: +find_each.each_slice(12)+. + # + # @param of [Integer, nil] records fetched per request + # @yieldparam records [Array] + # @return [Enumerator] when no block is given + def in_batches(of: nil, &block) + return to_enum(:in_batches, of: of) if !block + return with(per_page: page_size!(of, 'of')).in_batches(&block) if of + + walk(&block) + self + end + + # Returns a new collection limited to a single page. + # + # +per_page+ decides how big that page is, and so which records it holds: + # +page(2, per_page: 50)+ is records 51 to 100. A size larger than the endpoint + # serves is refused rather than reduced, because reducing it moves the + # page: +page(3, per_page: 500)+ against an endpoint capping at 100 was sent as + # +page=3&per_page=100+ and answered with records 201 to 300 instead of + # 1001 to 1500. A job that checkpoints a page number then re-read what it + # had already handled and never reached the rest. + # + # @example + # client.tickets.all.page(2, per_page: 50).to_a + # + # @param number [Integer] one-based page number + # @param per_page [Integer, nil] records on the page, as many as the endpoint + # serves by default + # @return [Collection] + # @raise [ArgumentError] for a page size the endpoint does not serve + def page(number, per_page: nil) + raise ArgumentError, 'page needs to be a positive integer' if !number.is_a?(Integer) || !number.positive? + return with(page: number) if per_page.nil? + + size = positive_integer!(per_page, 'per_page') + raise ArgumentError, "#{@path} serves at most #{@max_per_page} records per page, so page(#{number}, per_page: #{size}) would be sent as page #{number} of #{@max_per_page} and hold different records. Ask for page(#{number}, per_page: #{@max_per_page}) or fewer, or walk the records with find_each." if size > @max_per_page + + with(page: number, per_page: size) + end + + # Returns a new collection sorted by the server. + # + # Attributes named on their own sort ascending, and a keyword says which + # way one runs, the way ActiveRecord reads the same call. A second + # +order+ sorts within the first, so +order(:active).order(name: :desc)+ + # is +order(:active, name: :desc)+. + # + # This is the one thing an index endpoint does besides paging, which is + # why it has a name of its own. It used to be reached as + # +where(sort_by: 'name', order_by: 'desc')+, on a method that refused + # nearly everything else it was given: an index endpoint does not filter + # by attribute value, so +where(state: 'open')+ could only raise, and on + # tickets and users +where+ accepted nothing at all. Narrowing by a value + # is what {ResourceProxy#search} and {ResourceProxy#find_by} are for. + # + # Not every endpoint sorts. +/api/v1/tickets+ and +/api/v1/users+ are + # always served in id order, and drop +sort_by+ along with everything + # else they do not read, so this refuses them rather than handing back + # records it would be calling sorted. A search does sort, for every + # resource that can be searched. + # + # @example + # client.groups.order(:name).first(5) + # client.organizations.order(name: :desc) + # client.tickets.search('state.name:open').order(:priority_id, created_at: :desc) + # + # @param attributes [Array] attributes to sort by, + # ascending + # @param directions [Hash{Symbol => Symbol, String}] attributes to sort by, + # each with +:asc+ or +:desc+ + # @return [Collection] + # @raise [ArgumentError] for an endpoint that does not sort, no + # attribute at all, an attribute named twice, or a direction that is + # neither +:asc+ nor +:desc+ + def order(*attributes, **directions) + raise ArgumentError, "#{@path} is always served in the same order and ignores sort_by, so order would hand back the records as they were. #{@unsortable_hint}" if !@sortable + + requested = sort_columns(attributes, directions) + raise ArgumentError, 'order needs at least one attribute to sort by: order(:name), or order(name: :desc)' if requested.empty? + + sorted = sorted_by + repeated = requested.keys & sorted.keys + raise ArgumentError, "order was given #{repeated.join(', ')}, which this collection is already sorted by" if !repeated.empty? + + columns = sorted.merge(requested) + with(query: @query.merge(sort_by: columns.keys.join(','), order_by: columns.values.join(','))) + end + + # Reads one or more attributes from every record. + # + # Zammad has no way to ask an index endpoint for a subset of the fields, so + # this shapes the result rather than shrinking the request. + # + # @example + # client.users.all.pluck(:email) # => ["a@example.com", ...] + # client.tickets.all.pluck(:id, :title) # => [[1, "Help"], ...] + # + # @param keys [Array] attribute names + # @return [Array] one value per record for a single key, one array of + # values per record for several + # @raise [ArgumentError] when no attribute name was given + def pluck(*keys) + raise ArgumentError, 'pluck needs at least one attribute name' if keys.empty? + return map { it[keys.first] } if keys.one? + + map { |record| keys.map { record[it] } } + end + + # The first record, or the first +count+ of them. + # + # Sized to what was asked for, which +Enumerable#first+ cannot be: it + # takes its records off the front of a page this collection sized for + # walking, so +all.first+ downloaded a page of a thousand users to hand + # back one of them. + # + # The request is sized, not the collection. Limiting it to one page of + # +count+ records would have been the shorter way to write this and + # answers wrongly where the endpoint serves a smaller page than the + # +max_per_page+ this resource declares: +first(500)+ against a server + # capping at 100 came back with 100 records and nothing to say that the + # other 400 were there to be read. Sizing the request instead leaves the + # walk able to fetch a second page, and +Enumerable#first+ stops it as + # soon as it has what it asked for - so the ordinary case is still the one + # request it looks like. + # + # A collection {#page} already limited is left as it is. Its page size + # says which records it holds, so re-sizing it would move them - the same + # reason {#page_size!} refuses to. + # + # The size is where the read starts, and not what it is held to. A + # search can serve a page with nothing on it and hits still behind it, + # and a read that stayed this small then paid a request for every one + # of them: see {#widened}. + # + # A read that sizes its own request leaves out a record it has already + # handed over. The larger pages it asks for past an empty one are where + # an endpoint that pages smaller than it is asked hands a hit back twice, + # and a caller acting on the records - `first(5).each { notify(it) }` - + # would act on that one twice. It holds no more ids than records wanted, + # and asks for nothing more to do it: the read goes on to the next + # record, as it does past a stale hit. + # + # @param count [Integer, nil] how many records to read + # @return [Resources::Base, Array, nil] one record, or an + # array of them when +count+ was given + def first(count = nil) + wanted = count || 1 + # Through an enumerator rather than `super`, so that the sized + # collection does the reading and this method is not asked to be both + # the caller and the callee of Enumerable#first. + records = own_request_for_first?(wanted) ? with(per_page: wanted, widens: true).to_enum(:each_distinct) : each + count.nil? ? records.first : records.first(count) + end + + # The first +count+ records, read the way {#first} reads them. + # + # +take(n)+ and +first(n)+ ask one question, and +Enumerable+ answers both + # by taking records off the front of a page this collection sized for + # walking. With {#first} sizing its own request and this one left alone, + # what the same read cost depended on which of the two words was typed. + # + # @param count [Integer] how many records to read + # @return [Array] + def take(count) + # Enumerable#take always answers with an Array, and {#first} only does + # when it is given a count - a nil is "just the one" there. Refused with + # the error Enumerable#take raises for it, rather than quietly answering + # a different question with a different type. + raise TypeError, 'no implicit conversion from nil to integer' if count.nil? + + first(count) + end + + # +Enumerable#find+, which takes a block. + # + # Defined only to refuse the other reading of it. {ResourceProxy#find} + # takes an id - +client.tickets.find(1)+ is the lookup by id - and the same + # word on a collection is +Enumerable#find+, whose argument is an ifnone + # callable rather than an id. So +client.tickets.all.find(1)+ made no + # request, raised nothing, and answered with an Enumerator: a silent + # no-op, on the one spelling a caller is most likely to reach for. + # + # A collection cannot do the lookup either, even where it would be + # unambiguous - a search has already narrowed what it holds, so an id + # found through one collection would mean something different from an id + # found through another. + # + # @yieldparam record [Resources::Base] + # @return [Resources::Base, nil] + # @raise [ArgumentError] when given an id where a block belongs + def find(*args, &block) + raise ArgumentError, find_by_id_message(args.first) if block.nil? && !args.empty? + + super + end + + # Number of records in this collection. + # + # One request on a search, which Zammad can count without serving the + # records: +only_total_count+ is the first thing + # ApplicationController#model_search_render looks at, and it answers with + # the figure alone. + # + # Every other endpoint has to be walked. An index endpoint drops + # +only_total_count+ along with every other parameter it does not know - + # model_index_render reads +sort_by+, +order_by+ and the paging and + # nothing else - and there is no header to read a total from either, so + # there is nothing cheaper to ask. Probing anyway cost a wasted request + # before the walk that had to happen regardless. + # + # @return [Integer] + def count(*args, &block) + # A block or an argument is Enumerable counting matches, not this asking + # how large the result is. A collection limited to one page has to read + # that page, because the total describes the whole query. + return super if !args.empty? || block || @page || !@search + + total_count || super + end + + # Number of records in this collection. + # + # An alias of {#count}, and so the same cost: one request on a search + # endpoint, a walk of every page on any other. + # + # @return [Integer] + # @see #count + alias size count + + # @return [Integer] + # @see #count + alias length count + + # Whether this collection has no records. + # + # Costs the one request {#first} costs: a page of a single record, except + # on a collection limited to one page, where the page size decides which + # records that page holds and so cannot be narrowed. A search whose + # first hits have lost their records costs the few more it takes to read + # past them. + # + # @example + # client.tickets.search('state.name:merged').empty? + # + # @return [Boolean] + def empty? = first.nil? + + def inspect + "#<#{self.class.name} #{@resource_class.name} path=#{@path.inspect} per_page=#{@per_page}#{" page=#{@page}" if @page}>" + end + + private + + # Yields each record whose id has not been yielded already. A record + # without an id is yielded, there being nothing to tell it by. + def each_distinct + seen = {} + each do |record| + id = record.id + next if !id.nil? && seen.key?(id) + + seen[id] = true if !id.nil? + yield record + end + end + + # Whether a read of this many records is worth sizing the request for. + # + # Not where this collection is already limited to a page, whose size says + # which records it holds, and not where the count is larger than the + # endpoint serves - {#clamp_per_page} would reduce it to the same size the + # collection already has. A zero or negative count is left to + # Enumerable#first, which has its own answers for both. + def own_request_for_first?(count) + return false if @page + + count.is_a?(Integer) && count.positive? && count <= @max_per_page + end + + def find_by_id_message(id) + "find on a #{self.class.name} is Enumerable#find, which takes a block: #{id.inspect} would be read as its " \ + 'ifnone argument and answered with an Enumerator, without a request. ' \ + "Look a record up by id on the resource itself - #{resource_reader}.find(#{id.inspect}) - " \ + 'or pick one out of the records this collection holds with detect { ... }.' + end + + # How a caller reaches this resource from a client: + # ZammadAPI::Resources::TicketArticle is client.ticket_articles, and a + # resource class the caller declared is client.resource(TheirClass). Looked + # up at the moment it is needed, in an error message, so that this file + # does not have to load the client that loads it. + def resource_reader + name = Client::RESOURCES.key(@resource_class) + name ? "client.#{name}" : "client.resource(#{@resource_class.name})" + end + + # The attributes an +order+ call names, each with its direction, in the + # order they were written. + # + # @return [Hash{String => String}] + def sort_columns(attributes, directions) + # `order(:name, :desc)` is the spelling several other clients use, and + # read literally it sorts by an attribute called desc - which Zammad + # answers with a server error about an invalid column. + misplaced = attributes.find { SORT_DIRECTIONS.include?(it.to_s.downcase) } + raise ArgumentError, "order reads #{misplaced.inspect} as an attribute to sort by. A direction goes with its attribute: order(name: #{misplaced.to_s.downcase.to_sym.inspect})" if misplaced + + columns = {} #: Hash[String, String] + (attributes.map { [it, 'asc'] } + directions.to_a).each do |attribute, direction| + name = sort_attribute!(attribute) + raise ArgumentError, "order was given #{name} twice" if columns.key?(name) + + columns[name] = sort_direction!(name, direction) + end + columns + end + + def sort_attribute!(attribute) + name = attribute.to_s + raise ArgumentError, "order needs the name of an attribute to sort by, got #{attribute.inspect}" if (!attribute.is_a?(Symbol) && !attribute.is_a?(String)) || !SORT_ATTRIBUTE.match?(name) + + name + end + + def sort_direction!(name, direction) + normalized = direction.to_s.downcase + raise ArgumentError, "order sorts #{name} either :asc or :desc, got #{direction.inspect}" if !SORT_DIRECTIONS.include?(normalized) + + normalized + end + + # What this collection is already sorted by, read back out of the query + # it will send. + # + # @return [Hash{String => String}] + def sorted_by + @query.fetch(:sort_by, '').to_s.split(',').zip(@query.fetch(:order_by, '').to_s.split(',')).to_h + end + + def positive_integer!(value, name) + raise ArgumentError, "#{name} needs a positive integer" if !value.is_a?(Integer) || !value.positive? + + value + end + + # Re-sizing the page of a collection that {#page} already limited would + # change which records it holds: `page(3, per_page: 50)` names records 101 to + # 150, and re-sizing to 10 behind the caller's back served records 21 to + # 30 instead - a different answer to the same question, with nothing said + # about it. The two ways of naming a page cannot both be honoured, so this + # says so rather than picking one. + def page_size!(value, name) + size = positive_integer!(value, name) + raise ArgumentError, "#{name} cannot be combined with page: page(#{@page}, per_page: #{@per_page}) already named which records this collection holds. Size that page with page(#{@page}, per_page: #{size}), or slice the records with each_slice(#{size})." if @page + + size + end + + def walk + page = @page || 1 + previous = nil + page_size = 0 + # `while`, and not `loop`. Kernel#loop rescues StopIteration, which is + # there for an enumerator driven by hand inside it, and the block this + # yields to is the caller's: one that calls `next` on an enumerator of + # its own - `map { [it.id, labels.next] }` with fewer labels than + # records - raised it from in here, and the walk took it for its own + # end. The records and the pages after that were dropped and `map` + # answered with what it had, where the same block over an Array raises. + # Every way out of this loop is a `break` below. + per_page = @per_page + while page + records, digest, total = fetch(page, per_page) + + # Counted before the block has the page, not after. The Array handed + # over is the block's to do with as it likes, and a consumer that + # works a batch off with `shift` hands it back empty: read afterwards, + # that was an empty page, and an import stopped after its first batch + # with every later page still on the server. + received = records.size + + # Before the records are handed over, not after. Yielding first meant + # an endpoint that ignores `page` had its repeated page imported, + # queued or written by the block, and only then did the guard that + # exists to prevent that get to look at it. + # + # A digest rather than the pages themselves, because holding the + # previous page across the next fetch doubled a walk's peak memory for + # a guard that only ever asks whether two pages are equal. What it is + # a digest of is in #page_digest: the ids, where every record has one. + # + # Where it is the payload, it is the decoded one, not the bytes it + # arrived as. Hashing raw_body is cheaper and looks equivalent - + # identical bytes do mean identical records - but the implication that + # matters here runs the other way: an endpoint that ignores `page` and + # re-serializes the same records with a different key order produces + # different bytes every time, so the guard never fires, and because + # every page is full the short-page break does not fire either. A + # missed repeat is not a missed error, it is a walk that never ends. + # `Hash#hash` ignores key order and whitespace, which is exactly the + # insensitivity this needs - and taking it from the decoded payload + # rather than from the built records costs nothing extra, because that + # payload is what the records were built from one line earlier. + # + # An empty page is not held against the one before it. Two in a row + # are what a search serves for two pages of hits whose records are + # gone, with more beyond them - see #hits_past? - and there is nothing + # on either for the block to be handed twice. + raise PaginationError.build(operation: @operation, page: page, resource_class: @resource_class) if received.positive? && digest == previous + + yield records if received.positive? + + # A collection limited to a single page never advances. + break if @page + + # The hits the pages read so far have covered, reckoned in the size + # asked for. Every page this walk asks for starts where the one + # before it ended, whatever size either was, so the last page's + # number and size say it all. + covered = page * per_page + # An empty page ends the walk, unless it is a search saying that it + # has hits beyond this one. + break if received.zero? && !hits_past?(covered, total) + + # Every stop condition here is derived from the records the endpoint + # actually served, and the one figure read beside them - a search's + # total, in #hits_past? - can only keep a walk going. There was a + # stop condition that was not: an index endpoint was believed to + # report the size of the whole result in a header, which would have + # ended a short walk one request earlier. Zammad sends no such header + # from any endpoint, so it never once fired. What it did leave behind + # was a stop condition that could end a walk early on a figure the + # records did not corroborate, which is the one way a walk can be + # wrong rather than merely slow. + # + # How big a page this endpoint actually serves, learned from the first + # one rather than assumed. The requested size is clamped to a per- + # resource page limit, and where that guess was higher than the + # server's real cap - a lowered setting, a custom deployment, an + # endpoint whose cap was never this generous - every page came back + # short and the walk stopped on page one with a truncated result and + # nothing to show for it. + # + # Asked of an index endpoint only. Its page is one SQL query with an + # offset and a limit, so a page short of the size it has been serving + # is the last one. A search page is put together in two steps: + # ApplicationController#model_search_render has the search - through + # Elasticsearch, or through SQL - name the ids for the page, and then + # loads the records with `where(id: ids)`. An id whose record is gone + # by the second step is left out and nothing fills its place: a ticket + # deleted in between, or one Elasticsearch still lists because its + # index has drifted from the database. So a search can serve 199 of + # 200 on page two with page three still to come, and stopping there + # truncated the result with nothing to say so. Only an empty page + # ends a search walk, which costs one more request where the last + # page of hits is part-filled - and not every empty page does, for + # the same reason: see #hits_past?. + page_size = received if page_size.zero? + break if !@search && received < page_size + + previous = digest + page, per_page = page_after(page, per_page, received, total) + end + end + + # The page that follows one a walk has read, and its size: the next of + # the same size, except past an empty page in a read sized by {#first}, + # which asks for more at a time from there. Only a search gets this far + # with nothing received. + # + # @return [Array(Integer, Integer)] the page to ask for and its size + def page_after(page, per_page, received, total) + received.zero? && @widens ? widened(page * per_page, total) : [page + 1, per_page] + end + + # The page to ask for after an empty one, in a read that may widen: the + # largest the endpoint serves that starts exactly where the pages read so + # far ended. + # + # {#first} and {#empty?} size their request to the records they want, + # and a search is read on past a page with nothing on it while the total + # says there are hits behind it. Kept at that size, the two together + # cost a request for every stale hit: on an instance whose Elasticsearch + # index has drifted from its database - one restored without a reindex - + # `search(term).empty?` behind five thousand of them made five thousand + # requests, one after the other, before it answered. + # + # The size that was asked for stopped being the right one at the first + # empty page: it was chosen to fetch no more than was wanted, and what it + # fetched was nothing. But a larger page cannot simply be asked for from + # there. A page is a position - page 3 of 50 is hits 101 to 150 - so one + # of another size starts somewhere else, and a read that moved to it + # would pass over hits or be handed records a second time. + # + # So the next page is one whose size divides what has been covered, + # which makes its start fall exactly on the end of the last: with 8 hits + # covered, page 2 of 8 is hits 9 to 16. The size doubles that way from a + # page of one, and from the endpoint's own limit on it is the largest + # divisor that fits. Five thousand stale hits are read past in + # thirty-four requests. + # + # No page reaches past the total the search last reported, though the + # endpoint would serve one: with 256 hits covered of 300, the next page + # is 32 hits rather than 128. Zammad hands the offset and the size to + # Elasticsearch as they are, and an index whose result window was + # lowered below them - the per-model settings allow it - refuses the + # request, which Zammad answers as no hits and a total of nought. Asked + # for hits 257 to 384 against a window of 300, a read with a live hit + # at 280 answered nil where a page of one would have found it. The + # window cannot be seen from here, so a total beyond it still leaves the + # read to end there; the default window is a million hits. + # + # It takes the endpoint to serve the size it is asked for, up to + # +max_per_page+, which is what #hits_past? takes as well. One that + # serves less pages by its own size, so page 3 of 192 served as 100 is + # hits 201 to 300: hits are passed over, and the pages read cover less + # than the walk takes them to. A hit served twice is left out by + # {#first}. A page of one, which every endpoint serves, could not go + # wrong that way. Zammad serves a search the 200 this asks for at most, + # so it takes an instance whose cap was lowered, and the README says so + # beside the walk's own limits. + # + # Not for a size a caller chose. `in_batches(of: 10)` says how many + # records a batch may hold, and a page of 160 is not one of those. + # + # @param covered [Integer] the hits the pages read so far have covered + # @param total [Integer, nil] the hits the search last reported + # @return [Array(Integer, Integer)] the page to ask for and its size + def widened(covered, total) + limit = total ? (total - covered).clamp(1, @max_per_page) : @max_per_page + pages = covered.fdiv(limit).ceil + pages += 1 until (covered % pages).zero? + + [pages + 1, covered / pages] + end + + def with(page: @page, per_page: @per_page, query: @query, widens: false) + self.class.new( + transport: @transport, + resource_class: @resource_class, + path: @path, + operation: @operation, + max_per_page: @max_per_page, + sortable: @sortable, + unsortable_hint: @unsortable_hint, + query: query, + per_page: per_page, + page: page, + search: @search, + widens: widens + ) + end + + # Whether a search reports hits beyond the page just read, which is what + # tells a page with nothing on it from the end of the result. + # + # A search page can come back empty with hits still to come, for the + # reason it can come back short: every id the search named for it has + # lost its record. On a page of 200 that takes 200 stale hits in a row. + # On the page of one that {#first} and {#empty?} ask for it takes one, + # and a search sorts by `updated_at`, newest first - so the hit likeliest + # to be stale, a record deleted a moment ago that Elasticsearch has yet + # to drop, is the first one served. `search(term).first` answered nil and + # `empty?` true for a search with live hits right behind it, and `each` + # ended on such a page with the rest unread. + # + # So a search that is walked asks for the size of the whole result beside + # every page - see #page_query - and an empty page ends the walk only + # once the pages read have covered it. + # + # The figure is not used the other way round, to end a walk on a page + # that still held records and save the request after it. Elasticsearch + # stops counting at ten thousand hits and reports that as the total, so + # a walk ended on the figure would stop there with the rest unread - + # which is the stop condition the note in #walk is about. Past that + # figure an empty page ends the walk, as it does where there is no figure + # at all: a Zammad before 6.5.1 answers `with_total_count` under `expand` + # with the bare array. That is the gap this leaves. + # + # Reckoned in the page sizes that were asked for. An endpoint that pages + # smaller has covered fewer hits than this takes it to have, and the + # walk then ends on an empty page it might have read past - no earlier + # than it ended before the figure was read at all. + # + # What reading on costs is bounded by the same figure: a request per + # page of the hits the endpoint reports, and none beyond them. How large + # those pages are is what #widened is about. + # + # @param covered [Integer] the hits the pages read so far have covered + def hits_past?(covered, total) = !total.nil? && covered < total + + # Fetches one page: the records, the digest the repeated-page guard + # compares, and the size of the whole result where the endpoint reported + # it beside them. + # + # @return [Array(Array, Integer, Integer)] the records, + # the digest and the total + # @return [Array(Array, Integer, nil)] where no total + # was reported + def fetch(page, per_page) + response = @transport.get( + @path, + operation: @operation, + resource_class: @resource_class, + query: page_query(page, per_page) + ) + decoded, total = response.decoded_list(operation: @operation, resource_class: @resource_class) + # The digest for the repeated-page guard is taken here, from the decoded + # payload, which is the one structure that has everything the guard needs + # and is already in hand. See the guard in `walk` for why it is this and + # not the records or the raw body. + [decoded.map { @resource_class.from_response(@transport, it) }, page_digest(decoded), total] + end + + # The parameters of a request for one page. + # + # `with_total_count` goes out where the answer is read, which is a search + # being walked: see #hits_past?. An index drops the parameter along with + # everything else it does not know, and a collection limited to one page + # has no walk to end, so both are sent what they always were. + # + # It costs Zammad nothing it was not doing. model_search_render asks the + # search for the total on every request and leaves it out of the answer + # unless the parameter is there. + def page_query(page, per_page) + query = @query.merge(page: page, per_page: per_page) + + @search && @page.nil? ? query.merge(with_total_count: true) : query + end + + # What the repeated-page guard compares two pages by: which records they + # hold, where every record says which it is. + # + # The whole payload was the first answer, and it misses the repeat that + # matters most. A job that writes to the records it is handed changes + # what they serialize as - `updated_at`, if nothing else - so an endpoint + # that ignores `page` served the same records with a different payload + # every time. No two pages compared equal, every page was full, and the + # job went round the same records, writing to each of them again, for as + # long as it was left running. + # + # The ids as a set rather than as a list, because a write can reorder + # them too: a search sorts by `updated_at` unless told otherwise. + # + # The payload is still what is compared where a record carries no id. + # Compared by id, a page of those is a list of nils equal to every other + # such page, and a perfectly good paginator was reported as stuck. + # + # @return [Integer] + def page_digest(decoded) + ids = decoded.map { it[:id] } + + ids.include?(nil) ? decoded.hash : ids.to_set.hash + end + + # Asked only of a search endpoint, which is the only kind that answers + # +only_total_count+. Every one of them routes through + # model_search_render, which reads it before it reads anything else, so a + # shape other than the +{total_count: n}+ object means something has + # answered that is not the endpoint this was addressed to - a proxy error + # page, a login form - and the walk is the honest fallback. + # + # A negative figure is refused rather than trusted: it cannot describe a + # result, and a count is the one answer nothing downstream can sanity + # check - `Array.new(collection.count)` and `count.zero?` both take it at + # its word. + # + # @return [Integer, nil] nil when the endpoint did not report a total + def total_count + response = @transport.get( + @path, + operation: @operation, + resource_class: @resource_class, + query: @query.merge(only_total_count: true) + ) + return nil if !response.body.is_a?(Hash) + + total = response.body[:total_count] + total if total.is_a?(Integer) && !total.negative? + end + + # Reduced rather than refused, unlike the size {#page} takes. The + # asymmetry is deliberate: a batch size says how much to fetch at a time, + # so a smaller one costs more requests and still walks to the same last + # record, while {#page}'s size also decides which records the page holds, + # and reducing that answers a different question than the one asked. + # + # It is also what lets one batch size be written against resources that + # cap differently - the index endpoints allow 1000, tickets 100, a search + # 200 - without the caller looking each of them up. + def clamp_per_page(size) + raise ArgumentError, 'per_page needs to be a positive integer' if !size.is_a?(Integer) || !size.positive? + + [size, @max_per_page].min + end + end +end diff --git a/lib/zammad_api/config.rb b/lib/zammad_api/config.rb new file mode 100644 index 0000000..67d253d --- /dev/null +++ b/lib/zammad_api/config.rb @@ -0,0 +1,508 @@ +# frozen_string_literal: true + +require 'logger' +require 'uri' + +require_relative 'errors' +require_relative 'version' + +module ZammadAPI + # Immutable, validated client configuration. + # + # Credentials are never included in {#inspect} output, so configuration + # objects are safe to log or attach to exception reports. + # + # @example + # ZammadAPI::Config.new(url: 'https://zammad.example.com/', http_token: 'secret') + # + # @!attribute [r] url + # @return [String] base URL, always with a trailing slash + # @!attribute [r] user + # @return [String, nil] login for basic authentication + # @!attribute [r] password + # @return [String, nil] password for basic authentication + # @!attribute [r] http_token + # @return [String, nil] Zammad access token + # @!attribute [r] oauth2_token + # @return [String, nil] OAuth2 bearer token + # @!attribute [r] user_agent + # @return [String] value of the +User-Agent+ request header + # @!attribute [r] timeout + # @return [Numeric] seconds to wait for a response + # @!attribute [r] open_timeout + # @return [Numeric] seconds to wait for the connection + # @!attribute [r] retries + # @return [Integer] retry attempts for a request that only reads + # @!attribute [r] retry_interval + # @return [Numeric] seconds before the first retry, doubling after that. + # A +Retry-After+ header takes its place, and no wait is longer than + # {#timeout}. + # @!attribute [r] ssl_verify + # @return [Boolean] whether TLS certificates are verified + # @!attribute [r] proxy + # @return [String, nil] proxy URL + # @!attribute [r] adapter + # @return [Symbol, nil] name of the Faraday adapter, +nil+ for Faraday's + # default + # @!attribute [r] middleware + # @return [Proc, nil] called with the Faraday connection while it is + # being built + # @!attribute [r] logger + # @return [Logger] where debug output goes + Config = Data.define( + :url, + :user, + :password, + :http_token, + :oauth2_token, + :user_agent, + :timeout, + :open_timeout, + :retries, + :retry_interval, + :ssl_verify, + :proxy, + :adapter, + :middleware, + :logger + ) + + class Config + # Seconds to wait for a response before raising {TimeoutError}. + DEFAULT_TIMEOUT = 60 + + # Seconds to wait for the connection to be established. + DEFAULT_OPEN_TIMEOUT = 10 + + # How often a request that only reads is retried on a transient failure. + DEFAULT_RETRIES = 2 + + # Seconds to wait before the first retry; doubles on each attempt. + DEFAULT_RETRY_INTERVAL = 0.5 + + # Attributes whose values must never be rendered. + REDACTED_ATTRIBUTES = %i[password http_token oauth2_token].freeze + + # Placeholder rendered in place of a credential. + REDACTION = '[REDACTED]' + + # Identifies this gem in the +User-Agent+ header. + DEFAULT_USER_AGENT = "zammad_api-ruby/#{ZammadAPI::VERSION}".freeze + + SCHEME_PATTERN = %r{\Ahttps?://}i + + # An absolute http(s) URL, authority included. The host is part of the + # pattern because a bare scheme - +https://+ - passed a scheme-only check + # and was accepted here, then failed deep inside the adapter on the first + # request instead of at construction, which is the opposite of the + # up-front validation the rest of this class exists for. + URL_PATTERN = %r{\Ahttps?://[^/?\#]+}i + + # Where a URL stops being the part a trailing slash belongs on. + URL_SUFFIX_PATTERN = /[?\#]/ + + # The scheme of a URL, where it has one. A proxy is configured without + # one as often as with - +u:p@proxy:8080+ is the shape an +http_proxy+ + # style setting is copied out of - so the redaction below cannot assume + # it. + URL_SCHEME_PATTERN = %r{\A[a-z][a-z0-9+.-]*://}i + + # What RFC 3986 calls the authority of a URL: everything up to the first + # +/+, +?+ or +#+ after the scheme. + URL_AUTHORITY_PATTERN = %r{\A[^/?\#]*} + + # The options each authentication scheme is made of. + CREDENTIAL_OPTIONS = { + http_token: %i[http_token], + oauth2_token: %i[oauth2_token], + basic: %i[user password] + }.freeze + + # Lays +overrides+ over +options+, dropping the credentials they replace. + # + # A configuration authenticates one way, so an override that names + # another has to take the old one's place, not sit beside it. A plain + # merge left both, and the old scheme in charge: with +ZAMMAD_TOKEN+ set, + # +Client.from_env(user: 'u', password: 'p')+ still sent the + # environment's token, and +client.with(oauth2_token: 'x')+ on a token + # client went on acting as the account the token belonged to. Neither + # raised, and both read as if they had switched identity. Two schemes + # side by side are refused outright now, which is what makes dropping + # the old one here necessary rather than merely right. + # + # An override that names a scheme therefore takes the place of every + # other scheme. The options of its own scheme are kept, so overriding + # +password:+ alone still pairs it with the +user+ already there. + # + # @api private + # @param options [Hash{Symbol => Object}] the options being overridden + # @param overrides [Hash{Symbol => Object}] + # @return [Hash{Symbol => Object}] + def self.merge_options(options, overrides) + named = CREDENTIAL_OPTIONS.select { |_, keys| keys.any? { !overrides[it].to_s.empty? } } + replaced = named.empty? ? [] : CREDENTIAL_OPTIONS.except(*named.keys).values.flatten + + options.except(*replaced).merge(overrides) + end + + def initialize( + url:, + user: nil, + password: nil, + http_token: nil, + oauth2_token: nil, + user_agent: DEFAULT_USER_AGENT, + timeout: DEFAULT_TIMEOUT, + open_timeout: DEFAULT_OPEN_TIMEOUT, + retries: DEFAULT_RETRIES, + retry_interval: DEFAULT_RETRY_INTERVAL, + ssl_verify: true, + proxy: nil, + adapter: nil, + middleware: nil, + logger: nil + ) + # RBS cannot describe the initializer that Data.define generates, so + # these keyword arguments are invisible to the type checker. + # steep:ignore:start + super( + url: immutable(normalize_url(url)), + user: immutable(presence(user)), + password: immutable(presence(password)), + http_token: immutable(presence(http_token)), + oauth2_token: immutable(presence(oauth2_token)), + user_agent: immutable(presence(user_agent) || DEFAULT_USER_AGENT), + timeout: timeout, + open_timeout: open_timeout, + retries: retries, + retry_interval: retry_interval, + ssl_verify: ssl_verify, + proxy: immutable(normalize_proxy(proxy)), + adapter: normalize_adapter(adapter), + middleware: middleware, + logger: logger || Logger.new(IO::NULL) + ) + # steep:ignore:end + validate_credentials! + validate_numbers! + validate_user_agent! + validate_header_options! + validate_ssl_verify! + validate_middleware! + validate_logger! + end + + # The instance URL, with any inline credentials blanked. + # + # A URL that carries credentials is refused when the configuration is + # built - see {#normalize_url} - but only where it can be read as a URL + # at all. One that cannot, such as a password with an unencoded +#+ in + # it, is still held here until building the connection rejects it, and + # this is what that error and {#inspect} print in the meantime. The host + # has to stay readable for the URL to be worth printing, so the + # credentials are replaced rather than the whole value. + # + # @return [String] + def redacted_url = redacted(url) + + # Blanks the credentials in any URL this configuration holds. + # + # Public because {Transport} has to scrub the values it configured out of + # an error message raised from deep inside Faraday or URI, which quotes + # the proxy URL it rejected - credentials and all. + # + # @api private + # @param value [String] a URL that may carry inline credentials + # @return [String] the same URL with the credentials blanked + def redacted(value) = redact_userinfo(value) + + # The one way this configuration authenticates. There is never more than + # one to choose between: see {#validate_credentials!}. + # + # @return [Symbol] +:http_token+, +:oauth2_token+ or +:basic+ + def authentication_scheme + return :http_token if http_token + return :oauth2_token if oauth2_token + + :basic + end + + # Returns a copy with some options changed, re-validated. + # + # Through {.merge_options} rather than Data's own merge, so that naming + # one authentication scheme replaces the one this configuration had. + # + # @param options [Hash] any option this class accepts + # @return [Config] + # @raise [ConfigurationError] when the resulting options are invalid + def with(**options) = self.class.new(**self.class.merge_options(to_h, options)) + + # @return [String] configuration description with credentials redacted + def inspect + rendered = to_h.map { |key, value| "#{key}=#{render(key, value)}" } + "#" + end + alias to_s inspect + + # What +pp+ prints, which is what IRB and the Rails console show for a + # value typed at the prompt. + # + # +pp+ does not go through {#inspect} for a Data object: it has a printer + # of its own that renders the members directly. So +client.config+ in a + # console, or +pp config+ in a script, printed the token, the password + # and the credentials of a proxy in full - from the class documented as + # safe to log, and through the one route most likely to be looked at. + # + # @api private + # @param printer [PP] + # @return [void] + def pretty_print(printer) = printer.text(inspect) + + private + + # Blanks the +user:password@+ part of a URL, keeping the host visible. + # + # Everything up to the last +@+ goes, rather than up to the first: a + # password may carry an unencoded one, and +pa@ss+ used to leave +@ss+ in + # the rendered URL. + # + # Which +@+ is the last one depends on whether a password can be there at + # all. Without a colon in the authority there is none, so the search + # stays inside the authority and an +@+ in a path, a query string or a + # fragment is left alone: +https://host?a=b@c+ used to render as + # +https://[REDACTED]@c+, a host that does not exist, in every + # ConnectionError message. + # + # With a colon, the search runs to the end of the value. A password is + # not obliged to be URL-safe, and one carrying +/+, +?+ or +#+ ends the + # authority early as far as the syntax goes: +http://user:p#ss@proxy+ has + # the authority +user:p+, which holds no +@+, so a search bounded by it + # found nothing to blank and printed the password - in {#inspect}, and in + # the ConfigurationError that quotes a proxy URL the HTTP stack rejected. + # The cost is a URL with a port and an +@+ further on, such as + # +https://host:8443/a@b+, which renders with its host blanked. A colon + # cannot tell a port from a password, and of the two mistakes that is the + # one that leaks nothing. + # + # @param value [String] a URL that may carry inline credentials + # @return [String] the same URL with the credentials blanked + def redact_userinfo(value) + scheme = value[URL_SCHEME_PATTERN].to_s + rest = value.delete_prefix(scheme) + authority = rest[URL_AUTHORITY_PATTERN].to_s + boundary = authority.include?(':') ? rest.rindex('@') : authority.rindex('@') + return value if boundary.nil? + + "#{scheme}#{REDACTION}#{rest[boundary..]}" + end + + def render(key, value) + return REDACTION if REDACTED_ATTRIBUTES.include?(key) && value + # Loggers and procs have verbose default inspect output that would drown + # out the rest of the configuration. + return "#<#{value.class}>" if key == :logger + return "#<#{value.class}>" if key == :middleware && value + return redacted_url.inspect if key == :url + return redact_userinfo(value).inspect if key == :proxy && value + + value.inspect + end + + # The type check comes before the pattern, because every check after it + # is a String method. A URI is the plausible mistake here - it is what + # `URI(...)` hands back and it prints as the URL - and it used to reach + # `end_with?` and die there as a NoMethodError, past the ConfigurationError + # a caller had wrapped the constructor in. + def normalize_url(value) + raise ConfigurationError, 'missing url in config' if presence(value).nil? + raise ConfigurationError, "config url needs to be a string, got #{value.class}" if !value.is_a?(String) + raise ConfigurationError, 'config url needs to start with http:// or https://' if !SCHEME_PATTERN.match?(value) + raise ConfigurationError, "config url needs a host after the scheme, got #{value.inspect}" if !URL_PATTERN.match?(value) + raise ConfigurationError, inline_credentials_message(value) if inline_credentials?(value) + + # A trailing slash keeps Zammad installations served from a sub-path + # (e.g. https://example.com/zammad/) working, because request paths are + # appended relative to this prefix. + # + # Onto the path, not onto the end of the string. Appended blindly it + # landed behind a query string or fragment, so a url of + # `https://host/zammad?a=1` became `https://host/zammad?a=1/` - the base + # every request is resolved against, and the value {#redacted_url} + # prints in every ConnectionError and TimeoutError message. + path, separator, rest = value.partition(URL_SUFFIX_PATTERN) + path.end_with?('/') ? value : "#{path}/#{separator}#{rest}" + end + + # Whether the URL carries a +user:password@+ of its own. + # + # Asked of URI, because that is the parser Faraday reads the URL with: + # whatever it finds there, Faraday turns into a Basic +Authorization+ + # header on the connection, and its authorization middleware then leaves + # a header that is already set alone. So a URL with credentials silently + # replaced the scheme this class validated - an access token configured + # beside it was never sent, while {Client#inspect} went on reporting + # +auth=http_token+. + # + # A URL that URI cannot read is left for the connection to reject, which + # it does before any request is made. + def inline_credentials?(value) + !URI.parse(value).userinfo.nil? + rescue URI::InvalidURIError + false + end + + def inline_credentials_message(value) + "config url carries credentials of its own (#{redact_userinfo(value)}), which would be sent as basic authentication " \ + 'in place of the ones this configuration names. Leave them out of the url and pass user: and password:, ' \ + 'or http_token: or oauth2_token:, instead.' + end + + # One way to authenticate, and only one. + # + # Several used to be accepted together, and {#authentication_scheme} + # picked the first of them in a fixed order without a word. That is what + # let an override leave the old credential in charge - a token beside a + # user and password it was meant to replace - and it is the same mistake + # wherever it comes from: a client that holds two identities sends one of + # them, and which one is not something the call site shows. Refused here, + # a configuration says how it authenticates by construction, and the + # merges that build one - {.merge_options} - have to drop what an + # override replaces rather than keep it beside the new value. + # + # Half of a scheme counts as naming it, so a token beside a +user+ that + # has no password is refused as two schemes rather than passed as one. + def validate_credentials! + given = CREDENTIAL_OPTIONS.select { |_, options| options.any? { !public_send(it).nil? } }.keys + raise ConfigurationError, multiple_credentials_message(given) if given.size > 1 + return if http_token || oauth2_token + + raise ConfigurationError, 'missing user in config' if user.nil? + raise ConfigurationError, 'missing password in config' if password.nil? + end + + def multiple_credentials_message(schemes) + named = schemes.map { CREDENTIAL_OPTIONS.fetch(it).join(' and ') }.join(', ') + + "config names more than one way to authenticate (#{named}), and a request can carry only one. " \ + 'Pass http_token:, or oauth2_token:, or user: and password:, and leave the others out.' + end + + # Numeric is not the whole test. Complex is one and answers neither + # `positive?` nor `>`, so `timeout: Complex(1, 2)` left a NoMethodError + # where every other rejected option raises ConfigurationError - the same + # escape normalize_adapter, normalize_proxy and validate_logger! were each + # written to close. + def positive_number?(value) = value.is_a?(Numeric) && value.respond_to?(:positive?) && value.positive? + + def validate_numbers! + { timeout: timeout, open_timeout: open_timeout, retry_interval: retry_interval }.each do |name, value| + raise ConfigurationError, "config #{name} needs to be a positive number" if !positive_number?(value) + end + + raise ConfigurationError, 'config retries needs to be a non-negative integer' if !retries.is_a?(Integer) || retries.negative? + end + + # Not just a default: `user_agent: nil` reached Faraday as a nil header, + # and Faraday filled in its own, so the gem stopped identifying itself in + # the instance log an operator greps to find its requests - silently, and + # on every request. + def validate_user_agent! + return if user_agent.is_a?(String) + + raise ConfigurationError, 'config user_agent needs to be a string' + end + + # The options that are sent as a header: the two tokens in + # +Authorization+, and the user agent. + HEADER_OPTIONS = %i[http_token oauth2_token user_agent].freeze + private_constant :HEADER_OPTIONS + + # A line break inside one of these was taken here and refused by + # Net::HTTP at the first request, with the value in the message: see + # {Transport.line_break?}. Refused here instead, without the value. A + # user and password are not checked: basic authentication sends them + # Base64-encoded, which carries a line break like anything else. + def validate_header_options! + HEADER_OPTIONS.each do |name| + value = public_send(name) + next if !value.is_a?(String) || !Transport.line_break?(value) + + raise ConfigurationError, "config #{name} holds a line break, which a header cannot carry: #{Transport::LINE_BREAK_ADVICE}" + end + end + + # A proxy is the second string here that may carry credentials, and the + # only other one rendered rather than replaced wholesale. Unchecked, a + # URI - what `URI(...)` hands back, and what prints as the URL - was + # accepted here and reached String#sub inside {#inspect}, so the object + # this class documents as safe to log raised NoMethodError at exactly the + # moment something tried to log it. The same mistake {#normalize_url} + # already refuses for the instance URL. + def normalize_proxy(value) + return nil if presence(value).nil? + raise ConfigurationError, "config proxy needs to be a string, got #{value.class}" if !value.is_a?(String) + + value + end + + # `adapter&.to_sym` accepted anything that answered to_sym and died with + # a bare NoMethodError on anything that did not - `adapter: 1` and + # `adapter: true` both escaped the ConfigurationError that building a + # client is documented to need, from inside the constructor, before any + # of the validators below ran. + def normalize_adapter(value) + return nil if presence(value).nil? + raise ConfigurationError, "config adapter needs to be a symbol or a string, got #{value.class}" if !value.is_a?(Symbol) && !value.is_a?(String) + + value.to_sym + end + + # The one option that fails open. Every other value here is checked up + # front, while ssl_verify was passed to Faraday as it arrived: read from + # an environment variable, `ssl_verify: 'false'` is the string "false", + # which is truthy, so the setting a caller believed they had turned off + # was silently still on. That direction is the safe one, which is why it + # went unnoticed - `ssl_verify: 'no'` disables nothing either way, but a + # caller who cannot tell which of their settings took effect has no way + # to find out. + def validate_ssl_verify! + return if [true, false].include?(ssl_verify) + + raise ConfigurationError, "config ssl_verify needs to be true or false, got #{ssl_verify.inspect}" + end + + def validate_middleware! + return if middleware.nil? || middleware.respond_to?(:call) + + raise ConfigurationError, 'config middleware needs to respond to call' + end + + # In 1.x this option was a flag, so `logger: true` is a plausible thing to + # carry over. Without this it would be accepted here and raise NoMethodError + # at the first request instead. + def validate_logger! + return if logger.respond_to?(:debug) + + raise ConfigurationError, 'config logger needs to respond to debug' + end + + def presence(value) + return nil if value.nil? + return nil if value.respond_to?(:empty?) && value.empty? + + value + end + + # Ruby leaves the members of a Data object mutable, so a caller-supplied + # String would otherwise stay writable through the config - and shared + # with the caller's own variable. Freezing a copy keeps a Config, and any + # Transport built from one, genuinely immutable. + # + # This deliberately copies rather than using String#-@: interning would + # keep a credential in the global fstring table for the life of the + # process, well past the config that held it. + def immutable(value) + value.is_a?(String) ? value.dup.freeze : value + end + end +end diff --git a/lib/zammad_api/deep_copy.rb b/lib/zammad_api/deep_copy.rb new file mode 100644 index 0000000..cc7e8db --- /dev/null +++ b/lib/zammad_api/deep_copy.rb @@ -0,0 +1,83 @@ +# frozen_string_literal: true + +module ZammadAPI + # Recursive copies of the plain JSON structures this gem passes around. + # + # Three places need the same walk - a record freezing the attributes it was + # built with, a record handing a copy of them back, and the test kit + # recording the payload a request carried - and each used to carry its own. + # A rule written three times is one that gets fixed in one of them: the + # test kit's copy already differed by not symbolizing keys, and nothing + # said whether that was the point or an oversight. + # + # Only Hash, Array and String are walked, because that is the whole of what + # +JSON.parse+ builds and what a caller may hand in as attributes. Numbers, + # booleans and nil are immutable already and are passed through untouched. + # + # One walk, deliberately. A record built from a response copies every String + # of a body +JSON.parse+ has just built and nothing else holds, so a variant + # that froze such a body in place would save that copy on the paging hot + # path - which is a real cost, and still not a reason for a second walk: + # three of them is what this module replaced, and the one that differed did + # so without anything to say whether the difference was the point. If the + # copy is worth removing, it is an argument to this walk and it applies to + # the one place that can prove nothing else references the value. + # + # @api private + module DeepCopy + module_function + + # A frozen deep copy. + # + # Named for what it returns rather than `freeze`/`dup`, which would shadow + # the Object methods of those names inside this module and read as them at + # every call site. + # + # Freezing is what makes a record's attribute hash safe to hand out: one + # that gave away a writable hash would report changes it never staged and + # so never sent. Strings are copied before being frozen, so freezing a + # value the caller passed in does not reach back into their own variable. + # + # Keys are left alone. Ruby copies and freezes an unfrozen String key on + # insertion, so a Hash built here never holds the caller's own String, and + # symbolizing produces an immutable key anyway - which leaves only an + # Array or a custom object as a key that this walk would change. `JSON` + # cannot build one, so it could only come from a caller's own attribute + # hash, and paying a call per key on the record-building path for it is + # the cost this module's own note above weighs and declines. + # + # @param value [Object] + # @param symbolize_keys [Boolean] whether Hash keys become Symbols, so + # that caller-supplied attributes behave the same as decoded responses + # @return [Object] a frozen copy + def frozen_copy(value, symbolize_keys: false) + case value + when Hash then value.to_h { |key, nested| [symbolize_keys ? symbolize(key) : key, frozen_copy(nested, symbolize_keys: symbolize_keys)] }.freeze + when Array then value.map { frozen_copy(it, symbolize_keys: symbolize_keys) }.freeze + when String then value.dup.freeze + else value + end + end + + # A writable deep copy, for handing out something callers may treat as + # their own. The inverse of {frozen_copy}. + # + # @param value [Object] + # @return [Object] an unfrozen copy + def writable_copy(value) + case value + when Hash then value.to_h { |key, nested| [key, writable_copy(nested)] } + when Array then value.map { writable_copy(it) } + when String then value.dup + else value + end + end + + # A key that cannot become a Symbol is left as it is rather than refused: + # it came from a caller's attribute hash, and a record is not the place + # to decide that Zammad will not accept it. + # + # @api private + def symbolize(key) = key.respond_to?(:to_sym) ? key.to_sym : key + end +end diff --git a/lib/zammad_api/dispatcher.rb b/lib/zammad_api/dispatcher.rb deleted file mode 100644 index 07b311b..0000000 --- a/lib/zammad_api/dispatcher.rb +++ /dev/null @@ -1,12 +0,0 @@ -module ZammadAPI - class Dispatcher - def initialize(transport, resource) - @transport = transport - @resource = resource - end - - def method_missing(method, *args) - @resource.send(method, @transport, args[0]) - end - end -end diff --git a/lib/zammad_api/duplicate_keys.rb b/lib/zammad_api/duplicate_keys.rb new file mode 100644 index 0000000..24e6aad --- /dev/null +++ b/lib/zammad_api/duplicate_keys.rb @@ -0,0 +1,49 @@ +# frozen_string_literal: true + +module ZammadAPI + # One rule for two keys that name the same parameter. + # + # Both places that normalise caller-supplied parameter names had to refuse a + # collision, because normalising is what creates one: {ResourceProxy#search} + # maps every keyword to a Symbol and {Transport.stringify_query} maps every key to a + # String, so `sort_by` and `'sort_by'` become one key and the value that + # arrived first is dropped without a word. Written twice, the two refusals + # had already drifted into two different sentences for the same mistake. + # + # @api private + module DuplicateKeys + module_function + + # Maps every key through the block, refusing two that land on one name. + # + # The key each name was first seen as is kept, so the message can print + # both spellings: naming only the second left the reader to guess the + # first, which in a parameter hash assembled across several merges is the + # whole of the debugging. + # + # @param hash [Hash] + # @param prefix [String, nil] the parameter path this Hash sits at, for a + # nested structure + # @param noun [String] what the caller calls one of these, for the message + # @yieldparam key [Object] a key to normalise + # @return [Hash] the hash with normalised keys and untouched values + # @raise [ArgumentError] for two keys that name the same thing + def normalize(hash, prefix: nil, noun: 'parameter') + seen = {} + + hash.each_with_object({}) do |(key, value), result| + name = yield(key) + raise ArgumentError, message(noun, prefix ? "#{prefix}[#{name}]" : name, seen[name], key) if seen.key?(name) + + seen[name] = key + result[name] = value + end + end + + # @api private + def message(noun, path, first, second) + "#{noun} #{path} was given twice, as #{first.inspect} and as #{second.inspect}: " \ + 'pass it once, so that which value reaches the endpoint does not depend on Hash order' + end + end +end diff --git a/lib/zammad_api/errors.rb b/lib/zammad_api/errors.rb index 4e07e1d..c5bd351 100644 --- a/lib/zammad_api/errors.rb +++ b/lib/zammad_api/errors.rb @@ -1,62 +1,201 @@ -require 'json' +# frozen_string_literal: true module ZammadAPI - class Error < RuntimeError; end + # Base class for every error raised by this gem. + # + # Rescuing +ZammadAPI::Error+ catches all of them. + class Error < StandardError + # Formats the " ()" fragment shared by error + # messages, so every error reads the same way. + # + # @api private + # @param operation [String] + # @param resource_class [Class, nil] + # @return [String] + def self.subject_for(operation, resource_class) + resource_class ? "#{operation} (#{resource_class.name})" : operation + end + end + # Raised when {Config} cannot be built from the supplied options. class ConfigurationError < Error; end - class ResourceNotFoundError < Error; end + # Raised when a resource name is requested that this client does not know + # about, e.g. +client.unicorn+. + class UnknownResourceError < Error; end + + # Base class for failures that prevented a request from completing. + class TransportError < Error; end + + # Raised when the connection to the Zammad instance could not be + # established (DNS, refused connection, TLS failure, ...). + class ConnectionError < TransportError; end + + # Raised when a request exceeded {Config#open_timeout} or {Config#timeout}. + class TimeoutError < TransportError; end + # Raised when a response did not have the shape the caller expected. + class ParseError < Error + # @param operation [String] + # @param expected [Symbol, String] +:object+, +:array+, or a longer + # description of the shape that was wanted + # @param actual [Class, String] the class that was decoded instead, or a + # description of it + # @param resource_class [Class, nil] + # @return [ParseError] + def self.build(operation:, expected:, actual:, resource_class: nil) + new("Can't #{subject_for(operation, resource_class)}: expected a JSON #{expected}, got #{actual}") + end + end + + # Raised when the server answers a page request with the page before it, + # which means it is ignoring +page+ and a collection walk would never end. + class PaginationError < Error + # @param operation [String] + # @param page [Integer] the page that repeated its predecessor + # @param resource_class [Class, nil] + # @return [PaginationError] + def self.build(operation:, page:, resource_class: nil) + new("Can't #{subject_for(operation, resource_class)}: page #{page} repeated page #{page - 1}, so the endpoint is ignoring the page parameter") + end + end + + # Base class for errors carrying an HTTP response. + # + # Use {.build} rather than +new+ to get the most specific subclass for a + # given status code. class ResponseError < Error - attr_reader :response, :operation, :resource_class + # @return [Response, nil] the decoded HTTP response + attr_reader :response + + # @return [String] human readable description of what was attempted + attr_reader :operation + + # @return [Class, nil] the resource class involved, when applicable + attr_reader :resource_class - def initialize(operation:, response:, resource_class: nil) + # Returns the most specific error class for +response+ and instantiates it. + # + # @param response [Response, nil] + # @param operation [String] + # @param resource_class [Class, nil] + # @return [ResponseError] + def self.build(response, operation:, resource_class: nil) + error_class_for(response).new( + response: response, + operation: operation, + resource_class: resource_class + ) + end + + # @api private + def self.error_class_for(response) + return self if response.nil? + + STATUS_ERRORS.fetch(response.status) do + response.status >= 500 ? ServerError : ClientError + end + end + private_class_method :error_class_for + + # @param operation [String] what was attempted + # @param response [Response, nil] + # @param resource_class [Class, nil] + # @param detail [String, nil] replaces the part of the message that would + # otherwise describe the response, for a failure that has none + def initialize(operation:, response: nil, resource_class: nil, detail: nil) @operation = operation @response = response @resource_class = resource_class - super(default_message) + @detail = detail + super(build_message) end + # The status this error carries, or - for one this gem raised without a + # request, such as {ResourceProxy#find_by!} finding nothing - the status + # its class is the name for. A NotFoundError used to answer nil there, + # so `rescue NotFoundError => e; retry if e.status == 404` quietly stopped + # retrying for the one NotFoundError that came from this gem rather than + # from Zammad, while every other one carried 404. + # + # @return [Integer, nil] HTTP status code def status - response&.status + response&.status || STATUS_ERRORS.key(self.class) end + # @return [Hash, String, nil] parsed JSON body, or the raw body for + # non-JSON responses def body response&.body end - def self.from(response, **kwargs) - klass = if response.nil? - self - elsif response.status >= 500 - ServerError - else - ClientError - end - klass.new(response: response, **kwargs) + # @return [Hash] response headers, empty when there is no response + def headers + response&.headers || {} + end + + # @return [String, nil] the error message reported by Zammad, if any + def server_message + return nil if !body.is_a?(Hash) + + # Symbol keys only: both decode paths - Transport#decode_body and the + # test kit - parse with symbolize_names, so a string-keyed body cannot + # reach here and the fallbacks that read one were never run. + value = body[:error_human] || body[:error] + value.to_s.empty? ? nil : value.to_s end private - def default_message - subject = resource_class ? "#{operation} (#{resource_class.name})" : operation - "Can't #{subject}: #{detail}" + def build_message + "Can't #{Error.subject_for(operation, resource_class)}: #{detail}" end def detail - body_error || "HTTP #{status}" + @detail || server_message || (status ? "HTTP #{status}" : 'no response') end + end + + # Any 4xx response that has no more specific subclass. + class ClientError < ResponseError; end + + # Any 5xx response. + class ServerError < ResponseError; end + + # 401 - credentials missing, wrong, or expired. + class AuthenticationError < ClientError; end + + # 403 - authenticated, but not permitted to perform the operation. + class AuthorizationError < ClientError; end + + # 404 - the requested record does not exist. + class NotFoundError < ClientError; end - def body_error - return nil if body.to_s.strip.empty? + # 422 - Zammad rejected the submitted attributes. + class ValidationError < ClientError; end - parsed = JSON.parse(body) - parsed.is_a?(Hash) ? parsed['error'] : nil - rescue JSON::ParserError - nil + # 429 - too many requests. + class RateLimitError < ClientError + # @return [Integer, nil] value of the +Retry-After+ response header + def retry_after + # Downcased, because every {Response} is built with its header keys + # downcased - {Transport#decode} and {Test#stub} both do it - so there + # is no capitalised spelling left to fall back to. + value = headers['retry-after'] + return nil if value.nil? + + Integer(value, exception: false) end end - class ClientError < ResponseError; end - class ServerError < ResponseError; end + class ResponseError + STATUS_ERRORS = { + 401 => AuthenticationError, + 403 => AuthorizationError, + 404 => NotFoundError, + 422 => ValidationError, + 429 => RateLimitError + }.freeze + private_constant :STATUS_ERRORS + end end diff --git a/lib/zammad_api/json_helper.rb b/lib/zammad_api/json_helper.rb deleted file mode 100644 index fd8ca4c..0000000 --- a/lib/zammad_api/json_helper.rb +++ /dev/null @@ -1,11 +0,0 @@ -require 'json' - -module ZammadAPI - module JsonHelper - def safe_json_parse(string) - JSON.parse(string) - rescue JSON::ParserError - {} - end - end -end diff --git a/lib/zammad_api/list_all.rb b/lib/zammad_api/list_all.rb deleted file mode 100644 index 393c56a..0000000 --- a/lib/zammad_api/list_all.rb +++ /dev/null @@ -1,11 +0,0 @@ -require 'zammad_api/list_base' - -module ZammadAPI - class ListAll < ListBase - private - - def perform_request(parameter) - request('all', @url, parameter) - end - end -end diff --git a/lib/zammad_api/list_base.rb b/lib/zammad_api/list_base.rb deleted file mode 100644 index c8b692c..0000000 --- a/lib/zammad_api/list_base.rb +++ /dev/null @@ -1,84 +0,0 @@ -require 'zammad_api/json_helper' - -module ZammadAPI - class ListBase - include Enumerable - include ZammadAPI::JsonHelper - - def initialize(resource, transport, parameter = {}) - @resource = resource - @url = @resource.get_url - @transport = transport - @parameter = { - page: 1, - per_page: 10, - expand: 'true', - }.merge(parameter) - end - - def [](position) - local_parameter = @parameter.merge( - page: position + 1, - per_page: 1 - ) - perform_request(local_parameter)[0] - end - - def page(page, per_page, &block) - @parameter[:page] = page - @parameter[:per_page] = per_page - fetch_and_yield_each(&block) - end - - def page_next(&block) - @parameter[:page] += 1 - fetch_and_yield_each(&block) - end - - def page_prev(&block) - @parameter[:page] -= 1 - fetch_and_yield_each(&block) - end - - def each(&block) - fetch_and_yield_each(&block) - end - - private - - def fetch_and_yield_each(&block) - result = perform_request(@parameter) - result.each(&block) - end - - def request(request, url, parameter) - # convert parameters into a GET query - url += '?' + parameter.map { |key, value| - if !value.is_a? String - value = value.to_s - end - - "#{key}=#{CGI.escape value}" - }.join('&') - - response = @transport.get(url: url) - if response.status != 200 - raise ResponseError.from(response, operation: "get .#{request} of object", resource_class: @resource.class) - end - - data = safe_json_parse(response.body) - - list = [] - data.each do |local_data| - item = @resource.new(@transport, local_data) - item.new_instance = false - list.push item - end - list - end - - def perform_request(_parameter) - raise Error, "no perform_request implementation for #{self.class.name} found" - end - end -end diff --git a/lib/zammad_api/list_search.rb b/lib/zammad_api/list_search.rb deleted file mode 100644 index fac7f2b..0000000 --- a/lib/zammad_api/list_search.rb +++ /dev/null @@ -1,11 +0,0 @@ -require 'zammad_api/list_base' - -module ZammadAPI - class ListSearch < ListBase - private - - def perform_request(parameter) - request('search', "#{@url}/search", parameter) - end - end -end diff --git a/lib/zammad_api/log.rb b/lib/zammad_api/log.rb deleted file mode 100644 index b67ad26..0000000 --- a/lib/zammad_api/log.rb +++ /dev/null @@ -1,18 +0,0 @@ -module ZammadAPI - class Log - def initialize(config) - return if !config[:logger] - - require 'logger' - @logger = Logger.new($stderr) - #@logger.level = Logger::WARN - @logger.level = Logger::DEBUG - end - - def method_missing(method, *args) - return if !@logger - - @logger.send(method, args) - end - end -end diff --git a/lib/zammad_api/query_encoder.rb b/lib/zammad_api/query_encoder.rb new file mode 100644 index 0000000..fc90b6a --- /dev/null +++ b/lib/zammad_api/query_encoder.rb @@ -0,0 +1,162 @@ +# frozen_string_literal: true + +require 'faraday' + +module ZammadAPI + # Writes a query the way Rails reads it back into the structure it was. + # + # Faraday's own encoder did this, and does it for everything but a list of + # Hashes that do not all carry the same keys. A query string has no mark for + # where one element of a list ends: a list of Hashes goes out as + # `list[][key]=value` pairs, and Rack - and the parser Rails 8.1 has of its + # own, which follows it - starts a new element only when a pair names a key + # the element it is filling already has. Faraday writes the keys of every + # Hash in alphabetical order, so the first pair of an element named + # whichever of its keys sorts first, whether or not the element before had + # it. + # + # Zammad's expert conditions are such a list. A group of conditions nests + # them, and a group and a condition share `operator` and nothing else: + # + # conditions: [ + # {name: 'ticket.state_id', operator: 'is', value: [2]}, + # {operator: 'AND', conditions: [a, b]} + # ] + # + # The second element went out `conditions` first, which the first element + # does not have, so Rails read that into the first element and began the + # second at `operator`: one condition holding the whole group, followed by + # a group holding nothing. Zammad was handed a selector nobody wrote. It + # answered this one with a 500, and the same two elements the other way + # round with every ticket there is, as if no condition had been given. + # + # So an element that follows another Hash is written with a value the two + # both have a place for first - see {.lead_path} - and the rest in the + # order they always were. Where there is no such value no order works, and + # {Transport.stringify_query} refuses the query before it gets here. + # + # The escaping is still Faraday's: this hands it the pairs in order, which + # its encoder keeps for a list where it sorts a Hash. + # + # @api private + module QueryEncoder + module_function + + # @param params [Hash, nil] a query as {Transport.stringify_query} leaves + # it + # @return [String, nil] the query string, nil for no query + def encode(params) + return nil if params.nil? + + Faraday::NestedParamsEncoder.encode(hash_pairs(nil, params.to_hash, nil)) + end + + # Reading a query string back is not this module's business, and Faraday + # asks whatever encodes for it: a query written into the instance URL is + # decoded on the way in. + # + # @param query [String, nil] + # @return [Hash, nil] + def decode(query) = Faraday::NestedParamsEncoder.decode(query) + + # The value to write first for a Hash that follows another in a list, so + # that Rails begins a new element with it: one the element before has a + # place for as well, named by the keys that lead to it. + # + # A plain value, reached through Hashes alone. The pair that writes it + # names every key on the way down, and Rails begins a new element where + # the element it is filling has all of them already. A value inside a + # list never begins one, whatever the element before holds. + # + # @param element [Hash] + # @param previous [Object] the element before it + # @return [Array, nil] the keys leading to the value, outermost first. + # nil where no value will do, and where none is needed: the element is + # the first, or follows something that is not a Hash, and begins a new + # one whatever is written first + def lead_path(element, previous) + return nil if !previous.is_a?(Hash) + + sorted_keys(element).each do |key| + # Taken in the element before only where something was written for + # it there. A Hash with no value in it is not written, so the key is + # missing from what Rails read, and a pair naming it is read into + # that element rather than beginning the next. + next if !previous.key?(key) || !written?(previous[key]) + + value = element[key] + next if value.is_a?(Array) + return [key] if !value.is_a?(Hash) + + inner = lead_path(value, previous[key]) + return [key, *inner] if inner + end + + nil + end + + # Why Rails could not read an element of a list back as it was written, + # where it could not. + # + # +:merged+ is a Hash it would read into the Hash before it, there being + # no value to begin a new element with. +:empty+ is a Hash nothing is + # written for, which leaves the list one element short. +:list+ is a + # list directly inside a list: both are written `[]`, and each value of + # the inner one is read as a list of its own. + # + # @param element [Object] + # @param previous [Object] the element before it, nil for the first + # @return [Symbol, nil] nil for an element that is read back as it was + def misread(element, previous) + return :list if element.is_a?(Array) + return nil if !element.is_a?(Hash) + return :empty if !written?(element) + + :merged if previous.is_a?(Hash) && lead_path(element, previous).nil? + end + + # Whether anything is written for a value. Nothing is for a Hash with + # nothing in it, or with nothing but such Hashes in it, so as an element + # of a list it is not there for Rails to read. + # + # @return [Boolean] + def written?(value) = !value.is_a?(Hash) || value.each_value.any? { written?(it) } + + # @param lead [Array, nil] the keys leading to the value to write first + # @return [Array] one pair per value, in the order + # they are written + def hash_pairs(prefix, hash, lead) + keys = sorted_keys(hash) + keys = [lead.first, *(keys - [lead.first])] if lead + + keys.flat_map do |key| + # The rest of the way to the value, for the key that leads to it. + inner = lead && key == lead.first && lead.size > 1 ? lead.drop(1) : nil + + value_pairs(prefix ? "#{prefix}[#{key}]" : key.to_s, hash[key], inner) + end + end + + def value_pairs(path, value, lead = nil) + case value + when Hash then hash_pairs(path, value, lead) + when Array then array_pairs("#{path}[]", value) + else [[path, value]] + end + end + + def array_pairs(path, array) + # A list with nothing in it is written as its name alone, which is what + # Faraday wrote for one. + return [[path, nil]] if array.empty? + + array.each_with_index.flat_map do |element, index| + next value_pairs(path, element) if !element.is_a?(Hash) + + hash_pairs(path, element, index.zero? ? nil : lead_path(element, array[index - 1])) + end + end + + def sorted_keys(hash) = hash.keys.sort_by(&:to_s) + end +end diff --git a/lib/zammad_api/resource_proxy.rb b/lib/zammad_api/resource_proxy.rb new file mode 100644 index 0000000..a830b1c --- /dev/null +++ b/lib/zammad_api/resource_proxy.rb @@ -0,0 +1,611 @@ +# frozen_string_literal: true + +require 'forwardable' + +require_relative 'collection' +require_relative 'deep_copy' +require_relative 'duplicate_keys' +require_relative 'errors' +require_relative 'transport' + +module ZammadAPI + # Entry point for working with one kind of Zammad record. + # + # Obtained from {Client}, e.g. +client.tickets+, and exposes the operations + # that are not tied to an individual record. + # + # @example + # client.groups.find(1) + # client.groups.create(name: 'Support') + # client.groups.all.each { |group| puts group.name } + # client.groups.order(:name).first(5) + # client.groups.search('support').first + # + # A proxy is +Enumerable+ over {#all}, so the collection surface is reachable + # without naming it: + # + # @example + # client.groups.each { |group| puts group.name } + # client.groups.first(5) + # client.groups.map(&:name) + # client.groups.find_each(batch_size: 500) { |group| archive(group) } + # + # {#find} takes an id and is not +Enumerable#find+; +detect+ is still the + # block form. + class ResourceProxy + include Enumerable + extend Forwardable + + # Largest page size Zammad's search endpoints serve, from + # ApplicationController#model_search_render. + SEARCH_MAX_PER_PAGE = 200 + + # What every one of Zammad's search endpoints narrows by besides the term: + # the two parameters that CanSearch, the part all of them share, reads out + # of the call ApplicationController#model_search_render makes into + # Model.search. Unlike an index endpoint a search does narrow, but through + # these parameters and the term - never through an attribute name of its + # own. + # + # That call hands over +role_ids+, +group_ids+ and +permissions+ as well, + # and they used to be in this list for it. Only the user search reads + # them, so a resource says which of them its search takes: see + # {Resources::Base.search_filters}. + SEARCH_FILTER_KEYS = %i[condition ids].freeze + + # Why a search term with nothing in it is refused, and what to write + # for the answer Zammad would have given it: see {#search}. + BLANK_TERM_MESSAGE = 'search needs a non-empty query string: Zammad reads a blank one as no term at all and answers with ' \ + "every record. Search for '*' to ask for every record." + + # Said at the end of the error for sorting an index endpoint that is + # always served in id order, on a resource that can be searched. + SEARCHABLE_UNSORTABLE_HINT = 'A search does sort: search(term).order(...). Or sort what this collection yields, with sort_by { ... }.' + + # The same, for a resource Zammad routes no search endpoint for. + UNSORTABLE_HINT = 'Sort what this collection yields instead, with sort_by { ... }.' + + # @return [Class] the resource class this proxy operates on + attr_reader :resource_class + + # @api private + def initialize(transport, resource_class) + @transport = transport + @resource_class = resource_class + end + + # Builds an unsaved record. + # + # @param attributes [Hash] + # @return [Resources::Base] + def new(attributes = {}) + resource_class.new(@transport, attributes) + end + + # Builds and immediately saves a record. + # + # This raises when Zammad rejects the attributes, rather than handing back + # a record that looks created but is not. Use +new+ and + # {Resources::Base#save} to branch on a validation failure instead. + # + # @param attributes [Hash] + # @return [Resources::Base] + # @raise [ResponseError] when Zammad rejected the request + def create(attributes = {}) + record = new(attributes) + record.save! + record + end + + # Fetches a single record by id. + # + # @param id [Integer, String] + # @return [Resources::Base] + # @raise [NotFoundError] when no such record exists + def find(id) = resource_class.fetch_one(@transport, id) + + # Fetches the first record carrying all of these attribute values, from + # the candidates Zammad hands over: nil if none of them does. + # + # It answers for every resource and every kind of value. Where it walks + # the index, the candidates are every record this client can read, and nil + # means there is no such record. Where it searches, they are the hits, and + # nil means no hit carried the values - which is the same thing only for a + # value the search looks at. See "What the search can surface" below for + # which those are. Zammad cannot be asked the question directly - + # its index endpoints do not filter: ApplicationController#model_index_render + # sorts and pages and drops every other parameter, so a query parameter on + # the index, which is how this was first written, asked for + # +email=someone@example.com+ and got back the whole user index, of which + # it returned the first record. So the candidates are fetched and checked + # here, and there are two ways to fetch them: + # + # - A search, where the resource has a search endpoint and one of the + # values is a string to search on. That is the cheap way: Zammad narrows + # the candidates, and only the hits are read. + # - A walk of the index, everywhere else: +ticket_states+, + # +ticket_priorities+ and +ticket_articles+, which Zammad routes no + # search endpoint for, and a lookup such as +find_by(active: true)+ or + # +find_by(organization_id: 5)+ that has no string in it. That costs a + # request per page of records until one matches, and the whole index for + # a miss - nothing for a list of ticket states, and worth knowing before + # it is run against every ticket on an instance. + # + # Both used to be refused instead: a resource without a search endpoint + # raised, and so did a lookup without a string value. The caller was left + # to write +all.detect { ... }+, which is the walk this now makes, so the + # refusals kept nothing from happening and made +find_by+ a method that + # worked on four resources out of seven. + # + # Values are compared exactly, and against the record as Zammad stores it: + # +find_by(email: 'Someone@Example.com')+ does not match a login Zammad + # downcased. A record that does not carry an attribute does not match it, + # whatever the value - not even +nil+, which would otherwise match every + # record a misspelled name was asked of. + # + # The search term is one string value. Zammad searches by word, so a value + # of another type would go out as the word it prints as: +find_by(active: + # true)+ searched for "true" and matched records carrying that word, which + # is essentially none of them. Such a value is compared here instead. + # + # One value, never all of them joined. An instance searching without + # Elasticsearch matches the term literally, through a SQL LIKE over the + # string columns, so a joined term asks every column to contain the whole + # of it: +find_by(firstname: 'Jane', lastname: 'Doe')+ went out as "Jane + # Doe" and no column of Jane Doe's holds that, so a user that exists came + # back as nil and the +find_by(...) || create(...)+ this documents made a + # duplicate on every run. Single-attribute lookups were unaffected, which + # is why it stood. The longest value goes out, as the most selective of + # them, and every other value is compared here - which is where the + # non-string ones are compared anyway, so +find_by(email: ..., active: + # true)+ searches the email and then checks both. + # + # Values go out as they are. Quoting one that carries search syntax, so + # that it is looked for rather than obeyed, sounds like an improvement and + # is not: an instance searching without Elasticsearch matches the term + # literally, through a SQL LIKE over the string columns, so the quotes + # become characters the value has to contain. That made + # +find_by(name: 'support-eu')+ - a hyphen is syntax - find nothing on + # every such instance, which is how this was found. + # + # So a value carrying syntax is searched as syntax, and what that surfaces + # depends on the backend. On Elasticsearch +find_by(note: 'a AND b')+ goes + # out as a boolean query, and a value Elasticsearch cannot parse at all - + # an unbalanced +(+ or +"+ - takes SearchIndexBackend#search_by_index down + # the branch that logs the error and returns no hits, so it arrives here + # as a miss rather than as a failure. + # + # What the search can surface is Zammad's business. A value the instance + # has not indexed, or cannot index, is a record this does not find, so + # +find_by(...) || create(...)+ can still create a duplicate - exactly as + # writing the search out by hand would. + # + # Which values those are depends on the backend. Elasticsearch looks for + # the term in everything a record is indexed with. Without it the term is + # matched by the SQL LIKE mentioned above, and that reads a fixed set of + # columns: CanSearch takes the string columns of the model's own table, + # which covers users, organizations and groups, and Ticket::Search + # replaces that with the ticket's title and number and the from, to, + # subject and body of its articles. A name +expand+ adds for an + # association is not a column at all. So on such an instance + # +tickets.find_by(state: 'open')+, a ticket looked up by a custom + # attribute, and +users.find_by(organization: 'Acme')+ are searches for a + # word in fields that do not hold the value. They find the record only + # where the word happens to appear in one of those fields too, and + # otherwise answer nil for a record that exists. + # + # There is no walk of the index after a search that found nothing, which + # would close that gap. A miss is the ordinary case for what this is most + # used for - +find_by(email: ...) || create(...)+ on an address that is + # new - and the walk would turn each of them into a read of every user on + # the instance, a thousand to the request, to confirm what the search had + # already said correctly. Nothing here can tell that miss from one caused + # by a field the search does not read, because nothing in a response says + # which backend answered. The caller does know which lookup they are + # writing: +detect { ... }+ on the resource is the walk, over every + # record this client may read. Compared with +[]+ there, as it is below, + # because a reader raises for an attribute the record in hand does not + # carry and would end the walk on it. + # + # Every page of hits is read until one matches. Only the first + # {SEARCH_MAX_PER_PAGE} used to be, to keep a miss at one request, on the + # premise that hits come back by relevance and an exact match is at the + # top of them or nowhere. They do not: Zammad's search endpoints sort by + # +updated_at+, newest first, unless told otherwise, on the SQL path and + # the Elasticsearch one alike. So where more than a page of records + # matched the term - +find_by(name: 'Support')+ among a few hundred + # organizations with "Support" in their name - the one called exactly + # that could sit on any page, +find_by+ answered +nil+ for a record that + # exists, and +find_by(...) || create(...)+ created its duplicate. + # + # So a match costs as many requests as it takes to reach it, and a miss + # costs one per page of hits. The longest value is searched to keep + # those few. + # + # @example + # client.users.find_by(email: 'someone@example.com')&.id + # client.ticket_states.find_by(name: 'open') + # client.users.find_by(organization_id: 5, active: true) + # + # @param params [Hash] attribute names and the values to match exactly + # @return [Resources::Base, nil] nil when nothing matched + # @raise [ArgumentError] when no attribute was given + def find_by(**params) + raise ArgumentError, 'find_by needs at least one attribute to match' if params.empty? + + term = resource_class.searchable? ? search_term_for(params) : nil + candidates = term ? search(term) : all + + candidates.detect { |record| params.all? { |key, value| record.key?(key) && record[key] == value } } + end + + # Fetches the first record carrying all of these attribute values, raising + # when nothing matched. + # + # @param params [Hash] attribute names and the values to match exactly + # @return [Resources::Base] + # @raise [NotFoundError] when nothing matched + # @see #find_by + def find_by!(**params) + find_by(**params) || raise( + NotFoundError.new( + operation: "find object by #{params.keys.join(' and ')}", + resource_class: resource_class, + detail: 'no record matched' + ) + ) + end + + # Whether a record with this id exists. + # + # This costs one request, and reads the record to find out, because Zammad + # has no cheaper answer for a single id. + # + # @param id [Integer, String] + # @return [Boolean] + def exists?(id) + find(id) + true + rescue NotFoundError + false + end + + # Deletes a record by id, without fetching it first. + # + # @param id [Integer, String] + # @return [true] + # @raise [ResponseError] when Zammad rejected the request + def destroy(id) + @transport.delete(member_path(id), operation: 'destroy object', resource_class: resource_class) + true + end + + # Every record of this kind, as a lazily paginated collection. + # + # @return [Collection] + def all + collection(path, 'get .all of object') + end + + # @!group Collection shorthands + + # Everything below forwards to {#all}, the {Collection} that decides for + # itself what a missing block means and what a page size is measured + # against. + # + # Named once rather than written out one +def+ at a time. Each was a body + # that did nothing but pass its arguments on, and three carried a + # +steep:ignore+ because forwarding into {Collection}'s with-block and + # without-block overloads cannot be resolved - forwarded by name there is + # no call site left to resolve. What callers are checked against is + # sig/zammad_api/resource_proxy.rbs, where each of these is declared with + # the types {Collection} gives it. + + # @!method order(*attributes, **directions) + # Every record of this kind, sorted by the server. Shorthand for + # +all.order(...)+. + # @example + # client.groups.order(:name) + # client.organizations.order(name: :desc) + # @param attributes [Array] attributes to sort by, + # ascending + # @param directions [Hash{Symbol => Symbol, String}] attributes to sort + # by, each with +:asc+ or +:desc+ + # @return [Collection] + # @raise [ArgumentError] for a resource whose index endpoint does not + # sort + # @see Collection#order + + # @!method each(&block) + # Yields every record of this kind, fetching pages as needed. + # + # This is what makes a proxy +Enumerable+, so +first+, +map+, +lazy+ + # and the rest work straight off +client.groups+. + # @yieldparam record [Resources::Base] + # @return [Enumerator] when no block is given + # @see Collection#each + + # @!method find_each(batch_size: nil, &block) + # @param batch_size [Integer, nil] records fetched per request + # @yieldparam record [Resources::Base] + # @return [Enumerator] when no block is given + # @see Collection#find_each + + # @!method in_batches(of: nil, &block) + # @param of [Integer, nil] records fetched per request + # @yieldparam records [Array] + # @return [Enumerator] when no block is given + # @see Collection#in_batches + + # @!method page(number, per_page: nil) + # @param number [Integer] one-based page number + # @param per_page [Integer, nil] records on the page, as many as the + # endpoint serves by default + # @return [Collection] + # @see Collection#page + + # @!method pluck(*keys) + # @param keys [Array] attribute names + # @return [Array] + # @see Collection#pluck + + # @!method count(*args, &block) + # Overrides +Enumerable#count+ so that a collection counts the way it + # knows how. + # @return [Integer] + # @see Collection#count + + # @!method size + # @return [Integer] + # @see Collection#size + + # @!method length + # @return [Integer] + # @see Collection#size + + # @!method empty? + # @return [Boolean] + # @see Collection#empty? + + # @!method first(count = nil) + # Overrides +Enumerable#first+ so that it reads one sized page rather + # than taking records off the front of one sized for walking. + # @param count [Integer, nil] how many records to read + # @return [Resources::Base, Array, nil] + # @see Collection#first + + # @!method take(count) + # @param count [Integer] how many records to read + # @return [Array] + # @see Collection#take + + def_delegators :all, :order, :each, :find_each, :in_batches, :page, :pluck, :count, :size, :length, :empty?, :first, :take + + # @!endgroup + + # Records matching a Zammad search term, as a lazily paginated collection. + # + # The keywords are the other things a search endpoint narrows by. They + # are named here, on the call that searches, because they mean nothing + # anywhere else: they used to be passed to +where+ on the collection this + # returns, the one place that method accepted more than a sort. + # + # Anything else is refused rather than sent. Zammad drops a parameter it + # does not know, so +search('smith', active: true)+ would come back + # unnarrowed and nothing would say so. An attribute value belongs in the + # term, and a sort in {Collection#order}. + # + # That goes for a keyword another resource's search reads, too. + # +role_ids:+, +group_ids:+ and +permissions:+ narrow a user search and no + # other, and +client.tickets.search('printer', group_ids: [2])+ was sent + # as written and answered with tickets from every group the client can + # read. Tickets are narrowed by group through a +condition+ on + # +ticket.group_id+. + # + # +group_ids:+ comes in two forms, and they do not ask for the same + # thing. User::Search walks it as pairs of a group and an access, and + # HasGroups.group_access reads an access that is missing as +full+. So a + # list of ids, which names none, is the agents with full access to those + # groups, and +group_ids: [2]+ leaves out an agent who may only read + # group 2. A Hash names the access for each group, and +full+ always + # counts as having it: +group_ids: {2 => ['read']}+ is every agent with + # read or full access to group 2. + # + # A keyword with nothing in it is refused as well: an empty list, an + # empty Hash, a blank String. Zammad reads each of those as the keyword + # not having been given, the way it reads one it does not know. CanSearch + # narrows by +ids+ only where +params[:ids].present?+, so + # +search('smith', ids: allowed_ids)+ with no id allowed came back with + # every user matching the term, where the caller had asked for none of + # them. +role_ids+, +group_ids+ and +permissions+ are skipped the same + # way where the search runs through Elasticsearch, and an empty + # +condition+ does not reach the request at all. + # + # +permissions:+ is not an access check, and is sent as it is given all + # the same, because what it does is Zammad's to decide. User::Search + # resolves it to the roles granting one of the permissions and adds them + # to +role_ids+, so the two together widen each other. On the + # Elasticsearch path the role clause is then written only where there is + # a role to put in it: a permission no active role grants - a misspelt + # one, or one nobody has been given - resolves to none, the clause is + # left out, and the search answers with every user matching the term. + # The SQL path joins the roles against the empty list and answers with + # nobody. Nothing in a response says which path answered, and a user + # record carries role ids rather than permissions, so there is nothing + # here to check the hits against. +role_ids:+ with at least one id + # narrows on both paths. + # + # +role_ids:+ is no access check either. Both paths ask who holds the + # role - the SQL one joins the roles a user has, the Elasticsearch one + # matches the role ids a user is indexed with - and neither asks whether + # the role is active, which is what Zammad asks before it grants + # anything through one: Role.with_permissions leaves a disabled role + # out. Neither asks whether the user is active. So a user matches a role + # that grants nothing any more, and the hits are who to look at, not who + # may. + # + # @example + # client.users.search('smith') + # client.users.search('smith', role_ids: [2]) + # client.users.search('smith', group_ids: [2]) # full access to group 2 + # client.users.search('smith', group_ids: {2 => ['read']}) # read or full access to it + # client.tickets.search('printer', condition: {'ticket.state_id' => {operator: 'is', value: [1, 2]}}) + # client.tickets.search('state.name:open').order(created_at: :desc) + # + # A term with nothing in it is refused: Zammad reads it as no term, and + # answers with every record the filters and the account allow, which is + # what a search for a blank +params[:q]+ ought not to come back with. + # Nothing is what Rails calls blank, Unicode spaces included. `'*'` + # asks for that answer in so many words, which is how Zammad's own + # interface lists every user or organization, and is sent. + # + # @param term [String] the Zammad search term, `'*'` for every record + # @param filters [Hash] +condition:+ and +ids:+ on every search, and on + # users +role_ids:+, +permissions:+ and +group_ids:+ - the last as a + # list of group ids, for agents with full access to them, or as a Hash + # of group id to +read+, +create+, +change+, +overview+ or +full+, one + # or several + # @return [Collection] + # @raise [ArgumentError] when +term+ is not a non-empty string, or for a + # keyword the search endpoint does not read, a nil value, a keyword + # with nothing in it, two spellings of one key, or a list a query + # string cannot carry: see {Transport.stringify_query_list} + # @raise [Error] when Zammad routes no search endpoint for this resource + def search(term, **filters) + searchable! + raise ArgumentError, BLANK_TERM_MESSAGE if !term.is_a?(String) || Transport::BLANK.match?(Transport.wire_text(term, 'the search term')) + + collection( + "#{path}/search", + 'get .search of object', + # A copy of the term and the filters, taken here. The collection is + # lazy, so it reads them when it is enumerated, and it was reading the + # caller's own objects: `search('printer', ids: ids)` followed by + # `ids << 7`, or a term built up in a buffer that is then reused, + # searched for something other than what this call was given - after + # it had been checked, and with the collection already handed on. + query: DeepCopy.frozen_copy({ query: term }.merge(search_filters(filters))), + max_per_page: SEARCH_MAX_PER_PAGE, + sortable: true, + search: true + ) + end + + def inspect = "#<#{self.class.name} #{resource_class.name}>" + + private + + def collection(path, operation, query: {}, max_per_page: resource_class.page_limit, sortable: resource_class.sortable?, search: false) + Collection.new( + transport: @transport, + resource_class: resource_class, + path: path, + operation: operation, + max_per_page: max_per_page, + sortable: sortable, + unsortable_hint: resource_class.searchable? ? SEARCHABLE_UNSORTABLE_HINT : UNSORTABLE_HINT, + search: search, + query: { expand: true }.merge(query) + ) + end + + # The keywords of a search, checked at the call that wrote them. + # + # Through {Transport.stringify_query} for the refusals it makes at any + # depth - a nil value, two spellings of one key inside a +condition+, + # and a list of conditions a query string cannot keep apart - because + # left to the request they would be reported when the collection is + # first enumerated, some lines away from the search that wrote them. + # What it returns is what each keyword is asked about below, and not what + # is sent: the collection sends the values as they were given - a copy of + # them, see {#search} - and the transport stringifies them then, the + # same way. + # + # @return [Hash{Symbol => Object}] + # @raise [ArgumentError] + def search_filters(filters) + normalized = DuplicateKeys.normalize(filters) { it.to_s.to_sym } + unknown = normalized.keys - search_filter_keys + raise ArgumentError, unknown_search_filter_message(unknown) if !unknown.empty? + + sent = Transport.stringify_query(normalized) + empty = normalized.select { |name, _| empty_search_filter?(sent.fetch(name.to_s)) } + raise ArgumentError, empty_search_filter_message(empty) if !empty.empty? + + normalized + end + + # Whether Zammad would read a keyword's value as the keyword not having + # been given: what Rails calls blank, asked of the value as it goes on + # the wire. Asked of that and not of the value as given, because a + # Symbol or anything else with an empty +to_s+ is sent as an empty + # String, and a Hash that holds nothing but empty Hashes is not written + # at all - `condition: {'ticket.state_id' => {}}` left the request + # without a +condition+. + # + # Asked of the keyword's own value and not of what is nested in it - a + # +condition+ naming an attribute with an empty +value+ is a selector, + # and what that selects is Zammad's to say. An empty list is written, + # so a Hash holding one is not empty here. + # + # Blank as Rails reads it, Unicode spaces included: see + # {Transport::BLANK}. + # + # @param value [String, Array, Hash] as {Transport.stringify_query} + # leaves it + def empty_search_filter?(value) + case value + when String then Transport::BLANK.match?(value) + when Array then value.empty? + else !QueryEncoder.written?(value) + end + end + + def empty_search_filter_message(empty) + given = empty.map { |name, value| "#{name}: #{value.inspect}" }.join(', ') + + "search was given #{given} on #{path}, and Zammad reads a keyword with nothing in it as one that was not given: " \ + 'the search would come back with everything matching the term, not narrowed to nothing. ' \ + 'Leave the keyword out to search without it, and skip the search where there is nothing it may find.' + end + + # What the search endpoint of this resource narrows by besides the term. + # + # @return [Array] + def search_filter_keys = SEARCH_FILTER_KEYS + resource_class.search_filter_names + + def unknown_search_filter_message(unknown) + "search does not take #{unknown.join(', ')} on #{path}: this search endpoint narrows by the term, and by #{search_filter_keys.join(', ')}, " \ + 'and drops anything else, which would hand back an unnarrowed search. ' \ + "Put an attribute value in the term - search('state.name:open') - or in a condition - " \ + "search(term, condition: {'ticket.group_id' => {operator: 'is', value: [2]}}) - " \ + 'sort with search(term).order(...), and page with page, in_batches or find_each.' + end + + # Zammad routes a search endpoint per model, not for every model: users, + # organizations, tickets and groups have one, ticket states, ticket + # priorities and ticket articles do not. Asking one of the latter for + # `.../search` is a 404, which would arrive as a NotFoundError about a + # record from a call that asked for a list. + def searchable! + return if resource_class.searchable? + + raise Error, "Zammad routes no search endpoint for #{resource_class.name}, so it cannot be searched by term: #{path}/search answers 404, which would arrive here as a NotFoundError about a record. Look one record up by attribute value with find_by, which walks the records where it cannot search, or pick several out with select { ... }." + end + + # The one value {#find_by} searches on: the longest, as the most selective + # of them, which matters because a miss reads every page of hits. + # + # One value rather than all of them joined, and unquoted - both spellings + # find nothing on an instance without Elasticsearch, for the same reason. + # See {#find_by}. + # + # @return [String, nil] nil when no value can be searched on, in which + # case the index is walked instead + def search_term_for(params) = params.values.grep(String).reject { it.strip.empty? }.max_by(&:length) + + def path = resource_class.resource_path + + def member_path(id) = resource_class.member_path(id) + end +end diff --git a/lib/zammad_api/resources.rb b/lib/zammad_api/resources.rb index 8106a4d..f388c7d 100644 --- a/lib/zammad_api/resources.rb +++ b/lib/zammad_api/resources.rb @@ -1,17 +1,17 @@ -require 'zammad_api/list_base' -require 'zammad_api/list_all' -require 'zammad_api/list_search' -require 'zammad_api/resources/base' -require 'zammad_api/resources/user' -require 'zammad_api/resources/group' -require 'zammad_api/resources/organization' -require 'zammad_api/resources/ticket' -require 'zammad_api/resources/ticket_article' -require 'zammad_api/resources/ticket_article_attachment' -require 'zammad_api/resources/ticket_state' -require 'zammad_api/resources/ticket_priority' +# frozen_string_literal: true + +require_relative 'resources/base' +require_relative 'resources/group' +require_relative 'resources/organization' +require_relative 'resources/ticket' +require_relative 'resources/ticket_article' +require_relative 'resources/ticket_article_attachment' +require_relative 'resources/ticket_priority' +require_relative 'resources/ticket_state' +require_relative 'resources/user' module ZammadAPI - class Resource # rubocop:disable Lint/EmptyClass + # Namespace for the Zammad record classes. + module Resources end end diff --git a/lib/zammad_api/resources/base.rb b/lib/zammad_api/resources/base.rb index 2652c4d..b82317e 100644 --- a/lib/zammad_api/resources/base.rb +++ b/lib/zammad_api/resources/base.rb @@ -1,140 +1,975 @@ -require 'cgi' -require 'zammad_api/json_helper' -require 'zammad_api/transport' +# frozen_string_literal: true + +require_relative '../associations' +require_relative '../attribute_access' +require_relative '../deep_copy' +require_relative '../errors' +require_relative '../transport' module ZammadAPI module Resources + # Shared behaviour for every Zammad record. + # + # Attributes are read and written through +method_missing+, because Zammad + # records can carry administrator-defined custom attributes: + # + # group = client.groups.find(1) + # group.name # read + # group.name = 'Support' # stage a change + # group.changed? # => true + # group.save # persist class Base - include ZammadAPI::JsonHelper - extend ZammadAPI::JsonHelper + include AttributeAccess - attr_accessor :new_instance, :url, :attributes - attr_reader :changes + # Largest page size Zammad's generic index endpoints serve, from + # ApplicationController#model_index_render via CanPaginate. Resources + # whose endpoint caps lower declare +max_per_page+. + DEFAULT_MAX_PER_PAGE = 1000 - def initialize(transport, attributes = {}) - @new_instance = true - @transport = transport - @changes = {} - @url = self.class.get_url + # Guards the class-level memos on the singleton below. One lock for every + # resource, because it is held only while a memo is first built. + MEMO_LOCK = Mutex.new + private_constant :MEMO_LOCK + + # Staged changes as +attribute => [old_value, new_value]+. + # + # A copy, and frozen: writing to the change set a record hands out would + # decide what the next +save+ sends. + # + # @return [Hash{Symbol => Array(Object, Object)}] + def changes = @changes.dup.freeze - if attributes.nil? - attributes = {} + # The validation failure from the most recent {#save}, so that a +false+ + # return value can be acted on. Cleared when the next save is attempted, + # so it never describes anything but the most recent one. + # + # @return [ValidationError, nil] + attr_reader :error + + # @api private + attr_reader :transport + + class << self + # Declares the API path of this resource, relative to the instance URL. + # + # @param value [String] + # @return [void] + def path(value) + @path = value + end + + # Declares that Zammad routes a +/search+ endpoint for this resource. + # + # Declared rather than assumed, and false unless a resource says + # otherwise: an unrouted `.../search` answers 404, which arrives as a + # NotFoundError from inside {ResourceProxy#find_by} - a method + # documented to return nil when nothing matched. A resource that + # forgets to declare this is refused at the call site instead, which + # is a question about the resource rather than a wrong answer about a + # record. + # + # @param value [Boolean] + # @return [void] + def searchable(value) + @searchable = value + end + + # Declares what this resource's search endpoint narrows by, besides + # the term and the two filters every search reads. + # + # Every search endpoint goes through + # ApplicationController#model_search_render, which hands the same + # parameters to the search of whichever model it was asked for. What + # that search does with them is the model's own business. +condition+ + # and +ids+ are read by the part all of them share, CanSearch, and + # need no declaring. +role_ids+, +group_ids+ and +permissions+ are + # read by User::Search and by no other: a ticket search handed + # +group_ids+ takes it, drops it and answers unnarrowed, on the SQL + # path and the Elasticsearch one alike. + # + # Declared rather than accepted everywhere, so that + # {ResourceProxy#search} can refuse a keyword this resource's search + # would drop - the same refusal it makes for a keyword no search + # reads at all. + # + # @param names [Array] + # @return [void] + def search_filters(*names) + @search_filters = names.map(&:to_sym).freeze + end + + # Declares the largest page size this resource's index endpoint + # serves. + # + # @param value [Integer] + # @return [void] + def max_per_page(value) + @max_per_page = value end - @attributes = attributes - symbolize_keys_deep!(@attributes) - end - def method_missing(method, *args) - return @attributes[method] if !method.to_s.end_with?('=') + # Declares whether this resource's index endpoint sorts. + # + # ApplicationController#model_index_render builds its query as + # `reorder(order_sql).offset(...).limit(...)`: it reads +sort_by+ and + # +order_by+, pages, and drops every other parameter. That is the + # default, so a resource says nothing. One whose controller hardcodes + # the order declares +sortable false+, and {Collection#order} then + # refuses it rather than handing back records it would be calling + # sorted. + # + # There is no attribute filtering on an index endpoint at all; that + # is what /search is for. + # + # @param value [Boolean] + # @return [void] + def sortable(value) + @sortable = value + end + + # @return [String] the API path of this resource + def resource_path + declaration(:path) || raise(Error, "#{name} does not declare an API path") + end + + # @return [Boolean] whether Zammad routes a +/search+ endpoint here + def searchable? = declaration(:searchable) { false } + + # @return [Array] what this resource's search endpoint narrows + # by besides the term, +condition+ and +ids+ + def search_filter_names + declaration(:search_filters) do + [] #: Array[Symbol] + end + end + + # @return [Integer] the largest page size this endpoint serves + def page_limit = declaration(:max_per_page) { DEFAULT_MAX_PER_PAGE } + + # @return [Boolean] whether this resource's index endpoint reads + # +sort_by+ and +order_by+ + def sortable? = declaration(:sortable) { true } + + # The API path of one record of this kind. + # + # The id is escaped rather than interpolated, so that one taken from a + # request parameter cannot walk out of its segment into another + # endpoint. Held here because {ResourceProxy} builds this path too, + # from an id a caller handed it, and an escaping rule kept in two + # places is one that gets changed in one of them. + # + # @api private + # @param id [Integer, String] + # @return [String] + # @raise [ArgumentError] when the id cannot go into a path segment + def member_path(id) = "#{resource_path}/#{Transport.escape_path_segment(id)}" + + # Reads one record by id. + # + # On the resource rather than on {ResourceProxy}, because both callers + # of it need a proxy for nothing else: {ResourceProxy#find} has one, + # and {Associations::Proxy} was building a throwaway per association + # read until it grew a second copy of this instead. The resource + # already knows its member path and how to build itself from a body, + # which is the whole of the read. + # + # @api private + # @param transport [Transport] + # @param id [Integer, String] + # @return [Base] + def fetch_one(transport, id) + operation = 'find object' + response = transport.get( + member_path(id), + operation: operation, + resource_class: self, + query: { expand: true } + ) + from_response(transport, response.decoded(:object, operation: operation, resource_class: self)) + end - method = method.to_s[0, method.length - 1].to_sym - @changes[method] = [@attributes[method], args[0]] - @attributes[method] = args[0] - nil + # Builds a record that is already stored in Zammad. + # + # Straight to the state, past the constructor's refusal of attributes + # a caller may not stage. Zammad serves +id+ in every body it answers + # with, and +id+ is the one attribute that refusal exists for. + # + # @api private + # @param transport [Transport] + # @param attributes [Hash] + # @return [Base] + def from_response(transport, attributes) + record = allocate + record.send(:setup, transport, attributes) + record.send(:mark_persisted!) + record + end + + # Every association declared on this resource, including inherited + # ones. + # + # @return [Hash{Symbol => Hash}] + def associations + ancestors + .select { it.respond_to?(:declared_associations, true) } + .reverse + .inject({}) { |result, ancestor| result.merge(ancestor.send(:declared_associations)) } + end + + # The attributes a +belongs_to+ reader resolves through, so that + # writing one can drop the record it had already resolved to. + # + # Both of the class-level memos here are built under one lock, because + # a plain `@x ||=` is a write to shared state that two threads can + # reach at once: on JRuby or TruffleRuby each could see the ivar unset + # and build a different anonymous proxy class for the same resource, + # and whichever write lost would still be held by the records already + # built from it. + # + # Populating them eagerly was the earlier answer, first on first use, + # then in `Client#setup`, then at require time. Each move shrank the + # window without closing it: `Client.new` is itself something two + # threads can call, and a resource a caller subclasses themselves - + # `class MyTicket < Ticket; end`, which this gem supports - is never in + # any list built ahead of time. + # + # The unlocked read first, so the settled case stays a plain ivar read: + # this is asked on every attribute write, and a lock on that path would + # cost far more than the one build it guards. + # + # @api private + # @return [Array] + def belongs_to_foreign_keys + @belongs_to_foreign_keys || MEMO_LOCK.synchronize { @belongs_to_foreign_keys ||= associations.filter_map { |_, spec| spec[:foreign_key] if spec[:type] == :belongs_to } } + end + + # The class carrying this resource's association readers, reached + # through {Base#related}. + # + # @api private + # @return [Class] + def related_class + return @related_class if @related_class + + # A resource's proxy inherits its parent's readers, so Base's + # created_by and updated_by reach every resource. The parent is + # resolved before the lock is taken, because resolving it may build + # the parent's own proxy through this same method and a Mutex is not + # reentrant. + parent = superclass.respond_to?(:related_class) ? superclass.related_class : Associations::Proxy # steep:ignore NoMethod + MEMO_LOCK.synchronize { @related_class ||= Class.new(parent) } + end + + private + + # Reads a declaration from this class, or failing that from the + # resource it inherits from. + # + # A plain class-level ivar is not inherited, so `class MyTicket < + # Ticket; end` used to inherit all nine of Ticket's associations, its + # page limit and its searchability, and lose only its API path - + # `MyTicket.resource_path` raised "does not declare an API path" from + # a class that plainly did. {.associations} and {.related_class} both + # walk the ancestry deliberately; these read through the same way. + # + # `instance_variable_defined?` rather than a truth test, so that a + # resource may declare a value that is false or nil and have it + # override an inherited one. + def declaration(name, &default) + variable = :"@#{name}" + return instance_variable_get(variable) if instance_variable_defined?(variable) + return superclass.send(:declaration, name, &default) if superclass.respond_to?(:declaration, true) + + default&.call + end + + def declared_associations = @declared_associations ||= {} + + # Declares that this resource points at a single other record, through + # a foreign key on itself. + # + # The reader lands on {Base#related}, not on the record, because Zammad + # already expands the association into a name under the plain + # attribute: +ticket.customer+ is a login, +ticket.related.customer+ is + # the User record. + # + # @param name [Symbol] name of the reader on {Base#related} + # @param class_name [String] the target resource, named rather than + # referenced so that two resources may point at each other. A + # resource of this gem by its own name, +'User'+; one a caller + # declared by its full name, +'Acme::Role'+ + # @param foreign_key [Symbol] attribute holding the target's id + # @return [void] + def belongs_to(name, class_name:, foreign_key: :"#{name}_id") + declared_associations[name] = { type: :belongs_to, class_name: class_name, foreign_key: foreign_key } + # The block runs against a Proxy instance, which the type checker + # cannot see through define_method. + related_class.define_method(name) { belongs_to_target(name, class_name, foreign_key) } # steep:ignore NoMethod + end + + # Declares that this resource points at a list of other records, + # served by an endpoint of its own. + # + # The path has to name an endpoint that serves the whole list in one + # response, which is what the association endpoints Zammad routes do: + # TicketArticlesController#index_by_ticket renders every article of + # the ticket and reads no paging parameter. The reader spends one + # request and hands back an Array rather than a walking {Collection}. + # + # Nothing here can tell a whole list from the first page of one, so + # declaring this for an endpoint that pages would return that page + # and no more. This comment used to promise a refusal instead. The + # check behind that promise read a total from a response header + # Zammad has never sent, so it never ran, and it was removed for that + # reason. For an endpoint that pages, declare a resource and walk it + # as a {Collection}. + # + # @param name [Symbol] name of the reader on {Base#related} + # @param class_name [String] the target resource + # @param path [Proc] called with the record id, already escaped for + # a path segment, and returns the API path + # @return [void] + def has_many(name, class_name:, path:) + declared_associations[name] = { type: :has_many, class_name: class_name, path: path } + related_class.define_method(name) { has_many_target(name, class_name, path) } # steep:ignore NoMethod + end end - def new_record? - @new_instance + # Zammad stamps every object with the user that created and last + # touched it. + belongs_to :created_by, class_name: 'User' + belongs_to :updated_by, class_name: 'User' + + # @param transport [Transport] + # @param attributes [Hash, nil] + # @raise [Error] when an attribute cannot be staged, such as +id+ + def initialize(transport, attributes = {}) + given = attributes || {} + # The same refusal the writers make, at the one door that did not make + # it. `group.id = 99` is refused with a sentence about what an id is + # for, and `client.groups.new(id: 99)` was accepted in silence - and + # then `save` POSTed `{"id": 99, ...}`, because a new record is sent in + # full. So the one spelling that reached the wire was the one nothing + # checked, and Zammad's answer to it was the first news of the + # mistake. {.from_response} is the way in for a body Zammad served, + # which carries an id precisely because it is a record that has one. + given.each { |key, value| refuse_unwritable!(DeepCopy.symbolize(key), value) } + setup(transport, given) end - def changed? - !@changes.to_h.empty? + # Gives a +dup+ or +clone+ the state of its own that a write changes. + # + # The attributes need nothing done: they are frozen and replaced on + # write, so a copy sharing them never sees the original's next write. + # The change set is written in place, and the copy shared it: after + # +copy = record.dup; copy.name = 'X'+ the original reported + # +changed?+ and a change to +name+ while still reading +name+ as it + # was, and its next +save+ sent the copy's value - a change it had + # never shown. + # + # The association proxy goes too. It reads through the record it was + # built for, so a copy holding the original's would resolve its + # associations from the original's foreign keys. + # + # @api private + # @param source [Base] + # @return [void] + def initialize_copy(source) + super + @changes = @changes.dup + @related = nil end - def destroy - response = @transport.delete(url: "#{@url}/#{@attributes[:id]}") - return true if response.status == 200 + # @return [Boolean] whether this record has not been stored yet + def new_record? = @new_record + + # Whether this record exists in Zammad. + # + # False both before the first save and after {#destroy}, so this is not + # the inverse of {#new_record?}. + # + # @return [Boolean] + def persisted? = !@new_record && !@destroyed + + # Whether {#destroy} removed this record from Zammad. + # + # The attributes stay readable, so a destroyed record can still be logged + # or reported on; it just no longer stands for anything on the server. + # + # @return [Boolean] + def destroyed? = @destroyed - raise ResponseError.from(response, operation: 'destroy object', resource_class: self.class) + # @return [Boolean] whether there are unsaved changes + def changed? = !@changes.empty? + + # The records this one points at, each fetched on demand. + # + # Zammad expands an association into a name under the plain attribute, + # so +ticket.customer+ is already the customer's login. These readers + # return the whole record instead, which costs a request. + # + # @example + # ticket.customer # => "customer@example.com", already loaded + # ticket.related.customer.email # => the same, from the User record + # ticket.related.articles # => [TicketArticle, ...] + # + # @return [Associations::Proxy] + # @raise [Error] when the record was destroyed + # @see .associations + def related + # Asked here rather than left to the request. `destroy` drops the memo, + # and that was taken to be the whole of it - but this reader rebuilds + # on the next call, so a destroyed record went on handing out a working + # proxy and `related.articles` fetched the articles of a ticket that is + # gone. Clearing a memo is not refusing a reader, and only the refusal + # is worth asserting: the spec that covered this compared proxy + # identity, so it passed throughout. + raise_if_destroyed!('read related records from') + # One proxy for as long as the record lives. What a save, a reload or + # a write to a foreign key invalidates is what the proxy has resolved, + # and {#forget_related_targets} empties that where it is held. + @related ||= self.class.related_class.new(self) + end + + # Stages several attributes as changes, without saving. + # + # @example + # group.assign_attributes(name: 'Support 2', note: 'Renamed') + # group.changed? # => true + # + # @param attributes [Hash] attribute names and their new values + # @return [self] + # @raise [Error] when an attribute cannot be staged, such as +id+, or + # when the record was destroyed. Nothing is staged in either case, so + # the record is left as it was. + def assign_attributes(attributes) + # rubocop:disable Style/CombinableLoops -- combining them is the bug + # Two passes on purpose: every key is checked before any of them is + # written. Combined, `assign_attributes(name: 'X', id: 9, note: 'Y')` + # staged the name, raised on the id and never reached the note, leaving + # the record dirty with half a change set - the state `update` takes + # its own guard one line early to avoid. + # + # `write_attribute` checks again for each key, because it is also the + # direct writer's own guard and cannot assume a caller came through + # here. That is a second Symbol comparison per attribute, which is not + # worth a bypass to avoid. + attributes.each { |key, value| refuse_unwritable!(key.to_sym, value) } + attributes.each { |key, value| write_attribute(key.to_sym, value) } + # rubocop:enable Style/CombinableLoops + self end + # Creates or updates the record, reporting a validation failure as + # +false+ rather than by raising. + # + # Only a rejection of the submitted attributes is caught, and it is left + # in {#error}. A missing record, an expired token or an unreachable + # instance still raises, because retrying or branching on those is not + # the caller's business here. + # + # @example + # if group.save + # puts group.id + # else + # warn group.error.server_message + # end + # + # @return [Boolean] whether the record was stored + # @raise [ResponseError] for any failure other than a validation error + # @see #save! def save - attributes = saved_attributes - symbolize_keys_deep!(attributes) - attributes.delete(:article) - @attributes = attributes - @new_instance = false - @changes = {} + save! + rescue ValidationError => e + @error = e + false + end + + # Creates or updates the record, raising on any failure. + # + # New records are sent in full; existing records send only the attributes + # that changed. + # + # @return [true] + # @raise [ResponseError] when Zammad rejected the request + # @see #save + def save! + raise_if_destroyed!('save') + + # Before the request, not after it. Only the success path and the + # rescue in `save` used to clear this, so a save that raised anything + # else left the previous attempt's ValidationError in place and a + # caller reading #error to report the failure read the wrong cause. + @error = nil + + # What the request carries, held from before it goes out. The + # attributes are frozen and replaced on write, so this is the Hash the + # request is built from and stays that whatever is written meanwhile: + # see #acknowledge_changes!. + # + # Built from, and not only held beside. The body of an update used to + # be read out of the change set a few lines after this was taken, and + # those are two reads of a record another thread may write to in + # between: title "B" held here, "C" staged before the body was built, + # and the PUT carried "C" while an answer nothing could read settled + # the record on "B" - with nothing staged, so writing "B" again to + # put it right compared equal and sent nothing. One Hash is read once + # now, and both the body and what is settled come out of it. + sent = @attributes + + if new_record? + response = create_record(sent) + else + # An existing record is addressed by its id, so establish there is + # one before anything here can report success. Only a record left + # behind by a 2xx that did not decode reaches this without one, and + # for that record the short circuit below is a lie: nothing is + # staged, so `save` answered true without sending a request. + require_id! + + # An unchanged record has nothing to send. The empty PUT this used + # to issue was not just a wasted round trip: Zammad applies it, + # bumping updated_at and updated_by, so re-saving a record that + # nobody touched rewrote its audit trail and moved the timestamp + # that other callers use to tell whether it changed under them. + unsaved = unsaved_attributes(sent) + return true if unsaved.empty? + + response = update_record(unsaved) + end + + replace_attributes!(response, operation: 'save object', sent: sent) true end - def self.get_url - @url + # Stages several attributes and saves in one call. + # + # @example + # ticket.update(state: 'closed', priority: '1 low') + # + # @param attributes [Hash] attribute names and their new values + # @return [Boolean] whether the record was stored + # @raise [Error] when the record was destroyed, or when an attribute + # cannot be staged, such as +id+ + # @raise [ResponseError] for any failure other than a validation error + # @see #save + def update(attributes) + # Before the attributes are staged, not after. `save!` asks the same + # question one line later, but by then `assign_attributes` has already + # written into @changes, so `update` on a destroyed record raised and + # left it dirty with a change set that can never be sent - exactly the + # state `destroy` clears the staged changes to prevent. + raise_if_destroyed!('save') + assign_attributes(attributes) + save end - def self.url(value) - @url = value + # Stages several attributes and saves in one call, raising on any + # failure. + # + # @param attributes [Hash] attribute names and their new values + # @return [true] + # @raise [Error] when the record was destroyed, or when an attribute + # cannot be staged, such as +id+ + # @raise [ResponseError] when Zammad rejected the request + # @see #save! + def update!(attributes) + raise_if_destroyed!('save') + assign_attributes(attributes) + save! end - def self.all(transport, _) - ZammadAPI::ListAll.new(self, transport, per_page: 100) + # Re-reads the record from Zammad, discarding unsaved changes. + # + # @return [self] + # @raise [Error] when the record was destroyed + # @raise [ResponseError] when Zammad rejected the request + # @raise [ParseError] when the response is not a JSON object + def reload + raise_if_destroyed!('reload') + raise_if_new!('reload') + + response = transport.get( + member_path, + operation: 'reload object', + resource_class: self.class, + query: { expand: true } + ) + replace_attributes!(response, operation: 'reload object') + self end - def self.search(transport, parameter) - ZammadAPI::ListSearch.new(self, transport, parameter) + # Deletes the record. + # + # The record is marked {#destroyed?} rather than left looking live, so + # that a later {#save}, {#reload} or second {#destroy} fails here with + # the reason rather than one call later as a 404 from Zammad. The + # attributes stay readable, but the state that only meant something + # while the record existed does not: staged changes, the last validation + # failure, and the association readers all go, and a write to an + # attribute is refused from then on. + # + # Readable as the record last was in Zammad, which is not what dropping + # the staged changes alone left behind: `reset_pending_state!` empties + # `@changes` and leaves the writes those changes described standing in + # `@attributes`, so `group.name = 'B'; group.destroy` answered + # `changed?` with false, `changes` with `{}` and `name` with "B" - a + # value Zammad never saw, with nothing left to tell it apart from one it + # served. `@baseline` is what the record arrived with, and every other + # path through this state moves the two together. + # + # @return [true] + # @raise [Error] when the record was already destroyed + # @raise [ResponseError] when Zammad rejected the request + def destroy + raise_if_destroyed!('destroy') + raise_if_new!('destroy') + + transport.delete(member_path, operation: 'destroy object', resource_class: self.class) + @destroyed = true + @attributes = @baseline + reset_pending_state! + true end - def self.find(transport, id) - response = transport.get(url: "#{@url}/#{id}?expand=true") - if response.status != 200 - raise ResponseError.from(response, operation: 'find object', resource_class: self) - end + def inspect = "#<#{self.class.name} id=#{id.inspect} new_record=#{new_record?}#{' destroyed=true' if destroyed?} attributes=#{attributes.inspect}>" - data = safe_json_parse(response.body) - item = new(transport, data) - item.new_instance = false - item + protected + + # @see AttributeAccess#installation + def installation = transport.config.url + + private + + # Everything a record is, in the one place both ways of building one go + # through. Held apart, {.from_response} would restate this list by hand + # and the next field added to the constructor would be left unset on + # every record built from a response - the argument {Client#setup} is + # written around, one class over. + # + # @return [void] + def setup(transport, attributes) + @transport = transport + @attributes = frozen_attributes(attributes) + # What #changes measures against: the attributes this record arrived + # with, kept apart from the ones it currently holds. The two share the + # one frozen Hash until the first write copies it. + @baseline = @attributes + @changes = {} + @new_record = true + @destroyed = false + @error = nil + @related = nil + # Whether what this record holds came back from a save rather than + # from a read. Only {#no_id_message} asks, and only for a record left + # without an id, where the two lead somewhere quite different. + @saved = false end - def self.create(transport, data) - item = new(transport, data) - item.save - item + def mark_persisted! + @new_record = false end - def self.destroy(transport, id) - item = find(transport, id) - item.destroy - true + # Refuses an operation on a record Zammad never had. + # + # `destroyed?` was the only thing these asked, so a record built with an + # id it was simply handed - `client.groups.new(id: 99)`, which the + # attribute writers refuse but the constructor still allows - reported + # `new_record?` true and `persisted?` false and then issued a real DELETE + # against group 99. The id addresses a record this one does not stand + # for, and nothing about it came from Zammad. + def raise_if_new!(operation) + raise Error, "#{self.class.name} has not been saved, so there is nothing to #{operation}" if new_record? end - private + # Refuses an operation on a record Zammad no longer holds. + # + # `destroyed?` is sticky, and all three state-changing paths ask here. + # Only `save!` used to: `reload` re-read a record that no longer exists + # and cleared the flag on the way back, so a destroyed record came back + # reporting itself as persisted and its next `save` issued a PUT against + # the deleted path, while a second `destroy` surfaced Zammad's 404 + # instead of the local reason. A record that is gone is gone, and every + # path that acts on the server says so here rather than one request + # later. + def raise_if_destroyed!(action) + raise Error, "#{self.class.name} #{id} was destroyed, there is nothing to #{action}" if destroyed? + end + + def writable_attributes? = true - def saved_attributes - return save_new if @new_instance + # Asked by {#write_attribute} and by {AttributeAccess#respond_to_missing?}, + # so that a record never claims a writer it would then refuse. That is + # the invariant the writer branch of `respond_to_missing?` exists for. + def attribute_writable?(key) = key != :id - save_existing + # Everything a freshly loaded record has to forget, in the one place that + # every load path goes through. Held apart, `save!` and `reload` drifted + # the moment a sixth field was added to only one of them, and nothing + # would have caught a reloaded record still holding an association proxy + # from before the reload. + # The flag goes down before the body is decoded, because what makes a + # record persisted is that Zammad answered 2xx, not that the answer + # parsed. Decoded first, a create whose 201 carried something other than + # a JSON object - an HTML error page from an intervening proxy - raised + # ParseError with @new_record still true, so the ticket existed in + # Zammad while the record here still looked unsaved and a retried `save` + # POSTed a second one. + # + # What that leaves behind is a record which is persisted and carries no + # id, and the rest of this class has to treat it as the unusable thing + # it is: a record built by `new` has nothing staged, so without a word + # from {#require_id!} the retried `save` would have taken the "nothing + # to send" short circuit and reported true, having made no request at + # all, for a record that may or may not be in Zammad. + # + # +sent+ is what a save was sent with, and is what tells one from a + # read. + def replace_attributes!(response, operation:, sent: nil) + # First, while #new_record? still says whether this was a create. + acknowledge_changes!(sent) if sent + @new_record = false + @saved = !sent.nil? + @attributes = frozen_attributes(response.decoded(:object, operation: operation, resource_class: self.class)) + @baseline = @attributes + reset_pending_state! end - def save_new - response = @transport.post(url: "#{@url}?expand=true", params: @attributes) - return safe_json_parse(response.body) if response.status == 201 + # The same argument, for what was staged: a 2xx is Zammad saying it + # applied the changes, whether or not the rest of the answer parsed. + # + # They used to stay staged until the body had decoded. An update + # answered with a 2xx nothing could read - the same proxy page - raised + # ParseError with the whole change set still in place, so the next + # `save` sent all of it again along with whatever had been staged + # since. For most attributes that is the same value twice. For a + # ticket's `article` it is a second article, and a second e-mail to + # the customer: the one write {Transport::RETRIABLE_METHODS} leaves + # PUT out to keep from being repeated, repeated by the caller's next + # unrelated save instead. + # + # So the baseline moves up to what was sent, before the body is read. + # If that then raises, the record holds the values it sent and nothing + # staged: it is not what Zammad would serve - `updated_at` is behind, + # and anything Zammad derived is missing - and {#reload} is what + # brings that in. A save Zammad rejected never gets here, so what it + # was sent stays staged to be corrected and sent again. + # + # What was sent, and not what the record holds by the time the answer + # is in. The two differ where the record was written to while the + # request was out - by a logger or a middleware of the caller's that + # reaches the record, or by another thread - and the baseline used to + # be taken from the record as it then stood: a PUT that carried title + # "B", with "C" staged before the answer came, left the record reading + # "C" with nothing staged, so the next `save` reported true without a + # request for a value Zammad was never sent. A write made meanwhile is + # dropped instead, which is what a response that can be read does to + # it: the attributes it carries replace the record's, whatever was + # written to them since the request left. + # + # And of what was sent, only the attributes Zammad has served this + # record with. A key written since that it never sent back is not known + # to be an attribute at all. A ticket's `article` is the case that + # matters: a command that travels in the body of the same PUT and makes + # an article, and no part of what a ticket is served as. Settled into + # the baseline with the rest, it was remembered as the ticket's own + # state, so the same article assigned again - a second reply with the + # text of the first - compared equal to it, staged nothing, and `save` + # reported true without a request. A response that can be read leaves + # no such key behind, and neither does this. + # + # A record being created has nothing it was served with to measure + # against, and keeps all it sent. It has no id to be saved again by, + # so there is no second request for a key to be missing from. + # + # What the association proxy has resolved goes with the attributes it + # was resolved from. This puts the record back on what it sent, which + # is a write to every attribute at once, and it was the one write to a + # foreign key that left the proxy alone: `customer_id` sent as 9, + # written to 10 while the request was out and `related.customer` read + # then, and the record was back on 9 with user 10 still memoized as + # its customer. {#reset_pending_state!} empties the proxy too, but + # only once the body has decoded, and a body that does not is what + # this method is here for. + def acknowledge_changes!(sent) + settled = new_record? ? sent : sent.slice(*@baseline.keys).freeze + @attributes = settled + @baseline = settled + @changes = {} + forget_related_targets + end + + # The part of that which is not about arriving with new attributes, but + # about the record's state on the server having changed underneath what + # is held here. `destroy` is the third path through this, and was the + # one left out: a destroyed record went on reporting `changed?` and a + # change set that can never be sent, and went on handing out a `related` + # proxy that would happily request a record that no longer exists. + def reset_pending_state! + @changes = {} + @error = nil + forget_related_targets + end - save_error(response) + # Empties the association proxy, rather than dropping it. + # + # Dropping it was the earlier answer: `@related = nil`, and the next + # call to {#related} built a fresh one. That reached every caller who + # asked again and none who had kept what they were handed, so after + # `related = ticket.related` a reload, a save or `ticket.customer_id = 9` + # left `related.customer` answering with the record it had resolved + # before - the stale read these calls exist to prevent, one variable + # away from where it was fixed. + def forget_related_targets + @related&.send(:forget_targets) end - def save_existing - attributes_to_post = {} - @changes.each do |name, values| - attributes_to_post[name] = values[1] + # The baseline is the value this record was loaded with, not the value + # the previous assignment happened to leave behind. Writing twice must + # still report the original, and writing a value back to the original + # is not a change at all - but only where the record was loaded + # carrying that attribute in the first place. + # + # That last part is why the baseline is held rather than read back out + # of @attributes: an attribute the record does not carry - Zammad + # reduces the object it serializes for a permission-scoped client - + # compared nil against nil on the way in, staged nothing, and was still + # merged into @attributes below. The write was dropped without a word, + # no request was ever sent for it, and the record went on reporting a + # key Zammad had never sent it, so #changes and #attributes disagreed. + # + # A destroyed record takes no writes. `update` has refused one all + # along, so as not to leave a change set that can never be sent, but + # the writers themselves did not ask: `group.destroy; group.name = 'Z'` + # left `changed?` true and `name` reading "Z" on a record `destroy` + # promises to leave as it last was in Zammad, and the `save` after it + # was the first thing to object. Asked here, it holds for a named + # writer, `[]=` and `assign_attributes` alike, since all three write + # through this method. + def write_attribute(key, value) + raise_if_destroyed!('change') + refuse_unwritable!(key, value) + + staged = frozen_attributes(value) + + if @baseline.key?(key) && @baseline[key] == staged + @changes.delete(key) + else + @changes[key] = [@baseline[key], staged].freeze end - response = @transport.put(url: "#{@url}/#{@attributes[:id]}?expand=true", params: attributes_to_post) - return safe_json_parse(response.body) if response.status == 200 - save_error(response) + # Copy on write, because @attributes is frozen for the benefit of + # every reader that hands it out. + @attributes = @attributes.merge(key => staged).freeze + # A resolved association is only correct for the id it was resolved + # from. `replace_attributes!` forgets them on save and reload, but + # the write that actually changes a foreign key did not, so + # `ticket.customer_id = 9` left `ticket.related.customer` answering + # with user 3 and no request to show for it. Every target goes: + # evicting one reader means reaching into the cache by name for a + # saving that is one request at most. + forget_related_targets if self.class.belongs_to_foreign_keys.include?(key) + staged + end + + # The attributes of +held+ that differ from what this record arrived + # with, which is what an update sends. + # + # The same question {#write_attribute} asks before it stages a change, + # asked of one Hash of attributes rather than of the change set: see + # {#save!} for why the body of a request is not read from there. + # + # @param held [Hash{Symbol => Object}] attributes of this record + # @return [Hash{Symbol => Object}] + def unsaved_attributes(held) + baseline = @baseline + + held.reject { |key, value| baseline.key?(key) && baseline[key] == value } end - def save_error(response) - raise ResponseError.from(response, operation: 'save object', resource_class: self.class) + def create_record(body) + transport.post( + self.class.resource_path, + operation: 'save object', + resource_class: self.class, + query: { expand: true }, + body: body + ) end - def symbolize_keys_deep!(hash) - hash.keys.each do |key| - key_symbol = key.respond_to?(:to_sym) ? key.to_sym : key - hash[key_symbol] = hash.delete key # Preserve order even when key == key_symbol + def update_record(body) + transport.put( + member_path, + operation: 'save object', + resource_class: self.class, + query: { expand: true }, + body: body + ) + end + + # The id is what addresses the record, so it is not an attribute a caller + # stages. Written, it took effect immediately for every path that builds + # a URL from `@attributes` and not at all for the record those paths then + # reported on: `group.id = 99; group.destroy` sent DELETE to group 99 and + # left the record saying group 1 was the one destroyed. Zammad would not + # have applied it either - an id is not something its endpoints let you + # set - so there is no call here that a refusal takes away. + def refuse_unwritable!(key, value) + return if attribute_writable?(key) - symbolize_keys_deep! hash[key_symbol] if hash[key_symbol].is_a? Hash + message = "#{self.class.name}##{key} cannot be staged as an attribute" + # `attribute_writable?` is a hook a resource may override, so the + # reason belongs to the key that was refused rather than to the raise. + if key == :id + message += ', because it is what addresses this record; look up the record you meant ' \ + "with find(#{value.inspect})" end + raise Error, message + end + + def member_path = self.class.member_path(require_id!) + + # This record's id, for the paths and bodies that cannot be built + # without one. + # + # @return [Integer] the id + # @raise [Error] when the record has none + def require_id! + # Read once into a local, so that the guard below narrows what is + # handed on - `id` is an attribute reader, and the type checker cannot + # tell that two calls to one answer the same thing. + record_id = id + raise Error, no_id_message if record_id.nil? + + record_id + end + + # A record has no id in three quite different situations, and one message + # for more than one of them sends people looking in the wrong place. + # + # Before the first save there is simply nothing to address yet. + # + # After one there is - Zammad answered 2xx, so the record is in Zammad - + # but the response carried no id to address it by, which is what + # {#replace_attributes!} leaves behind when a 2xx body does not decode + # as the object it claims to be. + # + # And a record can arrive without one from a plain read: Zammad reduces + # the object it serializes for a permission-scoped client, which is the + # same thing {#write_attribute} is written around. Such a record is + # persisted, so it used to be told it "was saved" - pointing the caller + # at a save that never happened, when what they need to look at is which + # user the client authenticates as. + def no_id_message + return "#{self.class.name} has no id, save it first" if new_record? + + if @saved + return "#{self.class.name} was saved, but the response carried no id to address it by, " \ + 'so this record cannot act on the server. Look it up again to get one that can.' + end + + "#{self.class.name} was loaded without an id, so this record cannot act on the server. " \ + 'Zammad serves a reduced object where the authenticated user may not see the whole record, ' \ + 'so check what this client may read, then look it up again to get one that can.' end end end diff --git a/lib/zammad_api/resources/group.rb b/lib/zammad_api/resources/group.rb index 3a6a768..7e3cd64 100644 --- a/lib/zammad_api/resources/group.rb +++ b/lib/zammad_api/resources/group.rb @@ -1,3 +1,13 @@ -class ZammadAPI::Resources::Group < ZammadAPI::Resources::Base - url '/api/v1/groups' +# frozen_string_literal: true + +require_relative 'base' + +module ZammadAPI + module Resources + class Group < Base + path 'api/v1/groups' + + searchable true + end + end end diff --git a/lib/zammad_api/resources/organization.rb b/lib/zammad_api/resources/organization.rb index 671939f..2ffd0a3 100644 --- a/lib/zammad_api/resources/organization.rb +++ b/lib/zammad_api/resources/organization.rb @@ -1,3 +1,13 @@ -class ZammadAPI::Resources::Organization < ZammadAPI::Resources::Base - url '/api/v1/organizations' +# frozen_string_literal: true + +require_relative 'base' + +module ZammadAPI + module Resources + class Organization < Base + path 'api/v1/organizations' + + searchable true + end + end end diff --git a/lib/zammad_api/resources/ticket.rb b/lib/zammad_api/resources/ticket.rb index 448209b..3f3810a 100644 --- a/lib/zammad_api/resources/ticket.rb +++ b/lib/zammad_api/resources/ticket.rb @@ -1,25 +1,103 @@ -class ZammadAPI::Resources::Ticket < ZammadAPI::Resources::Base - url '/api/v1/tickets' +# frozen_string_literal: true - def articles - response = @transport.get(url: "/api/v1/ticket_articles/by_ticket/#{id}?expand=true") - if response.status != 200 - raise ZammadAPI::ResponseError.from(response, operation: 'get articles', resource_class: self.class) - end +require_relative 'base' +require_relative 'ticket_article' - data = safe_json_parse(response.body) +module ZammadAPI + module Resources + class Ticket < Base + path 'api/v1/tickets' - data.collect do |raw| - item = ZammadAPI::Resources::TicketArticle.new(@transport, raw) - item.new_instance = false - item - end - end + # TicketsController#index hardcodes `reorder(id: :asc)`, so it reads nothing + # but the paging - not even sort_by. + sortable false + + # /api/v1/tickets caps the page size at 100, unlike the generic index + # endpoints, see TicketsController#index. + max_per_page 100 + + searchable true + + belongs_to :customer, class_name: 'User' + belongs_to :owner, class_name: 'User' + belongs_to :organization, class_name: 'Organization' + belongs_to :group, class_name: 'Group' + belongs_to :state, class_name: 'TicketState' + belongs_to :priority, class_name: 'TicketPriority' - def article(data) - data[:ticket_id] = @attributes[:id] - item = ZammadAPI::Resources::TicketArticle.new(@transport, data) - item.save - item + has_many :articles, class_name: 'TicketArticle', path: ->(id) { "api/v1/ticket_articles/by_ticket/#{id}" } + + # Every article of this ticket, refetched on each call. + # + # The same list as +ticket.related.articles+; this is the older name and + # stays because it reads better than reaching through +related+ for the + # one association a ticket is usually asked for. + # + # @return [Array] + # @raise [ResponseError] when Zammad rejected the request + def articles = related.articles + + # Adds an article to this ticket. + # + # Named for what it does. It was +article+, a noun that sends a POST, + # next to +articles+, a noun that only reads - so the one letter + # between them was the difference between reading a ticket's history + # and writing to it. + # + # @example + # ticket.add_article(subject: 'Update', body: 'Reset link sent.', type: 'note') + # + # @param attributes [Hash] article attributes, e.g. +body:+, +type:+ + # @return [TicketArticle] the created article + # @raise [Error] when the ticket has no id yet, or was destroyed + # @raise [ResponseError] when Zammad rejected the request + def add_article(attributes = {}) + # A destroyed ticket takes no articles, and says so here rather than + # one request later. `require_id!` passes on its own, because destroy + # leaves the id readable, so without this the POST went out naming a + # ticket that is gone and Zammad's 422 about ticket_id was the first + # news of it - the fourth state-changing path, after the three that + # already ask. + raise_if_destroyed!('add an article to') + + # An article belongs to a ticket by id, so ask for one here rather + # than merging nil. Unchecked, this POSTed `ticket_id: null` and left + # the caller reading Zammad's 422 to work out that the ticket they + # were adding to had never been saved - the one path in the gem that + # needed a stored id and went to the server to find out it had none. + # + # Both spellings of the key are taken out before this ticket's id + # goes in. `merge(ticket_id: ...)` replaces a Symbol key and leaves a + # String one standing beside it, and the article symbolizes its keys + # in the order they come: given `ticket_id` under both spellings, the + # String one came last and won, so `add_article` on ticket 7 POSTed + # an article naming whichever ticket the caller's Hash did. + own = attributes.reject { |key, _| key.to_s == 'ticket_id' } + record = TicketArticle.new(transport, own.merge(ticket_id: require_id!)) + record.save! + record + end + + # Adds an article to this ticket, under the name the method had in 1.x. + # + # Warns in Ruby's +deprecated+ category, the way the singular readers + # on {Client} do: silent unless the application asks for deprecation + # warnings. + # + # The attributes are required, as they were in 1.x. With a default, + # a bare +ticket.article+ - which reads like the attribute a ticket is + # created with, `ticket.article = {body: 'reply'}` - sent a POST + # naming nothing but the ticket, which Zammad refused for want of a + # body. 1.x raised ArgumentError for it without a request, and so does + # this. + # + # @deprecated Use {#add_article}. + # @param attributes [Hash] article attributes + # @return [TicketArticle] the created article + def article(attributes) + warn("#{Ticket.name}#article is deprecated and will be removed in 3.0: use #add_article instead", uplevel: 1, category: :deprecated) + add_article(attributes) + end + end end end diff --git a/lib/zammad_api/resources/ticket_article.rb b/lib/zammad_api/resources/ticket_article.rb index 890918b..88a0434 100644 --- a/lib/zammad_api/resources/ticket_article.rb +++ b/lib/zammad_api/resources/ticket_article.rb @@ -1,11 +1,48 @@ -class ZammadAPI::Resources::TicketArticle < ZammadAPI::Resources::Base - url '/api/v1/ticket_articles' - - def attachments - @attributes[:attachments].collect do |raw| - raw[:ticket_id] = @attributes[:ticket_id] - raw[:article_id] = @attributes[:id] - ZammadAPI::Resources::TicketArticleAttachment.new(@transport, raw) +# frozen_string_literal: true + +require_relative '../errors' +require_relative 'base' +require_relative 'ticket_article_attachment' + +module ZammadAPI + module Resources + class TicketArticle < Base + path 'api/v1/ticket_articles' + + # Named the way a has_many reader names its own read - `get articles` - + # so the refusal below reads like every other one this gem raises. + ATTACHMENTS_OPERATION = 'get attachments' + private_constant :ATTACHMENTS_OPERATION + + belongs_to :ticket, class_name: 'Ticket' + + # @return [Array] the article's attachments + # @raise [ParseError] when the article does not carry attachment + # metadata in the shape Zammad serves + def attachments + list = attributes[:attachments] || [] + # The same check {Response#decoded} makes on a list of records, for + # the same reason: this metadata comes off a response body, and an + # element that is not an object reached `raw.merge` and died there as + # `undefined method 'merge' for an instance of String` - a bare + # NoMethodError from inside the gem, past the `rescue ZammadAPI::Error` + # every caller is told to write, for a body that was simply not what + # it claimed to be. + raise ParseError.build(operation: ATTACHMENTS_OPERATION, expected: 'array of objects', actual: list.class, resource_class: self.class) if !list.is_a?(Array) + + list.map { attachment(it) } + end + + private + + def attachment(raw) + raise ParseError.build(operation: ATTACHMENTS_OPERATION, expected: 'array of objects', actual: "an array holding #{raw.class}", resource_class: self.class) if !raw.is_a?(Hash) + + TicketArticleAttachment.new( + transport, + raw.merge(ticket_id: attributes[:ticket_id], article_id: id) + ) + end end end end diff --git a/lib/zammad_api/resources/ticket_article_attachment.rb b/lib/zammad_api/resources/ticket_article_attachment.rb index c3e06d9..c3035b0 100644 --- a/lib/zammad_api/resources/ticket_article_attachment.rb +++ b/lib/zammad_api/resources/ticket_article_attachment.rb @@ -1,18 +1,50 @@ -class ZammadAPI::Resources::TicketArticleAttachment < ZammadAPI::Resources::Base - def initialize(transport, attributes = {}) # rubocop:disable Lint/MissingSuper - @transport = transport - @attributes = attributes - symbolize_keys_deep!(@attributes) - end +# frozen_string_literal: true - def method_missing(method, *_args) - @attributes[method.to_sym] - end +require_relative '../attribute_access' +require_relative '../errors' +require_relative '../transport' + +module ZammadAPI + module Resources + # An attachment of a ticket article. + # + # Attachments are read-only metadata until {#download} is called, which + # returns the file contents. + class TicketArticleAttachment + include AttributeAccess + + # @api private + # @param transport [Transport] + # @param attributes [Hash] + def initialize(transport, attributes = {}) + @transport = transport + @attributes = frozen_attributes(attributes || {}) + end + + # Downloads the attachment. + # + # @return [String] the file contents, in +ASCII-8BIT+ encoding + # @raise [ResponseError] when Zammad rejected the request + def download + segments = %i[ticket_id article_id id].map { Transport.escape_path_segment(fetch(it)) } + response = @transport.get( + "api/v1/ticket_attachment/#{segments.join('/')}", + operation: 'download attachment', + resource_class: self.class + ) + # Attachments are arbitrary binary data; the transport's charset + # guess must not corrupt them. + response.raw_body.dup.force_encoding(Encoding::BINARY) + end + + def inspect + "#<#{self.class.name} id=#{id.inspect} filename=#{self[:filename].inspect} size=#{self[:size].inspect}>" + end - def download - response = @transport.get(url: "/api/v1/ticket_attachment/#{ticket_id}/#{article_id}/#{id}") - return response.body if response.status == 200 + protected - raise ZammadAPI::ResponseError.from(response, operation: 'get articles', resource_class: self.class) + # @see AttributeAccess#installation + def installation = @transport.config.url + end end end diff --git a/lib/zammad_api/resources/ticket_priority.rb b/lib/zammad_api/resources/ticket_priority.rb index c46534a..a02df3c 100644 --- a/lib/zammad_api/resources/ticket_priority.rb +++ b/lib/zammad_api/resources/ticket_priority.rb @@ -1,3 +1,11 @@ -class ZammadAPI::Resources::TicketPriority < ZammadAPI::Resources::Base - url '/api/v1/ticket_priorities' +# frozen_string_literal: true + +require_relative 'base' + +module ZammadAPI + module Resources + class TicketPriority < Base + path 'api/v1/ticket_priorities' + end + end end diff --git a/lib/zammad_api/resources/ticket_state.rb b/lib/zammad_api/resources/ticket_state.rb index d05b75f..091aa4d 100644 --- a/lib/zammad_api/resources/ticket_state.rb +++ b/lib/zammad_api/resources/ticket_state.rb @@ -1,3 +1,11 @@ -class ZammadAPI::Resources::TicketState < ZammadAPI::Resources::Base - url '/api/v1/ticket_states' +# frozen_string_literal: true + +require_relative 'base' + +module ZammadAPI + module Resources + class TicketState < Base + path 'api/v1/ticket_states' + end + end end diff --git a/lib/zammad_api/resources/user.rb b/lib/zammad_api/resources/user.rb index c5c667a..a879277 100644 --- a/lib/zammad_api/resources/user.rb +++ b/lib/zammad_api/resources/user.rb @@ -1,3 +1,28 @@ -class ZammadAPI::Resources::User < ZammadAPI::Resources::Base - url '/api/v1/users' +# frozen_string_literal: true + +require_relative 'base' + +module ZammadAPI + module Resources + class User < Base + path 'api/v1/users' + + # UsersController#index hardcodes `reorder(id: :asc)`, so it reads nothing + # but the paging - not even sort_by. + sortable false + + searchable true + + # User::Search is the one search that reads these: it joins the roles + # for +role_ids+, resolves +permissions+ to the roles that carry them, + # and +group_ids+ to the agents with access to those groups - full + # access where it is a list of ids, the access named for each group + # where it is a Hash. See {ResourceProxy#search}, also for what + # +permissions+ does not narrow where Zammad searches through + # Elasticsearch. + search_filters :role_ids, :group_ids, :permissions + + belongs_to :organization, class_name: 'Organization' + end + end end diff --git a/lib/zammad_api/response.rb b/lib/zammad_api/response.rb new file mode 100644 index 0000000..a444c20 --- /dev/null +++ b/lib/zammad_api/response.rb @@ -0,0 +1,170 @@ +# frozen_string_literal: true + +require 'json' + +require_relative 'errors' + +module ZammadAPI + # A decoded HTTP response. + # + # This deliberately does not expose Faraday objects, so that the HTTP client + # stays an implementation detail of {Transport}. + # + # @!attribute [r] status + # @return [Integer] HTTP status code + # @!attribute [r] headers + # @return [Hash{String => String}] response headers, keys downcased + # @!attribute [r] body + # @return [Hash, Array, String] JSON responses are decoded with symbol + # keys; every other content type is left as the raw body + # @!attribute [r] raw_body + # @return [String] the undecoded response body + # @!attribute [r] json + # @return [Boolean] whether {#body} was decoded from JSON + Response = Data.define(:status, :headers, :body, :raw_body, :json) + + class Response + SUCCESS_STATUSES = (200..299) + + # There is no reader here for the size of the whole result, and the + # absence is deliberate. This class carried a `reported_total` that read + # an `x-total-count` response header, and two stop conditions were built + # on it: {Collection#each} ended a walk one request early on it, and a + # has_many reader refused a list it judged truncated by it. + # + # Zammad has never sent that header, from any endpoint. Its only custom + # response header is `X-Failure`, and the totals it does report are + # fields in a JSON body: `only_total_count` and `with_total_count` on a + # search, `full` on the endpoints that render through + # model_index_render. So the reader answered nil every time, both guards + # were dead, and the one of them that could have acted - ending a walk on + # a figure the records did not corroborate - was the one that could have + # been wrong. {Collection#total_count} asks a search endpoint for its + # figure the way Zammad actually offers it, and {#decoded_list} reads + # the one a search reports beside a page. + + # @return [Boolean] whether the status code is in the 2xx range + def success? = SUCCESS_STATUSES.cover?(status) + + # Recorded at decode time, where the answer is known, rather than derived + # from `body` and `raw_body` being the same object. That identity held only + # while every producer was careful to hand the same String to both, and any + # edit that duped, re-encoded or normalised the raw body would have flipped + # this to true with nothing asserting otherwise. + # + # @return [Boolean] whether {#body} was decoded from JSON + def json? = json + + # Decodes a body the way this gem decodes every body, and says whether it + # did. + # + # Only JSON responses are decoded. Anything else - a proxy error page, a + # file download - is handed back untouched so that callers and error + # messages can still work with it. + # + # Here rather than on {Transport}, because {Test} has to answer the same + # way and was deciding from the Ruby type of the stub's body instead: a + # stub could declare `content-type: text/html` and still hand back a + # decoded Hash with `json?` true, where Zammad would have given the raw + # string and a ParseError. A stand-in whose decoding disagrees with the + # wire is the thing that kit exists to rule out. + # + # Public for that reason and no other, the way {Transport.stringify_query} + # is: both transports call it from outside this class. It is not part of + # what this gem promises a caller. + # + # @api private + # @param content_type [String, nil] + # @param raw_body [String] + # @return [Array(Hash | Array | String, bool)] the body and whether it was + # decoded from JSON + def self.decode_body(content_type, raw_body) + return [raw_body, false] if !content_type.to_s.include?('json') + return [raw_body, false] if raw_body.empty? + + [JSON.parse(raw_body, symbolize_names: true), true] + rescue JSON::ParserError + [raw_body, false] + end + + # Returns the decoded body once it matches the expected shape. + # + # Zammad answers with an object for a single record and an array for a + # list; anything else (a proxy error page, an unexpanded search result) + # is a {ParseError} rather than a confusing failure further downstream. + # + # @param shape [Symbol] +:object+ or +:array+ + # @param operation [String] description used in the error message + # @param resource_class [Class, nil] used in the error message + # @return [Hash, Array] + # @raise [ParseError] when the body has a different shape + def decoded(shape, operation:, resource_class: nil) + case [shape, body] + in [:object, Hash => object] then object + in [:array, Array => array] then array_of_objects!(array, operation: operation, resource_class: resource_class) + else + raise ParseError.build( + operation: operation, + expected: shape, + actual: body.class, + resource_class: resource_class + ) + end + end + + # Returns the records of a list, and the size of the whole result where + # the endpoint reports it beside them. + # + # A list is an array. A search asked for +with_total_count+ answers with + # an object instead, +{records: [...], total_count: n}+, where its Zammad + # reads that parameter under +expand+ - 6.5.1 and later - and with the + # array it always did where it does not. Both are a list, and + # {Collection} reads either. + # + # A total that cannot be one - a negative figure, a string - is reported + # as none rather than refused. The records beside it are still the page, + # and a walk without a total is a walk as it was before there was one. + # + # @param operation [String] description used in the error message + # @param resource_class [Class, nil] used in the error message + # @return [Array(Array, Integer)] the records and the total + # @return [Array(Array, nil)] where the endpoint reported no total + # @raise [ParseError] when the body is neither shape + def decoded_list(operation:, resource_class: nil) + case body + in { records: Array => records, total_count: total } + [array_of_objects!(records, operation: operation, resource_class: resource_class), total.is_a?(Integer) && !total.negative? ? total : nil] + else + [decoded(:array, operation: operation, resource_class: resource_class), nil] + end + end + + private + + # Only the top-level shape used to be checked, which is not what the + # promise above says. A search answering `[1, 2, 3]` - what an unexpanded + # one looks like - passed as an array, and every element went to + # `from_response`, which stored the Integer as a record's attributes. The + # first `record.id` then died with `TypeError: no implicit conversion of + # Symbol into Integer` from deep inside the gem: precisely the confusing + # failure further downstream. + # + # Asked for by position, because the element itself cannot say whether + # one was found. `find` answers nil for no offender and for an offender + # that is nil, so a list holding a JSON null - `[null]`, or one null + # among the records - passed as a list of objects, and the same failure + # came back one type over: NoMethodError for `nil[:id]`, from the walk + # that reads the ids of a page. + def array_of_objects!(array, operation:, resource_class:) + position = array.index { !it.is_a?(Hash) } + return array if position.nil? + + raise ParseError.build( + operation: operation, + expected: 'array of objects', + actual: "an array holding #{array.fetch(position).class}", + resource_class: resource_class + ) + end + end +end diff --git a/lib/zammad_api/transport.rb b/lib/zammad_api/transport.rb index 5ade333..6c2ded2 100644 --- a/lib/zammad_api/transport.rb +++ b/lib/zammad_api/transport.rb @@ -1,63 +1,1140 @@ +# frozen_string_literal: true + require 'faraday' +require 'faraday/retry' +require 'json' require 'openssl' +require 'socket' +require 'timeout' + +require_relative 'duplicate_keys' +require_relative 'errors' +require_relative 'query_encoder' +require_relative 'response' module ZammadAPI + # Performs the HTTP requests against a Zammad instance. + # + # Instances are immutable once built: {#with_on_behalf_of} returns a copy + # rather than mutating shared state, which makes a single transport safe to + # use from several threads. + # + # @api private class Transport - attr_accessor :url, :user, :password, :on_behalf_of + # The verb shorthands, defined once for the two transports that answer + # them. + # + # {Test::Transport} stands in for this class precisely so that the code + # under test cannot tell them apart, and it carried its own copy of this + # loop - so a fifth verb added here would have left the stand-in unable to + # answer one the real transport had. The same argument as + # {Transport.relative_path} and {Resources::Base.member_path}: a rule kept + # in two places is one that gets changed in one of them. + # + # @api private + module Verbs + # @!method get(path, operation:, query: nil, headers: nil, resource_class: nil) + # @!method post(path, operation:, query: nil, body: nil, headers: nil, resource_class: nil) + # @!method put(path, operation:, query: nil, body: nil, headers: nil, resource_class: nil) + # @!method delete(path, operation:, query: nil, headers: nil, resource_class: nil) + # @return [Response] + %i[get post put delete].each do |verb| + define_method(verb) do |path, **options| + request(verb, path, **options) # steep:ignore NoMethod + end + end + end + + include Verbs + + # HTTP methods that are safe to repeat against Zammad: the ones that only + # read. + # + # PUT and DELETE are idempotent in HTTP and used to be here for that + # reason, but neither is safe to repeat against Zammad. A ticket update + # carrying an `article` creates that article on every delivery, so an + # update answered with a 504 and then a 200 added the article twice and + # sent its e-mail twice, while `update` reported success once. And a + # DELETE whose first answer was lost was repeated into a 404, so + # `destroy` raised NotFoundError for a record it had just deleted. A + # write that fails is reported instead, the way a POST always was, and + # the caller - who knows what the request carried - decides. + RETRIABLE_METHODS = %i[get head options].freeze + + # Transient statuses worth retrying. + RETRIABLE_STATUSES = [429, 500, 502, 503, 504].freeze + + # Socket failures that mean the request ran out of time. Most adapters + # wrap these into a Faraday error, but not all do, and this gem lets a + # caller choose the adapter. + # + # `timeout` and `socket` are required above for this list and the next + # one. Both constants used to resolve only because `require 'faraday'` + # reaches net/http, which loads them - so the day Faraday stops eagerly + # loading its default adapter, or a caller picks a slimmer one, this class + # body raises NameError and `require 'zammad_api'` fails before a single + # request. The Steepfile has declared both libraries all along. + TIMEOUT_ERRORS = [Errno::ETIMEDOUT, Timeout::Error].freeze + + # Socket failures that mean the instance could not be reached. Listed + # rather than caught as SystemCallError, so that an unrelated Errno - a + # logger writing to a full disk, say - is not relabelled as a network + # problem. + CONNECTION_ERRORS = [ + Errno::ECONNREFUSED, + Errno::ECONNRESET, + Errno::EHOSTUNREACH, + Errno::ENETUNREACH, + Errno::EPIPE, + SocketError + ].freeze + + # TLS failures, for the same reason the socket errors above are listed: + # most adapters wrap one into a Faraday::SSLError, but this gem lets a + # caller choose the adapter and not every adapter does. Unlisted, a + # certificate mismatch through such an adapter left `request` raw, past + # the `rescue ZammadAPI::TransportError` a caller had written - the one + # thing the rescue clauses there exist to prevent. + # + # Not in {RETRIABLE_EXCEPTIONS}: a rejected certificate is a fact about + # the instance, not a transient failure, and retrying it only delays the + # error by the backoff. + SSL_ERRORS = [OpenSSL::SSL::SSLError].freeze + + # Failures worth retrying. Faraday::RetriableResponse is how the retry + # middleware signals a retriable status internally and must stay in this + # list, otherwise it escapes as an unhandled Faraday error. + # + # Composed from the two lists above rather than repeating them. Listed + # by hand, CONNECTION_ERRORS was left out: a transient ECONNRESET through + # an adapter that wraps it was retried as a Faraday::ConnectionFailed, + # while the same failure through an adapter that does not raised on the + # first attempt - so how often a request was retried depended on which + # adapter a caller picked, and `request` already documents these as + # failures this class expects to see. The retry middleware still only + # retries RETRIABLE_METHODS, so a write is not repeated. + RETRIABLE_EXCEPTIONS = [ + Faraday::RetriableResponse, + Faraday::ConnectionFailed, + Faraday::TimeoutError, + *TIMEOUT_ERRORS, + *CONNECTION_ERRORS + ].freeze + + # Substrings that mark a key of what a request carries - its payload, its + # query, its headers - as holding a credential. + # Matching on a substring rather than the whole key covers the variants + # Zammad and OAuth actually send - password_confirm, access_token, + # refresh_token, client_secret - which an exact-match list silently let + # through to the log. + # + # The same argument reaches further than the first version of this list + # took it. `password` alone wrote `passwd` and `pwd` out in full, and + # `private_key` covered exactly one of the key spellings, so `api_key` + # and a bare `key` went to the log intact. `key` is matched as a word + # rather than as a substring, so `ssh_key` and `key` are covered while + # `keyboard` and `monkey_id` are not; `apikey` is spelled out because + # nothing separates the word there. + # + # `cookie` and `authorization` are here for the headers. A raw request + # takes headers of its own, and the log prints them: `Cookie` carries a + # session and matched nothing above, so `client.get(path, headers: + # {'Cookie' => ...})` wrote it out in full at debug level, and + # `Proxy-Authorization` went the same way. `Authorization` itself never + # gets this far - {RESERVED_HEADERS} refuses it - but every header named + # after it carries what it carries. + SENSITIVE_KEY_PATTERN = /password|passwd|pwd|token|secret|credential|cookie|authorization|api_?key|(? 2}` used to collapse + # into one parameter and send whichever Hash insertion order put last, + # dropping the other value without a word - the same silent-wrong-result + # shape as the dropped nil above, and the reason {ResourceProxy#search} + # normalises its keywords before they ever reach here. + # + # @api private + # @param query [Hash] + # @return [Hash{String => String, Array, Hash}] + # @raise [ArgumentError] for a nil value, for two keys that name the + # same parameter, or for a list a query string cannot carry, any of + # them at any depth + def self.stringify_query(query) = stringify_query_hash(query, nil) + + # Stringifies one level of a query, at whatever depth it sits. + # + # The duplicate check lives here rather than at the top level alone, + # because `condition` - which the search endpoints read, and which + # {ResourceProxy#search} takes as a keyword - is a Hash, and two + # spellings inside it collapsed exactly + # the way two spellings at the top level did. The nil check below has been + # at every depth all along; this is the same kind of rule. + # + # The key each name was first seen as is kept, so the message can print + # both spellings. Naming only the second left the reader to guess the + # first, which in a query assembled across several merges is the whole of + # the debugging. + # + # @api private + # @param hash [Hash] + # @param prefix [String, nil] the parameter path this Hash sits at + # @return [Hash{String => String, Array, Hash}] + # + # A key with an empty name is refused, for the reason a list Rails + # cannot read back is: a query string has no way to write one. Inside a + # structure it is written `[]`, which Rails reads as a list - `{list: + # [{'' => '1'}]}` arrives as `[['1']]` - and at the top level as + # `=value`, which Rails drops. + def self.stringify_query_hash(hash, prefix) + DuplicateKeys + .normalize(hash, prefix: prefix, &:to_s) + .to_h do |name, value| + raise ArgumentError, empty_query_name_message(prefix) if name.empty? + + [name, stringify_query_value(prefix ? "#{prefix}[#{name}]" : name, value)] + end + end + + # @api private + # @return [String] + def self.empty_query_name_message(prefix) + found = if prefix + "query parameter #{prefix} holds a key with an empty name, and a query string writes that as #{prefix}[], which Rails reads as a list" + else + 'a query parameter has an empty name, and a query string writes that as nothing but its value, which Rails drops' + end + + "#{found}. Name the key, or put a structure a query string cannot carry in the JSON body of a raw request, such as client.post." + end + + # Stringifies the scalars and leaves the structure to {QueryEncoder}. + # + # A nested value used to be rendered with to_s, so the `condition` that + # Zammad's search endpoints read - and that {ResourceProxy#search} takes + # as a keyword - went on the wire as a Ruby inspect string. Zammad could not parse that, dropped the parameter, and + # answered with an unnarrowed search that nothing marked as unnarrowed. + # A Hash is written as `condition[ticket.state_id][operator]=is`, which + # is the shape Rails reads back. + # + # @api private + # @param key [String] the parameter path, for the error message + # @param value [Object] + # @return [String, Array, Hash] + # @raise [ArgumentError] for a nil value, or a list a query string cannot + # carry + def self.stringify_query_value(key, value) + case value + when nil then raise ArgumentError, "query parameter #{key} is nil, and Zammad has no way to read that: pass a value, or leave the parameter out" + when Hash then stringify_query_hash(value, key) + when Array then stringify_query_list(key, value) + else wire_text(value, "query parameter #{key}") + end + end + + # Stringifies a list, and refuses one Rails could not read back as the + # list it was. + # + # A query string does not mark where an element of a list ends, so one + # Hash after another is a new element only once it is written with a + # value the one before has a place for too - see {QueryEncoder} - and two + # with none are read as one: `[{a: 1}, {b: 2}]` arrives as + # `[{a: 1, b: 2}]`. A Hash with nothing in it is not written at all, and + # the list arrives one element short. A list directly inside a list is + # written `[]` like the one around it, and `[[1, 2], [3]]` arrives as + # three lists of one. + # + # Refused, because the other answer is a request that carries something + # the caller did not write, to an endpoint that then narrows by it. + # + # @api private + # @param key [String] the parameter path, for the error message + # @param list [Array] + # @return [Array] + # @raise [ArgumentError] + def self.stringify_query_list(key, list) + elements = list.each_with_index.map { |inner, index| stringify_query_value("#{key}[#{index}]", inner) } + + elements.each_with_index do |element, index| + reason = QueryEncoder.misread(element, index.zero? ? nil : elements[index - 1]) + raise ArgumentError, misread_element_message("#{key}[#{index}]", reason) if reason + end + + elements + end + + # What a query string does to each kind of element {QueryEncoder.misread} + # names. + MISREAD_ELEMENTS = { + merged: 'has no plain value under a key the element before it has as well, and that is all a query string has to say ' \ + 'where one element of a list ends and the next begins: Rails would read the two as one. Every condition and ' \ + 'every group of conditions in a Zammad selector carries `operator`, which is such a key', + empty: 'is a Hash with no value in it, and a query string writes nothing for one: Rails would read the list one ' \ + 'element short', + list: 'is a list directly inside a list, and a query string writes both as `[]`: Rails would read each value of ' \ + 'the inner list as a list of its own' + }.freeze + private_constant :MISREAD_ELEMENTS + + # @api private + # @return [String] + def self.misread_element_message(path, reason) + "query parameter #{path} #{MISREAD_ELEMENTS.fetch(reason)}. To send a structure a query string cannot carry, " \ + 'put it in the JSON body of a raw request, such as client.post, which carries it as it is.' + end + + # Header names this class sets from the configuration, and will not take + # from a caller. + # + # +Authorization+ is built from the credentials {Config} validated, and + # +From+ is what {Client#on_behalf_of} means. Faraday's authorization + # middleware leaves a header that is already set alone, so a raw request + # carrying one of these would have replaced the client's own - quietly, + # and while {Client#inspect} went on reporting the authentication scheme + # it was built with. Naming the option that does mean it is the useful + # answer; overwriting in silence is not. + RESERVED_HEADERS = { + 'authorization' => 'authentication is configured on the client: pass http_token:, oauth2_token:, or user: and password:, or build a second client with Client#with', + 'from' => 'the From header is what on_behalf_of sets: use client.on_behalf_of(...) to perform requests for another user' + }.freeze + + # The headers a request carries beyond the ones this class sets. + # + # Names are downcased, which is what makes two spellings of one header + # comparable at all: HTTP treats them as the same header, so + # +{'Accept' => 'a', 'accept' => 'b'}+ would otherwise send whichever Hash + # order put last and drop the other without a word - the silent drop + # {DuplicateKeys} exists to refuse. + # + # Values are stringified for the reason {#with_on_behalf_of} stringifies + # the +From+ scope: a header is text on the wire, and a value of another + # type reaches Net::HTTP intact and dies there with + # `undefined method 'strip' for an instance of Integer`. + # + # Public for the same reason as {.stringify_query}: {Test} records what a + # request would have carried, and a stand-in whose recorded values + # disagree with the wire makes green tests mean less than they appear to. + # + # @api private + # @param headers [Hash] + # @return [Hash{String => String}] + # @raise [ArgumentError] for a nil value, a value that is not text, two + # spellings of one header, or a header this class sets itself + def self.stringify_headers(headers) + DuplicateKeys + .normalize(headers, noun: 'header') { it.to_s.downcase } + .to_h { |name, value| [name, stringify_header_value(name, value)] } + end + + # @api private + # @return [String] + def self.stringify_header_value(name, value) + reserved = RESERVED_HEADERS[name] + raise ArgumentError, "header #{name} is set by this client, not by a request: #{reserved}" if reserved + raise ArgumentError, "header #{name} is nil, and a header is always text: pass a value, or leave the header out" if value.nil? + raise ArgumentError, "header #{name} was given as #{value.inspect}, and a header is always text: pass a String" if !value.is_a?(String) && !value.is_a?(Symbol) && !value.is_a?(Numeric) + + text = wire_text(value, "header #{name}") + raise ArgumentError, "header #{name} holds a line break, which a header cannot carry: #{LINE_BREAK_ADVICE}" if line_break?(text) + + text + end + + # What to do about a line break in a header value, said wherever one is + # refused. + LINE_BREAK_ADVICE = 'the value is not quoted here, as it may be a credential. Read it without the line break - ' \ + 'a value read from a file usually ends in one, which is taken, but one inside it is not.' + + # Whether a header value holds a line break no header can carry. + # + # Net::HTTP strips the whitespace around a header value and refuses one + # with a line break left in it, with an ArgumentError that quotes the + # value: `http_token: "abc\ndef"` was taken when the client was built + # and raised at its first request, neither as a {ZammadAPI::Error} nor + # where the token was configured, with the token in the message. The + # +From+ scope and a raw request's headers went the same way. A line + # break at either end is stripped there, so a token read from a file + # with its newline still on works, and is still taken. + # + # @api private + # @param text [String] + # @return [Boolean] + def self.line_break?(text) + text = text.encode(Encoding::UTF_8) if !text.encoding.ascii_compatible? + /[\r\n]/.match?(text.strip) + rescue EncodingError + false + end + + # The +From+ scope as a transport holds it: text, and a copy of its own. + # + # Text, because a user id is a documented way to name the user and + # arrives as an Integer, which reached Net::HTTP intact and died there + # with `undefined method 'strip' for an instance of Integer`. + # + # A copy, because `String#to_s` hands back the receiver. The scoped + # client held the caller's own String, so a login buffer that was reused + # after `client.on_behalf_of(login)` changed who every later request from + # that client was performed for - the one thing a scope exists to pin. + # Copied rather than interned, for the reason {Config} copies what it is + # given: nothing a caller passed in should outlive what holds it. + # + # Public for the same reason as {.stringify_query}: {Test} carries the + # scope the way this class does, so that what it records is what the + # header would have carried. + # + # An identifier that names nobody is refused here, the one place every + # way to a +From+ header goes through, rather than only by + # {Client#on_behalf_of}. Zammad skips a header with nothing in it, so a + # transport scoped to one sent every request as the account it + # authenticates as. Nothing in it is what Rails calls blank, which + # counts Unicode spaces as well as ASCII ones: Zammad asks + # `request_header_from.blank?`. + # + # @api private + # @param identifier [String, Integer, nil] login, email or user id + # @return [String, nil] frozen, or nil for no scope + # @raise [ArgumentError] for an identifier with nothing in it + def self.stringify_on_behalf_of(identifier) + return nil if identifier.nil? + + text = wire_text(identifier, 'on_behalf_of') + raise ArgumentError, blank_on_behalf_of_message(identifier) if BLANK.match?(text) + raise ArgumentError, "on_behalf_of holds a line break, which the From header cannot carry: #{LINE_BREAK_ADVICE}" if line_break?(text) + + text.dup.freeze + end + + # What Rails calls blank, for a String: nothing but whitespace, Unicode + # spaces included. +strip+ removes the ASCII ones only, so a no-break + # space passed a check built on it and was then read as nothing. + # + # Asked of a String {.wire_text} has had: the pattern is US-ASCII, and + # matching it against text in an encoding ASCII is no part of raises + # Encoding::CompatibilityError. + BLANK = /\A[[:space:]]*\z/ + + # A value as text a request can carry: in UTF-8 where it was given in an + # encoding ASCII is no part of, such as UTF-16. + # + # Such a String cannot be joined to the ASCII around it. Faraday's + # escaping of a query value and Net::HTTP's writing of a header both + # raised Encoding::CompatibilityError for one, as did {BLANK} asked of a + # +From+ scope or a search keyword: neither a {ZammadAPI::Error} nor the + # ArgumentError a malformed value is refused with, and for a non-blank + # value, one that had nothing wrong with it but its encoding. Converted, + # it is the same text, in the encoding Zammad reads. + # + # An encoding ASCII is a part of is left as it was, binary included: its + # bytes are what went on the wire, and still are. + # + # @api private + # @param value [Object] + # @param name [String] what the value is, for the error message + # @return [String] + # @raise [ArgumentError] for text that cannot be converted to UTF-8 + def self.wire_text(value, name) + text = value.to_s + return text if text.encoding.ascii_compatible? + + begin + text.encode(Encoding::UTF_8) + rescue EncodingError + raise ArgumentError, "#{name} was given as #{text.encoding} text that cannot be converted to UTF-8, which is what " \ + 'a request carries: it holds a byte sequence that is not valid in its own encoding.' + end + end + + # @api private + # @return [String] + def self.blank_on_behalf_of_message(identifier) + "on_behalf_of needs the login, email address or id of a user, and was given #{identifier.inspect}. " \ + 'Zammad reads a From header with nothing in it as no header at all, so every request would be performed ' \ + 'as the account this client authenticates as, with nothing to say the scope was missing.' + end + + # Percent-encodes one segment of a request path. + # + # Record ids are pasted into the path, and an id taken straight from a + # request parameter used to be pasted in whole: `find("1/../../api/v1/ + # users/1")` resolved to the users endpoint, so the parameter, not the + # call, chose which records the verb applied to. Encoding everything + # outside the unreserved set keeps a separator inside the segment it was + # written in, and a caller that really means a sub-path can spell it out + # with the raw request methods. + # + # A dot segment is refused rather than encoded. `.` and `..` are unreserved + # all the way through, so the encoding below returns them exactly as they + # arrived and `find('..')` still resolved one path level up - onto the + # index endpoint, and through a has_many path onto every article on the + # instance offered as one ticket's. Percent-encoding the dots would hold + # them inside the segment here, but a proxy that normalises a path before + # routing it would undo that, and no Zammad record is named for one. + # + # Public for the same reason as {.stringify_query}: {Test} builds the + # paths it records with it. + # + # @api private + # @param value [Object] + # @return [String] + # @raise [ArgumentError] when there is nothing to send, or when the id + # navigates instead of naming a record + def self.escape_path_segment(value) + segment = value.to_s + raise ArgumentError, 'a record id is required, and this one is empty' if segment.empty? + raise ArgumentError, "#{segment.inspect} points at another endpoint rather than naming a record" if DOT_SEGMENTS.include?(segment) + + segment.gsub(UNRESERVED_IN_PATH) { |character| character.bytes.map { format('%%%02X', it) }.join } + end + + # Strips the leading slashes from a path so that it resolves against the + # instance URL rather than against the host. + # + # {Config#url} always ends in a slash and every request path is appended + # relative to it, so a leading slash would drop the sub-path of a Zammad + # served from one - `https://host/zammad/` + `/api/v1/tickets` resolves to + # `https://host/api/v1/tickets`. + # + # A path that names a host of its own is refused. Faraday lets an absolute + # URL replace the instance URL and still attaches this client's headers, + # so `client.get('https://other.example/collect')` - a link lifted from a + # response body, say - sent the access token and the on_behalf_of scope + # to that host. Record ids are held inside their segment by + # {.escape_path_segment}; this is the same escape, one level up. The + # message does not quote the path, which may carry a secret of its own. + # + # Public for the same reason as {.stringify_query} and + # {.escape_path_segment}: {Client} and {Test} both apply this rule, the + # latter to decide which stub a request matches, and a path rule kept in + # three places is one that gets changed in one of them - at which point + # the stand-in quietly stops matching what the client sends. + # + # A path that cannot be read as a URL is refused here as well, which is + # where it stops being Faraday's to refuse. Faraday reads the path with + # URI when the request is built, and URI raises an error of its own for + # one it cannot read: `client.get('api/v1/tägs')` and + # `client.get(' api/v1/x')` left as URI::InvalidURIError, which is + # neither a {ZammadAPI::Error} nor the ArgumentError a raw request + # documents for a path, so no rescue a caller was told to write caught + # it. And it was raised after the request had been logged, leaving a line + # for a request that never left - what {#perform} stringifies the query + # and the headers first to prevent. + # + # @api private + # @param path [Object] + # @return [String] + # @raise [ArgumentError] for an absolute URL, or a path that cannot be + # read as a URL + def self.relative_path(path) + relative = path.to_s.sub(%r{\A/+}, '') + if ABSOLUTE_URL.match?(relative) + raise ArgumentError, 'a request path is relative to the instance URL, and this one is an absolute URL: sending it would hand ' \ + "this client's credentials to another host. Pass the path alone, such as 'api/v1/tickets'." + end + + refuse_unreadable_path!(relative) + relative + end + + # Reads a path the two ways Faraday will: the whole of it as a URL, and + # a query string written into it as parameters. + # + # The second can fail where the first does not. `?a=1&a[b]=2` names one + # parameter as a value and as a structure, and decoding it raised + # TypeError from inside the connection. + # + # Neither message quotes the path, for the reason the one above does + # not, and neither passes on the error underneath, which does quote it: + # not its message, and not the error itself as the cause, which Ruby + # attaches to an error raised in a rescue and prints with it, so an + # exception tracker recorded the path, credentials and all. + # + # @api private + # @param relative [String] + # @return [void] + # @raise [ArgumentError] + def self.refuse_unreadable_path!(relative) + begin + URI.parse(relative) + rescue URI::InvalidURIError + raise ArgumentError, unreadable_path_message(relative), cause: nil + end - def initialize(config, logger) - @logger = logger - @logger.debug "Transport to #{config[:url]} with #{config[:user]}:#{config[:password]}" - @conn = Faraday.new(url: config[:url]) do |faraday| - #faraday.request :url_encoded # form-encode POST params - #faraday.response :logger # log requests to STDOUT - faraday.adapter Faraday.default_adapter # make requests with Net::HTTP + begin + QueryEncoder.decode(relative.partition('#').first.partition('?').last) + rescue TypeError, Faraday::Error + raise ArgumentError, 'the query string written into this request path cannot be read as parameters: it names one of them ' \ + 'both as a value and as a structure, or nests them deeper than a query string is read. ' \ + 'Pass the parameters as query: instead, which takes them as a Hash.', cause: nil end - @conn.headers[:user_agent] = 'Zammad API Ruby' - if config[:http_token] && !config[:http_token].empty? - @conn.request :authorization, 'Token', config[:http_token] - elsif config[:oauth2_token] && !config[:oauth2_token].empty? - @conn.request :authorization, 'Bearer', config[:oauth2_token] - else - @conn.request :authorization, :basic, config[:user], config[:password] + end + + # @api private + # @return [String] + def self.unreadable_path_message(relative) + found = relative.ascii_only? ? 'a space, or another character a URL does not allow, or a % that begins no escape' : 'a character outside ASCII' + + "a request path is written the way a URL is, and this one cannot be read as one: it holds #{found}. " \ + 'Percent-encode what a URL cannot hold as it is - a space is %20, and ä is %C3%A4 - ' \ + 'or pass a parameter as query:, which encodes its value.' + end + + # A request path as it may be printed: with the credentials of a query + # string written into it blanked. + # + # A raw request may carry its query in the path - + # `client.get('api/v1/users/password_reset_verify?token=...')` is how the + # Zammad documentation spells that endpoint - and the path is printed in + # three places: the two log lines for a request, the message of a + # timeout, and the operation a raw request is named by in every error it + # raises. The `query:` Hash is redacted by key before it is logged, and + # the same parameter written into the path went out in full in all + # three. + # + # Redacted by name, as the Hash is, and written back as it was given + # otherwise. A name that cannot be decoded cannot be read, so its value + # is blanked rather than assumed to be harmless. + # + # Public for {Client}, which names a raw request by its path. + # + # @api private + # @param path [Object] + # @return [String] + def self.redact_path(path) + base, mark, query = path.to_s.partition('?') + return base if mark.empty? + + "#{base}?#{query.split('&', -1).map { redact_query_pair(it) }.join('&')}" + end + + # @api private + # @return [String] + def self.redact_query_pair(pair) + name, mark, = pair.partition('=') + return pair if mark.empty? + + decoded = begin + URI.decode_www_form_component(name) + rescue ArgumentError + nil end + + decoded && !SENSITIVE_KEY_PATTERN.match?(decoded) ? pair : "#{name}=#{REDACTED}" + end + + # The bytes a request body goes out as. + # + # Encoded here rather than left to Faraday's JSON middleware, because a + # body that cannot be encoded raised JSON::GeneratorError from inside the + # stack and nothing mapped it: `client.post(path, body: {data: + # File.binread('a.png')})` with the bytes not Base64-encoded, or any body + # holding a Float::NAN, went past the +rescue ZammadAPI::Error+ every + # caller is told to write, and a record whose +save+ carried the same + # value took the same way out. It is also encoded before the request is + # logged, for the reason the query and the headers are stringified + # first: a refused body leaves no line claiming a request that was never + # made. + # + # A String is passed through, as the middleware passes it: it is the + # caller saying the body is already encoded. + # + # Public for the same reason as {.stringify_query}: {Test} refuses what + # the wire would refuse. + # + # @api private + # @param body [Object] + # @param operation [String] description used in the error message + # @param resource_class [Class, nil] used in the error message + # @return [String, nil] nil for a request without a body + # @raise [Error] when the body cannot be encoded as JSON + def self.encode_body(body, operation:, resource_class: nil) + return body if body.nil? || body.is_a?(String) + + JSON.generate(body) + rescue JSON::JSONError => e + raise Error, "Can't #{Error.subject_for(operation, resource_class)}: the request body cannot be encoded as JSON (#{e.message}). " \ + 'Every value has to be a JSON type, and text has to be valid UTF-8: Base64-encode binary data such as an ' \ + 'attachment, and leave out a Float that is NaN or infinite.' + end + + # @param config [Config] + def initialize(config) + @config = config + @on_behalf_of = nil + @connection = build_connection + end + + # Returns a copy of this transport that sends the +From+ header. + # + # The scope is stringified here rather than at the point the header is + # set, so that {Test} records the value the wire would carry: an Integer + # used to die inside Net::HTTP while the test kit accepted it happily. + # See {.stringify_on_behalf_of} for what is held. + # + # @param identifier [String, Integer, nil] login, email or user id + # @return [Transport] + def with_on_behalf_of(identifier) + copy = dup + copy.instance_variable_set(:@on_behalf_of, Transport.stringify_on_behalf_of(identifier)) + copy end - %w[get post put delete].each do |method| - class_eval <<-RUBY, __FILE__, __LINE__ + 1 - def #{method}(params) # def get(params) - run_request(:#{method}, params) # run_request(:get, params) - end # end - RUBY + # Returns a transport of this kind configured with +config+, keeping any + # {#with_on_behalf_of} scope. + # + # {Client#with} goes through here rather than building a Transport itself, + # so that a client whose transport was replaced - the test kit's stand-in, + # say - derives another of the same kind instead of silently reverting to + # a real HTTP one. + # + # @param config [Config] + # @return [Transport] + def with_config(config) = self.class.new(config).with_on_behalf_of(on_behalf_of) + + # Says where this transport points and how it authenticates, and nothing + # else. + # + # Left to Ruby, this printed the instance variables, and one of them is + # the Faraday connection: its proxy options carry the proxy password and + # its middleware stack carries the arguments it was built with, the + # access token among them. Every record holds its transport, so that was + # one +inspect+ away from any of them. Defining this covers +pp+ as well, + # which uses an +inspect+ a class defines for itself. + # + # @return [String] + def inspect + "#<#{self.class.name} url=#{config.redacted_url.inspect} auth=#{config.authentication_scheme}#{" on_behalf_of=#{on_behalf_of.inspect}" if on_behalf_of}>" + end + + # Performs a request and raises on anything but a 2xx response. + # + # @param method [Symbol] +:get+, +:post+, +:put+ or +:delete+ + # @param path [String] path relative to {Config#url} + # @param operation [String] description used in error messages + # @param query [Hash, nil] query string parameters + # @param body [Hash, nil] request payload, encoded as JSON + # @param headers [Hash, nil] request headers, beyond the ones this class + # sets from the configuration + # @param resource_class [Class, nil] used in error messages + # @return [Response] + # @raise [ResponseError] for non-2xx responses + # @raise [TimeoutError] when the request timed out + # @raise [ConnectionError] when the instance was unreachable + # + # @raise [Error] when the body cannot be encoded as JSON + # + # Every failure leaves here as a {ZammadAPI::Error}. The bare socket + # errors are caught alongside the Faraday ones because they are already + # in {RETRIABLE_EXCEPTIONS}, which is this class saying it expects to see + # them: an adapter that does not wrap them used to let them out raw once + # the retries were spent, past every rescue a caller had written. + def request(method, path, operation:, query: nil, body: nil, headers: nil, resource_class: nil) + # Here as well as in {Client}, because this is the one door every + # request goes through, whichever caller built the path. + path = Transport.relative_path(path) + payload = Transport.encode_body(body, operation: operation, resource_class: resource_class) + started = Process.clock_gettime(Process::CLOCK_MONOTONIC) + response = decode(perform(method, path, query, body, payload, headers)) + log_response(method, path, response, started) + + return response if response.success? + + raise ResponseError.build(response, operation: operation, resource_class: resource_class) + rescue Faraday::TimeoutError, *TIMEOUT_ERRORS => e + raise TimeoutError, "Can't #{operation}: request to #{Transport.redact_path(path)} timed out (#{e.message})" + rescue Faraday::SSLError, *SSL_ERRORS => e + raise ConnectionError, "Can't #{operation}: TLS handshake with #{config.redacted_url} failed (#{e.message})" + rescue Faraday::ConnectionFailed, *CONNECTION_ERRORS => e + # Before it is called unreachable, because one kind of connection + # failure is a timeout. See #timed_out?. + raise TimeoutError, "Can't #{operation}: connecting to #{config.redacted_url} timed out (#{e.message})" if timed_out?(e) + + raise ConnectionError, "Can't #{operation}: #{config.redacted_url} is unreachable (#{e.message})" end private - def run_request(verb, param) - @logger.debug "#{verb.to_s.upcase}: #{@url}#{param[:url]}" + # Whether a connection failure is a timeout underneath. + # + # An exceeded +open_timeout+ is raised by Net::HTTP as Net::OpenTimeout, + # and the default adapter wraps that into Faraday::ConnectionFailed along + # with every other failure to connect. So it was reported as "is + # unreachable (execution expired)", a ConnectionError, and skipped the + # +rescue ZammadAPI::TimeoutError+ that is documented to catch an + # exceeded +open_timeout+. + # + # Both places an adapter can leave the original are looked at: Faraday's + # own +wrapped_exception+, and the +cause+ Ruby records for an error + # raised while another was being handled. + def timed_out?(error) + wrapped = error.respond_to?(:wrapped_exception) ? error.wrapped_exception : nil + + [wrapped, error.cause].any? { |inner| TIMEOUT_ERRORS.any? { inner.is_a?(it) } } + end - with_params = !param[:params].nil? - if with_params - @logger.debug "Params: #{param[:params].inspect}" + # +body+ is what the caller handed over, which is what the log redacts + # and prints; +payload+ is the same thing encoded, which is what is sent. + def perform(method, path, query, body, payload, headers) + # Built before the request is logged, so a rejected query or header does + # not leave a line claiming a request that was never made. + params = query && Transport.stringify_query(query) + fields = headers && Transport.stringify_headers(headers) + log_request(method, path, query, body, fields) + + @connection.public_send(method, path) do |request| + request.params.update(params) if params + # One at a time rather than in bulk, so that every name goes through + # Faraday's own case-insensitive writer and replaces the header it + # names rather than sitting beside it under another spelling. + fields&.each { |name, value| request.headers[name] = value } + request.body = payload if payload + request.headers['From'] = on_behalf_of if on_behalf_of end + end - response = @conn.public_send(verb) do |req| - req.url param[:url] + def build_connection + connection = Faraday.new( + url: config.url, + proxy: config.proxy, + ssl: { verify: config.ssl_verify }, + # The encoder is this gem's own: see {QueryEncoder} for the one + # structure Faraday's writes so that Rails reads another. + request: { timeout: config.timeout, open_timeout: config.open_timeout, params_encoder: QueryEncoder }, + headers: { 'User-Agent' => config.user_agent, 'Accept' => 'application/json' } + ) do |faraday| + apply_authentication(faraday) + faraday.request :json + faraday.request :retry, retry_options + # Last in the stack, so a caller's middleware sees the request as this + # gem finished building it and the response before anything else does. + config.middleware&.call(faraday) + faraday.adapter(config.adapter || Faraday.default_adapter) + end - if with_params - req.headers['Content-Type'] = 'application/json' - req.body = param[:params].to_json - end + refuse_unusable_middleware!(connection) + connection + rescue ZammadAPI::Error + raise + rescue => e + # An unregistered adapter, a proxy that is not a URL, or a middleware + # that rejects its options is a configuration mistake, and neither + # Faraday nor URI is part of this gem's surface. + # + # Caught as StandardError rather than as Faraday::Error, because the + # failures that do not come from Faraday are the ones a caller is least + # equipped to place: `proxy: 'http://user:pa ss@host'` escaped as + # URI::InvalidURIError and a `middleware` callable that raises escaped + # as whatever it raised, both straight past the + # `rescue ZammadAPI::ConfigurationError` that building a client is + # documented to need. The class is named in the message because + # "bad URI (is not URI?)" on its own says nothing about where to look. + raise ConfigurationError, "config could not be used to build a connection: #{e.class}: #{redact_config_values(e.message)}", cause: reportable_cause(e) + end - if !on_behalf_of.nil? - req.headers['From'] = on_behalf_of - end + # The error to keep as the cause of the ConfigurationError above, where + # it can be kept. + # + # Ruby attaches the error being rescued to the one raised in its place, + # and a report prints the whole chain: `full_message`, a logger's + # formatter, an error tracker. So the message above was scrubbed and the + # original went out right behind it, `caused by URI::InvalidURIError: bad + # URI (is not URI?): "http://user:pa ss@host:3128"`, password and all. + # + # Dropped only where that is what would happen. The whole report is + # asked, causes of its own included, because the whole report is what + # gets printed, and it is asked the question the message was: whether it + # quotes a configured value that redaction changes. Every other failure + # keeps its cause. A `middleware:` callable that raises is a bug in the + # caller's own code, and the backtrace into it is the one thing the + # message cannot carry. + # + # An error that cannot render its report is dropped as well. Rendering is + # the error's own code - `detailed_message` is there to be overridden, + # and one written without the `highlight:` keyword raises ArgumentError + # from inside `full_message` - and this runs in the rescue above, so what + # it raised left in place of the ConfigurationError, past the rescue + # building a client is documented to need. A report that cannot be read + # cannot be shown to quote nothing, which is the one condition a cause is + # kept on. + def reportable_cause(error) + report = error.full_message(highlight: false) + + redact_config_values(report) == report ? error : nil + rescue + nil + end - yield(req) if block_given? + # The underlying error quotes the value it rejected, and for a proxy that + # value carries its credentials: `proxy: 'http://user:pa ss@host:3128'` + # came back as URI::InvalidURIError with the whole URL, password included, + # in its message - and that message goes into the ConfigurationError + # above, which lands in every log and exception report. The one case + # {Config#inspect} and {Config#redacted} exist to prevent, reached by + # another route. + # + # The configured values are swapped for their redacted forms rather than + # the message being dropped, because "bad URI (is not URI?)" without the + # URI says nothing about where to look. Substring replacement, because + # the message embeds the value verbatim, and the url as well as the proxy + # because {Config} can only refuse the credentials in a url it can read: + # one that is not a URL at all gets this far, and is quoted here. + def redact_config_values(message) + [config.proxy, config.url].compact.inject(message.to_s) do |text, value| + redacted = config.redacted(value) + + # The block form. A String replacement expands the backslash + # sequences it contains, and the replacement here is the configured + # value with its userinfo blanked - so a value carrying `\0` or `\&` + # put the whole matched text back, credentials included, into the + # message it had just been taken out of, and one carrying `\1` cut + # the replacement short instead. + # + # Every spelling of the value, because the error being quoted may + # have inspected it rather than interpolated it: URI::InvalidURIError + # does, and inspect escapes exactly the backslashes, quotes and + # control characters that make a URL invalid in the first place. The + # escaped text no longer equals the value as configured, so the swap + # matched nothing and left the password standing in full - the case + # this method exists for, reached through the quoting rather than + # the value. + quoted_spellings(value).inject(text) { |scrubbed, spelling| scrubbed.gsub(spelling) { redacted } } + end + end + + # The value as an error may have quoted it: as it is, as +inspect+ + # writes it, and as +dump+ does. + # + # The last two part ways at the first character outside ASCII, which + # +inspect+ leaves standing and +dump+ writes as an escape, and URI + # rejects a URL holding one with the +dump+ spelling: "URI must be ascii + # only" and the value with every such character as `\u00E4`. A password + # with an umlaut in it therefore matched neither of the two spellings + # that were looked for, and stayed in the message - and in the cause, + # which is kept wherever redaction finds nothing to change. + def quoted_spellings(value) = [value, value.inspect[1...-1], value.dump[1...-1]].compact.uniq + + def apply_authentication(faraday) + case config.authentication_scheme + when :http_token then faraday.request :authorization, 'Token', config.http_token + when :oauth2_token then faraday.request :authorization, 'Bearer', config.oauth2_token + else faraday.request :authorization, :basic, config.user, config.password end + end + + # +max_interval+ is what bounds a wait. The retry middleware sleeps for + # whatever a +Retry-After+ header says, and its own ceiling defaults to + # no ceiling at all: a maintenance page answering 503 with + # +Retry-After: 3600+ held the calling thread for an hour per retry, + # whatever +timeout+ and +retry_interval+ said, before raising the error + # it could have raised at once. + # + # +timeout+ is the bound, because it is already how long this client + # was told it may wait for an answer. A +Retry-After+ within it is + # honoured; a longer one is not waited out, and the response it came + # with is reported as the error it is, with the figure still readable + # from {RateLimitError#retry_after}. + def retry_options + { + max: config.retries, + interval: config.retry_interval, + max_interval: config.timeout, + interval_randomness: 0.5, + backoff_factor: 2, + retry_statuses: RETRIABLE_STATUSES, + methods: RETRIABLE_METHODS, + exceptions: RETRIABLE_EXCEPTIONS + } + end + + def decode(faraday_response) + headers = faraday_response.headers.to_h.transform_keys { it.to_s.downcase }.freeze + raw_body = raw_body!(faraday_response.body) + body, json = Response.decode_body(headers['content-type'], raw_body) + + Response.new( + status: faraday_response.status, + headers: headers, + body: body, + raw_body: raw_body, + json: json + ) + end + + # Middleware this gem cannot do its own work behind, each with what it + # takes away and how it is usually spelled. Matched by name so that naming + # one does not require it to be loaded, and looked for among the ancestors + # of what is in the stack: see {#refused_middleware}. + # + # The first reads the body before this gem can. The second raises for a + # 4xx or 5xx before this gem sees the response, and it sits below the + # retry middleware, which is where a caller's middleware goes: a GET + # answered 503 left as Faraday::ServerError without being retried, a 404 + # as Faraday::ResourceNotFound, so `exists?` raised for a record that is + # merely absent, and a 422 as an error `save` does not turn into false. + # None of them is a {ZammadAPI::Error}, which is what every failure is + # documented to leave as. + REFUSED_MIDDLEWARE = { + 'Faraday::Response::Json' => ['which decodes the response body before this gem can. This gem parses JSON itself, and hands ' \ + 'the undecoded bytes to attachment downloads, so it needs the body as it arrives', + 'c.response :json'].freeze, + 'Faraday::Response::RaiseError' => ['which raises a Faraday error for a 4xx or 5xx response before this gem sees it. This gem ' \ + 'raises its own error for each status, and retries a read that was answered 429 or 5xx, ' \ + 'and behind this middleware it does neither', + 'c.response :raise_error'].freeze + }.freeze + private_constant :REFUSED_MIDDLEWARE + + # Refuses a stack this gem cannot work behind, while the stack is still + # the only thing that has happened. + # + # `raw_body!` below catches a decoded body too, but only once a response + # is in hand - which is one request too late: `client.groups.create(...)` + # sent the POST, Zammad created the group, and only then did a + # ConfigurationError come back, so a caller retrying what looked like a + # configuration failure created a second one. The middleware is fully + # visible here, where the unregistered adapter and the unusable proxy are + # already refused before anything is sent. + def refuse_unusable_middleware!(connection) + connection.builder.handlers.each do |handler| + refused = refused_middleware(handler.klass) + raise ConfigurationError, refused_middleware_message(handler.klass, refused) if refused + end + end + + # Which refused middleware a class in the stack is, if it is one: itself, + # or the one it inherits from. + # + # Only the class's own name used to be asked, and a subclass has another. + # `class QuietRaiseError < Faraday::Response::RaiseError`, the usual way + # to adjust what that middleware raises, went through `c.use` unrefused, + # and its inherited handler then raised Faraday::ResourceNotFound for a + # 404 before this gem saw the response - everything the refusal is there + # to prevent, one `<` away from it. + # + # @return [String, nil] the name it is refused under + def refused_middleware(klass) = klass.ancestors.filter_map(&:name).find { REFUSED_MIDDLEWARE.key?(it) } + + # A subclass is named along with what it inherits from, because the + # reason describes the parent - and it is told to drop "it", because the + # line that added a subclass is not the one the parent is usually spelled + # with. + def refused_middleware_message(klass, refused) + reason, spelling = REFUSED_MIDDLEWARE.fetch(refused) + found, drop = klass.name == refused ? [refused, "`#{spelling}`"] : ["#{klass.name || 'an anonymous class'}, a subclass of #{refused}", 'it'] - @logger.debug "Response: #{response.body}" - response + "the configured middleware includes #{found}, #{reason}: drop #{drop} from the `middleware:` callable." end + + # The body as it came off the wire. + # + # `middleware:` is a documented seam and `c.response :json` is a + # reasonable thing to put through it, at which point Faraday hands over a + # Hash rather than the bytes. `to_s` turned that into a Ruby inspect + # string, which JSON.parse then refused, so every record built from the + # response died in {Response#decoded} with a ParseError naming Zammad for + # what the caller's own stack had done. + # + # A backstop rather than the first line of defence: the stack is checked + # when it is built, which catches `c.response :json` before a request goes + # out. This is what is left for a middleware that decodes without being one + # of the names that check knows. + # + # Said plainly instead. Re-encoding the parsed structure was the other + # way out, and it is worse than it looks: {Response#raw_body} is + # documented as the undecoded body and + # {Resources::TicketArticleAttachment#download} hands exactly those bytes + # back as the file, so a re-encoding silently returns something that is + # not what Zammad stored - and JSON.generate has its own failures, which + # would escape from here past the `rescue ZammadAPI::Error` every caller + # is told to write. Once the bytes are gone they cannot be recovered, so + # the honest answer is to name the cause while it is still visible. + def raw_body!(body) + return body.to_s if body.nil? || body.is_a?(String) + + raise ConfigurationError, + 'the configured middleware decoded the response body before this gem could ' \ + "(Faraday handed over #{body.class} rather than the raw body). This gem parses JSON itself, " \ + 'and hands the undecoded bytes to attachment downloads, so it needs the body as it arrived: ' \ + 'drop the parsing middleware - `c.response :json` is the usual one - from the `middleware:` callable.' + end + + def log_request(method, path, query, body, headers) + logger.debug do + "Zammad API request: #{method.to_s.upcase} #{Transport.redact_path(path)}#{" query=#{redact(query).inspect}" if query}#{" headers=#{redact(headers).inspect}" if headers}" + end + logger.debug { "Zammad API payload: #{loggable_body(body).inspect}" } if body + end + + def log_response(method, path, response, started) + duration = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round + logger.debug { "Zammad API response: #{method.to_s.upcase} #{Transport.redact_path(path)} -> #{response.status} in #{duration}ms" } + end + + # What the log prints for a request body. + # + # A body handed over as a String is the caller's own encoding, and + # {#redact} works by key: it had no keys to go by, so + # `client.post(path, body: '{"login":"a","password":"hunter2"}')` was + # written to the log as it stood. Where the String is JSON it is read + # for its keys and redacted like the structure it spells. Where it is + # not - a form body, a file - nothing in it can be told from a + # credential, and its size is logged in its place. + def loggable_body(body) + return redact(body) if !body.is_a?(String) + + decoded = JSON.parse(body) + decoded.is_a?(Hash) || decoded.is_a?(Array) ? redact(decoded) : unlogged_body(body) + rescue JSON::JSONError, EncodingError + unlogged_body(body) + end + + def unlogged_body(body) = "[#{body.bytesize} bytes that are not a JSON object or array, not logged]" + + def redact(value) + case value + when Hash then value.to_h { |key, nested| [key, SENSITIVE_KEY_PATTERN.match?(key.to_s) ? REDACTED : redact(nested)] } + when Array then value.map { redact(it) } + else value + end + end + + def logger = config.logger end end diff --git a/lib/zammad_api/version.rb b/lib/zammad_api/version.rb index 4915c54..f8df209 100644 --- a/lib/zammad_api/version.rb +++ b/lib/zammad_api/version.rb @@ -1,3 +1,5 @@ +# frozen_string_literal: true + module ZammadAPI - VERSION = '1.4.0'.freeze + VERSION = '2.0.0.alpha1' end diff --git a/script/live_target.rb b/script/live_target.rb new file mode 100644 index 0000000..a237e76 --- /dev/null +++ b/script/live_target.rb @@ -0,0 +1,37 @@ +# frozen_string_literal: true + +# The Zammad the live checks run against: the integration specs, `rake spec`, +# `rake check_connection` and script/check_connection.rb. +# +# Each of them creates and deletes records, so none has a default for where, +# and each asks here whether one was named. They used to ask with a check of +# their own, three copies of one rule that only stayed in step by being +# changed together - and the day one of them read a TEST_URL as set that the +# others read as unset, rake would refuse a run that rspec then made, or the +# other way round. +# +# Plain Ruby with nothing required, so that the check script, which loads +# nothing of the spec suite on purpose, can load it too. +module LiveTarget + # What to write where TEST_URL is not set. A placeholder that cannot reach + # anything if it is pasted as it is: `.example` is reserved and never + # resolves. `http://localhost:3000/`, which this used to suggest, is where + # a Zammad under development listens. + EXAMPLE = 'TEST_URL=https://zammad.example/ TEST_USER=admin@example.com TEST_PASSWORD=test' + + module_function + + # @return [String, nil] TEST_URL, or nil where it is unset or blank - + # Unicode spaces included, as Rails reads blank + def url + value = ENV['TEST_URL'].to_s + value.match?(/\A[[:space:]]*\z/) ? nil : value.strip + end + + # @param what [String] what the refusing check would have done, and to what + # @return [String] + def unset_message(what) + "TEST_URL is not set. #{what} creates and deletes records in the Zammad it runs against, so name one, " \ + "and make it one you can lose: #{EXAMPLE}" + end +end diff --git a/spec/integration/authentication_spec.rb b/spec/integration/authentication_spec.rb new file mode 100644 index 0000000..79a8380 --- /dev/null +++ b/spec/integration/authentication_spec.rb @@ -0,0 +1,29 @@ +# frozen_string_literal: true + +RSpec.describe ZammadAPI, 'authentication' do + it 'has a version number' do + expect(ZammadAPI::VERSION).not_to be_nil + end + + context 'with invalid credentials' do + let(:client) { Helper.client(user: 'not_existing', password: 'not_existing') } + + it 'raises AuthenticationError with the failing operation' do + expect { client.users.find(1) }.to raise_error(ZammadAPI::AuthenticationError) do |error| + expect(error.status).to eq(401) + expect(error.operation).to eq('find object') + expect(error.resource_class).to eq(ZammadAPI::Resources::User) + end + end + + it 'raises a ClientError, so both can be rescued together' do + expect { client.users.find(1) }.to raise_error(ZammadAPI::ClientError) + end + + %i[organization group ticket_priority ticket_state].each do |resource| + it "raises for #{resource}" do + expect { client.public_send(resource).find(1) }.to raise_error(ZammadAPI::AuthenticationError) + end + end + end +end diff --git a/spec/zammad_api/resources/group_spec.rb b/spec/integration/group_spec.rb similarity index 83% rename from spec/zammad_api/resources/group_spec.rb rename to spec/integration/group_spec.rb index 6caf0d3..f3ab1b6 100644 --- a/spec/zammad_api/resources/group_spec.rb +++ b/spec/integration/group_spec.rb @@ -1,22 +1,22 @@ -require 'spec_helper' +# frozen_string_literal: true -describe ZammadAPI, 'group object basics' do +RSpec.describe ZammadAPI, 'group object basics' do client = Helper.client name = "some_group#{Helper.random}" group = nil it 'new with invalid attributes' do - group_invalid = client.group.new + group_invalid = client.groups.new expect(group_invalid.class).to eq(ZammadAPI::Resources::Group) expect(group_invalid.new_record?).to be(true) - expect { group_invalid.save }.to raise_error(ZammadAPI::ClientError) + expect { group_invalid.save! }.to raise_error(ZammadAPI::ClientError) end it 'new with valid attributes' do - group = client.group.new( + group = client.groups.new( name: name, assignment_timeout: 100, follow_up_assignment: false, @@ -37,6 +37,7 @@ end it 'save' do + group = established!(group, 'new with valid attributes') result = group.save expect(result).to be(true) @@ -76,7 +77,8 @@ end it 'find' do - group_lookup = client.group.find(group.id) + group = established!(group, 'new with valid attributes') + group_lookup = client.groups.find(group.id) expect(group_lookup.class).to eq(ZammadAPI::Resources::Group) expect(group_lookup.id).to eq(group.id) @@ -89,7 +91,8 @@ end it 'all' do - groups = client.group.all + group = established!(group, 'new with valid attributes') + groups = client.groups.all group_exists = nil groups.each do |local_group| @@ -109,7 +112,7 @@ group_exists.active = true group_exists.save - group_lookup = client.group.find(group.id) + group_lookup = client.groups.find(group.id) expect(group_lookup.class).to eq(ZammadAPI::Resources::Group) expect(group_lookup.id).to eq(group.id) expect(group_lookup.name).to eq("#{name}-2") @@ -121,9 +124,9 @@ end it 'pagination with all' do - groups = client.group.all + groups = client.groups.all - expect(groups[0].class).to eq(ZammadAPI::Resources::Group) + expect(groups.first.class).to eq(ZammadAPI::Resources::Group) count = 0 groups.each do |local_group| @@ -133,13 +136,13 @@ expect(count).to eq(3) count = 0 - groups = client.group.all - groups.page(1, 3) do |local_group| + groups = client.groups.all + groups.page(1, per_page: 3).each do |local_group| expect(local_group.class).to eq(ZammadAPI::Resources::Group) count += 1 end expect(count).to eq(3) - groups.page(2, 3) do |local_group| + groups.page(2, per_page: 3).each do |local_group| expect(local_group.class).to eq(ZammadAPI::Resources::Group) count += 1 end @@ -147,6 +150,7 @@ end it 'destroy' do + group = established!(group, 'new with valid attributes') result = group.destroy expect(result).to be(true) diff --git a/spec/zammad_api/resources/organization_spec.rb b/spec/integration/organization_spec.rb similarity index 80% rename from spec/zammad_api/resources/organization_spec.rb rename to spec/integration/organization_spec.rb index 7851181..2bfd08c 100644 --- a/spec/zammad_api/resources/organization_spec.rb +++ b/spec/integration/organization_spec.rb @@ -1,22 +1,22 @@ -require 'spec_helper' +# frozen_string_literal: true -describe ZammadAPI, 'organization object basics' do +RSpec.describe ZammadAPI, 'organization object basics' do client = Helper.client name = "some_organization#{Helper.random}" organization = nil it 'new with invalid attributes' do - organization_invalid = client.organization.new + organization_invalid = client.organizations.new expect(organization_invalid.class).to eq(ZammadAPI::Resources::Organization) expect(organization_invalid.new_record?).to be(true) - expect { organization_invalid.save }.to raise_error(ZammadAPI::ClientError) + expect { organization_invalid.save! }.to raise_error(ZammadAPI::ClientError) end it 'new with valid attributes' do - organization = client.organization.new( + organization = client.organizations.new( name: name, shared: false, note: '', @@ -33,6 +33,7 @@ end it 'save' do + organization = established!(organization, 'new with valid attributes') result = organization.save expect(result).to be(true) @@ -72,7 +73,8 @@ end it 'find' do - organization_lookup = client.organization.find(organization.id) + organization = established!(organization, 'new with valid attributes') + organization_lookup = client.organizations.find(organization.id) expect(organization_lookup.class).to eq(ZammadAPI::Resources::Organization) expect(organization_lookup.id).to eq(organization.id) @@ -85,7 +87,8 @@ end it 'all' do - organizations = client.organization.all + organization = established!(organization, 'new with valid attributes') + organizations = client.organizations.all organization_exists = nil organizations.each do |local_organization| @@ -104,7 +107,7 @@ organization_exists.active = true organization_exists.save - organization_lookup = client.organization.find(organization.id) + organization_lookup = client.organizations.find(organization.id) expect(organization_lookup.class).to eq(ZammadAPI::Resources::Organization) expect(organization_lookup.id).to eq(organization.id) expect(organization_lookup.name).to eq("#{name}-2") @@ -115,9 +118,9 @@ end it 'pagination with all' do - organizations = client.organization.all + organizations = client.organizations.all - expect(organizations[0].class).to eq(ZammadAPI::Resources::Organization) + expect(organizations.first.class).to eq(ZammadAPI::Resources::Organization) count = 0 organizations.each do |local_organization| @@ -127,13 +130,13 @@ expect(count).to eq(2) count = 0 - organizations = client.organization.all - organizations.page(1, 3) do |local_organization| + organizations = client.organizations.all + organizations.page(1, per_page: 3).each do |local_organization| expect(local_organization.class).to eq(ZammadAPI::Resources::Organization) count += 1 end expect(count).to eq(2) - organizations.page(2, 3) do |local_organization| + organizations.page(2, per_page: 3).each do |local_organization| expect(local_organization.class).to eq(ZammadAPI::Resources::Organization) count += 1 end @@ -141,7 +144,8 @@ end it 'search' do - organizations = client.organization.search(query: name) + organization = established!(organization, 'new with valid attributes') + organizations = client.organizations.search(name) organization_exists = nil organizations.each do |local_organization| @@ -160,7 +164,7 @@ organization_exists.active = false organization_exists.save - organization_lookup = client.organization.find(organization.id) + organization_lookup = client.organizations.find(organization.id) expect(organization_lookup.class).to eq(ZammadAPI::Resources::Organization) expect(organization_lookup.id).to eq(organization.id) expect(organization_lookup.name).to eq("#{name}-2") @@ -171,9 +175,10 @@ end it 'pagination with search' do - organizations = client.organization.search(query: "#{name}-2") + organization = established!(organization, 'new with valid attributes') + organizations = client.organizations.search("#{name}-2") - expect(organizations[0].class).to eq(ZammadAPI::Resources::Organization) + expect(organizations.first.class).to eq(ZammadAPI::Resources::Organization) count = 0 organization_exists = nil @@ -194,13 +199,13 @@ expect(organization_exists.updated_by).to eq('admin@example.com') count = 0 - organizations = client.organization.search(query: 'zammad') - organizations.page(1, 3) do |local_organization| + organizations = client.organizations.search('zammad') + organizations.page(1, per_page: 3).each do |local_organization| expect(local_organization.class).to eq(ZammadAPI::Resources::Organization) count += 1 end expect(count).to eq(1) - organizations.page(2, 3) do |local_organization| + organizations.page(2, per_page: 3).each do |local_organization| expect(local_organization.class).to eq(ZammadAPI::Resources::Organization) count += 1 end @@ -208,6 +213,7 @@ end it 'destroy' do + organization = established!(organization, 'new with valid attributes') result = organization.destroy expect(result).to be(true) diff --git a/spec/zammad_api/resources/ticket_priority_spec.rb b/spec/integration/ticket_priority_spec.rb similarity index 75% rename from spec/zammad_api/resources/ticket_priority_spec.rb rename to spec/integration/ticket_priority_spec.rb index 45f41a8..646eda2 100644 --- a/spec/zammad_api/resources/ticket_priority_spec.rb +++ b/spec/integration/ticket_priority_spec.rb @@ -1,22 +1,22 @@ -require 'spec_helper' +# frozen_string_literal: true -describe ZammadAPI, 'ticket priority object basics' do +RSpec.describe ZammadAPI, 'ticket priority object basics' do client = Helper.client name = "some_ticket_priority#{Helper.random}" ticket_priority = nil it 'new with invalid attributes' do - ticket_priority_invalid = client.ticket_priority.new + ticket_priority_invalid = client.ticket_priorities.new expect(ticket_priority_invalid.class).to eq(ZammadAPI::Resources::TicketPriority) expect(ticket_priority_invalid.new_record?).to be(true) - expect { ticket_priority_invalid.save }.to raise_error(ZammadAPI::ClientError) + expect { ticket_priority_invalid.save! }.to raise_error(ZammadAPI::ClientError) end it 'new with valid attributes' do - ticket_priority = client.ticket_priority.new( + ticket_priority = client.ticket_priorities.new( name: name, note: '', active: true, @@ -31,6 +31,7 @@ end it 'save' do + ticket_priority = established!(ticket_priority, 'new with valid attributes') result = ticket_priority.save expect(result).to be(true) @@ -61,7 +62,8 @@ end it 'find' do - ticket_priority_lookup = client.ticket_priority.find(ticket_priority.id) + ticket_priority = established!(ticket_priority, 'new with valid attributes') + ticket_priority_lookup = client.ticket_priorities.find(ticket_priority.id) expect(ticket_priority_lookup.class).to eq(ZammadAPI::Resources::TicketPriority) expect(ticket_priority_lookup.id).to eq(ticket_priority.id) @@ -71,7 +73,8 @@ end it 'all' do - ticket_priorities = client.ticket_priority.all + ticket_priority = established!(ticket_priority, 'new with valid attributes') + ticket_priorities = client.ticket_priorities.all ticket_priority_exists = nil ticket_priorities.each do |local_ticket_priority| @@ -88,7 +91,7 @@ ticket_priority_exists.active = true ticket_priority_exists.save - ticket_priority_lookup = client.ticket_priority.find(ticket_priority.id) + ticket_priority_lookup = client.ticket_priorities.find(ticket_priority.id) expect(ticket_priority_lookup.class).to eq(ZammadAPI::Resources::TicketPriority) expect(ticket_priority_lookup.id).to eq(ticket_priority.id) expect(ticket_priority_lookup.name).to eq("#{name}-2") @@ -97,9 +100,9 @@ end it 'pagination with all' do - ticket_priorities = client.ticket_priority.all + ticket_priorities = client.ticket_priorities.all - expect(ticket_priorities[0].class).to eq(ZammadAPI::Resources::TicketPriority) + expect(ticket_priorities.first.class).to eq(ZammadAPI::Resources::TicketPriority) count = 0 ticket_priorities.each do |local_ticket_priority| @@ -109,18 +112,18 @@ expect(count).to eq(4) count = 0 - ticket_priorities = client.ticket_priority.all - ticket_priorities.page(1, 2) do |local_ticket_priority| + ticket_priorities = client.ticket_priorities.all + ticket_priorities.page(1, per_page: 2).each do |local_ticket_priority| expect(local_ticket_priority.class).to eq(ZammadAPI::Resources::TicketPriority) count += 1 end expect(count).to eq(2) - ticket_priorities.page(2, 2) do |local_ticket_priority| + ticket_priorities.page(2, per_page: 2).each do |local_ticket_priority| expect(local_ticket_priority.class).to eq(ZammadAPI::Resources::TicketPriority) count += 1 end expect(count).to eq(4) - ticket_priorities.page(3, 2) do |local_ticket_priority| + ticket_priorities.page(3, per_page: 2).each do |local_ticket_priority| expect(local_ticket_priority.class).to eq(ZammadAPI::Resources::TicketPriority) count += 1 end @@ -128,6 +131,7 @@ end it 'destroy' do + ticket_priority = established!(ticket_priority, 'new with valid attributes') result = ticket_priority.destroy expect(result).to be(true) diff --git a/spec/zammad_api/resources/ticket_spec.rb b/spec/integration/ticket_spec.rb similarity index 84% rename from spec/zammad_api/resources/ticket_spec.rb rename to spec/integration/ticket_spec.rb index 1c95705..fb7a75d 100644 --- a/spec/zammad_api/resources/ticket_spec.rb +++ b/spec/integration/ticket_spec.rb @@ -1,22 +1,22 @@ -require 'spec_helper' +# frozen_string_literal: true -describe ZammadAPI, 'ticket object basics' do +RSpec.describe ZammadAPI, 'ticket object basics' do client = Helper.client title = "some ticket title ##{Helper.random}" ticket = nil it 'new with invalid attributes' do - ticket_invalid = client.ticket.new + ticket_invalid = client.tickets.new expect(ticket_invalid.class).to eq(ZammadAPI::Resources::Ticket) expect(ticket_invalid.new_record?).to be(true) - expect { ticket_invalid.save }.to raise_error(ZammadAPI::ClientError) + expect { ticket_invalid.save! }.to raise_error(ZammadAPI::ClientError) end it 'new with valid attributes' do - ticket = client.ticket.new( + ticket = client.tickets.new( title: title, state: 'new', priority: '2 normal', @@ -42,6 +42,7 @@ end it 'save' do + ticket = established!(ticket, 'new with valid attributes') result = ticket.save expect(result).to be(true) @@ -80,11 +81,11 @@ articles = ticket.articles expect(articles.length).to eq(1) - expect(articles[0].class).to eq(ZammadAPI::Resources::TicketArticle) + expect(articles.first.class).to eq(ZammadAPI::Resources::TicketArticle) expect(articles[0].subject).to eq('some subject') expect(articles[0].body).to eq('some body') - ticket.article( + ticket.add_article( subject: 'some subject2', body: 'some body2', ) @@ -96,7 +97,7 @@ expect(articles[1].body).to eq('some body2') expect(articles[1].attachments.count).to eq(0) - ticket.article( + ticket.add_article( subject: 'some subject3', body: 'some body3', attachments: [ @@ -121,7 +122,8 @@ end it 'find' do - ticket_lookup = client.ticket.find(ticket.id) + ticket = established!(ticket, 'new with valid attributes') + ticket_lookup = client.tickets.find(ticket.id) expect(ticket_lookup.class).to eq(ZammadAPI::Resources::Ticket) expect(ticket_lookup.id).to eq(ticket.id) @@ -135,7 +137,8 @@ end it 'all' do - tickets = client.ticket.all + ticket = established!(ticket, 'new with valid attributes') + tickets = client.tickets.all ticket_exists = nil tickets.each do |local_ticket| @@ -156,7 +159,7 @@ ticket_exists.state = 'closed' ticket_exists.save - ticket_lookup = client.ticket.find(ticket.id) + ticket_lookup = client.tickets.find(ticket.id) expect(ticket_lookup.class).to eq(ZammadAPI::Resources::Ticket) expect(ticket_lookup.id).to eq(ticket.id) expect(ticket_lookup.title).to eq("#{title}-2") @@ -169,8 +172,9 @@ end it 'pagination with all' do + ticket = established!(ticket, 'new with valid attributes') (1..10).each do |local_count| - client.ticket.create( + client.tickets.create( title: "test count ticket #{local_count}", state: 'new', priority: '2 normal', @@ -187,8 +191,8 @@ ) end - tickets = client.ticket.all - expect(tickets[0].class).to eq(ZammadAPI::Resources::Ticket) + tickets = client.tickets.all + expect(tickets.first.class).to eq(ZammadAPI::Resources::Ticket) count = 0 tickets.each do |local_ticket| expect(local_ticket.class).to eq(ZammadAPI::Resources::Ticket) @@ -197,18 +201,18 @@ expect(count).to eq(12) count = 0 - tickets = client.ticket.all - tickets.page(1, 5) do |local_ticket| + tickets = client.tickets.all + tickets.page(1, per_page: 5).each do |local_ticket| expect(local_ticket.class).to eq(ZammadAPI::Resources::Ticket) count += 1 end expect(count).to eq(5) - tickets.page(2, 5) do |local_ticket| + tickets.page(2, per_page: 5).each do |local_ticket| expect(local_ticket.class).to eq(ZammadAPI::Resources::Ticket) count += 1 end expect(count).to eq(10) - tickets.page(3, 5) do |local_ticket| + tickets.page(3, per_page: 5).each do |local_ticket| expect(local_ticket.class).to eq(ZammadAPI::Resources::Ticket) count += 1 end @@ -216,6 +220,7 @@ end it 'destroy' do + ticket = established!(ticket, 'new with valid attributes') result = ticket.destroy expect(result).to be(true) diff --git a/spec/zammad_api/resources/ticket_state_spec.rb b/spec/integration/ticket_state_spec.rb similarity index 84% rename from spec/zammad_api/resources/ticket_state_spec.rb rename to spec/integration/ticket_state_spec.rb index d672398..8b62bc4 100644 --- a/spec/zammad_api/resources/ticket_state_spec.rb +++ b/spec/integration/ticket_state_spec.rb @@ -1,22 +1,22 @@ -require 'spec_helper' +# frozen_string_literal: true -describe ZammadAPI, 'ticket state object basics' do +RSpec.describe ZammadAPI, 'ticket state object basics' do client = Helper.client name = "some_ticket_state#{Helper.random}" ticket_state = nil it 'new with invalid attributes' do - ticket_state_invalid = client.ticket_state.new + ticket_state_invalid = client.ticket_states.new expect(ticket_state_invalid.class).to eq(ZammadAPI::Resources::TicketState) expect(ticket_state_invalid.new_record?).to be(true) - expect { ticket_state_invalid.save }.to raise_error(ZammadAPI::ClientError) + expect { ticket_state_invalid.save! }.to raise_error(ZammadAPI::ClientError) end it 'new with valid attributes' do - ticket_state = client.ticket_state.new( + ticket_state = client.ticket_states.new( name: name, state_type: 'new', next_state_id: nil, @@ -30,7 +30,7 @@ expect(ticket_state.id).to be_nil expect(ticket_state.name).to eq(name) expect(ticket_state.state_type).to eq('new') - expect(ticket_state.state_type_id).to be_nil + expect(ticket_state.key?(:state_type_id)).to be(false) expect(ticket_state.next_state_id).to be_nil expect(ticket_state.ignore_escalation).to be(false) expect(ticket_state.note).to eq('') @@ -38,6 +38,7 @@ end it 'save' do + ticket_state = established!(ticket_state, 'new with valid attributes') result = ticket_state.save expect(result).to be(true) @@ -91,7 +92,8 @@ end it 'find' do - ticket_state_lookup = client.ticket_state.find(ticket_state.id) + ticket_state = established!(ticket_state, 'new with valid attributes') + ticket_state_lookup = client.ticket_states.find(ticket_state.id) expect(ticket_state_lookup.class).to eq(ZammadAPI::Resources::TicketState) expect(ticket_state_lookup.id).to eq(ticket_state.id) @@ -108,7 +110,8 @@ end it 'all' do - ticket_states = client.ticket_state.all + ticket_state = established!(ticket_state, 'new with valid attributes') + ticket_states = client.ticket_states.all ticket_state_exists = nil ticket_states.each do |local_ticket_state| @@ -132,7 +135,7 @@ ticket_state_exists.active = true ticket_state_exists.save - ticket_state_lookup = client.ticket_state.find(ticket_state.id) + ticket_state_lookup = client.ticket_states.find(ticket_state.id) expect(ticket_state_lookup.class).to eq(ZammadAPI::Resources::TicketState) expect(ticket_state_lookup.id).to eq(ticket_state.id) expect(ticket_state_lookup.name).to eq("#{name}-2") @@ -147,9 +150,9 @@ end it 'pagination with all' do - ticket_states = client.ticket_state.all + ticket_states = client.ticket_states.all - expect(ticket_states[0].class).to eq(ZammadAPI::Resources::TicketState) + expect(ticket_states.first.class).to eq(ZammadAPI::Resources::TicketState) count = 0 ticket_states.each do |local_ticket_state| @@ -159,18 +162,18 @@ expect(count).to be >= 7 count = 0 - ticket_states = client.ticket_state.all - ticket_states.page(1, 3) do |local_ticket_state| + ticket_states = client.ticket_states.all + ticket_states.page(1, per_page: 3).each do |local_ticket_state| expect(local_ticket_state.class).to eq(ZammadAPI::Resources::TicketState) count += 1 end expect(count).to eq(3) - ticket_states.page(2, 3) do |local_ticket_state| + ticket_states.page(2, per_page: 3).each do |local_ticket_state| expect(local_ticket_state.class).to eq(ZammadAPI::Resources::TicketState) count += 1 end expect(count).to eq(6) - ticket_states.page(3, 3) do |local_ticket_state| + ticket_states.page(3, per_page: 3).each do |local_ticket_state| expect(local_ticket_state.class).to eq(ZammadAPI::Resources::TicketState) count += 1 end @@ -178,6 +181,7 @@ end it 'destroy' do + ticket_state = established!(ticket_state, 'new with valid attributes') result = ticket_state.destroy expect(result).to be(true) diff --git a/spec/zammad_api/resources/user_spec.rb b/spec/integration/user_spec.rb similarity index 86% rename from spec/zammad_api/resources/user_spec.rb rename to spec/integration/user_spec.rb index a82b94b..41fd018 100644 --- a/spec/zammad_api/resources/user_spec.rb +++ b/spec/integration/user_spec.rb @@ -1,6 +1,6 @@ -require 'spec_helper' +# frozen_string_literal: true -describe ZammadAPI, 'user object basics' do +RSpec.describe ZammadAPI, 'user object basics' do client = Helper.client random = Helper.random @@ -10,16 +10,16 @@ user = nil it 'new with invalid attributes' do - user_invalid = client.user.new + user_invalid = client.users.new expect(user_invalid.class).to eq(ZammadAPI::Resources::User) expect(user_invalid.new_record?).to be(true) - expect { user_invalid.save }.to raise_error(ZammadAPI::ClientError) + expect { user_invalid.save! }.to raise_error(ZammadAPI::ClientError) end it 'new with valid attributes' do - user = client.user.new( + user = client.users.new( firstname: firstname, lastname: lastname, email: email, @@ -44,6 +44,7 @@ end it 'save' do + user = established!(user, 'new with valid attributes') result = user.save expect(result).to be(true) @@ -88,7 +89,8 @@ end it 'find' do - user_lookup = client.user.find(user.id) + user = established!(user, 'new with valid attributes') + user_lookup = client.users.find(user.id) expect(user_lookup.class).to eq(ZammadAPI::Resources::User) expect(user_lookup.id).to eq(user.id) @@ -105,7 +107,8 @@ end it 'all' do - users = client.user.all + user = established!(user, 'new with valid attributes') + users = client.users.all user_exists = nil users.each do |local_user| @@ -128,7 +131,7 @@ expect(user_exists.updated_by).to eq('admin@example.com') user_exists.save - user_lookup = client.user.find(user.id) + user_lookup = client.users.find(user.id) expect(user_lookup.class).to eq(ZammadAPI::Resources::User) expect(user_lookup.id).to eq(user.id) expect(user_lookup.firstname).to eq("#{firstname}-2") @@ -146,7 +149,7 @@ it 'pagination with all' do (1..10).each do |local_count| - client.user.create( + client.users.create( firstname: "firstname#{local_count}", lastname: "lastname#{local_count}", email: "customer_email#{local_count}@example.com", @@ -157,9 +160,9 @@ ) end - users = client.user.all + users = client.users.all - expect(users[0].class).to eq(ZammadAPI::Resources::User) + expect(users.first.class).to eq(ZammadAPI::Resources::User) count = 0 users.each do |local_user| expect(local_user.class).to eq(ZammadAPI::Resources::User) @@ -168,19 +171,19 @@ expect(count).to eq(15) count = 0 - users = client.user.all - users.page(1, 4) do |local_user| + users = client.users.all + users.page(1, per_page: 4).each do |local_user| expect(local_user.class).to eq(ZammadAPI::Resources::User) count += 1 end expect(count).to eq(4) - users.page(2, 5) do |local_user| + users.page(2, per_page: 5).each do |local_user| expect(local_user.class).to eq(ZammadAPI::Resources::User) count += 1 end expect(count).to eq(9) count = 0 - users.page(1, 200) do |local_user| + users.page(1, per_page: 200).each do |local_user| expect(local_user.class).to eq(ZammadAPI::Resources::User) count += 1 end @@ -188,7 +191,8 @@ end it 'search' do - users = client.user.search(query: firstname) + user = established!(user, 'new with valid attributes') + users = client.users.search(firstname) user_exists = nil users.each do |local_user| @@ -210,7 +214,7 @@ user_exists.active = false user_exists.save - user_lookup = client.user.find(user.id) + user_lookup = client.users.find(user.id) expect(user_lookup.class).to eq(ZammadAPI::Resources::User) expect(user_lookup.id).to eq(user.id) expect(user_lookup.firstname).to eq("#{firstname}-2") @@ -224,9 +228,10 @@ end it 'pagination with search' do - users = client.user.search(query: firstname) + user = established!(user, 'new with valid attributes') + users = client.users.search(firstname) - expect(users[0].class).to eq(ZammadAPI::Resources::User) + expect(users.first.class).to eq(ZammadAPI::Resources::User) count = 0 user_exists = nil @@ -250,13 +255,13 @@ expect(user_exists.updated_by).to eq('admin@example.com') count = 0 - users = client.user.search(query: firstname) - users.page(1, 3) do |local_user| + users = client.users.search(firstname) + users.page(1, per_page: 3).each do |local_user| expect(local_user.class).to eq(ZammadAPI::Resources::User) count += 1 end expect(count).to eq(1) - users.page(2, 3) do |local_user| + users.page(2, per_page: 3).each do |local_user| expect(local_user.class).to eq(ZammadAPI::Resources::User) count += 1 end @@ -264,6 +269,7 @@ end it 'destroy' do + user = established!(user, 'new with valid attributes') # wait until zammad scheduler wrote some entries to activity stream # to have some references and not allow users to delete sleep 12 diff --git a/spec/spec_helper.rb b/spec/spec_helper.rb index 6c318c4..bb3ab91 100644 --- a/spec/spec_helper.rb +++ b/spec/spec_helper.rb @@ -1,50 +1,86 @@ +# frozen_string_literal: true + +if ENV['COVERAGE'] + require 'simplecov' + SimpleCov.start do + enable_coverage :branch + skip '/spec/' + minimum_coverage line: 90, branch: 75 + end +end + $LOAD_PATH.unshift File.expand_path('../lib', __dir__) -# we don't require 'webmock/rspec' over here -# since we want to mock only certain requests -# but the API should be available in general -require 'webmock' +# Unit specs run entirely against stubs; integration specs opt back out below. +require 'webmock/rspec' +require 'zammad_api' + +Dir[File.expand_path('support/**/*.rb', __dir__)].each { require it } RSpec.configure do |config| - config.include WebMock::API - config.include WebMock::Matchers -end + config.include ClientHelper + config.include LifecycleState, :integration -require 'zammad_api' + config.expect_with(:rspec) { it.syntax = :expect } + config.mock_with(:rspec) { it.verify_partial_doubles = true } -class Helper - def self.config - { - url: ENV['TEST_URL'] || 'http://localhost:3000/', - user: ENV['TEST_USER'] || 'admin@example.com', - password: ENV['TEST_PASSWORD'] || 'test' - } - end + config.disable_monkey_patching! + config.warnings = false + config.filter_run_when_matching :focus + config.example_status_persistence_file_path = 'tmp/rspec_status.txt' + config.shared_context_metadata_behavior = :apply_to_host_groups - def self.client(params = {}) - ZammadAPI::Client.new( - url: params[:url] || config[:url], - user: params[:user] || config[:user], - password: params[:password] || config[:password], - ) + # Specs are grouped by what they need: unit specs run against WebMock stubs + # and never touch the network, integration specs need a live Zammad. + # + # The integration specs also walk a record through its lifecycle across + # ordered examples, so they are pinned to definition order. Without that a + # `--seed` or `--order random` run scrambled the lifecycle and failed on a + # record that had not been built yet. Unit specs stay order-independent. + config.define_derived_metadata(file_path: %r{/spec/unit/}) { it[:unit] = true } + config.define_derived_metadata(file_path: %r{/spec/integration/}) do |metadata| + metadata[:integration] = true + metadata[:order] = :defined end - # start auto wizard - def self.auto_wizard - conn = Faraday.new(url: config[:url]) do |faraday| - faraday.adapter Faraday.default_adapter # make requests with Net::HTTP - end - - url_auto_wizard = '/api/v1/getting_started/auto_wizard' - response = conn.get url_auto_wizard - data = JSON.parse(response.body) + # Integration specs write to the Zammad they are pointed at, so they run + # only where TEST_URL names one: see Helper.target. Left out rather than + # failed, so that a bare `rspec` is the unit specs and nothing else, and + # said once so that nobody takes it for a run of them. + # + # The notice goes out when the first of them is loaded rather than before + # the suite: RSpec runs no suite hook for a run that selected nothing, + # which is what `rspec spec/integration` is without a TEST_URL. + # + # A run that selected nothing but them fails, though: `rspec + # spec/integration` without a TEST_URL left every example out and passed + # with `0 examples, 0 failures`, so a CI job that lost its TEST_URL went + # green having run nothing. A bare `rspec` still runs the unit specs, so + # this fires only where everything selected was left out. + config.fail_if_no_examples = true - return true if data['auto_wizard_success'] + if Helper.target.nil? + config.filter_run_excluding :integration + config.when_first_matching_example_defined(:integration) do + warn 'Integration specs left out: they create and delete records, so they run only against the Zammad that ' \ + 'TEST_URL names. Set TEST_URL, TEST_USER and TEST_PASSWORD to run them.' + end + end - raise "Unable to start auto wizard: #{response.body}" + # The instance has to have an admin account before anything can + # authenticate. Doing this from a hook rather than from one spec file keeps + # the suite independent of file order. + config.before(:each, :integration) do + Helper.ensure_configured! end - def self.random - rand(99_999_999).to_s + # Integration specs need the real network, so WebMock steps aside for them. + config.around(:each, :integration) do |example| + WebMock.allow_net_connect! + WebMock.disable! + example.run + ensure + WebMock.enable! + WebMock.disable_net_connect! end end diff --git a/spec/support/bare_socket_adapter.rb b/spec/support/bare_socket_adapter.rb new file mode 100644 index 0000000..6e6f870 --- /dev/null +++ b/spec/support/bare_socket_adapter.rb @@ -0,0 +1,46 @@ +# frozen_string_literal: true + +require 'faraday' +require 'openssl' + +# A Faraday adapter that lets a socket error out raw. +# +# Most adapters wrap one into Faraday::ConnectionFailed, but this gem lets a +# caller choose the adapter, and an adapter that does not wrap is the only way +# to tell apart the two halves of the retry configuration: which failures are +# mapped to a ZammadAPI error, and which are retried before being mapped. +class BareSocketAdapter < Faraday::Adapter + class << self + # @return [Array] the verb of every request that reached here + attr_accessor :attempts + end + self.attempts = [] + + def call(env) + self.class.attempts << env.method + raise Errno::ECONNRESET + end +end + +Faraday::Adapter.register_middleware(bare_socket: BareSocketAdapter) + +# A Faraday adapter that lets a TLS failure out raw. +# +# The counterpart of BareSocketAdapter for OpenSSL::SSL::SSLError, which most +# adapters wrap into Faraday::SSLError. Unwrapped and unlisted, it escaped +# `request` entirely, past every `rescue ZammadAPI::Error` a caller had +# written. +class BareTlsAdapter < Faraday::Adapter + class << self + # @return [Array] the verb of every request that reached here + attr_accessor :attempts + end + self.attempts = [] + + def call(env) + self.class.attempts << env.method + raise OpenSSL::SSL::SSLError, 'certificate verify failed' + end +end + +Faraday::Adapter.register_middleware(bare_tls: BareTlsAdapter) diff --git a/spec/support/client_helper.rb b/spec/support/client_helper.rb new file mode 100644 index 0000000..51110dd --- /dev/null +++ b/spec/support/client_helper.rb @@ -0,0 +1,29 @@ +# frozen_string_literal: true + +# Helpers for unit specs, which talk to WebMock stubs instead of a Zammad. +module ClientHelper + BASE_URL = 'http://zammad.test/' + + # Retries are disabled by default so that specs exercising error paths do + # not wait for the backoff intervals. + def unit_config(**overrides) + { url: BASE_URL, http_token: 'test-token', retries: 0 }.merge(overrides) + end + + def unit_client(**overrides) + ZammadAPI::Client.new(**unit_config(**overrides)) + end + + def unit_transport(**overrides) + ZammadAPI::Transport.new(ZammadAPI::Config.new(**unit_config(**overrides))) + end + + # @return [Hash] arguments for WebMock's +to_return+ with a JSON body + def json_response(body, status: 200, headers: {}) + { + status: status, + body: JSON.generate(body), + headers: { 'Content-Type' => 'application/json' }.merge(headers) + } + end +end diff --git a/spec/support/integration_helper.rb b/spec/support/integration_helper.rb new file mode 100644 index 0000000..f753d39 --- /dev/null +++ b/spec/support/integration_helper.rb @@ -0,0 +1,147 @@ +# frozen_string_literal: true + +require 'securerandom' +require_relative '../../script/live_target' + +# Helpers for integration specs, which need a reachable Zammad instance. +class Helper + class SetupError < StandardError; end + + # The Zammad the integration specs run against, where one was named. + # + # There is no default. These specs run the auto wizard and then create, + # change and delete groups, organizations, users, tickets, states and + # priorities, and `http://localhost:3000/` used to stand in for a TEST_URL + # that was not set. That is where a Zammad under development listens, and + # a bare `rspec` runs these files along with the unit specs, so the + # commonest way to run the suite wrote test records into whatever was + # there. Where to write is for whoever runs them to say. + # + # Asked of {LiveTarget}, which rake and script/check_connection.rb ask + # as well, so that the three agree on whether a target was named. + # + # @return [String, nil] nil when TEST_URL is not set + def self.target = LiveTarget.url + + # Where no TEST_URL is set, a URL nothing answers at stands in for it. The + # spec files build their client while they are loaded, which is before + # RSpec has left their examples out, so this cannot raise; the examples + # never run, and {.ensure_configured!} refuses them if they are made to. + # `.invalid` is reserved for names that never resolve. + UNSET_URL = 'http://test-url-not-set.invalid/' + + def self.config + { + url: target || UNSET_URL, + user: ENV['TEST_USER'] || 'admin@example.com', + password: ENV['TEST_PASSWORD'] || 'test' + } + end + + def self.client(**overrides) + settings = config + ZammadAPI::Client.new( + url: overrides.fetch(:url, settings[:url]), + user: overrides.fetch(:user, settings[:user]), + password: overrides.fetch(:password, settings[:password]), + **overrides.except(:url, :user, :password) + ) + end + + # Makes sure the instance has an admin account, running Zammad's auto wizard + # once per suite. + # + # Memoized and idempotent, so it does not matter which spec file happens to + # run first, and re-running the suite against an already configured instance + # is not an error. + # The failure is memoized alongside the success, because `||=` memoizes + # neither. A TEST_URL with nothing behind it re-ran the whole probe - two + # requests, each with a ten second open timeout - once per example, so a + # Zammad that never came up took the suite a very long time to say so. + def self.ensure_configured! + raise SetupError, 'TEST_URL is not set, so there is no Zammad to run the integration specs against' if target.nil? + return true if @ensure_configured + raise @setup_failure if @setup_failure + + begin + auto_wizard? || verify_setup_done! + @ensure_configured = true + rescue SetupError => e + @setup_failure = e + raise + end + end + + # The body is asked about only where it is a JSON object. Valid JSON + # that is not one - `null`, a list, a number - raised NoMethodError on + # the lookup, which is neither the SetupError {.ensure_configured!} + # memoizes nor an answer, so every example ran the probe again. Anything + # but an object saying the wizard ran leaves {.verify_setup_done!} to + # decide. + # + # @return [Boolean] whether the auto wizard ran now + # @raise [SetupError] when the instance cannot be reached at all + def self.auto_wizard? + response = connection.get('api/v1/getting_started/auto_wizard') + body = parse(response.body) + body.is_a?(Hash) && body['auto_wizard_success'] == true + rescue Faraday::Error => e + # {.verify_setup_done!} wraps its failure into a SetupError naming the URL + # and the user; this probe runs one line earlier and did not, so the + # commonest failure of all - CI booting against a Zammad that never came + # up - reached every example as a bare Faraday exception from a helper + # that exists to explain exactly that. + raise SetupError, + "Zammad at #{config[:url]} could not be reached: the setup check failed to connect " \ + "(#{e.class}: #{e.message}). Set TEST_URL to a running instance." + end + + # A configured Zammad requires authentication even for + # /api/v1/getting_started, so the setup state cannot be read from there. + # Proving that the configured credentials work answers the only question + # that matters here. + def self.verify_setup_done! + ZammadAPI::Client.new(**config).groups.all.page(1, per_page: 1).to_a + true + rescue ZammadAPI::Error => e + raise SetupError, + "Zammad at #{config[:url]} is not usable: the auto wizard did not run and " \ + "authenticating as #{config[:user]} failed (#{e.class}: #{e.message})" + end + + # Finite timeouts matter here: a TEST_URL that accepts the connection but + # never answers would otherwise hang the integration job until the CI + # timeout rather than failing the setup check. + def self.connection + Faraday.new(url: config[:url], request: { open_timeout: 10, timeout: 30 }) + end + + def self.parse(body) + JSON.parse(body) + rescue JSON::ParserError + {} + end + + def self.random + SecureRandom.random_number(99_999_999).to_s + end + + private_class_method :verify_setup_done!, :connection, :parse +end + +# Each integration spec file walks one record through its lifecycle - new, +# save, find, destroy - and every step asserts on what the previous one left +# behind, so the record is shared across ordered examples. +# +# That coupling is fine as long as the whole file runs in definition order, +# and silent nonsense as soon as it does not: `--only-failures`, `-e 'save'` +# or a `--seed` reordering used to fail as `NoMethodError: undefined method +# 'save' for nil`, which says nothing about the actual cause. This says it. +module LifecycleState + def established!(record, example) + return record if record + + raise "this example continues the record built by '#{example}', which did not run in this process. " \ + 'These examples share one record and have to run as a whole file, in definition order.' + end +end diff --git a/spec/unit/zammad_api/associations/proxy_spec.rb b/spec/unit/zammad_api/associations/proxy_spec.rb new file mode 100644 index 0000000..a34ee78 --- /dev/null +++ b/spec/unit/zammad_api/associations/proxy_spec.rb @@ -0,0 +1,433 @@ +# frozen_string_literal: true + +RSpec.describe ZammadAPI::Associations::Proxy do + subject(:ticket) { client.tickets.find(42) } + + let(:client) { unit_client } + let(:ticket_url) { "#{ClientHelper::BASE_URL}api/v1/tickets/42" } + let(:users_url) { "#{ClientHelper::BASE_URL}api/v1/users" } + + let(:ticket_attributes) do + { + id: 42, + title: 'Help', + customer: 'customer@example.com', + customer_id: 7, + state: 'open', + state_id: 2, + group: 'Users', + group_id: 1 + } + end + + before do + stub_request(:get, ticket_url).with(query: hash_including({})).to_return(json_response(ticket_attributes)) + end + + describe 'belongs_to' do + it 'fetches the whole record behind a foreign key' do + stub_request(:get, "#{users_url}/7").with(query: { 'expand' => 'true' }) + .to_return(json_response({ id: 7, email: 'customer@example.com', firstname: 'Nicole' })) + + expect(ticket.related.customer.firstname).to eq('Nicole') + end + + it 'returns the resource class of the target' do + stub_request(:get, "#{users_url}/7").with(query: hash_including({})).to_return(json_response({ id: 7 })) + + expect(ticket.related.customer).to be_a(ZammadAPI::Resources::User) + end + + it 'returns a persisted record' do + stub_request(:get, "#{users_url}/7").with(query: hash_including({})).to_return(json_response({ id: 7 })) + + expect(ticket.related.customer).to be_persisted + end + + it 'leaves the expanded attribute alone, so reading a name stays free' do + expect(ticket.customer).to eq('customer@example.com') + expect(a_request(:get, "#{users_url}/7").with(query: hash_including({}))).not_to have_been_made + end + + it 'does not shadow an expanded attribute that names a state' do + expect(ticket.state).to eq('open') + end + + it 'is nil when the foreign key is not set' do + stub_request(:get, ticket_url).with(query: hash_including({})).to_return(json_response({ id: 42 })) + + expect(ticket.related.customer).to be_nil + end + + it 'makes no request when the foreign key is not set' do + stub_request(:get, ticket_url).with(query: hash_including({})).to_return(json_response({ id: 42 })) + + ticket.related.customer + expect(a_request(:get, %r{api/v1/users}).with(query: hash_including({}))).not_to have_been_made + end + + it 'memoizes, so a loop does not refetch the same record' do + stub_request(:get, "#{users_url}/7").with(query: hash_including({})).to_return(json_response({ id: 7 })) + + held = ticket + 3.times { held.related.customer } + + expect(a_request(:get, "#{users_url}/7").with(query: hash_including({}))).to have_been_made.once + end + + it 'uses the declared foreign key rather than the association name' do + stub = stub_request(:get, "#{ClientHelper::BASE_URL}api/v1/ticket_states/2") + .with(query: hash_including({})) + .to_return(json_response({ id: 2, name: 'open' })) + + ticket.related.state + expect(stub).to have_been_requested + end + + it 'reaches the group resource' do + stub = stub_request(:get, "#{ClientHelper::BASE_URL}api/v1/groups/1") + .with(query: hash_including({})) + .to_return(json_response({ id: 1, name: 'Users' })) + + expect(ticket.related.group.name).to eq('Users') + expect(stub).to have_been_requested + end + + it 'propagates a failure to load the target' do + stub_request(:get, "#{users_url}/7").with(query: hash_including({})) + .to_return(json_response({ error: 'not found' }, status: 404)) + + expect { ticket.related.customer }.to raise_error(ZammadAPI::NotFoundError) + end + end + + describe 'has_many' do + let(:articles_url) { "#{ClientHelper::BASE_URL}api/v1/ticket_articles/by_ticket/42" } + + it 'fetches the list from the association endpoint' do + stub_request(:get, articles_url).with(query: { 'expand' => 'true' }) + .to_return(json_response([{ id: 1, body: 'first' }])) + + expect(ticket.related.articles.map(&:body)).to eq(['first']) + end + + it 'returns records of the target class' do + stub_request(:get, articles_url).with(query: hash_including({})).to_return(json_response([{ id: 1 }])) + + expect(ticket.related.articles.first).to be_a(ZammadAPI::Resources::TicketArticle) + end + + it 'is not memoized, so an article added afterwards shows up' do + stub_request(:get, articles_url).with(query: hash_including({})) + .to_return(json_response([{ id: 1 }]), json_response([{ id: 1 }, { id: 2 }])) + + held = ticket + expect(held.related.articles.size).to eq(1) + expect(held.related.articles.size).to eq(2) + end + + it 'names the association in a parse failure' do + stub_request(:get, articles_url).with(query: hash_including({})).to_return(json_response({ id: 1 })) + + expect { ticket.related.articles } + .to raise_error(ZammadAPI::ParseError, /Can't get articles \(ZammadAPI::Resources::TicketArticle\)/) + end + + # The one list in the gem read in a single request, because the endpoint + # it is declared against serves the whole thing: index_by_ticket iterates + # `ticket.articles` and renders them all, with no pagination to opt into. + # A guard used to sit here for a target that paged anyway, reading a total + # from a response header - a header Zammad sends from no endpoint, so it + # never once looked at a figure. + it 'reads the whole list in one request' do + stub_request(:get, articles_url).with(query: hash_including({})) + .to_return(json_response([{ id: 1 }, { id: 2 }])) + + expect(ticket.related.articles.size).to eq(2) + end + + it 'says to save an unsaved record rather than requesting a path without an id' do + unsaved = ZammadAPI::Resources::Ticket.new(unit_transport, title: 'Help') + + expect { unsaved.related.articles } + .to raise_error(ZammadAPI::Error, /has no id, so it has no articles to read; save it first/) + end + + it 'escapes a traversal in the id instead of reaching another endpoint' do + escaped = "#{ClientHelper::BASE_URL}api/v1/ticket_articles/by_ticket/1%2F..%2F..%2Fusers" + stub = stub_request(:get, escaped).with(query: hash_including({})).to_return(json_response([])) + escaping = ZammadAPI::Resources::Ticket.from_response(unit_transport, id: '1/../../users') + + escaping.related.articles + + expect(stub).to have_been_requested + expect(a_request(:get, "#{ClientHelper::BASE_URL}api/v1/users").with(query: hash_including({}))) + .not_to have_been_made + end + end + + describe 'inheritance' do + it 'gives every resource the stamps Zammad puts on every object' do + expect(ZammadAPI::Resources::Group.associations.keys).to eq(%i[created_by updated_by]) + end + + it 'adds a resource its own associations on top' do + expect(ZammadAPI::Resources::User.associations.keys).to include(:created_by, :organization) + end + + it 'does not leak one resource\'s associations into another' do + expect(ZammadAPI::Resources::Group.associations).not_to have_key(:customer) + end + + it 'does not define another resource\'s reader on the proxy' do + group = ZammadAPI::Resources::Group.from_response(unit_transport, id: 1) + expect(group.related).not_to respond_to(:customer) + end + + it 'raises NoMethodError for an association that was never declared' do + expect { ticket.related.unicorn }.to raise_error(NoMethodError) + end + end + + describe 'the memo' do + before do + stub_request(:get, "#{users_url}/7").with(query: hash_including({})).to_return(json_response({ id: 7 })) + end + + it 'is dropped by reload, because the foreign key may have moved' do + held = ticket + held.related.customer + held.reload + held.related.customer + + expect(a_request(:get, "#{users_url}/7").with(query: hash_including({}))).to have_been_made.twice + end + + it 'is dropped by a save' do + stub_request(:put, ticket_url).with(query: hash_including({})).to_return(json_response(ticket_attributes)) + + held = ticket + held.related.customer + held.update!(title: 'Renamed') + held.related.customer + + expect(a_request(:get, "#{users_url}/7").with(query: hash_including({}))).to have_been_made.twice + end + + it 'is dropped when the foreign key it resolved from is written' do + stub_request(:get, "#{users_url}/9").with(query: hash_including({})) + .to_return(json_response({ id: 9, email: 'nine@example.com' })) + + held = ticket + expect(held.related.customer.id).to eq(7) + + held.customer_id = 9 + + expect(held.related.customer.id).to eq(9) + end + + it 'survives a write to an attribute no association resolves through' do + held = ticket + held.related.customer + held.title = 'Renamed' + held.related.customer + + expect(a_request(:get, "#{users_url}/7").with(query: hash_including({}))).to have_been_made.once + end + + it 'is dropped by assign_attributes touching a foreign key' do + stub_request(:get, "#{users_url}/9").with(query: hash_including({})) + .to_return(json_response({ id: 9 })) + + held = ticket + held.related.customer + held.assign_attributes(title: 'Renamed', customer_id: 9) + + expect(held.related.customer.id).to eq(9) + end + end + + # `related = ticket.related` is the natural thing to write before reading + # two associations. The record used to drop its proxy and build another, so + # everything under 'the memo' above held for a caller who asked the record + # again and for nobody who had kept what they were handed. + describe 'a proxy the caller kept' do + let(:related) { ticket.related } + + before do + stub_request(:get, "#{users_url}/7").with(query: hash_including({})).to_return(json_response({ id: 7 })) + stub_request(:get, "#{users_url}/9").with(query: hash_including({})).to_return(json_response({ id: 9 })) + end + + it 'is the one the record goes on handing out' do + related.customer + ticket.customer_id = 9 + + expect(ticket.related).to be(related) + end + + it 'follows a foreign key that was written' do + expect(related.customer.id).to eq(7) + + ticket.customer_id = 9 + + expect(related.customer.id).to eq(9) + end + + it 'follows a foreign key that assign_attributes wrote' do + related.customer + ticket.assign_attributes(title: 'Renamed', customer_id: 9) + + expect(related.customer.id).to eq(9) + end + + it 'follows a foreign key that a reload moved' do + related.customer + stub_request(:get, ticket_url).with(query: hash_including({})).to_return(json_response(ticket_attributes.merge(customer_id: 9))) + ticket.reload + + expect(related.customer.id).to eq(9) + end + + it 'fetches the target again after a reload that left the foreign key alone' do + related.customer + ticket.reload + related.customer + + expect(a_request(:get, "#{users_url}/7").with(query: hash_including({}))).to have_been_made.twice + end + + it 'fetches the target again after a save' do + stub_request(:put, ticket_url).with(query: hash_including({})).to_return(json_response(ticket_attributes)) + + related.customer + ticket.update!(title: 'Renamed') + related.customer + + expect(a_request(:get, "#{users_url}/7").with(query: hash_including({}))).to have_been_made.twice + end + + it 'keeps its memo across a write no association resolves through' do + related.customer + ticket.title = 'Renamed' + related.customer + + expect(a_request(:get, "#{users_url}/7").with(query: hash_including({}))).to have_been_made.once + end + + context 'when the record was destroyed' do + before do + stub_request(:delete, ticket_url).to_return(json_response({})) + related.customer + ticket.destroy + end + + it 'refuses a target it had already resolved' do + expect { related.customer } + .to raise_error(ZammadAPI::Error, 'ZammadAPI::Resources::Ticket 42 was destroyed, there is nothing to read customer from') + end + + it 'refuses a list, rather than requesting it for a record that is gone' do + expect { related.articles }.to raise_error(ZammadAPI::Error, /was destroyed/) + expect(a_request(:get, %r{ticket_articles/by_ticket})).not_to have_been_made + end + end + + # The write clears the memo, and the lookup that was already out then + # filled it again, with the record behind the value from before. A logger + # or a middleware of the caller's that reaches the record is enough, on + # one thread; so is a second thread. + context 'when the foreign key is written while a lookup is on the wire' do + before do + stub_request(:get, "#{users_url}/7").with(query: hash_including({})).to_return do + ticket.customer_id = 9 + json_response({ id: 7 }) + end + end + + it 'answers that lookup with the record it asked for' do + expect(related.customer.id).to eq(7) + end + + it 'does not keep that answer for the record the key now names' do + related.customer + + expect(related.customer.id).to eq(9) + end + + it 'memoizes the lookup made after it' do + 3.times { related.customer } + + expect(a_request(:get, "#{users_url}/9").with(query: hash_including({}))).to have_been_made.once + end + end + + it 'leaves the proxy of a copy to the copy' do + related.customer + copy = ticket.dup + copy.customer_id = 9 + + expect(related.customer.id).to eq(7) + expect(copy.related.customer.id).to eq(9) + end + end + + describe '.belongs_to_foreign_keys' do + it 'lists the keys a resource resolves associations through' do + expect(ZammadAPI::Resources::Ticket.belongs_to_foreign_keys) + .to include(:customer_id, :owner_id, :group_id, :state_id, :priority_id, :organization_id) + end + + it 'includes the ones inherited from Base' do + expect(ZammadAPI::Resources::Group.belongs_to_foreign_keys).to eq(%i[created_by_id updated_by_id]) + end + end + + describe '#inspect' do + it 'names the record and what can be reached from it' do + expect(ticket.related.inspect) + .to eq( + '#' + ) + end + end + + # A resource a caller declares can point at another of theirs, which is in + # no namespace of this gem. + describe 'an association declared on a resource a caller wrote' do + before do + stub_const('Acme::Role', Class.new(ZammadAPI::Resources::Base) { path 'api/v1/roles' }) + stub_const('Acme::Membership', Class.new(ZammadAPI::Resources::Base) do + path 'api/v1/memberships' + belongs_to :role, class_name: 'Acme::Role' + belongs_to :user, class_name: 'User' + end) + end + + let(:membership) { Acme::Membership.from_response(unit_transport, id: 1, role_id: 2, user_id: 3) } + + it 'resolves a target named by its full name' do + stub_request(:get, "#{ClientHelper::BASE_URL}api/v1/roles/2").with(query: hash_including({})) + .to_return(json_response({ id: 2, name: 'Agent' })) + + expect(membership.related.role).to be_a(Acme::Role) + end + + it 'still resolves a resource of this gem by its own name' do + stub_request(:get, "#{ClientHelper::BASE_URL}api/v1/users/3").with(query: hash_including({})) + .to_return(json_response({ id: 3, login: 'agent' })) + + expect(membership.related.user).to be_a(ZammadAPI::Resources::User) + end + + # An application is likely to have a User of its own at the top level. + it 'prefers the resource of this gem over a top-level constant of the same name' do + stub_const('User', Class.new) + stub_request(:get, "#{ClientHelper::BASE_URL}api/v1/users/3").with(query: hash_including({})) + .to_return(json_response({ id: 3, login: 'agent' })) + + expect(membership.related.user).to be_a(ZammadAPI::Resources::User) + end + end +end diff --git a/spec/unit/zammad_api/attribute_access_spec.rb b/spec/unit/zammad_api/attribute_access_spec.rb new file mode 100644 index 0000000..a0397ed --- /dev/null +++ b/spec/unit/zammad_api/attribute_access_spec.rb @@ -0,0 +1,394 @@ +# frozen_string_literal: true + +RSpec.describe ZammadAPI::AttributeAccess do + subject(:record) { record_class.new(attributes) } + + let(:record_class) do + Class.new do + include ZammadAPI::AttributeAccess + + def initialize(attributes) + @attributes = frozen_attributes(attributes) + end + end + end + + let(:attributes) do + { + 'id' => 1, + 'name' => 'Support', + 'preferences' => { 'notes' => [{ 'body' => 'hello' }] } + } + end + + describe 'key normalization' do + it 'symbolizes top level keys' do + expect(record.attributes.keys).to eq(%i[id name preferences]) + end + + it 'symbolizes nested hash keys' do + expect(record.attributes[:preferences].keys).to eq([:notes]) + end + + it 'symbolizes hash keys inside arrays' do + expect(record.attributes[:preferences][:notes].first).to eq({ body: 'hello' }) + end + + it 'leaves keys alone that cannot become symbols' do + expect(record_class.new(1 => 'one').attributes).to eq(1 => 'one') + end + end + + describe 'reading' do + it 'reads through a reader method' do + expect(record.name).to eq('Support') + end + + it 'reads through #[]' do + expect(record[:name]).to eq('Support') + end + + it 'accepts a string key in #[]' do + expect(record['name']).to eq('Support') + end + + it 'exposes the id' do + expect(record.id).to eq(1) + end + + # A reader used to answer nil here, which made a typo a silent nil that + # flowed on into whatever was written with it - and put respond_to? and + # the call itself at odds, since respond_to?(:custom_field) was false + # throughout. + it 'raises for an attribute the record does not carry' do + expect { record.custom_field }.to raise_error(NoMethodError, /undefined attribute custom_field/) + end + + it 'names the readers that tolerate an absent attribute' do + expect { record.custom_field }.to raise_error(NoMethodError, /fetch\(:custom_field, nil\)/) + end + + it 'says the record may be one Zammad served less of' do + expect { record.custom_field }.to raise_error(NoMethodError, /reduced object/) + end + + it 'lists what the record does carry, so the spelling can be compared' do + expect { record.custom_field }.to raise_error(NoMethodError, /carries id, name, preferences/) + end + + # A key that could not become a Symbol is left as it arrived, so sorting + # the keys themselves would raise from inside the message. + it 'lists mixed keys without raising from the message itself' do + expect { record_class.new(1 => 'one', 'name' => 'X').custom_field } + .to raise_error(NoMethodError, /carries 1, name/) + end + + it 'says so plainly for a record that carries nothing' do + expect { record_class.new({}).custom_field } + .to raise_error(NoMethodError, /carries no attributes at all/) + end + + it 'carries the name and the receiver a bare NoMethodError would' do + expect { record.custom_field }.to raise_error(NoMethodError) do |error| + expect(error.name).to eq(:custom_field) + expect(error.receiver).to be(record) + end + end + + it 'still reads an attribute the record carries but Zammad left nil' do + expect(record_class.new('note' => nil).note).to be_nil + end + + it 'leaves [] and fetch answering for an absent attribute' do + expect(record[:custom_field]).to be_nil + expect(record.fetch(:custom_field, 'fallback')).to eq('fallback') + end + + it 'reports known attributes via #key?' do + expect(record.key?(:name)).to be(true) + end + + it 'returns a copy from #to_h' do + record.to_h[:name] = 'changed' + expect(record.name).to eq('Support') + end + end + + describe 'immutability' do + it 'freezes the attribute hash' do + expect { record.attributes[:name] = 'changed' }.to raise_error(FrozenError) + end + + it 'freezes a nested hash' do + expect { record.attributes[:preferences][:notes] = [] }.to raise_error(FrozenError) + end + + it 'freezes a nested array' do + expect { record.attributes[:preferences][:notes] << {} }.to raise_error(FrozenError) + end + + it 'freezes a hash inside an array' do + expect { record.attributes[:preferences][:notes].first[:body] = 'changed' }.to raise_error(FrozenError) + end + + it 'freezes a string value' do + expect { record.name << '!' }.to raise_error(FrozenError) + end + + it 'hands out a deep copy from #to_h' do + copy = record.to_h + copy[:preferences][:notes].first[:body] = 'changed' + + expect(record.attributes[:preferences][:notes].first[:body]).to eq('hello') + end + + it 'hands out mutable strings from #to_h' do + copy = record.to_h + copy[:name] << '!' + + expect(record.name).to eq('Support') + end + end + + describe '#fetch' do + it 'returns the value for a known attribute' do + expect(record.fetch(:name)).to eq('Support') + end + + it 'raises for an unknown attribute' do + expect { record.fetch(:nope) }.to raise_error(KeyError) + end + + it 'supports a default' do + expect(record.fetch(:nope, 'fallback')).to eq('fallback') + end + + # Hash#fetch refuses a third argument, and so does this: collected with a + # splat and read as `default.first`, `fetch(:a, :b, :c)` - a multi-key read + # this has never been - was answered with `:b`. + it 'refuses more than one fallback, the way Hash#fetch does' do + expect { record.fetch(:nope, 'one', 'two') } + .to raise_error(ArgumentError, 'wrong number of arguments (given 3, expected 1..2)') + end + + # Hash#fetch warns and then ignores the default. Silently picking one of + # two fallbacks a caller cannot have meant to pass together is the same + # swallowed mistyped call the arity check above refuses. + # rubocop:disable Lint/UselessDefaultValueArgument -- the call under test + it 'says so when a block supersedes the default, the way Hash#fetch does' do + expect { record.fetch(:nope, 'fallback') { 'block' } } + .to output(/block supersedes default value argument/).to_stderr + end + + it 'still answers from the block when both were given' do + expect { expect(record.fetch(:nope, 'fallback') { 'block' }).to eq('block') }.to output.to_stderr + end + + # Hash#fetch names the line that made the call. A bare Kernel#warn named + # nothing at all - neither the call site nor the library it came from, + # which in an application with several such calls is everything the reader + # needs. `uplevel` supplies both that location and the `warning: ` prefix. + it 'names the line that made the call, the way Hash#fetch does' do + expect { record.fetch(:nope, 'fallback') { 'block' } } + .to output(/attribute_access_spec\.rb:\d+: warning: block supersedes/).to_stderr + end + # rubocop:enable Lint/UselessDefaultValueArgument + end + + # `record[:x] = v` reached method_missing as `:[]=`, which the writer branch + # took for an attribute called `[]` - it staged the index as the value, lost + # the write, and sent `{"[]": "x"}` on the next save. Ruby's operators end in + # `=` too, so `record <= 5` did the same for an attribute called `<`. + describe '#[]=' do + it 'goes through the same refusal a named writer does on a read-only record' do + expect { record[:note] = 'x' }.to raise_error(NoMethodError, /attributes are read-only/) + end + + it 'names the attribute that was tried, not the operator' do + expect { record[:note] = 'x' }.to raise_error(NoMethodError, /tried to set note/) + end + + # `[]=` is a defined method, so respond_to_missing? never sees it: a + # read-only record claimed the one writer it has while denying every named + # one, then raised when it was called - the invariant the writer branch of + # respond_to_missing? is conditional for. + it 'is not claimed by a record that would refuse it' do + expect(record).not_to respond_to(:[]=) + end + + it 'agrees with the named writers on the same record' do + expect(record.respond_to?(:[]=)).to eq(record.respond_to?(:name=)) + end + + # `respond_to?` takes either spelling and Ruby does not normalise the + # argument, so a Symbol-only comparison let the String fall through to the + # definition and answer true on a record that refuses every write. + it 'answers the same for the String spelling' do + # rubocop:disable-next Performance/StringIdentifierArgument -- the String spelling is the point + expect(record.respond_to?('[]=')).to eq(record.respond_to?(:[]=)) + end + end + + describe 'a name that only looks like a writer' do + it 'does not invent an attribute from a comparison operator' do + # Sent rather than written as `record <= 5`, which RuboCop reads as a + # void literal and rewrites away, taking the spec with it. + expect { record.public_send(:<=, 5) }.to raise_error(NoMethodError) + + expect(record.attributes.keys).not_to include(:<) + end + + it 'is not claimed as a writer' do + expect(record).not_to respond_to(:<=) + end + end + + describe '#respond_to?' do + it 'is true for a known attribute' do + expect(record).to respond_to(:name) + end + + it 'is false for an unknown attribute' do + expect(record).not_to respond_to(:nope) + end + + it 'is false for a writer on a read-only record, which would raise' do + expect(record).not_to respond_to(:anything=) + end + + it 'is true for any writer on a record that stages changes' do + expect(ZammadAPI::Resources::Group.new(unit_transport)).to respond_to(:anything=) + end + + it 'is false for a predicate' do + expect(record).not_to respond_to(:name?) + end + end + + describe 'method names that are not attributes' do + it 'raises NoMethodError for a bang method, so typos surface' do + expect { record.save! }.to raise_error(NoMethodError) + end + + it 'raises NoMethodError for a predicate' do + expect { record.active? }.to raise_error(NoMethodError) + end + end + + describe 'pattern matching' do + it 'matches on attribute values' do + result = case record + in { name: 'Support' } then :matched + else :not_matched + end + expect(result).to eq(:matched) + end + + it 'binds matched values' do + case record + in { name: String => name } + expect(name).to eq('Support') + end + end + + it 'matches nested structures' do + case record + in { preferences: { notes: [{ body: String => body }, *] } } + expect(body).to eq('hello') + end + end + + it 'does not match an absent attribute' do + result = case record + in { nope: _ } then :matched + else :not_matched + end + expect(result).to eq(:not_matched) + end + + it 'returns every attribute for a nil key list' do + expect(record.deconstruct_keys(nil)).to eq(record.attributes) + end + + it 'returns only the requested keys' do + expect(record.deconstruct_keys([:name])).to eq(name: 'Support') + end + end + + describe 'equality' do + it 'is the same record as another of its class carrying the same id' do + expect(record).to eq(record_class.new('id' => 1, 'name' => 'Renamed since')) + end + + it 'is not the same record as one with a different id' do + expect(record).not_to eq(record_class.new('id' => 2, 'name' => 'Support')) + end + + it 'is not the same record as one of another class with the same id' do + expect(record).not_to eq(Class.new(record_class).new('id' => 1)) + end + + it 'is not equal to something that is not a record' do + expect(record).not_to eq('id' => 1) + end + + it 'answers #eql? too, so a record can be a Hash key' do + expect({ record => :found }[record_class.new('id' => 1)]).to eq(:found) + end + + it 'hashes equal records alike' do + expect(record.hash).to eq(record_class.new('id' => 1).hash) + end + + it 'deduplicates equal records' do + expect([record, record_class.new('id' => 1)].uniq.size).to eq(1) + end + + it 'collects equal records into one Set member' do + expect(Set[record, record_class.new('id' => 1)].size).to eq(1) + end + + context 'without an id' do + subject(:unsaved) { record_class.new('name' => 'Support') } + + it 'is still itself, so it can be found again as a Hash key' do + expect({ unsaved => :found }[unsaved]).to eq(:found) + end + + it 'is not equal to an identical record, which is still a second record' do + expect(unsaved).not_to eq(record_class.new('name' => 'Support')) + end + + it 'is kept apart from an identical record' do + expect([unsaved, record_class.new('name' => 'Support')].uniq.size).to eq(2) + end + end + end + + describe 'serialization' do + it 'renders the attributes as a JSON object' do + expect(JSON.parse(record.to_json)) + .to eq('id' => 1, 'name' => 'Support', 'preferences' => { 'notes' => [{ 'body' => 'hello' }] }) + end + + it 'renders as its attributes when nested in a structure being generated' do + expect(JSON.parse(JSON.generate(group: record))['group']).to include('name' => 'Support') + end + + it 'carries the generator state, so pretty printing reaches the attributes' do + expect(JSON.pretty_generate(record)).to include("\n") + end + + it 'exposes the attributes to an encoder through #as_json' do + expect(record.as_json).to eq(record.to_h) + end + + it 'hands #as_json a copy rather than the frozen attributes' do + expect(record.as_json).not_to be_frozen + end + end + + it 'rejects writes by default' do + expect { record.name = 'other' }.to raise_error(NoMethodError, /read-only/) + end +end diff --git a/spec/unit/zammad_api/client_spec.rb b/spec/unit/zammad_api/client_spec.rb new file mode 100644 index 0000000..60b158c --- /dev/null +++ b/spec/unit/zammad_api/client_spec.rb @@ -0,0 +1,1141 @@ +# frozen_string_literal: true + +RSpec.describe ZammadAPI::Client do + let(:url) { "#{ClientHelper::BASE_URL}api/v1/users/1" } + + describe '.new' do + it 'refuses more than one way to authenticate' do + expect { described_class.new(url: 'http://zammad.test/', http_token: 't', user: 'u', password: 'p') } + .to raise_error(ZammadAPI::ConfigurationError, /more than one way to authenticate/) + end + + it 'accepts keyword arguments' do + expect(described_class.new(url: 'http://zammad.test/', http_token: 'token')).to be_a(described_class) + end + + it 'surfaces configuration errors' do + expect { described_class.new(http_token: 'token') }.to raise_error(ArgumentError) + end + + it 'rejects a missing url' do + expect { described_class.new(url: nil, http_token: 'token') } + .to raise_error(ZammadAPI::ConfigurationError, 'missing url in config') + end + + it 'rejects an unsupported scheme' do + expect { described_class.new(url: 'ftp://example.com', http_token: 'token') } + .to raise_error(ZammadAPI::ConfigurationError, /needs to start with http/) + end + + it 'rejects missing credentials' do + expect { described_class.new(url: 'http://zammad.test/') } + .to raise_error(ZammadAPI::ConfigurationError, 'missing user in config') + end + + it 'rejects an unknown option' do + expect { described_class.new(url: 'http://zammad.test/', http_token: 't', nonsense: 1) } + .to raise_error(ArgumentError) + end + + it 'exposes the configuration' do + expect(unit_client.config).to be_a(ZammadAPI::Config) + end + end + + describe '.from_env' do + it 'reads the url and access token' do + stub_const('ENV', { 'ZAMMAD_URL' => 'http://zammad.test/', 'ZAMMAD_TOKEN' => 'from-env' }) + + config = described_class.from_env.config + expect(config.url).to eq('http://zammad.test/') + expect(config.http_token).to eq('from-env') + end + + it 'reads basic auth credentials' do + stub_const('ENV', { 'ZAMMAD_URL' => 'http://zammad.test/', 'ZAMMAD_USER' => 'u', 'ZAMMAD_PASSWORD' => 'p' }) + + expect(described_class.from_env.config.authentication_scheme).to eq(:basic) + end + + it 'reads an OAuth2 token' do + stub_const('ENV', { 'ZAMMAD_URL' => 'http://zammad.test/', 'ZAMMAD_OAUTH2_TOKEN' => 'oauth' }) + + expect(described_class.from_env.config.oauth2_token).to eq('oauth') + end + + it 'prefers ZAMMAD_HTTP_TOKEN over ZAMMAD_TOKEN' do + stub_const('ENV', { 'ZAMMAD_URL' => 'http://zammad.test/', 'ZAMMAD_TOKEN' => 'short', 'ZAMMAD_HTTP_TOKEN' => 'explicit' }) + + expect(described_class.from_env.config.http_token).to eq('explicit') + end + + it 'lets an argument win over the environment' do + stub_const('ENV', { 'ZAMMAD_URL' => 'http://zammad.test/', 'ZAMMAD_TOKEN' => 'from-env' }) + + expect(described_class.from_env(http_token: 'passed in').config.http_token).to eq('passed in') + end + + # A credential is read in a fixed order, so a plain merge left the + # environment's token in charge of a client that was handed another way to + # authenticate - and nothing said so. + context 'when an argument names another way to authenticate' do + before do + stub_const('ENV', { 'ZAMMAD_URL' => 'http://zammad.test/', 'ZAMMAD_TOKEN' => 'from-env' }) + end + + it 'uses a user and password passed in, not the token in the environment' do + expect(described_class.from_env(user: 'u', password: 'p').config.authentication_scheme).to eq(:basic) + end + + it 'drops the token the environment held' do + expect(described_class.from_env(user: 'u', password: 'p').config.http_token).to be_nil + end + + it 'uses an OAuth2 token passed in, not the token in the environment' do + expect(described_class.from_env(oauth2_token: 'x').config.authentication_scheme).to eq(:oauth2_token) + end + + it 'sends what was passed in' do + stub = stub_request(:get, 'http://zammad.test/api/v1/users/1') + .with(query: hash_including({}), basic_auth: %w[u p]) + .to_return(json_response({ id: 1 })) + + described_class.from_env(user: 'u', password: 'p', retries: 0).users.find(1) + expect(stub).to have_been_requested + end + end + + # Two ways to authenticate in the environment, and nothing passed in to + # say which is meant. + it 'refuses an environment that sets more than one way to authenticate' do + stub_const('ENV', { 'ZAMMAD_URL' => 'http://zammad.test/', 'ZAMMAD_TOKEN' => 't', 'ZAMMAD_USER' => 'u', 'ZAMMAD_PASSWORD' => 'p' }) + + expect { described_class.from_env } + .to raise_error(ZammadAPI::ConfigurationError, /more than one way to authenticate \(http_token, user and password\)/) + end + + it 'lets an argument say which of them is meant' do + stub_const('ENV', { 'ZAMMAD_URL' => 'http://zammad.test/', 'ZAMMAD_TOKEN' => 't', 'ZAMMAD_USER' => 'u', 'ZAMMAD_PASSWORD' => 'p' }) + + expect(described_class.from_env(http_token: 't').config.authentication_scheme).to eq(:http_token) + end + + it 'keeps the user from the environment when only the password is passed in' do + stub_const('ENV', { 'ZAMMAD_URL' => 'http://zammad.test/', 'ZAMMAD_USER' => 'u', 'ZAMMAD_PASSWORD' => 'old' }) + + config = described_class.from_env(password: 'new').config + expect([config.user, config.password]).to eq(%w[u new]) + end + + it 'accepts options that have no environment variable' do + stub_const('ENV', { 'ZAMMAD_URL' => 'http://zammad.test/', 'ZAMMAD_TOKEN' => 't' }) + + expect(described_class.from_env(timeout: 300).config.timeout).to eq(300) + end + + it 'treats an empty variable as unset' do + stub_const('ENV', { 'ZAMMAD_URL' => 'http://zammad.test/', 'ZAMMAD_TOKEN' => '', 'ZAMMAD_USER' => 'u', 'ZAMMAD_PASSWORD' => 'p' }) + + expect(described_class.from_env.config.authentication_scheme).to eq(:basic) + end + + it 'names the variable to set when the url is missing' do + stub_const('ENV', { 'ZAMMAD_TOKEN' => 't' }) + + expect { described_class.from_env } + .to raise_error(ZammadAPI::ConfigurationError, /set ZAMMAD_URL or pass url:/) + end + + it 'still validates the credentials' do + stub_const('ENV', { 'ZAMMAD_URL' => 'http://zammad.test/' }) + + expect { described_class.from_env }.to raise_error(ZammadAPI::ConfigurationError, 'missing user in config') + end + end + + describe '#me' do + it 'reads the current user' do + stub_request(:get, "#{ClientHelper::BASE_URL}api/v1/users/me") + .with(query: { 'expand' => 'true' }) + .to_return(json_response({ id: 3, email: 'agent@example.com' })) + + expect(unit_client.me.email).to eq('agent@example.com') + end + + it 'returns a persisted user record' do + stub_request(:get, "#{ClientHelper::BASE_URL}api/v1/users/me").with(query: hash_including({})) + .to_return(json_response({ id: 3 })) + + me = unit_client.me + expect(me).to be_a(ZammadAPI::Resources::User) + expect(me).to be_persisted + end + + it 'follows an on_behalf_of scope' do + stub = stub_request(:get, "#{ClientHelper::BASE_URL}api/v1/users/me") + .with(query: hash_including({}), headers: { 'From' => 'agent@example.com' }) + .to_return(json_response({ id: 3 })) + + unit_client.on_behalf_of('agent@example.com').me + expect(stub).to have_been_requested + end + + it 'raises AuthenticationError for invalid credentials' do + stub_request(:get, "#{ClientHelper::BASE_URL}api/v1/users/me").with(query: hash_including({})) + .to_return(json_response({ error: 'authentication failed' }, status: 401)) + + expect { unit_client.me }.to raise_error(ZammadAPI::AuthenticationError) + end + end + + describe '#version' do + it 'reports the version of the Zammad instance' do + stub_request(:get, "#{ClientHelper::BASE_URL}api/v1/version").to_return(json_response({ version: '6.4.0' })) + + expect(unit_client.version).to eq('6.4.0') + end + + it 'is nil when the instance reports no version' do + stub_request(:get, "#{ClientHelper::BASE_URL}api/v1/version").to_return(json_response({})) + + expect(unit_client.version).to be_nil + end + + it 'is not the version of this gem' do + stub_request(:get, "#{ClientHelper::BASE_URL}api/v1/version").to_return(json_response({ version: '6.4.0' })) + + expect(unit_client.version).not_to eq(ZammadAPI::VERSION) + end + end + + describe 'resource readers' do + ZammadAPI::Client::RESOURCES.each do |name, resource_class| + it "exposes ##{name}" do + expect(unit_client.public_send(name).resource_class).to eq(resource_class) + end + + it "responds to ##{name}" do + expect(unit_client).to respond_to(name) + end + end + + it 'returns a proxy' do + expect(unit_client.groups).to be_a(ZammadAPI::ResourceProxy) + end + + it 'lists the supported resource names' do + expect(unit_client.resource_names).to eq(ZammadAPI::Client::RESOURCES.keys) + end + end + + # A proxy is Enumerable over every record of its kind, so the readers are + # plural. The singular names are what they were called in 1.x, when a proxy + # was only a dispatcher for find and create. + describe 'the singular names the readers had in 1.x' do + around do |example| + enabled = Warning[:deprecated] + Warning[:deprecated] = true + example.run + ensure + Warning[:deprecated] = enabled + end + + ZammadAPI::Client::DEPRECATED_RESOURCES.each do |old_name, name| + it "still answers ##{old_name} with what ##{name} answers" do + client = unit_client + proxy = nil + + expect { proxy = client.public_send(old_name) }.to output.to_stderr + expect(proxy).to be(client.public_send(name)) + end + end + + it 'covers every reader' do + expect(ZammadAPI::Client::DEPRECATED_RESOURCES.values).to eq(ZammadAPI::Client::RESOURCES.keys) + end + + it 'warns, naming the replacement' do + expect { unit_client.ticket } + .to output(/ZammadAPI::Client#ticket is deprecated and will be removed in 3\.0: use #tickets instead/).to_stderr + end + + it 'names the line that made the call, not one inside the gem' do + expect { unit_client.ticket }.to output(/#{Regexp.escape(__FILE__)}:#{__LINE__}: warning: /).to_stderr + end + + it 'does not warn for the plural name' do + expect { unit_client.tickets }.not_to output.to_stderr + end + + # Ruby's own category for this, so an application decides whether to hear + # it: a script that has not been migrated does not print a line per call. + it 'says nothing unless deprecation warnings are on' do + Warning[:deprecated] = false + expect { unit_client.ticket }.not_to output.to_stderr + end + + it 'is not listed among the resource names' do + expect(unit_client.resource_names).not_to include(:ticket) + end + end + + describe '#resource' do + it 'accepts a symbol' do + expect(unit_client.resource(:groups).resource_class).to eq(ZammadAPI::Resources::Group) + end + + it 'accepts a string' do + expect(unit_client.resource('groups').resource_class).to eq(ZammadAPI::Resources::Group) + end + + it 'answers with the proxy the reader answers with' do + client = unit_client + expect(client.resource(:ticket_priorities)).to be(client.ticket_priorities) + end + + it 'raises for an unknown resource' do + expect { unit_client.resource(:unicorn) } + .to raise_error(ZammadAPI::UnknownResourceError, /Unknown resource unicorn/) + end + + it 'lists the available resources in the error' do + expect { unit_client.resource(:unicorn) }.to raise_error(/available resources are: groups, organizations/) + end + + # The way to the parts of the API this gem does not model: 1.x reached any + # subclass of Base through const_get, 2.0 closed that, and raw requests + # were all that was left. + context 'with a resource class a caller declared' do + let(:client) { unit_client } + let(:roles_url) { "#{ClientHelper::BASE_URL}api/v1/roles" } + + before do + stub_const('Role', Class.new(ZammadAPI::Resources::Base) { path 'api/v1/roles' }) + end + + it 'answers with a proxy for that class' do + expect(client.resource(Role).resource_class).to be(Role) + end + + it 'reads records of that class from the path it declares' do + stub_request(:get, roles_url).with(query: hash_including({})) + .to_return(json_response([{ id: 1, name: 'Admin' }]), json_response([])) + + expect(client.resource(Role).map { [it.class, it.name] }).to eq([[Role, 'Admin']]) + end + + it 'finds one by id' do + stub_request(:get, "#{roles_url}/2").with(query: hash_including({})).to_return(json_response({ id: 2, name: 'Agent' })) + + expect(client.resource(Role).find(2).name).to eq('Agent') + end + + it 'saves a change to one, sending only what changed' do + stub_request(:get, "#{roles_url}/2").with(query: hash_including({})).to_return(json_response({ id: 2, name: 'Agent', note: nil })) + update = stub_request(:put, "#{roles_url}/2").with(query: hash_including({}), body: { note: 'Reviewed' }) + .to_return(json_response({ id: 2, name: 'Agent', note: 'Reviewed' })) + + client.resource(Role).find(2).update(note: 'Reviewed') + expect(update).to have_been_requested + end + + it 'creates one' do + create = stub_request(:post, roles_url).with(query: hash_including({}), body: { name: 'Auditor' }) + .to_return(json_response({ id: 9, name: 'Auditor' }, status: 201)) + + expect(client.resource(Role).create(name: 'Auditor').id).to eq(9) + expect(create).to have_been_requested + end + + it 'sends the scope of the client it was asked of' do + stub = stub_request(:get, "#{roles_url}/2") + .with(query: hash_including({}), headers: { 'From' => 'agent@example.com' }) + .to_return(json_response({ id: 2 })) + + client.on_behalf_of('agent@example.com').resource(Role).find(2) + expect(stub).to have_been_requested + end + + it 'answers a class this gem models with the proxy its reader answers with' do + expect(client.resource(ZammadAPI::Resources::Ticket)).to be(client.tickets) + end + + it 'takes a subclass of a class this gem models' do + stub_const('MyTicket', Class.new(ZammadAPI::Resources::Ticket)) + stub_request(:get, "#{ClientHelper::BASE_URL}api/v1/tickets/1").with(query: hash_including({})).to_return(json_response({ id: 1 })) + + expect(client.resource(MyTicket).find(1)).to be_a(MyTicket) + end + + it 'leaves the client as it was built' do + expect { client.resource(Role) }.not_to(change { client.instance_variable_get(:@resources).size }) + end + + it 'refuses a class that is not a resource' do + expect { client.resource(String) } + .to raise_error(ArgumentError, /resource takes the name of a resource or a subclass of ZammadAPI::Resources::Base, and String is neither/) + end + + # Reported by the call that named the class, not by its first request. + it 'refuses a resource class that declares no path' do + stub_const('Pathless', Class.new(ZammadAPI::Resources::Base)) + + expect { client.resource(Pathless) }.to raise_error(ZammadAPI::Error, /Pathless does not declare an API path/) + end + + it 'names the class in the hint a collection gives for a lookup by id' do + expect { client.resource(Role).all.find(1) }.to raise_error(ArgumentError, /client\.resource\(Role\)\.find\(1\)/) + end + end + + context 'with a name from 1.x' do + around do |example| + enabled = Warning[:deprecated] + Warning[:deprecated] = true + example.run + ensure + Warning[:deprecated] = enabled + end + + it 'still answers, with the proxy the plural answers with' do + client = unit_client + proxy = nil + + expect { proxy = client.resource(:ticket) }.to output.to_stderr + expect(proxy).to be(client.tickets) + end + + it 'warns, naming the line that made the call' do + expect { unit_client.resource('ticket') } + .to output(/#{Regexp.escape(__FILE__)}:#{__LINE__ - 1}: warning: ZammadAPI::Client#ticket is deprecated/).to_stderr + end + end + end + + describe 'unknown methods' do + it 'raises UnknownResourceError for an unknown resource name' do + expect { unit_client.unicorn }.to raise_error(ZammadAPI::UnknownResourceError, /Unknown resource unicorn/) + end + + it 'does not claim to respond to it' do + expect(unit_client).not_to respond_to(:unicorn) + end + + it 'still raises NoMethodError for a bang method' do + expect { unit_client.save! }.to raise_error(NoMethodError) + end + + it 'still raises NoMethodError for a predicate' do + expect { unit_client.valid? }.to raise_error(NoMethodError) + end + + it 'stays usable in array operations that rely on to_ary' do + client = unit_client + expect([client].flatten).to eq([client]) + end + + it 'leaves Ruby core methods alone, so only declared resources are dispatched' do + expect(unit_client.hash).to be_an(Integer) + end + + it 'defines resource readers on the client itself, so they win over inherited methods' do + expect(described_class.instance_method(:users).owner).to eq(described_class) + end + end + + describe 'raw requests' do + subject(:client) { unit_client } + + let(:roles_url) { "#{ClientHelper::BASE_URL}api/v1/roles" } + + describe '#get' do + it 'reaches an endpoint the gem does not model' do + stub_request(:get, roles_url).to_return(json_response([{ id: 1, name: 'Admin' }])) + + expect(client.get('api/v1/roles').body).to eq([{ id: 1, name: 'Admin' }]) + end + + it 'returns a Response, so the status and headers stay reachable' do + stub_request(:get, roles_url).to_return(json_response([], headers: { 'X-Total-Count' => '7' })) + + response = client.get('api/v1/roles') + expect(response).to be_a(ZammadAPI::Response) + expect(response.status).to eq(200) + expect(response.headers['x-total-count']).to eq('7') + end + + it 'ignores a leading slash, so paths can be pasted from the Zammad docs' do + stub = stub_request(:get, roles_url).to_return(json_response([])) + + client.get('/api/v1/roles') + expect(stub).to have_been_requested + end + + it 'keeps the sub-path of a Zammad served from one' do + stub = stub_request(:get, 'http://zammad.test/helpdesk/api/v1/roles').to_return(json_response([])) + + unit_client(url: 'http://zammad.test/helpdesk/').get('/api/v1/roles') + expect(stub).to have_been_requested + end + + # Faraday lets an absolute URL replace the instance URL and still sends + # the client's headers, so this handed the access token to another host. + it 'refuses an absolute URL rather than sending the credentials to another host' do + expect { client.get('https://other.example/collect') } + .to raise_error(ArgumentError, /a request path is relative to the instance URL/) + end + + it 'makes no request for an absolute URL' do + stub_request(:any, /other\.example/) + + expect { client.get('https://other.example/collect') }.to raise_error(ArgumentError) + expect(a_request(:any, /other\.example/)).not_to have_been_made + end + + it 'refuses an absolute URL whatever the case of its scheme' do + expect { client.get('HTTP://other.example/collect') }.to raise_error(ArgumentError, /absolute URL/) + end + + it 'refuses an absolute URL behind a leading slash' do + expect { client.get('/https://other.example/collect') }.to raise_error(ArgumentError, /absolute URL/) + end + + it 'refuses an absolute URL for every verb' do + %i[post put delete].each do |verb| + expect { client.public_send(verb, 'https://other.example/collect') }.to raise_error(ArgumentError, /absolute URL/) + end + end + + it 'does not quote the path it refuses, which may carry a secret' do + expect { client.get('https://other.example/collect?token=s3cret') } + .to raise_error(ArgumentError) { |error| expect(error.message).not_to include('s3cret') } + end + + # Faraday reads the path with URI, and URI raises an error of its own + # for one it cannot read: neither a ZammadAPI::Error nor the + # ArgumentError a path is documented to raise, and raised after the + # request had been logged. + describe 'a path that cannot be read as a URL' do + it 'refuses one holding a character outside ASCII' do + expect { client.get('api/v1/tägs') } + .to raise_error(ArgumentError, /this one cannot be read as one: it holds a character outside ASCII/) + end + + it 'refuses one holding a space' do + expect { client.get(' api/v1/roles') }.to raise_error(ArgumentError, /it holds a space, or another character a URL does not allow/) + end + + it 'refuses one holding a % that begins no escape' do + expect { client.get('api/v1/roles%zz') }.to raise_error(ArgumentError, /cannot be read as one/) + end + + it 'refuses one whose query string holds what a URL cannot' do + expect { client.get('api/v1/roles?name=prüfung') }.to raise_error(ArgumentError, /a character outside ASCII/) + end + + it 'says how to write it' do + expect { client.get('api/v1/tägs') }.to raise_error(ArgumentError, /a space is %20, and ä is %C3%A4 - or pass a parameter as query:/) + end + + it 'refuses a query string that names a parameter as two kinds of thing' do + expect { client.get('api/v1/roles?a=1&a[b]=2') } + .to raise_error(ArgumentError, /the query string written into this request path cannot be read as parameters/) + end + + it 'does not quote the path, which may carry a secret' do + expect { client.get('api/v1/ro les?token=s3cret') } + .to raise_error(ArgumentError) { |error| expect(error.message).not_to include('s3cret') } + end + + # Ruby attaches the error a rescue raised in to the one it raises, + # and prints it with it. URI's quotes the path. + it 'does not carry the error that quotes the path along as its cause' do + expect { client.get('api/v1/ro les?token=s3cret') }.to raise_error(ArgumentError) { |error| + expect(error.cause).to be_nil + expect(error.full_message(highlight: false)).not_to include('s3cret') + } + end + + it 'does not carry one along for a query string it cannot read either' do + expect { client.get('api/v1/roles?token=s3cret&token[b]=2') } + .to raise_error(ArgumentError) { |error| expect(error.cause).to be_nil } + end + + it 'refuses it for every verb' do + %i[post put delete].each do |verb| + expect { client.public_send(verb, 'api/v1/tägs') }.to raise_error(ArgumentError, /cannot be read as one/) + end + end + + it 'makes no request and leaves no log line for one' do + log = StringIO.new + logged = unit_client(logger: Logger.new(log, level: Logger::DEBUG)) + stub_request(:any, /zammad\.test/) + + expect { logged.get('api/v1/tägs') }.to raise_error(ArgumentError) + expect(a_request(:any, /zammad\.test/)).not_to have_been_made + expect(log.string).to be_empty + end + + it 'still sends the same path percent-encoded' do + stub = stub_request(:get, 'http://zammad.test/api/v1/t%C3%A4gs').to_return(json_response([])) + + client.get('api/v1/t%C3%A4gs') + expect(stub).to have_been_requested + end + + it 'still sends a query string written into the path' do + stub = stub_request(:get, roles_url).with(query: { 'name' => 'prüfung', 'page' => '2' }).to_return(json_response([])) + + client.get('api/v1/roles?name=pr%C3%BCfung&page=2') + expect(stub).to have_been_requested + end + end + + it 'keeps a protocol-relative path on the instance' do + stub = stub_request(:get, 'http://zammad.test/other.example/collect').to_return(json_response([])) + + client.get('//other.example/collect') + expect(stub).to have_been_requested + end + + it 'still sends a path that merely contains a colon' do + stub = stub_request(:get, 'http://zammad.test/api/v1/tags:search').to_return(json_response([])) + + client.get('api/v1/tags:search') + expect(stub).to have_been_requested + end + + it 'passes query parameters' do + stub = stub_request(:get, roles_url).with(query: { 'active' => 'true' }).to_return(json_response([])) + + client.get('api/v1/roles', query: { active: true }) + expect(stub).to have_been_requested + end + + it 'sends the configured authentication' do + stub = stub_request(:get, roles_url) + .with(headers: { 'Authorization' => 'Token test-token' }) + .to_return(json_response([])) + + client.get('api/v1/roles') + expect(stub).to have_been_requested + end + + it 'carries an on_behalf_of scope' do + stub = stub_request(:get, roles_url) + .with(headers: { 'From' => 'agent@example.com' }) + .to_return(json_response([])) + + client.on_behalf_of('agent@example.com').get('api/v1/roles') + expect(stub).to have_been_requested + end + + # An escape hatch that cannot set a header does not reach an endpoint + # that needs one. + it 'sends the headers it was given' do + stub = stub_request(:get, roles_url) + .with(headers: { 'Accept-Language' => 'de-de' }) + .to_return(json_response([])) + + client.get('api/v1/roles', headers: { 'Accept-Language' => 'de-de' }) + expect(stub).to have_been_requested + end + + it 'stringifies a header value the wire could not carry' do + stub = stub_request(:get, roles_url) + .with(headers: { 'X-Retry' => '3' }) + .to_return(json_response([])) + + client.get('api/v1/roles', headers: { 'X-Retry' => 3 }) + expect(stub).to have_been_requested + end + + # Faraday's authorization middleware leaves a header that is already set + # alone, so this would have replaced the client's own credentials - + # quietly, while #inspect went on reporting the scheme it was built with. + it 'refuses to replace the configured authentication' do + expect { client.get('api/v1/roles', headers: { 'Authorization' => 'Token other' }) } + .to raise_error(ArgumentError, /header authorization is set by this client/) + end + + it 'names the option that does mean it' do + expect { client.get('api/v1/roles', headers: { 'Authorization' => 'Token other' }) } + .to raise_error(ArgumentError, /pass http_token:, oauth2_token:, or user: and password:/) + end + + it 'refuses the From header that on_behalf_of owns' do + expect { client.get('api/v1/roles', headers: { from: 'agent@example.com' }) } + .to raise_error(ArgumentError, /use client\.on_behalf_of/) + end + + it 'refuses a nil header value rather than sending an empty one' do + expect { client.get('api/v1/roles', headers: { 'X-Trace' => nil }) } + .to raise_error(ArgumentError, /header x-trace is nil/) + end + + it 'refuses a header value that is not text' do + expect { client.get('api/v1/roles', headers: { 'X-Trace' => ['a'] }) } + .to raise_error(ArgumentError, /a header is always text/) + end + + # HTTP reads the two names as one header, so a merge would send whichever + # Hash order put last and drop the other without a word. + it 'refuses two spellings of one header' do + expect { client.get('api/v1/roles', headers: { 'Accept-Language' => 'de', 'accept-language' => 'en' }) } + .to raise_error(ArgumentError, /header accept-language was given twice/) + end + + it 'makes no request for a header it refuses' do + expect { client.get('api/v1/roles', headers: { 'X-Trace' => nil }) }.to raise_error(ArgumentError) + expect(a_request(:any, /zammad\.test/)).not_to have_been_made + end + + it 'raises the mapped error class' do + stub_request(:get, roles_url).to_return(json_response({ error: 'nope' }, status: 403)) + + expect { client.get('api/v1/roles') }.to raise_error(ZammadAPI::AuthorizationError, /nope/) + end + + it 'names the request in the error message' do + stub_request(:get, roles_url).to_return(json_response({}, status: 500)) + + expect { client.get('api/v1/roles') } + .to raise_error(ZammadAPI::ServerError, "Can't GET api/v1/roles: HTTP 500") + end + + # The path names the request in every error it raises, and a query + # written into it went along: a token in an exception report. + it 'names it without a credential in a query written into the path' do + stub_request(:get, roles_url).with(query: hash_including({})).to_return(json_response({}, status: 500)) + + expect { client.get('api/v1/roles?token=path-s3cret&page=2') } + .to raise_error(ZammadAPI::ServerError, "Can't GET api/v1/roles?token=[REDACTED]&page=2: HTTP 500") + end + + it 'hands back a non-JSON body untouched' do + stub_request(:get, roles_url).to_return(status: 200, body: 'plain', headers: { 'Content-Type' => 'text/plain' }) + + expect(client.get('api/v1/roles').body).to eq('plain') + end + end + + describe '#post' do + it 'sends a JSON body' do + stub = stub_request(:post, roles_url) + .with(body: JSON.generate({ name: 'Agent' }), headers: { 'Content-Type' => 'application/json' }) + .to_return(json_response({ id: 2 })) + + expect(client.post('api/v1/roles', body: { name: 'Agent' }).body).to eq({ id: 2 }) + expect(stub).to have_been_requested + end + + it 'is not retried, so a failed create cannot be duplicated' do + stub_request(:post, roles_url).to_return(json_response({}, status: 500)) + + expect { unit_client(retries: 3).post('api/v1/roles', body: {}) }.to raise_error(ZammadAPI::ServerError) + expect(a_request(:post, roles_url)).to have_been_made.once + end + + it 'redacts credentials from the log' do + stub_request(:post, roles_url).to_return(json_response({})) + + log = StringIO.new + logger = Logger.new(log, level: Logger::DEBUG) + unit_client(logger: logger).post('api/v1/roles', body: { password: 'hunter2' }) + + expect(log.string).to include('[REDACTED]') + expect(log.string).not_to include('hunter2') + end + + it 'redacts a credential-bearing header from the log too' do + stub_request(:post, roles_url).to_return(json_response({})) + + log = StringIO.new + logger = Logger.new(log, level: Logger::DEBUG) + unit_client(logger: logger).post('api/v1/roles', headers: { 'X-Api-Key' => 'hunter2' }) + + expect(log.string).to include('[REDACTED]') + expect(log.string).not_to include('hunter2') + end + + it 'sends the headers it was given' do + stub = stub_request(:post, roles_url).with(headers: { 'X-Trace' => 'abc' }).to_return(json_response({})) + + client.post('api/v1/roles', body: {}, headers: { 'X-Trace' => 'abc' }) + expect(stub).to have_been_requested + end + end + + describe '#put' do + it 'sends a JSON body' do + stub = stub_request(:put, "#{roles_url}/1").with(body: JSON.generate({ name: 'Agent' })).to_return(json_response({ id: 1 })) + + client.put('api/v1/roles/1', body: { name: 'Agent' }) + expect(stub).to have_been_requested + end + + it 'sends the headers it was given' do + stub = stub_request(:put, "#{roles_url}/1").with(headers: { 'X-Trace' => 'abc' }).to_return(json_response({})) + + client.put('api/v1/roles/1', body: {}, headers: { 'X-Trace' => 'abc' }) + expect(stub).to have_been_requested + end + end + + describe '#delete' do + it 'passes query parameters, which is how Zammad takes tag removals' do + stub = stub_request(:delete, "#{ClientHelper::BASE_URL}api/v1/tags/remove") + .with(query: { 'object' => 'Ticket', 'o_id' => '1', 'item' => 'urgent' }) + .to_return(json_response({ success: true })) + + client.delete('api/v1/tags/remove', query: { object: 'Ticket', o_id: 1, item: 'urgent' }) + expect(stub).to have_been_requested + end + + it 'sends the headers it was given' do + stub = stub_request(:delete, roles_url).with(headers: { 'X-Trace' => 'abc' }).to_return(json_response({})) + + client.delete('api/v1/roles', headers: { 'X-Trace' => 'abc' }) + expect(stub).to have_been_requested + end + end + + # The scope is set after the caller's headers, so a request cannot take the + # header out from under the client that was scoped. + it 'keeps the on_behalf_of scope alongside a caller header' do + stub = stub_request(:get, roles_url) + .with(headers: { 'From' => 'agent@example.com', 'X-Trace' => 'abc' }) + .to_return(json_response([])) + + client.on_behalf_of('agent@example.com').get('api/v1/roles', headers: { 'X-Trace' => 'abc' }) + expect(stub).to have_been_requested + end + + it 'does not shadow a resource reader' do + expect(client.resource_names).not_to include(:get, :post, :put, :delete) + end + end + + describe '#on_behalf_of' do + before do + stub_request(:get, url).with(query: hash_including({})).to_return(json_response({ id: 1 })) + end + + it 'sends the From header' do + stub = stub_request(:get, url) + .with(query: hash_including({}), headers: { 'From' => 'agent@example.com' }) + .to_return(json_response({ id: 1 })) + + unit_client.on_behalf_of('agent@example.com').users.find(1) + expect(stub).to have_been_requested + end + + it 'returns a new client' do + client = unit_client + expect(client.on_behalf_of('someone')).not_to be(client) + end + + it 'leaves the original client unscoped' do + client = unit_client + client.on_behalf_of('someone') + client.users.find(1) + + expect(a_request(:get, url).with { |request| request.headers.key?('From') }).not_to have_been_made + end + + it 'keeps the scoped client usable for several requests' do + scoped = unit_client.on_behalf_of('agent@example.com') + scoped.users.find(1) + scoped.users.find(1) + + expect(a_request(:get, url).with(query: hash_including({}), headers: { 'From' => 'agent@example.com' })) + .to have_been_made.twice + end + + # Zammad skips a From header with nothing in it, and a nil sent none, so + # each of these handed back a client that ran every request as the + # account it authenticates as - with no error to say the scope was gone. + describe 'an identifier that names nobody' do + [nil, '', ' ', "\t\n", "\u00A0", "\u3000"].each do |blank| + it "refuses #{blank.inspect}" do + expect { unit_client.on_behalf_of(blank) } + .to raise_error(ArgumentError, /on_behalf_of needs the login, email address or id of a user, and was given #{Regexp.escape(blank.inspect)}/) + end + end + + # Client.build takes anything with a transport's interface. One whose + # with_on_behalf_of stores what it is given would otherwise send an + # empty From header. + it 'refuses one through a transport that does not check it' do + storing = Class.new do + attr_reader :on_behalf_of + + def initialize(on_behalf_of = nil) = @on_behalf_of = on_behalf_of + def with_on_behalf_of(identifier) = self.class.new(identifier) + end + client = described_class.build(unit_client.config, storing.new) + + expect { client.on_behalf_of("\u00A0") }.to raise_error(ArgumentError, /on_behalf_of needs the login/) + end + + it 'hands such a transport the scope as the text the header carries' do + storing = Class.new do + attr_reader :on_behalf_of + + def initialize(on_behalf_of = nil) = @on_behalf_of = on_behalf_of + def with_on_behalf_of(identifier) = self.class.new(identifier) + end + + expect(described_class.build(unit_client.config, storing.new).on_behalf_of(7).inspect).to include('on_behalf_of="7"') + end + + it 'says what the request would have run as' do + expect { unit_client.on_behalf_of(nil) }.to raise_error(ArgumentError, /performed as the account this client authenticates as/) + end + + it 'refuses it before the block is run' do + ran = false + expect { unit_client.on_behalf_of('') { ran = true } }.to raise_error(ArgumentError) + + expect(ran).to be(false) + end + + it 'still takes a user id' do + stub = stub_request(:get, url).with(query: hash_including({}), headers: { 'From' => '7' }).to_return(json_response({ id: 1 })) + unit_client.on_behalf_of(7).users.find(1) + + expect(stub).to have_been_requested + end + end + + describe 'block form' do + it 'yields a scoped client' do + unit_client.on_behalf_of('agent@example.com') { |scoped| scoped.users.find(1) } + + expect(a_request(:get, url).with(query: hash_including({}), headers: { 'From' => 'agent@example.com' })) + .to have_been_made + end + + it 'returns the block value' do + expect(unit_client.on_behalf_of('agent@example.com') { :done }).to eq(:done) + end + + it 'does not affect the outer client when the block raises' do + client = unit_client + + expect { client.on_behalf_of('agent@example.com') { raise 'boom' } }.to raise_error('boom') + + client.users.find(1) + expect(a_request(:get, url).with { |request| request.headers.key?('From') }).not_to have_been_made + end + end + end + + describe '#with' do + it 'returns a new client' do + client = unit_client + expect(client.with(timeout: 5)).not_to be(client) + end + + it 'applies the changed option' do + expect(unit_client.with(timeout: 5).config.timeout).to eq(5) + end + + it 'leaves the original client untouched' do + client = unit_client + client.with(timeout: 5) + expect(client.config.timeout).to eq(ZammadAPI::Config::DEFAULT_TIMEOUT) + end + + it 'keeps the options that were not changed' do + expect(unit_client.with(timeout: 5).config.http_token).to eq('test-token') + end + + it 're-validates the resulting configuration' do + expect { unit_client.with(timeout: -1) } + .to raise_error(ZammadAPI::ConfigurationError, /positive number/) + end + + # Merged beside the token it was meant to replace, the new credential was + # never sent: the derived client went on acting as the old account. + context 'when it names another way to authenticate' do + it 'switches to an OAuth2 token' do + expect(unit_client.with(oauth2_token: 'x').config.authentication_scheme).to eq(:oauth2_token) + end + + it 'switches to a user and password' do + expect(unit_client.with(user: 'u', password: 'p').config.authentication_scheme).to eq(:basic) + end + + it 'drops the credential it replaced' do + expect(unit_client.with(oauth2_token: 'x').config.http_token).to be_nil + end + + it 'sends the new credential' do + stub = stub_request(:get, url) + .with(query: hash_including({}), headers: { 'Authorization' => 'Bearer x' }) + .to_return(json_response({ id: 1 })) + + unit_client.with(oauth2_token: 'x').users.find(1) + expect(stub).to have_been_requested + end + + it 'leaves the original client on its own credential' do + client = unit_client + client.with(oauth2_token: 'x') + expect(client.config.authentication_scheme).to eq(:http_token) + end + + it 'switches back to an access token from basic authentication' do + basic = unit_client(http_token: nil, user: 'u', password: 'p') + expect(basic.with(http_token: 't').config.to_h.slice(:user, :password, :http_token)) + .to eq({ user: nil, password: nil, http_token: 't' }) + end + end + + it 'replaces a token of the same kind' do + expect(unit_client.with(http_token: 'other').config.http_token).to eq('other') + end + + it 'keeps the user when only the password changes' do + basic = unit_client(http_token: nil, user: 'u', password: 'old').with(password: 'new') + expect([basic.config.user, basic.config.password]).to eq(%w[u new]) + end + + it 'carries an on_behalf_of scope over to the derived client' do + stub = stub_request(:get, url) + .with(query: hash_including({}), headers: { 'From' => 'agent@example.com' }) + .to_return(json_response({ id: 1 })) + + unit_client.on_behalf_of('agent@example.com').with(timeout: 5).users.find(1) + expect(stub).to have_been_requested + end + + it 'still works for requests' do + stub_request(:get, url).with(query: hash_including({})).to_return(json_response({ id: 1 })) + expect(unit_client.with(timeout: 5).users.find(1).id).to eq(1) + end + end + + describe 'concurrent use' do + it 'does not leak an on_behalf_of scope between threads' do + stub_request(:get, url).with(query: hash_including({})).to_return(json_response({ id: 1 })) + + client = unit_client + logins = %w[a@example.com b@example.com c@example.com] + + threads = logins.map do |login| + Thread.new { 5.times { client.on_behalf_of(login).users.find(1) } } + end + threads << Thread.new { 5.times { client.users.find(1) } } + threads.each(&:join) + + logins.each do |login| + expect(a_request(:get, url).with(query: hash_including({}), headers: { 'From' => login })) + .to have_been_made.times(5) + end + end + + it 'leaves the shared client unscoped throughout' do + stub_request(:get, url).with(query: hash_including({})).to_return(json_response({ id: 1 })) + + client = unit_client + threads = %w[a@example.com b@example.com].map do |login| + Thread.new { 5.times { client.on_behalf_of(login).users.find(1) } } + end + threads.each(&:join) + + client.users.find(1) + + expect( + a_request(:get, url).with(query: hash_including({})) { |request| !request.headers.key?('From') } + ).to have_been_made + end + end + + describe '#inspect' do + it 'shows the url and auth scheme' do + expect(unit_client.inspect) + .to eq('#') + end + + it 'does not leak the token' do + expect(unit_client(http_token: 'super-secret').inspect).not_to include('super-secret') + end + + # A scoped client printed as the one it was derived from, so nothing in a + # log told the two apart. + it 'shows the user a scoped client acts for' do + expect(unit_client.on_behalf_of('agent@example.com').inspect) + .to eq('#') + end + + # They used to be sent in place of the configured token, while this went + # on reporting auth=http_token. + it 'cannot be built from a url that carries credentials, so it never reports a scheme it does not use' do + expect { unit_client(url: 'https://admin:url-s3cret@zammad.example.com/') } + .to raise_error(ZammadAPI::ConfigurationError, /config url carries credentials of its own/) + end + end + + # A proxy holds nothing but the client's transport and the resource class, + # and `client.tickets` is the idiom every call starts with - each one used to + # allocate a fresh one. + describe 'resource proxies' do + subject(:client) { unit_client } + + it 'hands out the same proxy for the same resource' do + first = client.tickets + + expect(client.tickets).to be(first) + end + + # Built up front rather than memoized on first use. A client is documented + # as immutable once built and safe to share between threads without + # locking, and a memo filled in by the first `client.tickets` in each worker + # is a write to shared state - harmless under CRuby's GVL, but not the + # contract that was written down. + it 'is not mutated by reading a proxy off it' do + before_read = client.instance_variable_get(:@resources) + client.tickets + + expect(client.instance_variable_get(:@resources)).to be(before_read) + end + + it 'holds a proxy for every resource before any is asked for' do + expect(client.instance_variable_get(:@resources).size).to eq(client.resource_names.size) + end + + it 'refuses to be written to after it is built' do + expect(client.instance_variable_get(:@resources)).to be_frozen + end + + it 'hands out a different proxy per resource' do + expect(client.tickets).not_to be(client.users) + end + + # The cache belongs to one transport, so a derived client must not be + # handed proxies still wired to the transport it was derived from. + it 'does not carry a proxy over to an on_behalf_of client' do + expect(client.on_behalf_of('agent@example.com').tickets).not_to be(client.tickets) + end + + it 'does not carry a proxy over to a client built with #with' do + expect(client.with(timeout: 5).tickets).not_to be(client.tickets) + end + + # The point of not sharing the cache: a proxy from the derived client has + # to send that client's From header, not the original's. + it 'gives a derived client a proxy that carries its own scope' do + stub_request(:get, "#{ClientHelper::BASE_URL}api/v1/tickets/1") + .with(query: hash_including({})).to_return(json_response({ id: 1 })) + + client.tickets + client.on_behalf_of('agent@example.com').tickets.find(1) + + expect(a_request(:get, "#{ClientHelper::BASE_URL}api/v1/tickets/1") + .with(query: hash_including({}), headers: { 'From' => 'agent@example.com' })).to have_been_made + end + end +end diff --git a/spec/unit/zammad_api/collection_spec.rb b/spec/unit/zammad_api/collection_spec.rb new file mode 100644 index 0000000..9124d10 --- /dev/null +++ b/spec/unit/zammad_api/collection_spec.rb @@ -0,0 +1,1306 @@ +# frozen_string_literal: true + +RSpec.describe ZammadAPI::Collection do + subject(:collection) { client.groups.all } + + let(:client) { unit_client } + let(:url) { "#{ClientHelper::BASE_URL}api/v1/groups" } + + # What a collection over this endpoint fetches per request when nothing asks + # for another size: as many as the endpoint serves. Read off the resource + # rather than written out, so that these stubs follow the declaration. + def default_per_page = ZammadAPI::Resources::Group.page_limit + + def stub_page(page, records, per_page: default_per_page) + stub_request(:get, url) + .with(query: { 'expand' => 'true', 'page' => page.to_s, 'per_page' => per_page.to_s }) + .to_return(json_response(records)) + end + + # The walk asks for another page only after a full one, so anything about + # walking needs a page of the size that was requested. + def full_page(first_id = 1) + Array.new(default_per_page) { { id: first_id + it } } + end + + # A short page cannot be told apart from one the server shrank, so the walk + # confirms the end with one more request. Stubbing that empty page is what a + # collection that fits in a single page looks like from out here. + def stub_last_page(page, records, per_page: default_per_page) + stub_page(page, records, per_page: per_page) + stub_page(page + 1, [], per_page: per_page) + end + + # Mirrors Zammad's CanPaginate::Pagination: the endpoint reduces per_page to + # its own maximum and pages by that reduced size. + def stub_capped_endpoint(url, total:, max:) + stub_request(:get, url).with(query: hash_including({})).to_return do |request| + params = URI.decode_www_form(URI(request.uri).query).to_h + limit = [Integer(params['per_page']), max].min + offset = (Integer(params['page']) - 1) * limit + json_response(Array(offset...[offset + limit, total].min).map { { id: it + 1 } }) + end + end + + it 'is an Enumerable' do + expect(described_class.ancestors).to include(Enumerable) + end + + describe '#each' do + it 'walks every page until the server runs out of records' do + stub_page(1, full_page) + stub_page(2, [{ id: default_per_page + 1 }]) + + expect(collection.map(&:id)).to eq((1..(default_per_page + 1)).to_a) + end + + it 'confirms the end of a short first page rather than assuming it' do + stub_last_page(1, [{ id: 1 }]) + + expect(collection.map(&:id)).to eq([1]) + expect(a_request(:get, url).with(query: hash_including('page' => '2'))).to have_been_made + end + + it 'stops on a page shorter than the one the endpoint has been serving' do + stub_page(1, full_page) + stub_page(2, [{ id: default_per_page + 1 }]) + + expect(collection.map(&:id)).to eq((1..(default_per_page + 1)).to_a) + expect(a_request(:get, url).with(query: hash_including('page' => '3'))).not_to have_been_made + end + + it 'walks an endpoint that serves a smaller page than it was asked for' do + stub_capped_endpoint(url, total: 120, max: 50) + + expect(collection.map(&:id)).to eq((1..120).to_a) + end + + it 'stops on an empty page' do + stub_page(1, full_page) + stub_page(2, []) + + expect(collection.map(&:id)).to eq((1..default_per_page).to_a) + end + + it 'yields persisted records' do + stub_page(1, [{ id: 1 }], per_page: 1) + + expect(collection.first).to be_persisted + end + + it 'yields records of the right class' do + stub_page(1, [{ id: 1 }], per_page: 1) + + expect(collection.first).to be_a(ZammadAPI::Resources::Group) + end + + it 'returns an Enumerator without a block' do + expect(collection.each).to be_a(Enumerator) + end + + it 'does not make a request until it is iterated' do + collection + expect(a_request(:get, url).with(query: hash_including({}))).not_to have_been_made + end + + it 'stops fetching early when the caller stops consuming' do + stub_page(1, [{ id: 1 }], per_page: 1) + + expect(collection.first).to be_a(ZammadAPI::Resources::Group) + expect(a_request(:get, url).with(query: hash_including('page' => '2'))).not_to have_been_made + end + + it 'works with lazy enumeration' do + stub_page(1, [{ id: 1 }, { id: 2 }]) + + expect(collection.lazy.map(&:id).first(2)).to eq([1, 2]) + end + + it 'raises ParseError when the endpoint does not return a list' do + stub_request(:get, url).with(query: hash_including({})).to_return(json_response({ id: 1 })) + + expect { collection.to_a } + .to raise_error(ZammadAPI::ParseError, /expected a JSON array, got Hash/) + end + + it 'raises PaginationError when the endpoint ignores the page parameter' do + stub_request(:get, url).with(query: hash_including({})) + .to_return(json_response(full_page)) + + expect { collection.to_a } + .to raise_error(ZammadAPI::PaginationError, /ignoring the page parameter/) + end + + it 'keeps walking records that carry no id' do + stub_page(1, Array.new(default_per_page) { { name: "a#{it}" } }) + stub_page(2, [{ name: 'b0' }]) + + expect(collection.map(&:name)).to eq(Array.new(default_per_page) { "a#{it}" } + ['b0']) + end + + it 'does not hand the repeated page to the block before raising' do + stub_request(:get, url).with(query: hash_including({})) + .to_return(json_response(full_page)) + + batches = [] + + expect { collection.in_batches { batches << it } }.to raise_error(ZammadAPI::PaginationError) + expect(batches.size).to eq(1) + end + + it 'does not yield the repeated records to each either' do + stub_request(:get, url).with(query: hash_including({})) + .to_return(json_response(full_page)) + + seen = 0 + + expect { collection.each { seen += 1 } }.to raise_error(ZammadAPI::PaginationError) + expect(seen).to eq(default_per_page) + end + + # The guard compares the decoded payload, not the bytes it arrived as. + # Hashing raw_body is cheaper and looks equivalent - identical bytes do + # mean identical records - but the implication that matters runs the other + # way: an endpoint that ignores `page` and re-serializes the same records + # with a different key order produces different bytes every time, so the + # guard never fires. Every page is full, so neither the short-page break + # nor the total break fires either, and the walk never ends. + it 'raises PaginationError when a repeated page is re-serialized differently' do + forwards = Array.new(default_per_page) { { id: it, name: "a#{it}" } } + backwards = forwards.map { { name: it[:name], id: it[:id] } } + # Every page differs from the one before it in bytes and from none of + # them in records, which a fixed sequence cannot express: WebMock repeats + # its last response, so two pages running would come back byte-identical + # and a byte digest would catch them one page later. + order = [forwards, backwards].cycle + stub_request(:get, url).with(query: hash_including({})).to_return { json_response(order.next) } + + # Bounded, because what this guards against is a walk that never ends + # rather than one that ends wrongly - unbounded, a regression here hangs + # the suite instead of failing it. + expect { Timeout.timeout(5) { collection.to_a } } + .to raise_error(ZammadAPI::PaginationError, /ignoring the page parameter/) + end + + # A job that writes to the records it is handed changes what they + # serialize as, so the page an endpoint repeats is never the same payload + # twice. Compared by payload the guard never fired: every page was full, + # and the job went round the same records for as long as it ran. + it 'raises PaginationError when a repeated page comes back with its records changed' do + round = 0 + stub_request(:get, url).with(query: hash_including({})).to_return do + round += 1 + json_response(Array.new(default_per_page) { { id: it + 1, updated_at: "2026-11-18T10:00:#{format('%02d', round)}Z" } }) + end + + batches = 0 + + expect { Timeout.timeout(5) { collection.in_batches { batches += 1 } } } + .to raise_error(ZammadAPI::PaginationError, /ignoring the page parameter/) + expect(batches).to eq(1) + end + + # A search sorts by updated_at, so the write that changes a record's + # payload moves it within the page as well. + it 'raises PaginationError when a repeated page comes back changed and in another order' do + round = 0 + stub_request(:get, url).with(query: hash_including({})).to_return do + round += 1 + page = Array.new(default_per_page) { { id: it + 1, note: "round #{round}" } } + json_response(round.odd? ? page : page.reverse) + end + + expect { Timeout.timeout(5) { collection.to_a } } + .to raise_error(ZammadAPI::PaginationError, /ignoring the page parameter/) + end + + it 'does not take two pages that share some of their records for a repeat' do + stub_page(1, full_page) + stub_page(2, full_page(2)) + stub_page(3, []) + + expect(collection.map(&:id)).to eq([*1..default_per_page, *2..(default_per_page + 1)]) + end + + it 'raises PaginationError when records without an id repeat' do + page = Array.new(default_per_page) { { name: "a#{it}" } } + stub_request(:get, url).with(query: hash_including({})).to_return(json_response(page)) + + expect { collection.to_a } + .to raise_error(ZammadAPI::PaginationError, /ignoring the page parameter/) + end + + # The walk ran inside Kernel#loop, which rescues StopIteration for an + # enumerator driven by hand inside it. The block here is the caller's, and + # one raised from it was taken for the end of the walk: the rest of the + # records were dropped and `map` answered with the ones before it. + context 'when the block raises StopIteration' do + let(:labels) { %w[x y].each } + + before { stub_last_page(1, [{ id: 1 }, { id: 2 }, { id: 3 }]) } + + it 'raises it, as the same block over an Array does' do + expect { collection.map { |group| [group.id, labels.next] } }.to raise_error(StopIteration) + end + + it 'raises it from each, rather than ending the walk as if it were complete' do + seen = [] + expect { collection.each { |group| seen << [group.id, labels.next] } }.to raise_error(StopIteration) + + expect(seen).to eq([[1, 'x'], [2, 'y']]) + end + + it 'raises it from in_batches' do + expect { collection.in_batches { raise StopIteration } }.to raise_error(StopIteration) + end + end + + # What Enumerable does with a walk it has had enough of is not an error, + # and still ends it there. + it 'still ends a walk that a break leaves early' do + stub_page(1, full_page) + + expect(collection.each { |group| break group.id if group.id == 2 }).to eq(2) + expect(a_request(:get, url).with(query: hash_including({}))).to have_been_made.once + end + end + + describe '#find_each' do + it 'yields every record' do + stub_page(1, [{ id: 1 }, { id: 2 }], per_page: 2) + stub_page(2, [{ id: 3 }], per_page: 2) + + ids = [] + collection.find_each(batch_size: 2) { ids << it.id } + expect(ids).to eq([1, 2, 3]) + end + + it 'walks at the default page size without one' do + stub_last_page(1, [{ id: 1 }]) + + ids = [] + collection.find_each { ids << it.id } + expect(ids).to eq([1]) + end + + it 'takes the page size inline' do + stub_last_page(1, [{ id: 1 }], per_page: 50) + + expect(collection.find_each(batch_size: 50).map(&:id)).to eq([1]) + end + + it 'returns an Enumerator without a block' do + expect(collection.find_each).to be_a(Enumerator) + end + + it 'rejects a non-positive page size' do + expect { collection.find_each(batch_size: 0) { nil } } + .to raise_error(ArgumentError, 'batch_size needs a positive integer') + end + + # Re-sizing the page silently changed which records the collection held: + # page(3, per_page: 50) names records 101 to 150, and a batch_size of 10 turned + # that into records 21 to 30 with nothing said about it. + it 'refuses to re-size a collection already limited to a page' do + expect { collection.page(3, per_page: 50).find_each(batch_size: 10) { nil } } + .to raise_error(ArgumentError, /batch_size cannot be combined with page/) + end + + it 'says how to name the page it would have served' do + expect { collection.page(3, per_page: 50).find_each(batch_size: 10) { nil } } + .to raise_error(ArgumentError, /page\(3, per_page: 10\)/) + end + end + + describe '#in_batches' do + it 'yields one array per page' do + stub_page(1, [{ id: 1 }, { id: 2 }], per_page: 2) + stub_page(2, [{ id: 3 }], per_page: 2) + + batches = [] + collection.in_batches(of: 2) { batches << it.map(&:id) } + expect(batches).to eq([[1, 2], [3]]) + end + + it 'yields a whole page at the default size without one' do + stub_last_page(1, [{ id: 1 }, { id: 2 }]) + + batches = [] + collection.in_batches { batches << it.map(&:id) } + expect(batches).to eq([[1, 2]]) + end + + # The batch is the block's own Array, and working it off with `shift` is + # an ordinary way to consume one. The walk used to read the size of that + # Array after the block returned, so a drained batch looked like an empty + # page and ended the walk. + it 'keeps walking when the block empties the batch it was handed' do + stub_page(1, [{ id: 1 }, { id: 2 }], per_page: 2) + stub_page(2, [{ id: 3 }], per_page: 2) + + ids = [] + collection.in_batches(of: 2) { |batch| ids << batch.shift.id until batch.empty? } + expect(ids).to eq([1, 2, 3]) + end + + it 'does not take a batch the block shortened for a short page' do + stub_page(1, [{ id: 1 }, { id: 2 }], per_page: 2) + stub_page(2, [{ id: 3 }, { id: 4 }], per_page: 2) + stub_page(3, [], per_page: 2) + + ids = [] + collection.in_batches(of: 2) do |batch| + ids.concat(batch.map(&:id)) + batch.pop if ids.size > 2 + end + expect(ids).to eq([1, 2, 3, 4]) + expect(a_request(:get, url).with(query: hash_including('page' => '3'))).to have_been_made + end + + it 'returns an Enumerator without a block' do + expect(collection.in_batches).to be_a(Enumerator) + end + + it 'refuses to re-size a collection already limited to a page' do + expect { collection.page(3, per_page: 50).in_batches(of: 10) { nil } } + .to raise_error(ArgumentError, /of cannot be combined with page/) + end + + it 'pulls one page per Enumerator#next' do + stub_page(1, [{ id: 1 }, { id: 2 }], per_page: 2) + + expect(collection.in_batches(of: 2).next.map(&:id)).to eq([1, 2]) + expect(a_request(:get, url).with(query: hash_including('page' => '2'))).not_to have_been_made + end + + it 'rejects a non-positive page size' do + expect { collection.in_batches(of: 0) { nil } } + .to raise_error(ArgumentError, 'of needs a positive integer') + end + end + + describe '#page' do + it 'fetches only the requested page' do + stub_page(2, [{ id: 3 }, { id: 4 }]) + + expect(collection.page(2).map(&:id)).to eq([3, 4]) + expect(a_request(:get, url).with(query: hash_including('page' => '3'))).not_to have_been_made + end + + it 'sizes the page, and so decides which records it holds' do + stub_page(2, [{ id: 3 }], per_page: 3) + + expect(collection.page(2, per_page: 3).map(&:id)).to eq([3]) + end + + it 'keeps the size when the page moves' do + stub_page(3, [{ id: 5 }], per_page: 3) + + expect(collection.page(2, per_page: 3).page(3).map(&:id)).to eq([5]) + end + + it 'returns a new collection and leaves the original unpaged' do + stub_last_page(1, [{ id: 1 }]) + + expect(collection.page(2)).not_to be(collection) + expect(collection.map(&:id)).to eq([1]) + end + + it 'rejects page zero' do + expect { collection.page(0) }.to raise_error(ArgumentError, /positive integer/) + end + + it 'rejects a non-integer page' do + expect { collection.page('2') }.to raise_error(ArgumentError, /positive integer/) + end + + it 'rejects a non-positive page size' do + expect { collection.page(1, per_page: 0) }.to raise_error(ArgumentError, 'per_page needs a positive integer') + end + + it 'rejects a non-integer page size' do + expect { collection.page(1, per_page: '7') }.to raise_error(ArgumentError, 'per_page needs a positive integer') + end + end + + describe 'page size caps' do + it 'clamps a walk to what a generic index endpoint serves' do + stub_page(1, [], per_page: 1000) + + client.groups.all.find_each(batch_size: 5000).to_a + expect(a_request(:get, url).with(query: hash_including('per_page' => '1000'))).to have_been_made + end + + it 'refuses a page larger than a generic index endpoint serves' do + expect { client.groups.all.page(1, per_page: 5000) } + .to raise_error(ArgumentError, /serves at most 1000 records per page/) + end + + it 'refuses a page larger than the ticket index endpoint serves' do + expect { client.tickets.all.page(1, per_page: 5000) } + .to raise_error(ArgumentError, /serves at most 100 records per page/) + end + + it 'refuses a page larger than a search endpoint serves' do + expect { client.users.search('smith').page(1, per_page: 5000) } + .to raise_error(ArgumentError, /serves at most 200 records per page/) + end + + it 'names the page that would have been served instead' do + expect { client.tickets.all.page(3, per_page: 500) } + .to raise_error(ArgumentError, /page\(3, per_page: 500\) would be sent as page 3 of 100/) + end + + it 'names a page size the endpoint does serve' do + expect { client.tickets.all.page(3, per_page: 500) } + .to raise_error(ArgumentError, /Ask for page\(3, per_page: 100\) or fewer/) + end + + it 'accepts a page exactly the size the endpoint serves' do + expect(client.tickets.all.page(2, per_page: 100).inspect).to include('per_page=100') + end + + it 'walks the whole list when asked for more per page than the endpoint serves' do + stub_capped_endpoint("#{ClientHelper::BASE_URL}api/v1/tickets", total: 250, max: 100) + + expect(client.tickets.all.find_each(batch_size: 250).map(&:id)).to eq((1..250).to_a) + end + end + + it 'raises rather than building records out of a list of ids' do + stub_page(1, [1, 2, 3]) + + expect { collection.to_a } + .to raise_error(ZammadAPI::ParseError, /expected a JSON array of objects, got an array holding Integer/) + end + + # An index endpoint sorts and pages and does nothing else, so sorting has a + # name of its own. It was reached through `where`, which refused nearly + # everything else it was given. + describe '#order' do + def sorted_request(sort_by, order_by) + a_request(:get, url).with(query: hash_including('sort_by' => sort_by, 'order_by' => order_by)) + end + + before { stub_request(:get, url).with(query: hash_including({})).to_return(json_response([])) } + + it 'sorts ascending by an attribute named on its own' do + collection.order(:name).to_a + expect(sorted_request('name', 'asc')).to have_been_made + end + + it 'sorts the way a keyword says' do + collection.order(name: :desc).to_a + expect(sorted_request('name', 'desc')).to have_been_made + end + + # Zammad pairs the two lists by position and skips an attribute that has + # no direction, so each attribute is sent with one. + it 'sorts by several attributes, each with a direction' do + collection.order(:active, name: :desc).to_a + expect(sorted_request('active,name', 'asc,desc')).to have_been_made + end + + it 'takes an attribute and a direction as strings' do + collection.order('active', 'name' => 'DESC').to_a + expect(sorted_request('active,name', 'asc,desc')).to have_been_made + end + + it 'sorts within an earlier order when chained' do + collection.order(:active).order(name: :desc).to_a + expect(sorted_request('active,name', 'asc,desc')).to have_been_made + end + + it 'keeps the sort on every page it walks' do + stub_request(:get, url).with(query: hash_including('page' => '1')).to_return(json_response(full_page)) + + collection.order(:name).to_a + expect(sorted_request('name', 'asc').with(query: hash_including('page' => '2'))).to have_been_made + end + + it 'keeps the sort on an explicit page' do + collection.order(:name).page(2, per_page: 10).to_a + expect(sorted_request('name', 'asc').with(query: hash_including('page' => '2', 'per_page' => '10'))).to have_been_made + end + + it 'returns a new collection' do + expect(collection.order(:name)).not_to be(collection) + end + + it 'leaves the collection it was called on unsorted' do + collection.order(:name) + collection.to_a + + expect(a_request(:get, url).with(query: { 'expand' => 'true', 'page' => '1', 'per_page' => default_per_page.to_s })) + .to have_been_made + end + + it 'makes no request until the collection is read' do + collection.order(:name) + expect(a_request(:get, url).with(query: hash_including({}))).not_to have_been_made + end + + it 'raises without an attribute to sort by' do + expect { collection.order }.to raise_error(ArgumentError, /order needs at least one attribute to sort by/) + end + + it 'raises for an attribute named twice in one call' do + expect { collection.order(:name, name: :desc) }.to raise_error(ArgumentError, /order was given name twice/) + end + + it 'raises for an attribute the collection is already sorted by' do + expect { collection.order(:name).order(name: :desc) } + .to raise_error(ArgumentError, /order was given name, which this collection is already sorted by/) + end + + it 'raises for a direction that is neither asc nor desc' do + expect { collection.order(name: :down) } + .to raise_error(ArgumentError, /order sorts name either :asc or :desc, got :down/) + end + + # The spelling several other clients use. Read literally it sorts by an + # attribute called desc, which Zammad answers with a server error. + it 'raises for a direction written where an attribute belongs, and says how to write it' do + expect { collection.order(:name, :desc) } + .to raise_error(ArgumentError, /order reads :desc as an attribute to sort by.*order\(name: :desc\)/) + end + + # Several attributes go out as one comma-separated parameter. + it 'raises for a name that would be read as more than one attribute' do + expect { collection.order('name,id') } + .to raise_error(ArgumentError, /order needs the name of an attribute to sort by, got "name,id"/) + end + + it 'raises for something that is not a name at all' do + expect { collection.order(1) }.to raise_error(ArgumentError, /order needs the name of an attribute/) + end + + # TicketsController#index and UsersController#index hardcode the order and + # drop sort_by with everything else they do not read. + context 'with an index endpoint that is always served in id order' do + it 'refuses, rather than handing back records it would be calling sorted' do + expect { client.tickets.all.order(:title) } + .to raise_error(ArgumentError, %r{api/v1/tickets is always served in the same order and ignores sort_by}) + end + + it 'refuses for users too' do + expect { client.users.all.order(:login) }.to raise_error(ArgumentError, %r{api/v1/users is always served}) + end + + it 'points at a search, which does sort' do + expect { client.tickets.all.order(:title) }.to raise_error(ArgumentError, /search\(term\)\.order\(\.\.\.\)/) + end + + it 'makes no request' do + expect { client.tickets.all.order(:title) }.to raise_error(ArgumentError) + expect(a_request(:any, /zammad\.test/)).not_to have_been_made + end + end + + context 'with a search' do + let(:search_url) { "#{ClientHelper::BASE_URL}api/v1/tickets/search" } + + before { stub_request(:get, search_url).with(query: hash_including({})).to_return(json_response([])) } + + it 'sorts, though the index of the same resource does not' do + client.tickets.search('printer').order(created_at: :desc).to_a + + expect(a_request(:get, search_url).with(query: hash_including('query' => 'printer', 'sort_by' => 'created_at', 'order_by' => 'desc'))) + .to have_been_made + end + end + + # Pointing at a search would send the caller in a circle where the + # resource has none. + it 'points at sort_by alone for an unsortable resource Zammad does not search' do + unsortable = Class.new(ZammadAPI::Resources::Base) do + path 'api/v1/things' + sortable false + end + + expect { ZammadAPI::ResourceProxy.new(unit_transport, unsortable).order(:name) } + .to raise_error(ArgumentError, /ignores sort_by, so order would hand back the records as they were\. Sort what this collection yields instead/) + end + end + + describe '#pluck' do + it 'returns one value per record for a single attribute' do + stub_last_page(1, [{ id: 1, name: 'Users' }, { id: 2, name: 'Support' }]) + + expect(collection.pluck(:name)).to eq(%w[Users Support]) + end + + it 'returns one array per record for several attributes' do + stub_last_page(1, [{ id: 1, name: 'Users' }, { id: 2, name: 'Support' }]) + + expect(collection.pluck(:id, :name)).to eq([[1, 'Users'], [2, 'Support']]) + end + + it 'accepts string keys' do + stub_last_page(1, [{ id: 1, name: 'Users' }]) + + expect(collection.pluck('name')).to eq(['Users']) + end + + it 'yields nil for an attribute a record does not carry' do + stub_last_page(1, [{ id: 1 }]) + + expect(collection.pluck(:name)).to eq([nil]) + end + + it 'walks every page, like each' do + stub_page(1, full_page) + stub_page(2, [{ id: default_per_page + 1 }]) + + expect(collection.pluck(:id)).to eq((1..(default_per_page + 1)).to_a) + end + + it 'needs at least one attribute name' do + expect { collection.pluck }.to raise_error(ArgumentError, 'pluck needs at least one attribute name') + end + end + + describe '#count' do + let(:search_url) { "#{ClientHelper::BASE_URL}api/v1/users/search" } + + it 'asks a search endpoint for the total in one request' do + stub_request(:get, search_url) + .with(query: { 'expand' => 'true', 'query' => 'smith', 'only_total_count' => 'true' }) + .to_return(json_response({ total_count: 4711 })) + + expect(client.users.search('smith').count).to eq(4711) + end + + # model_index_render reads sort_by, order_by and the paging and drops + # every other parameter, so only_total_count means nothing to it, and + # there is no header to read a total from either. Probing anyway spent a + # request before the walk that had to happen regardless. + it 'walks an index endpoint rather than probing it for a total it cannot give' do + stub_page(1, full_page) + stub_page(2, [{ id: default_per_page + 1 }]) + + expect(collection.count).to eq(default_per_page + 1) + expect(a_request(:get, url).with(query: hash_including('only_total_count' => 'true'))).not_to have_been_made + end + + # A count is the one answer nothing downstream can sanity check: + # `Array.new(collection.count)` and `count.zero?` both take it at its word. + it 'walks rather than reporting a total that cannot describe a result' do + stub_request(:get, search_url).with(query: hash_including('page' => '1')) + .to_return(json_response([{ id: 1 }])) + stub_request(:get, search_url).with(query: hash_including('page' => '2')) + .to_return(json_response([])) + stub_request(:get, search_url).with(query: hash_including('only_total_count' => 'true')) + .to_return(json_response({ total_count: -3 })) + + expect(client.users.search('smith').count).to eq(1) + end + + it 'walks the pages when a search endpoint answers with no total at all' do + stub_request(:get, search_url).with(query: hash_including('page' => '1')) + .to_return(json_response([{ id: 1 }])) + stub_request(:get, search_url).with(query: hash_including('page' => '2')) + .to_return(json_response([])) + stub_request(:get, search_url).with(query: hash_including('only_total_count' => 'true')) + .to_return(json_response({})) + + expect(client.users.search('smith').count).to eq(1) + end + + it 'walks the pages when the total it answers with is not a count' do + stub_request(:get, search_url).with(query: hash_including('page' => '1')) + .to_return(json_response([{ id: 1 }])) + stub_request(:get, search_url).with(query: hash_including('page' => '2')) + .to_return(json_response([])) + stub_request(:get, search_url).with(query: hash_including('only_total_count' => 'true')) + .to_return(json_response({ total_count: 'lots' })) + + expect(client.users.search('smith').count).to eq(1) + end + + # Not an endpoint Zammad has - all four search actions route through + # model_search_render, which reads only_total_count before it reads + # anything else - but something other than the endpoint can answer: a + # proxy error page, a login form, an HTML body with a 200 on it. + it 'walks the pages when something answers with records instead of a total' do + stub_request(:get, search_url).with(query: hash_including('page' => '1')) + .to_return(json_response([{ id: 1 }, { id: 2 }])) + stub_request(:get, search_url).with(query: hash_including('page' => '2')) + .to_return(json_response([])) + stub_request(:get, search_url).with(query: hash_including('only_total_count' => 'true')) + .to_return(json_response([{ id: 1 }, { id: 2 }])) + + expect(client.users.search('smith').count).to eq(2) + end + + it 'counts one page only when limited to a page' do + stub_page(3, [{ id: 5 }, { id: 6 }]) + + expect(collection.page(3).count).to eq(2) + end + + it 'counts matches when given a block' do + stub_last_page(1, [{ id: 1 }, { id: 2 }, { id: 3 }]) + + expect(collection.count { it.id > 1 }).to eq(2) + end + end + + describe '#size' do + it 'walks the pages, like #count' do + stub_last_page(1, [{ id: 1 }, { id: 2 }]) + + expect(collection.size).to eq(2) + end + + it 'asks a search endpoint for the total in one request' do + stub_request(:get, "#{ClientHelper::BASE_URL}api/v1/users/search") + .with(query: { 'expand' => 'true', 'query' => 'smith', 'only_total_count' => 'true' }) + .to_return(json_response({ total_count: 4711 })) + + expect(client.users.search('smith').size).to eq(4711) + end + + it 'is also spelled #length' do + stub_last_page(1, [{ id: 1 }]) + + expect(collection.length).to eq(1) + end + end + + describe '#empty?' do + it 'is false when the endpoint has a record' do + stub_request(:get, url).with(query: hash_including({})).to_return(json_response([{ id: 1 }])) + + expect(collection).not_to be_empty + end + + it 'is true when the endpoint has none' do + stub_request(:get, url).with(query: hash_including({})).to_return(json_response([])) + + expect(collection).to be_empty + end + + it 'asks for a single record rather than a whole page' do + stub_request(:get, url).with(query: hash_including({})).to_return(json_response([{ id: 1 }])) + + collection.empty? + expect(a_request(:get, url).with(query: hash_including('per_page' => '1'))).to have_been_made + end + + it 'leaves the page size alone on a collection limited to one page' do + stub_request(:get, url).with(query: hash_including({})).to_return(json_response([{ id: 3 }])) + + collection.page(2, per_page: 5).empty? + expect(a_request(:get, url).with(query: hash_including('page' => '2', 'per_page' => '5'))).to have_been_made + end + end + + # `take(n)` and `first(n)` ask one question. Enumerable answers both by + # taking records off the front of a page sized for walking, so with #first + # sizing its own page and this one left alone, what the same read cost + # depended on which word was typed. + describe '#take' do + it 'reads a page sized for what was asked for' do + stub_page(1, [{ id: 1 }, { id: 2 }], per_page: 2) + + expect(collection.take(2).map(&:id)).to eq([1, 2]) + end + + it 'costs what the same read through #first costs' do + stub_page(1, [{ id: 1 }, { id: 2 }], per_page: 2) + + collection.take(2) + expect(a_request(:get, url).with(query: hash_including('per_page' => '2'))).to have_been_made.once + end + + it 'walks when more records are asked for than the endpoint serves' do + stub_page(1, full_page) + stub_page(2, [{ id: default_per_page + 1 }]) + + expect(collection.take(default_per_page + 1).size).to eq(default_per_page + 1) + end + + it 'leaves a zero count to Enumerable' do + expect(collection.take(0)).to eq([]) + end + + # Enumerable#take always answers with an Array, where `first` reads a nil + # as "just the one" and answers with a record. + it 'refuses a nil the way Enumerable#take does' do + expect { collection.take(nil) }.to raise_error(TypeError, /no implicit conversion/) + end + + it 'reads on where the endpoint serves a smaller page than it was asked for' do + stub_capped_endpoint(url, total: 5, max: 2) + + expect(collection.take(5).map(&:id)).to eq([1, 2, 3, 4, 5]) + end + end + + # `find` on the proxy is the lookup by id, and Enumerable#find reads its + # argument as an ifnone callable - so `all.find(1)` answered with an + # Enumerator, made no request and raised nothing. + describe '#find' do + it 'is Enumerable#find with a block' do + stub_last_page(1, [{ id: 1, name: 'Users' }, { id: 2, name: 'Support' }]) + + expect(collection.find { it.name == 'Support' }.id).to eq(2) + end + + it 'refuses an id where a block belongs' do + expect { collection.find(1) } + .to raise_error(ArgumentError, /find on a ZammadAPI::Collection is Enumerable#find, which takes a block/) + end + + it 'names the lookup that does take an id' do + expect { collection.find(1) }.to raise_error(ArgumentError, /client\.groups\.find\(1\)/) + end + + it 'names the resource the way a client does, for a multi-word one' do + expect { client.ticket_articles.all.find(7) } + .to raise_error(ArgumentError, /client\.ticket_articles\.find\(7\)/) + end + + it 'points at detect for the block form' do + expect { collection.find(1) }.to raise_error(ArgumentError, /detect \{ \.\.\. \}/) + end + + it 'makes no request for the id it refuses' do + expect { collection.find(1) }.to raise_error(ArgumentError) + expect(a_request(:any, /zammad\.test/)).not_to have_been_made + end + + it 'still returns an Enumerator without a block or an argument' do + expect(collection.find).to be_a(Enumerator) + end + end + + # Enumerable#first takes its records off the front of a page this collection + # sized for walking, so `all.first` downloaded a whole page to hand back one + # record. + describe '#first' do + it 'reads a page of one for a single record' do + stub_page(1, [{ id: 1 }], per_page: 1) + + expect(collection.first.id).to eq(1) + end + + it 'is nil when the endpoint has nothing' do + stub_page(1, [], per_page: 1) + + expect(collection.first).to be_nil + end + + it 'sizes the page to the number of records asked for' do + stub_page(1, [{ id: 1 }, { id: 2 }], per_page: 2) + + expect(collection.first(2).map(&:id)).to eq([1, 2]) + end + + it 'walks instead when more records are asked for than the endpoint serves' do + stub_page(1, full_page) + stub_page(2, [{ id: default_per_page + 1 }]) + + expect(collection.first(default_per_page + 1).size).to eq(default_per_page + 1) + end + + # The page size of a collection limited to one says which records it + # holds, so re-sizing it would move them - the same reason batch_size + # cannot be combined with page. + it 'leaves a collection already limited to a page at its own size' do + stub_page(3, [{ id: 5 }, { id: 6 }], per_page: 2) + + expect(collection.page(3, per_page: 2).first.id).to eq(5) + end + + it 'leaves a zero count to Enumerable' do + expect(collection.first(0)).to eq([]) + end + + it 'makes no request for a zero count' do + expect(collection.first(0)).to eq([]) + expect(a_request(:any, /zammad\.test/)).not_to have_been_made + end + + # Sizing the request rather than limiting the collection to one page: + # limited, this came back with whatever the first page held and nothing to + # say the rest were there to be read. + it 'reads on where the endpoint serves a smaller page than it was asked for' do + stub_capped_endpoint(url, total: 5, max: 2) + + expect(collection.first(5).map(&:id)).to eq([1, 2, 3, 4, 5]) + end + + it 'stops as soon as it has what it asked for' do + stub_capped_endpoint(url, total: 500, max: 2) + + expect(collection.first(3).map(&:id)).to eq([1, 2, 3]) + expect(a_request(:get, url).with(query: hash_including('page' => '3'))).not_to have_been_made + end + end + + describe '#inspect' do + it 'describes the collection without fetching it' do + expect(collection.inspect) + .to eq("#") + end + + it 'mentions the page when limited to one' do + expect(collection.page(4).inspect).to include('page=4') + end + end + + # A walk stops on what the endpoint served, and the size it serves is + # learned from the first page rather than taken from `max_per_page`. Where + # the server's cap is lower than the request - a cap the gem's declaration + # has gone stale on - every page is short of what was asked for, and reading + # the requested size would make each one look like the last. + # A search names the ids for a page and then loads the records by id, so an + # id whose record is gone by then leaves the page one short - on any page, + # not only the last. An index page is a single query and has no such gap. + describe 'a search, which can serve a page short before the last one' do + subject(:search) { client.users.search('smith') } + + let(:search_url) { "#{ClientHelper::BASE_URL}api/v1/users/search" } + let(:page_size) { ZammadAPI::ResourceProxy::SEARCH_MAX_PER_PAGE } + + def stub_search_page(page, records) + stub_request(:get, search_url) + .with(query: hash_including('page' => page.to_s)) + .to_return(json_response(records)) + end + + def hits(range) = range.map { { id: it } } + + it 'walks on past a page that came back short' do + stub_search_page(1, hits(1..page_size)) + stub_search_page(2, hits((page_size + 1)...(page_size * 2))) + stub_search_page(3, hits([900, 901])) + stub_search_page(4, []) + + expect(search.map(&:id)).to eq([*1...(page_size * 2), 900, 901]) + end + + it 'walks on past a short first page too' do + stub_search_page(1, hits(1...page_size)) + stub_search_page(2, hits(page_size..(page_size * 2))) + stub_search_page(3, []) + + expect(search.map(&:id)).to eq((1..(page_size * 2)).to_a) + end + + # The bare array is what a Zammad before 6.5.1 answers with, and it says + # nothing about how many hits there are. An empty page is then all there + # is to end on, hits behind it or not: see the next group for an endpoint + # that does say. + it 'ends on the empty page where the endpoint reports no total' do + stub_search_page(1, hits(1..3)) + last = stub_search_page(2, []) + stub_search_page(3, hits([4])) + + expect(search.map(&:id)).to eq([1, 2, 3]) + expect(last).to have_been_requested.once + expect(a_request(:get, search_url).with(query: hash_including('page' => '3'))).not_to have_been_made + end + + it 'still raises PaginationError for a search that ignores the page parameter' do + stub_request(:get, search_url).with(query: hash_including({})).to_return(json_response(hits(1..3))) + + expect { search.to_a }.to raise_error(ZammadAPI::PaginationError, /ignoring the page parameter/) + end + + it 'still reads only the one page a search was limited to' do + stub_search_page(2, hits(1..3)) + + expect(search.page(2).map(&:id)).to eq([1, 2, 3]) + expect(a_request(:get, search_url).with(query: hash_including('page' => '3'))).not_to have_been_made + end + end + + # A page of a search can hold nothing with hits still behind it, for the + # reason it can come back short: every id the search named for it has lost + # its record. It takes one stale hit on the page of one that `first` and + # `empty?` ask for, and a search serves the newest first. A Zammad from 6.5.1 + # on reports the size of the whole result beside the page where it is asked + # to, which is what tells such a page from the end. + describe 'a search that reports its total beside each page' do + subject(:search) { client.users.search('smith') } + + let(:search_url) { "#{ClientHelper::BASE_URL}api/v1/users/search" } + + def stub_counted_page(page, ids, total:) + stub_request(:get, search_url) + .with(query: hash_including('page' => page.to_s)) + .to_return(json_response({ records: ids.map { { id: it } }, total_count: total })) + end + + def walked_ids(per_page:) = search.find_each(batch_size: per_page).map(&:id) + + it 'asks for the total with every page of a walk' do + stub_counted_page(1, [1], total: 2) + stub_counted_page(2, [2], total: 2) + stub_counted_page(3, [], total: 2) + walked_ids(per_page: 1) + + expect(a_request(:get, search_url).with(query: hash_including('with_total_count' => 'true'))).to have_been_made.times(3) + end + + it 'reads the records out of the object the total arrives in' do + stub_counted_page(1, [1, 2, 3], total: 3) + stub_counted_page(2, [], total: 3) + + expect(search.map(&:id)).to eq([1, 2, 3]) + end + + it 'reads on past an empty page the total says has hits behind it' do + stub_counted_page(1, [1], total: 3) + stub_counted_page(2, [], total: 3) + stub_counted_page(3, [3], total: 3) + stub_counted_page(4, [], total: 3) + + expect(walked_ids(per_page: 1)).to eq([1, 3]) + end + + # Two empty pages hold the same nothing, and the guard against a page + # that repeats used to read that as an endpoint ignoring `page`. + it 'reads on past two empty pages in a row' do + stub_counted_page(1, [1], total: 4) + stub_counted_page(2, [], total: 4) + stub_counted_page(3, [], total: 4) + stub_counted_page(4, [4], total: 4) + stub_counted_page(5, [], total: 4) + + expect(walked_ids(per_page: 1)).to eq([1, 4]) + end + + it 'ends on an empty page once the pages read cover the total' do + stub_counted_page(1, [1, 2], total: 4) + last = stub_counted_page(2, [], total: 4) + stub_counted_page(3, [5], total: 4) + + expect(walked_ids(per_page: 2)).to eq([1, 2]) + expect(last).to have_been_requested.once + expect(a_request(:get, search_url).with(query: hash_including('page' => '3'))).not_to have_been_made + end + + # Elasticsearch stops counting at ten thousand hits and reports that as + # the total. A walk ended on the figure would stop there. + it 'does not end on the total while a page still holds records' do + stub_counted_page(1, [1], total: 2) + stub_counted_page(2, [2], total: 2) + stub_counted_page(3, [3], total: 2) + stub_counted_page(4, [], total: 2) + + expect(walked_ids(per_page: 1)).to eq([1, 2, 3]) + end + + it 'makes no more requests than the total has pages' do + (1..5).each { stub_counted_page(it, [], total: 3) } + + expect(walked_ids(per_page: 1)).to eq([]) + expect(a_request(:get, search_url).with(query: hash_including({}))).to have_been_made.times(3) + end + + it 'finds the first live hit behind a stale one' do + stub_counted_page(1, [], total: 3) + stub_counted_page(2, [2], total: 3) + + expect(search.first.id).to eq(2) + end + + it 'is not empty where the first hit is stale and the next is live' do + stub_counted_page(1, [], total: 3) + stub_counted_page(2, [2], total: 3) + + expect(search.empty?).to be(false) + end + + it 'is empty, in one request, where the stale hit was the only one' do + stub_counted_page(1, [], total: 1) + + expect(search.empty?).to be(true) + expect(a_request(:get, search_url).with(query: hash_including({}))).to have_been_made.once + end + + # `first` and `empty?` ask for a page of the size they want, and a search + # is read on past an empty one. Held to that size, the two cost a request + # for every stale hit in a row: five thousand of them for `empty?` on an + # instance whose index has drifted from its database. + describe 'read by first, behind hits that have lost their records' do + # A search over `hits`, of which `stale` have lost their record, served + # the way Zammad serves one: the ids for the page first, and then the + # records that are still there. Answers with every page it was asked + # for, as page and size. + # + # `serves` is a page size the endpoint holds to whatever it is asked + # for, paging by it. `window` is an Elasticsearch result window: a page + # that reaches past it is refused, and Zammad answers that as no hits + # and a total of nought. + def stub_search_over(hits, stale: [], serves: nil, window: nil) + asked = [] + stub_request(:get, search_url).with(query: hash_including({})).to_return do |request| + params = URI.decode_www_form(URI(request.uri).query).to_h + page = Integer(params['page']) + size = Integer(params['per_page']) + asked << [page, size] + next json_response({ records: [], total_count: 0 }) if window && page * size > window + + size = [size, serves].min if serves + json_response({ records: (Array(hits)[(page - 1) * size, size].to_a - Array(stale)).map { { id: it } }, total_count: Array(hits).size }) + end + asked + end + + it 'asks for a larger page after each empty one, starting where the last ended' do + asked = stub_search_over(1..32, stale: 1..32) + + expect(search.empty?).to be(true) + expect(asked).to eq([[1, 1], [2, 1], [2, 2], [2, 4], [2, 8], [2, 16]]) + end + + # A page that reaches past the total is one an index whose result + # window was lowered may refuse. + it 'asks for no page that reaches past the total the search reported' do + asked = stub_search_over(1..20, stale: 1..20) + search.empty? + + expect(asked).to eq([[1, 1], [2, 1], [2, 2], [2, 4], [2, 8], [5, 4]]) + end + + # Hits 257 to 384 were asked for, past the window, which Zammad answers + # as nothing at all, and the read ended there with the live hit unread. + it 'finds a live hit inside a lowered result window behind stale ones' do + stub_search_over(1..300, stale: 1..279, window: 300) + + expect(search.first.id).to eq(280) + end + + # Larger pages served by a smaller size start at other positions than + # the ones asked for, behind hits already read: hit 100 came back twice. + it 'hands back no record twice where the endpoint pages smaller than it is asked' do + stub_search_over(1..1000, stale: (1..1000).to_a - [100, 160], serves: 50) + + expect(search.first(2).map(&:id)).to eq([100, 160]) + end + + it 'reads past five thousand stale hits in tens of requests, not thousands' do + asked = stub_search_over(1..5000, stale: 1..5000) + + expect(search.empty?).to be(true) + expect(asked.size).to eq(34) + end + + it 'never asks for a page larger than the endpoint serves' do + asked = stub_search_over(1..5000, stale: 1..5000) + search.first(3) + + expect(asked.map(&:last).max).to be <= ZammadAPI::ResourceProxy::SEARCH_MAX_PER_PAGE + end + + it 'covers every hit once, however the pages were sized' do + asked = stub_search_over(1..5000, stale: 1..5000) + search.first(7) + + covered = asked.flat_map { |page, size| Array.new(size) { ((page - 1) * size) + it + 1 } } + expect(covered.first(5000)).to eq((1..5000).to_a) + end + + it 'finds the first live hit behind a run of stale ones' do + stub_search_over(1..300, stale: 1..137) + + expect(search.first.id).to eq(138) + end + + # Whatever is stale, the answer is the live hits in the order they are + # served: none passed over where a page changed size, none handed over + # twice. + [ + { stale: [], wanted: 3 }, + { stale: [1], wanted: 3 }, + { stale: [2, 3, 4, 5, 6, 7], wanted: 3 }, + { stale: (1..40).to_a - [17], wanted: 2 }, + { stale: (2..90).to_a, wanted: 5 }, + { stale: (1..300).step(2), wanted: 9 }, + { stale: (4..250).to_a, wanted: 4 } + ].each do |example| + it "reads the first #{example[:wanted]} live hits in order with #{example[:stale].to_a.size} of 300 stale" do + stub_search_over(1..300, stale: example[:stale]) + + expect(search.first(example[:wanted]).map(&:id)).to eq(((1..300).to_a - example[:stale].to_a).first(example[:wanted])) + end + end + + it 'still costs one request where the first hit is live' do + asked = stub_search_over(1..300) + search.first + + expect(asked).to eq([[1, 1]]) + end + + # A batch size is the caller saying how many records a batch may hold. + it 'does not widen a batch size the caller chose' do + asked = stub_search_over(1..100, stale: 1..100) + search.in_batches(of: 10) { nil } + + expect(asked.map(&:last).uniq).to eq([10]) + end + end + + it 'still raises PaginationError for a search that repeats a page of records' do + stub_request(:get, search_url).with(query: hash_including({})).to_return(json_response({ records: [{ id: 1 }], total_count: 9 })) + + expect { search.to_a }.to raise_error(ZammadAPI::PaginationError, /ignoring the page parameter/) + end + + it 'ends on the empty page where the total is not a count' do + stub_counted_page(1, [1], total: 'lots') + stub_counted_page(2, [], total: -4) + stub_counted_page(3, [3], total: 'lots') + + expect(walked_ids(per_page: 1)).to eq([1]) + end + + it 'raises ParseError for an object that is not a page of records' do + stub_request(:get, search_url).with(query: hash_including({})).to_return(json_response({ total_count: 3 })) + + expect { search.to_a }.to raise_error(ZammadAPI::ParseError, /expected a JSON array, got Hash/) + end + + # The walk reads the id of every record on a page, so a null that got + # past the shape check died there as NoMethodError rather than as the + # ParseError a response of the wrong shape is. + it 'raises ParseError for a null among the records' do + stub_request(:get, search_url).with(query: hash_including({})).to_return(json_response({ records: [nil, { id: 2 }], total_count: 2 })) + + expect { search.to_a }.to raise_error(ZammadAPI::ParseError, /an array holding NilClass/) + end + + # One page is one request whatever it holds, so there is no walk for a + # total to end, and the request is the one it always was. + it 'does not ask a search limited to one page for the total' do + stub_request(:get, search_url).with(query: hash_including({})).to_return(json_response([{ id: 1 }])) + search.page(2).to_a + + expect(a_request(:get, search_url).with(query: { 'expand' => 'true', 'query' => 'smith', 'page' => '2', 'per_page' => '200' })).to have_been_made.once + end + + # model_index_render drops the parameter with every other it does not + # know, so asking would be noise on every request of every walk. + it 'does not ask an index for the total' do + index_url = "#{ClientHelper::BASE_URL}api/v1/users" + stub_request(:get, index_url).with(query: hash_including({})).to_return(json_response([])) + client.users.all.to_a + + expect(a_request(:get, index_url).with(query: { 'expand' => 'true', 'page' => '1', 'per_page' => '1000' })).to have_been_made.once + end + end + + describe 'an endpoint that pages smaller than it was asked for' do + it 'is walked to the end rather than truncated at the first short page' do + stub_capped_endpoint(url, total: 5, max: 2) + + expect(collection.map(&:id)).to eq([1, 2, 3, 4, 5]) + end + end +end diff --git a/spec/unit/zammad_api/config_spec.rb b/spec/unit/zammad_api/config_spec.rb new file mode 100644 index 0000000..a45f743 --- /dev/null +++ b/spec/unit/zammad_api/config_spec.rb @@ -0,0 +1,683 @@ +# frozen_string_literal: true + +require 'pp' + +RSpec.describe ZammadAPI::Config do + def build(url: 'https://zammad.example.com', http_token: 'token', **overrides) + described_class.new(url: url, http_token: http_token, **overrides) + end + + describe 'url handling' do + it 'appends a trailing slash so sub-path installations keep working' do + expect(build(url: 'https://example.com/zammad').url).to eq('https://example.com/zammad/') + end + + it 'leaves an existing trailing slash alone' do + expect(build(url: 'https://example.com/').url).to eq('https://example.com/') + end + + it 'rejects a missing url' do + expect { build(url: nil) } + .to raise_error(ZammadAPI::ConfigurationError, 'missing url in config') + end + + it 'rejects an empty url' do + expect { build(url: '') } + .to raise_error(ZammadAPI::ConfigurationError, 'missing url in config') + end + + it 'rejects a non-http scheme' do + expect { build(url: 'ftp://example.com') } + .to raise_error(ZammadAPI::ConfigurationError, 'config url needs to start with http:// or https://') + end + + # Appended blindly, the slash landed behind the query string and every + # request was resolved against a base ending in `?tenant=acme/`. + it 'puts the trailing slash on the path, not behind a query string' do + expect(build(url: 'https://example.com/zammad?tenant=acme').url) + .to eq('https://example.com/zammad/?tenant=acme') + end + + it 'puts the trailing slash on the path, not behind a fragment' do + expect(build(url: 'https://example.com/zammad#top').url) + .to eq('https://example.com/zammad/#top') + end + + # Accepted, this failed deep inside the adapter on the first request + # instead of here. + it 'rejects a scheme with no host after it' do + expect { build(url: 'https://') } + .to raise_error(ZammadAPI::ConfigurationError, 'config url needs a host after the scheme, got "https://"') + end + + # URI(...) is what a caller reaches for, and it prints as the URL, so it + # reached String#end_with? and died there as a NoMethodError - past the + # ConfigurationError the constructor is documented to raise. + it 'rejects a url that is not a string' do + expect { build(url: URI('https://example.com/')) } + .to raise_error(ZammadAPI::ConfigurationError, 'config url needs to be a string, got URI::HTTPS') + end + end + + describe 'credentials' do + it 'accepts an access token' do + expect(build(http_token: 'token').authentication_scheme).to eq(:http_token) + end + + it 'accepts an OAuth2 token' do + expect(build(http_token: nil, oauth2_token: 'token').authentication_scheme).to eq(:oauth2_token) + end + + it 'accepts user and password' do + expect(build(http_token: nil, user: 'u', password: 'p').authentication_scheme).to eq(:basic) + end + + # Several used to be accepted together, and the first in a fixed order + # was sent without a word about the others - which is what let an override + # leave the credential it was meant to replace in charge. + context 'with more than one way to authenticate' do + it 'refuses a token beside a user and password' do + expect { build(http_token: 'token', user: 'u', password: 'p') } + .to raise_error(ZammadAPI::ConfigurationError, /config names more than one way to authenticate \(http_token, user and password\)/) + end + + it 'refuses two kinds of token' do + expect { build(http_token: 'token', oauth2_token: 'other') } + .to raise_error(ZammadAPI::ConfigurationError, /more than one way to authenticate \(http_token, oauth2_token\)/) + end + + it 'refuses all three, naming each' do + expect { build(http_token: 'token', oauth2_token: 'other', user: 'u', password: 'p') } + .to raise_error(ZammadAPI::ConfigurationError, /\(http_token, oauth2_token, user and password\)/) + end + + it 'says what to pass instead' do + expect { build(http_token: 'token', oauth2_token: 'other') } + .to raise_error(ZammadAPI::ConfigurationError, /Pass http_token:, or oauth2_token:, or user: and password:, and leave the others out/) + end + + # Half a scheme is still a second one being named. + it 'refuses a token beside a user that has no password' do + expect { build(http_token: 'token', user: 'u') } + .to raise_error(ZammadAPI::ConfigurationError, /more than one way to authenticate/) + end + + it 'keeps the credentials out of the message' do + expect { build(http_token: 'tok-s3cret', user: 'u', password: 'pw-s3cret') } + .to raise_error(ZammadAPI::ConfigurationError) { |error| expect(error.message).not_to include('s3cret') } + end + + it 'does not count a blank credential as one' do + expect(build(http_token: 'token', oauth2_token: '', user: nil, password: '').authentication_scheme).to eq(:http_token) + end + end + + it 'rejects a missing user' do + expect { build(http_token: nil, password: 'p') } + .to raise_error(ZammadAPI::ConfigurationError, 'missing user in config') + end + + it 'rejects a missing password' do + expect { build(http_token: nil, user: 'u') } + .to raise_error(ZammadAPI::ConfigurationError, 'missing password in config') + end + + it 'treats blank credentials as absent' do + expect { build(http_token: '', oauth2_token: '', user: '', password: '') } + .to raise_error(ZammadAPI::ConfigurationError, 'missing user in config') + end + end + + describe 'defaults' do + it 'sets a request timeout' do + expect(build.timeout).to eq(described_class::DEFAULT_TIMEOUT) + end + + it 'sets a connection timeout' do + expect(build.open_timeout).to eq(described_class::DEFAULT_OPEN_TIMEOUT) + end + + it 'retries transient failures' do + expect(build.retries).to eq(described_class::DEFAULT_RETRIES) + end + + it 'identifies itself with the gem version' do + expect(build.user_agent).to eq("zammad_api-ruby/#{ZammadAPI::VERSION}") + end + + it 'verifies TLS certificates' do + expect(build.ssl_verify).to be(true) + end + + it 'discards log output when no logger is supplied' do + expect(build.logger).to be_a(Logger) + end + + it 'leaves the Faraday adapter to Faraday' do + expect(build.adapter).to be_nil + end + + it 'installs no extra middleware' do + expect(build.middleware).to be_nil + end + end + + describe 'the user agent' do + # Handed to Faraday as a nil header, Faraday filled in its own, so the gem + # stopped identifying itself in the instance log an operator greps to find + # its requests - on every request, with nothing said about it. + it 'falls back to the default when it is nil' do + expect(build(user_agent: nil).user_agent).to eq("zammad_api-ruby/#{ZammadAPI::VERSION}") + end + + it 'falls back to the default when it is empty' do + expect(build(user_agent: '').user_agent).to eq("zammad_api-ruby/#{ZammadAPI::VERSION}") + end + + it 'rejects one that is not a string' do + expect { build(user_agent: 42) } + .to raise_error(ZammadAPI::ConfigurationError, 'config user_agent needs to be a string') + end + end + + # Each is sent as a header. Net::HTTP refused a line break inside one at + # the first request, with an ArgumentError that quoted the value. + describe 'a line break in an option sent as a header' do + { + http_token: { http_token: "secret-abc\nsecret-def" }, + oauth2_token: { http_token: nil, oauth2_token: "secret-abc\r\nsecret-def" }, + user_agent: { user_agent: "my-app\nsecret-def" } + }.each do |name, options| + it "refuses one inside #{name}, without quoting it" do + expect { build(**options) }.to raise_error(ZammadAPI::ConfigurationError) { |error| + expect(error.message).to start_with("config #{name} holds a line break, which a header cannot carry") + expect(error.message).not_to include('secret-def') + } + end + end + + # Net::HTTP strips it, so a token read from a file with its newline on + # worked, and still does. + it 'takes a token that only ends in one' do + expect(build(http_token: "secret\n").http_token).to eq("secret\n") + end + + it 'does not check a password, which basic authentication encodes' do + expect(build(http_token: nil, user: 'agent', password: "pass\nword").password).to eq("pass\nword") + end + end + + describe 'the Faraday seam' do + it 'symbolizes an adapter given as a string' do + expect(build(adapter: 'test').adapter).to eq(:test) + end + + it 'keeps an adapter given as a symbol' do + expect(build(adapter: :test).adapter).to eq(:test) + end + + it 'keeps the middleware callable' do + hook = ->(builder) { builder } + expect(build(middleware: hook).middleware).to be(hook) + end + + it 'rejects middleware that cannot be called' do + expect { build(middleware: 'not callable') } + .to raise_error(ZammadAPI::ConfigurationError, 'config middleware needs to respond to call') + end + + it 'accepts any callable, not only a proc' do + callable = Class.new { def call(builder) = builder }.new + expect(build(middleware: callable).middleware).to be(callable) + end + end + + describe 'the logger' do + it 'keeps the logger it is given' do + logger = Logger.new(IO::NULL) + expect(build(logger: logger).logger).to be(logger) + end + + it 'accepts anything that logs at debug, not only a Logger' do + logger = Class.new { def debug(...) = nil }.new + expect(build(logger: logger).logger).to be(logger) + end + + # 1.x took `logger: true` as "log to $stderr". + it 'rejects a boolean, as 1.x accepted' do + expect { build(logger: true) } + .to raise_error(ZammadAPI::ConfigurationError, 'config logger needs to respond to debug') + end + end + + describe 'numeric validation' do + # Complex is a Numeric and answers neither `positive?` nor `>`, so this + # left a NoMethodError where every other rejected option raises the error + # building a client is documented to need. + it 'rejects a Numeric that cannot be compared, as a configuration error' do + expect { build(timeout: Complex(1, 2)) } + .to raise_error(ZammadAPI::ConfigurationError, 'config timeout needs to be a positive number') + end + + it 'rejects a zero timeout' do + expect { build(timeout: 0) } + .to raise_error(ZammadAPI::ConfigurationError, 'config timeout needs to be a positive number') + end + + it 'rejects a negative open_timeout' do + expect { build(open_timeout: -1) } + .to raise_error(ZammadAPI::ConfigurationError, 'config open_timeout needs to be a positive number') + end + + it 'rejects a non-numeric timeout' do + expect { build(timeout: 'soon') } + .to raise_error(ZammadAPI::ConfigurationError, 'config timeout needs to be a positive number') + end + + it 'rejects negative retries' do + expect { build(retries: -1) } + .to raise_error(ZammadAPI::ConfigurationError, 'config retries needs to be a non-negative integer') + end + + it 'allows disabling retries' do + expect(build(retries: 0).retries).to eq(0) + end + end + + describe '#inspect' do + subject(:rendered) { build(http_token: nil, user: 'u', password: 'pw-s3cret').inspect } + + it 'redacts the password' do + expect(rendered).not_to include('pw-s3cret') + end + + it 'redacts the access token' do + expect(build(http_token: 'tok-s3cret').inspect).not_to include('tok-s3cret') + end + + it 'redacts the OAuth2 token' do + expect(build(http_token: nil, oauth2_token: 'oauth-s3cret').inspect).not_to include('oauth-s3cret') + end + + it 'marks redacted values' do + expect(rendered).to include('password=[REDACTED]') + end + + it 'keeps non-sensitive values readable' do + expect(rendered).to include('url="https://zammad.example.com/"') + end + + it 'does not dump the logger internals' do + expect(rendered).to include('logger=#') + end + + it 'does not dump the middleware internals' do + expect(build(middleware: ->(builder) { builder }).inspect).to include('middleware=#') + end + + it 'still shows that no middleware is configured' do + expect(rendered).to include('middleware=nil') + end + + it 'is used for to_s as well' do + config = build(http_token: nil, user: 'u', password: 'hunter2') + expect(config.to_s).to eq(config.inspect) + end + + context 'with an authenticated proxy' do + subject(:rendered) { build(proxy: 'http://puser:pproxy-s3cret@proxy.test:8080').inspect } + + it 'redacts the proxy credentials' do + expect(rendered).not_to include('pproxy-s3cret') + end + + it 'keeps the proxy host visible' do + expect(rendered).to include('proxy.test:8080') + end + + it 'marks the redacted userinfo' do + expect(rendered).to include('proxy="http://[REDACTED]@proxy.test:8080"') + end + end + + it 'redacts a proxy password carrying an unencoded @' do + rendered = build(proxy: 'http://puser:pa@ss-s3cret@proxy.test:8080').inspect + + expect(rendered).to include('proxy="http://[REDACTED]@proxy.test:8080"') + expect(rendered).not_to include('ss-s3cret') + end + + # A password is not obliged to be URL-safe, and each of these ends the + # authority early as far as the syntax goes: `user:p` is all that is left + # of it, with no @ in it, so a search bounded by the authority found no + # credential to blank and printed the password. + { + 'a #' => 'http://puser:pa#ss-s3cret@proxy.test:8080', + 'a /' => 'http://puser:pa/ss-s3cret@proxy.test:8080', + 'a ?' => 'http://puser:pa?ss-s3cret@proxy.test:8080' + }.each do |character, proxy| + it "redacts a proxy password carrying #{character}" do + rendered = build(proxy: proxy).inspect + + expect(rendered).to include('proxy="http://[REDACTED]@proxy.test:8080"') + expect(rendered).not_to match(/pa.ss|s3cret/) + end + end + + it 'redacts such a password on a proxy configured without a scheme' do + rendered = build(proxy: 'puser:pa#ss-s3cret@proxy.test:8080').inspect + + expect(rendered).to include('proxy="[REDACTED]@proxy.test:8080"') + expect(rendered).not_to include('s3cret') + end + + it 'leaves a proxy without credentials alone' do + expect(build(proxy: 'http://proxy.test:8080').inspect).to include('proxy="http://proxy.test:8080"') + end + + # The shape an http_proxy style setting is copied out of. Anchored on a + # `://` lookbehind, the redaction never fired and the password went into + # every log line and exception report this class promises to be safe in. + it 'redacts the credentials of a proxy configured without a scheme' do + rendered = build(proxy: 'puser:pproxy-s3cret@proxy.test:8080').inspect + + expect(rendered).to include('proxy="[REDACTED]@proxy.test:8080"') + expect(rendered).not_to include('pproxy-s3cret') + end + + it 'leaves a scheme-less proxy without credentials alone' do + expect(build(proxy: 'proxy.test:8080').inspect).to include('proxy="proxy.test:8080"') + end + + it 'leaves a url without credentials alone' do + expect(build(url: 'https://zammad.example.com/').inspect).to include('url="https://zammad.example.com/"') + end + end + + # pp has a printer of its own for a Data object, which renders the members + # without going through #inspect - and pp is what IRB and the Rails console + # print a value with. + describe 'pretty printing' do + it 'redacts the password' do + expect(build(http_token: nil, user: 'u', password: 'pw-s3cret').pretty_inspect).not_to include('pw-s3cret') + end + + it 'redacts the access token' do + expect(build(http_token: 'tok-s3cret').pretty_inspect).not_to include('tok-s3cret') + end + + it 'redacts the OAuth2 token' do + expect(build(http_token: nil, oauth2_token: 'oauth-s3cret').pretty_inspect).not_to include('oauth-s3cret') + end + + it 'redacts the proxy credentials' do + expect(build(proxy: 'http://puser:pproxy-s3cret@proxy.test:8080').pretty_inspect).not_to include('pproxy-s3cret') + end + + it 'prints what inspect prints' do + config = build(http_token: nil, user: 'u', password: 'hunter2') + expect(config.pretty_inspect).to eq("#{config.inspect}\n") + end + + it 'stays redacted nested inside another structure' do + expect({ config: build(http_token: 'tok-s3cret') }.pretty_inspect).not_to include('tok-s3cret') + end + end + + # Faraday turns the userinfo of a URL into a Basic Authorization header, and + # its authorization middleware leaves a header that is already set alone - + # so the credentials in the URL were sent in place of the configured ones. + describe 'credentials in the instance url' do + it 'refuses them' do + expect { build(url: 'https://admin:url-s3cret@zammad.example.com/') } + .to raise_error(ZammadAPI::ConfigurationError, /config url carries credentials of its own/) + end + + it 'says where they belong instead' do + expect { build(url: 'https://admin:url-s3cret@zammad.example.com/') } + .to raise_error(ZammadAPI::ConfigurationError, /pass user: and password:/) + end + + it 'keeps the password out of the message' do + expect { build(url: 'https://admin:url-s3cret@zammad.example.com/') } + .to raise_error(ZammadAPI::ConfigurationError) { |error| expect(error.message).not_to include('url-s3cret') } + end + + it 'still names the instance in the message' do + expect { build(url: 'https://admin:url-s3cret@zammad.example.com/') } + .to raise_error(ZammadAPI::ConfigurationError, %r{https://\[REDACTED\]@zammad\.example\.com/}) + end + + it 'refuses them beside basic authentication too, where they would win just the same' do + expect { build(url: 'https://old:creds@zammad.example.com/', http_token: nil, user: 'u', password: 'p') } + .to raise_error(ZammadAPI::ConfigurationError, /config url carries credentials of its own/) + end + + it 'refuses a user name without a password' do + expect { build(url: 'https://admin@zammad.example.com/') } + .to raise_error(ZammadAPI::ConfigurationError, /config url carries credentials of its own/) + end + + it 'accepts a url whose path merely contains an @' do + expect(build(url: 'https://zammad.example.com/tenant@acme/').url).to eq('https://zammad.example.com/tenant@acme/') + end + end + + describe '#redacted' do + it 'blanks inline credentials' do + expect(build.redacted('https://admin:s3cret@zammad.example.com/')) + .to eq('https://[REDACTED]@zammad.example.com/') + end + + # Anchoring on the first @ left the tail of the password in the rendered + # URL, which is interpolated into every ConnectionError message. + it 'blanks a password carrying an unencoded @' do + expect(build.redacted('https://admin:pa@ss-s3cret@zammad.example.com/')) + .to eq('https://[REDACTED]@zammad.example.com/') + end + + # The same three characters, in the instance url. URI cannot read these, + # so they are not refused the way a readable url with credentials is, and + # stay printable until the connection rejects them. + it 'blanks a password carrying a #, which ends the authority early' do + expect(build.redacted('https://admin:pa#ss-s3cret@zammad.example.com/')) + .to eq('https://[REDACTED]@zammad.example.com/') + end + + it 'blanks a password carrying a /' do + expect(build.redacted('https://admin:pa/ss-s3cret@zammad.example.com/')) + .to eq('https://[REDACTED]@zammad.example.com/') + end + + it 'blanks a password carrying a ?' do + expect(build.redacted('https://admin:pa?ss-s3cret@zammad.example.com/')) + .to eq('https://[REDACTED]@zammad.example.com/') + end + + it 'blanks a password carrying both an @ and a /' do + expect(build.redacted('https://admin:pa@ss/w0rd@zammad.example.com/')) + .to eq('https://[REDACTED]@zammad.example.com/') + end + + it 'leaves a host and port alone' do + expect(build.redacted('https://zammad.example.com:8443/helpdesk/')).to eq('https://zammad.example.com:8443/helpdesk/') + end + + it 'leaves an IPv6 host alone' do + expect(build.redacted('http://[::1]:3128')).to eq('http://[::1]:3128') + end + + # A colon cannot tell a port from a password, and `user:8443/s3cret@host` + # is a password with a slash in it just as much as it is a port and a + # path. Blanking too much shows a wrong host; blanking too little shows a + # password. + it 'blanks rather than guesses where a colon could be either a port or a password' do + expect(build.redacted('https://zammad.example.com:8443/tenant@acme/')).to eq('https://[REDACTED]@acme/') + end + end + + describe '#redacted_url' do + it 'blanks a password the url is too malformed to be refused for' do + expect(build(url: 'https://admin:pa#ss-s3cret@zammad.example.com/').redacted_url) + .to eq('https://[REDACTED]@zammad.example.com/') + end + + it 'leaves an @ in the path alone' do + expect(build(url: 'https://zammad.example.com/tenant@acme/').redacted_url) + .to eq('https://zammad.example.com/tenant@acme/') + end + + # Bounded only by the path, the match crossed into the query string and + # rendered a host that does not exist - into every ConnectionError message. + it 'leaves an @ in a query string alone' do + expect(build(url: 'https://zammad.example.com?tenant=a@acme').redacted_url) + .to eq('https://zammad.example.com/?tenant=a@acme') + end + + it 'leaves an @ in a fragment alone' do + expect(build(url: 'https://zammad.example.com#a@b').redacted_url) + .to eq('https://zammad.example.com/#a@b') + end + + it 'leaves a url without credentials alone' do + expect(build(url: 'https://zammad.example.com/').redacted_url).to eq('https://zammad.example.com/') + end + end + + describe '#with' do + it 'changes an option' do + expect(build.with(timeout: 5).timeout).to eq(5) + end + + it 'keeps the rest' do + expect(build(proxy: 'http://proxy.test:8080').with(timeout: 5).proxy).to eq('http://proxy.test:8080') + end + + it 're-validates' do + expect { build.with(retries: -1) }.to raise_error(ZammadAPI::ConfigurationError, /non-negative integer/) + end + + it 'replaces the authentication scheme rather than adding a second one' do + derived = build.with(user: 'u', password: 'p') + expect(derived.to_h.slice(:http_token, :user, :password)).to eq({ http_token: nil, user: 'u', password: 'p' }) + end + + it 'does not read an explicit nil as naming a scheme' do + expect(build.with(oauth2_token: nil).authentication_scheme).to eq(:http_token) + end + + # The refusal of two schemes is what makes this necessary: merged beside + # the token, the new credential would no longer be ignored but refused. + it 'can switch to any scheme from any other without naming two at once' do + switched = build.with(oauth2_token: 'o').with(user: 'u', password: 'p').with(http_token: 't') + expect(switched.to_h.slice(:http_token, :oauth2_token, :user, :password)) + .to eq({ http_token: 't', oauth2_token: nil, user: nil, password: nil }) + end + + it 'still refuses two schemes named in one call' do + expect { build.with(oauth2_token: 'o', user: 'u', password: 'p') } + .to raise_error(ZammadAPI::ConfigurationError, /more than one way to authenticate/) + end + end + + describe '.merge_options' do + it 'lays the overrides over the options' do + expect(described_class.merge_options({ url: 'a', timeout: 1 }, { timeout: 2 })).to eq({ url: 'a', timeout: 2 }) + end + + it 'drops the credentials an override replaces' do + expect(described_class.merge_options({ http_token: 't' }, { oauth2_token: 'o' })).to eq({ oauth2_token: 'o' }) + end + + it 'keeps the other half of a scheme the override names' do + expect(described_class.merge_options({ user: 'u', password: 'old' }, { password: 'new' })) + .to eq({ user: 'u', password: 'new' }) + end + + it 'leaves the credentials alone when the overrides name none' do + expect(described_class.merge_options({ http_token: 't' }, { timeout: 2 })).to eq({ http_token: 't', timeout: 2 }) + end + end + + describe 'immutability of string members' do + it 'freezes the url' do + expect(build.url).to be_frozen + end + + it 'does not share the url with the caller' do + supplied = +'https://zammad.example.com/' + config = described_class.new(url: supplied, http_token: 'tok') + supplied << 'mutated' + expect(config.url).to eq('https://zammad.example.com/') + end + + it 'freezes the credentials' do + config = build(user: 'u', password: +'pw', http_token: nil) + expect(config.password).to be_frozen + end + + it 'freezes the proxy' do + expect(build(proxy: +'http://proxy.test:8080').proxy).to be_frozen + end + + it 'freezes the user agent' do + expect(build(user_agent: +'custom/1.0').user_agent).to be_frozen + end + end + + it 'is immutable' do + expect(build).to be_frozen + end + + # Every other option is checked up front; these three were not, so a bad + # value escaped the ConfigurationError that building a client is documented + # to need - two as a bare NoMethodError, one by silently staying on. + describe 'option validation' do + it 'rejects a proxy that is not a string' do + expect { build(proxy: URI('http://user:secret@proxy:3128')) } + .to raise_error(ZammadAPI::ConfigurationError, 'config proxy needs to be a string, got URI::HTTP') + end + + # The whole point of refusing it: a URI reached String#sub inside #inspect + # and died there, so the object this class documents as safe to log raised + # at the moment something logged it. + it 'keeps a proxy-bearing config renderable' do + expect { build(proxy: 'http://user:secret@proxy:3128').inspect }.not_to raise_error + end + + it 'redacts the credentials in a proxy it renders' do + rendered = build(proxy: 'http://user:secret@proxy:3128').inspect + + expect(rendered).to include('proxy="http://[REDACTED]@proxy:3128"') + expect(rendered).not_to include('secret') + end + + it 'rejects an adapter that cannot be a symbol' do + expect { build(adapter: 1) } + .to raise_error(ZammadAPI::ConfigurationError, 'config adapter needs to be a symbol or a string, got Integer') + end + + # `adapter: true` is the 1.x-flavoured mistake: it answered to_sym on + # nothing and raised NoMethodError from inside the constructor. + it 'rejects a boolean adapter' do + expect { build(adapter: true) } + .to raise_error(ZammadAPI::ConfigurationError, /config adapter needs to be a symbol or a string/) + end + + it 'accepts an adapter named as a string' do + expect(build(adapter: 'net_http').adapter).to eq(:net_http) + end + + # Read from an environment variable this is the string "false", which is + # truthy, so verification stayed on while the caller believed they had + # turned it off. + it 'rejects an ssl_verify that is not a boolean' do + expect { build(ssl_verify: 'false') } + .to raise_error(ZammadAPI::ConfigurationError, 'config ssl_verify needs to be true or false, got "false"') + end + + it 'accepts ssl_verify: false' do + expect(build(ssl_verify: false).ssl_verify).to be(false) + end + end +end diff --git a/spec/unit/zammad_api/query_encoder_spec.rb b/spec/unit/zammad_api/query_encoder_spec.rb new file mode 100644 index 0000000..05e6369 --- /dev/null +++ b/spec/unit/zammad_api/query_encoder_spec.rb @@ -0,0 +1,180 @@ +# frozen_string_literal: true + +# What is asserted here is the order the pairs of a query are written in, +# because that order is all a query string has to say where one element of a +# list ends. Rack, and the parser Rails 8.1 has of its own, fill the element +# they are on until a pair names a place in it that is already taken, and +# begin a new one there. The orders below were read back with both, from the +# Zammad this gem is developed against, and came out as written. +RSpec.describe ZammadAPI::QueryEncoder do + def written(query) = URI.decode_www_form(described_class.encode(ZammadAPI::Transport.stringify_query(query))) + + def faraday(query) = Faraday::NestedParamsEncoder.encode(ZammadAPI::Transport.stringify_query(query)) + + let(:by_group) { { name: 'ticket.group_id', operator: 'is', value: [1] } } + let(:by_title) { { name: 'ticket.title', operator: 'contains', value: 'x' } } + + describe '.encode' do + # Everything but a list of Hashes that differ is written as it was. + { + 'plain values' => { query: 'smith', page: 2, expand: true }, + 'a list of plain values' => { ids: [3, 1, 2] }, + 'a Hash of lists' => { group_ids: { 3 => %w[read change], 4 => 'full' } }, + 'a condition keyed by name' => { condition: { 'ticket.state_id' => { operator: 'is', value: [1, 2] } } }, + 'a list of Hashes alike' => { condition: { operator: 'AND', conditions: [{ name: 'a', operator: 'is', value: [1] }, { name: 'b', operator: 'is', value: [2] }] } }, + 'a list with nothing in it' => { ids: [] }, + 'a value that needs escaping' => { query: 'a b&c=d[e]' }, + 'a list of Hashes of Hashes' => { list: [{ a: { x: 1 } }, { a: { x: 2 } }] }, + 'plain values among the Hashes' => { list: [1, { a: 1 }, 2, { b: 3 }] } + }.each do |name, query| + it "writes #{name} as Faraday does" do + expect(described_class.encode(ZammadAPI::Transport.stringify_query(query))).to eq(faraday(query)) + end + end + + # A condition and a group of conditions share `operator` and nothing + # else. Written `conditions` first, the group was read into the condition + # before it, and what was left of it began an element holding nothing but + # its operator. + it 'begins a group of conditions with the key it shares with the condition before it' do + condition = { operator: 'OR', conditions: [{ name: 'ticket.state_id', operator: 'is', value: [2] }, { operator: 'AND', conditions: [by_group, by_title] }] } + + expect(written(condition: condition)).to eq( + [ + ['condition[conditions][][name]', 'ticket.state_id'], + ['condition[conditions][][operator]', 'is'], + ['condition[conditions][][value][]', '2'], + ['condition[conditions][][operator]', 'AND'], + ['condition[conditions][][conditions][][name]', 'ticket.group_id'], + ['condition[conditions][][conditions][][operator]', 'is'], + ['condition[conditions][][conditions][][value][]', '1'], + ['condition[conditions][][conditions][][name]', 'ticket.title'], + ['condition[conditions][][conditions][][operator]', 'contains'], + ['condition[conditions][][conditions][][value]', 'x'], + ['condition[operator]', 'OR'] + ] + ) + end + + # The other way round: `name` sorts first, and the group before has none. + it 'begins a condition with the key it shares with the group before it' do + condition = { operator: 'OR', conditions: [{ operator: 'AND', conditions: [by_group] }, { name: 'ticket.state_id', operator: 'is', value: [2] }] } + + expect(written(condition: condition).last(4)).to eq( + [ + ['condition[conditions][][operator]', 'is'], + ['condition[conditions][][name]', 'ticket.state_id'], + ['condition[conditions][][value][]', '2'], + ['condition[operator]', 'OR'] + ] + ) + end + + it 'begins every group in a row of them with its operator' do + condition = { conditions: [{ operator: 'OR', conditions: [by_group] }, { operator: 'NOT', conditions: [by_title] }, { operator: 'AND', conditions: [by_group] }] } + + expect(written(condition: condition).map(&:first).each_cons(2).count { |before, pair| pair == 'condition[conditions][][operator]' && before != pair }) + .to eq(2) + end + + # The shared place may be further down, and every key on the way to it + # goes first. + it 'begins an element with a value it shares further down' do + list = [{ a: { x: 1, y: { z: 1 } }, b: [1] }, { a: { w: [2], y: { q: 3, z: 2 } }, c: 4 }] + + expect(written(list: list).drop(3)).to eq([['list[][a][y][z]', '2'], ['list[][a][y][q]', '3'], ['list[][a][w][]', '2'], ['list[][c]', '4']]) + end + + it 'writes nothing for no query' do + expect(described_class.encode(nil)).to be_nil + end + + it 'writes an empty string for a query with nothing in it' do + expect(described_class.encode({})).to eq('') + end + end + + describe '.decode' do + it 'reads a query string the way Faraday does' do + expect(described_class.decode('a[]=1&a[]=2&b[c]=3')).to eq('a' => %w[1 2], 'b' => { 'c' => '3' }) + end + end + + describe '.lead_path' do + it 'is the first key both have that holds a plain value' do + expect(described_class.lead_path({ 'conditions' => [], 'operator' => 'AND' }, { 'name' => 'a', 'operator' => 'is' })).to eq(['operator']) + end + + it 'is not needed after something that is not a Hash' do + expect(described_class.lead_path({ 'a' => '1' }, 'x')).to be_nil + end + + it 'does not go through a list' do + expect(described_class.lead_path({ 'a' => ['1'] }, { 'a' => ['2'] })).to be_nil + end + + it 'goes through a Hash to a place the element before has too' do + expect(described_class.lead_path({ 'a' => { 'x' => '1' } }, { 'a' => { 'x' => '2' } })).to eq(%w[a x]) + end + + it 'does not go through a Hash where the element before holds a plain value' do + expect(described_class.lead_path({ 'a' => { 'x' => '1' } }, { 'a' => '2' })).to be_nil + end + + it 'is nil where the two share no key' do + expect(described_class.lead_path({ 'a' => '1' }, { 'b' => '2' })).to be_nil + end + + # Nothing is written for an empty Hash, so Rails never saw the key in the + # element before, and a pair naming it is read into that element. + it 'does not take a key the element before holds an empty Hash under' do + expect(described_class.lead_path({ 'a' => '2', 'c' => '3' }, { 'a' => {}, 'b' => '1' })).to be_nil + end + + it 'does not take one further down either' do + expect(described_class.lead_path({ 'a' => { 'x' => '2' } }, { 'a' => { 'x' => {} } })).to be_nil + end + + it 'takes another key the two share instead' do + expect(described_class.lead_path({ 'a' => '2', 'b' => '3' }, { 'a' => {}, 'b' => '1' })).to eq(['b']) + end + end + + describe '.misread' do + it 'is nil for a plain value' do + expect(described_class.misread('x', { 'a' => '1' })).to be_nil + end + + it 'is nil for the first Hash of a list' do + expect(described_class.misread({ 'a' => ['1'] }, nil)).to be_nil + end + + it 'is nil for a Hash after a plain value' do + expect(described_class.misread({ 'a' => '1' }, 'x')).to be_nil + end + + it 'is nil for a Hash that shares a plain value with the one before' do + expect(described_class.misread({ 'operator' => 'AND', 'conditions' => [] }, { 'operator' => 'is', 'name' => 'a' })).to be_nil + end + + it 'names a Hash that would be read into the one before' do + expect(described_class.misread({ 'b' => '2' }, { 'a' => '1' })).to eq(:merged) + end + + it 'names a Hash nothing is written for' do + expect(described_class.misread({}, nil)).to eq(:empty) + end + + it 'names a Hash holding nothing but such Hashes' do + expect(described_class.misread({ 'a' => { 'b' => {} } }, nil)).to eq(:empty) + end + + it 'names a Hash whose only shared key holds an empty Hash in the element before' do + expect(described_class.misread({ 'a' => '2', 'c' => '3' }, { 'a' => {}, 'b' => '1' })).to eq(:merged) + end + + it 'names a list directly inside a list' do + expect(described_class.misread(%w[1 2], nil)).to eq(:list) + end + end +end diff --git a/spec/unit/zammad_api/resource_proxy_spec.rb b/spec/unit/zammad_api/resource_proxy_spec.rb new file mode 100644 index 0000000..1390e47 --- /dev/null +++ b/spec/unit/zammad_api/resource_proxy_spec.rb @@ -0,0 +1,1069 @@ +# frozen_string_literal: true + +RSpec.describe ZammadAPI::ResourceProxy do + subject(:proxy) { client.groups } + + let(:client) { unit_client } + let(:url) { "#{ClientHelper::BASE_URL}api/v1/groups" } + + it 'exposes the resource class' do + expect(proxy.resource_class).to eq(ZammadAPI::Resources::Group) + end + + describe '#new' do + it 'builds an unsaved record' do + expect(proxy.new(name: 'Support')).to be_new_record + end + + it 'does not talk to the server' do + proxy.new(name: 'Support') + expect(a_request(:any, /zammad\.test/)).not_to have_been_made + end + + it 'accepts no attributes at all' do + expect(proxy.new.attributes).to eq({}) + end + end + + describe '#find' do + it 'requests the record with expanded attributes' do + stub = stub_request(:get, "#{url}/1").with(query: { 'expand' => 'true' }).to_return(json_response({ id: 1, name: 'Users' })) + + proxy.find(1) + expect(stub).to have_been_requested + end + + it 'returns a persisted record' do + stub_request(:get, "#{url}/1").with(query: hash_including({})).to_return(json_response({ id: 1, name: 'Users' })) + + expect(proxy.find(1)).to be_persisted + end + + it 'maps the attributes' do + stub_request(:get, "#{url}/1").with(query: hash_including({})).to_return(json_response({ id: 1, name: 'Users' })) + + expect(proxy.find(1).name).to eq('Users') + end + + it 'raises NotFoundError for an unknown id' do + stub_request(:get, "#{url}/404").with(query: hash_including({})).to_return(json_response({ error: 'not found' }, status: 404)) + + expect { proxy.find(404) }.to raise_error(ZammadAPI::NotFoundError) + end + + it 'raises ParseError when the response is not an object' do + stub_request(:get, "#{url}/1").with(query: hash_including({})).to_return(json_response([{ id: 1 }])) + + expect { proxy.find(1) }.to raise_error(ZammadAPI::ParseError, /expected a JSON object, got Array/) + end + end + + describe 'ids in the request path' do + it 'escapes a traversal instead of reaching another endpoint' do + stub = stub_request(:get, "#{url}/1%2F..%2F..%2Fapi%2Fv1%2Fusers%2F1") + .with(query: { 'expand' => 'true' }) + .to_return(json_response({ error: 'not found' }, status: 404)) + + expect { proxy.find('1/../../api/v1/users/1') }.to raise_error(ZammadAPI::NotFoundError) + expect(stub).to have_been_requested + expect(a_request(:get, %r{/api/v1/users/1\z})).not_to have_been_made + end + + it 'escapes the id on destroy too' do + stub = stub_request(:delete, "#{url}/1%2F..%2F..%2Fapi%2Fv1%2Fusers%2F1").to_return(status: 200, body: '') + + proxy.destroy('1/../../api/v1/users/1') + expect(stub).to have_been_requested + end + + it 'escapes the id a record uses for its own writes' do + record = ZammadAPI::Resources::Group.from_response(client.instance_variable_get(:@transport), { id: '1/../../api/v1/users/1' }) + stub = stub_request(:delete, "#{url}/1%2F..%2F..%2Fapi%2Fv1%2Fusers%2F1").to_return(status: 200, body: '') + + record.destroy + expect(stub).to have_been_requested + end + + it 'rejects an empty id rather than requesting the index' do + expect { proxy.find('') }.to raise_error(ArgumentError, /record id is required/) + expect(a_request(:any, /zammad\.test/)).not_to have_been_made + end + end + + describe '#create' do + it 'posts the attributes' do + stub = stub_request(:post, url) + .with(query: { 'expand' => 'true' }, body: '{"name":"Support"}') + .to_return(json_response({ id: 5, name: 'Support' }, status: 201)) + + proxy.create(name: 'Support') + expect(stub).to have_been_requested + end + + it 'returns the persisted record' do + stub_request(:post, url).with(query: hash_including({})).to_return(json_response({ id: 5, name: 'Support' }, status: 201)) + + expect(proxy.create(name: 'Support')).to be_persisted + end + + it 'raises ValidationError when Zammad rejects the attributes' do + stub_request(:post, url).with(query: hash_including({})) + .to_return(json_response({ error: 'Name is required' }, status: 422)) + + expect { proxy.create({}) }.to raise_error(ZammadAPI::ValidationError, /Name is required/) + end + end + + describe '#find_by' do + let(:search_url) { "#{url}/search" } + + it 'searches instead of filtering an index that cannot filter' do + stub = stub_request(:get, search_url) + .with(query: hash_including('query' => 'Users')) + .to_return(json_response([{ id: 1, name: 'Users' }])) + + proxy.find_by(name: 'Users') + + expect(stub).to have_been_requested + expect(a_request(:get, url).with(query: hash_including({}))).not_to have_been_made + end + + it 'returns the matching record' do + stub_request(:get, search_url).with(query: hash_including({})).to_return(json_response([{ id: 1, name: 'Users' }])) + + expect(proxy.find_by(name: 'Users').id).to eq(1) + end + + # Zammad's search sorts by updated_at, newest first, not by relevance, so + # the exact match can sit on any page of hits. Reading only the first one + # answered nil for a record that exists, and find_by(...) || create(...) + # then created its duplicate. + context 'when more records match the term than one page holds' do + let(:page_size) { ZammadAPI::ResourceProxy::SEARCH_MAX_PER_PAGE } + let(:others) { Array.new(page_size) { { id: it + 1, name: 'Users Archive' } } } + + def stub_page(number, records) + stub_request(:get, search_url) + .with(query: hash_including('page' => number.to_s)) + .to_return(json_response(records)) + end + + it 'finds a match on a later page' do + stub_page(1, others) + stub_page(2, [{ id: 999, name: 'Users' }]) + + expect(proxy.find_by(name: 'Users').id).to eq(999) + end + + it 'answers nil only once every page has been read' do + stub_page(1, others) + stub_page(2, others.map { it.merge(id: it[:id] + page_size) }) + last = stub_page(3, []) + + expect(proxy.find_by(name: 'Users')).to be_nil + expect(last).to have_been_requested + end + + it 'reads no further than the page the match is on' do + stub_page(1, [*others.first(page_size - 1), { id: 999, name: 'Users' }]) + second = stub_page(2, []) + + proxy.find_by(name: 'Users') + expect(second).not_to have_been_requested + end + end + + it 'asks for hits at the size the search endpoint serves' do + stub = stub_request(:get, search_url) + .with(query: hash_including('page' => '1', 'per_page' => ZammadAPI::ResourceProxy::SEARCH_MAX_PER_PAGE.to_s)) + .to_return(json_response([{ id: 1, name: 'Users' }])) + + proxy.find_by(name: 'Users') + + expect(stub).to have_been_requested + end + + it 'returns a persisted record' do + stub_request(:get, search_url).with(query: hash_including({})).to_return(json_response([{ id: 1, name: 'Users' }])) + + expect(proxy.find_by(name: 'Users')).to be_persisted + end + + it 'skips a hit the search returned that does not actually match' do + stub_request(:get, search_url).with(query: hash_including({})) + .to_return(json_response([{ id: 1, name: 'Users Archive' }, { id: 2, name: 'Users' }])) + + expect(proxy.find_by(name: 'Users').id).to eq(2) + end + + it 'returns nil when the search matched nothing this record carries' do + stub_request(:get, search_url).with(query: hash_including({})) + .to_return(json_response([{ id: 1, name: 'Users Archive' }]), json_response([])) + + expect(proxy.find_by(name: 'Users')).to be_nil + end + + # Quoting a value that carries search syntax, to have it looked for rather + # than obeyed, cost more than it bought: an instance searching without + # Elasticsearch matches the term literally through a SQL LIKE, so the + # quotes became characters the value had to contain, and a hyphen is + # syntax - so `find_by(name: 'support-eu')` found nothing at all there. + it 'sends a value carrying search syntax as it is' do + stub = stub_request(:get, search_url) + .with(query: hash_including('query' => 'support-eu')) + .to_return(json_response([])) + + proxy.find_by(name: 'support-eu') + + expect(stub).to have_been_requested + end + + it 'sends a value that reads as a boolean query as it is' do + stub = stub_request(:get, search_url) + .with(query: hash_including('query' => 'a AND b')) + .to_return(json_response([])) + + proxy.find_by(name: 'a AND b') + + expect(stub).to have_been_requested + end + + # Whatever the term meant to the backend, the answer is decided here. + it 'still matches the record exactly' do + stub_request(:get, search_url).with(query: hash_including({})) + .to_return(json_response([{ id: 1, name: 'a AND b' }])) + + expect(proxy.find_by(name: 'a AND b').id).to eq(1) + end + + it 'returns nil when nothing matched' do + stub_request(:get, search_url).with(query: hash_including({})).to_return(json_response([])) + + expect(proxy.find_by(name: 'Nope')).to be_nil + end + + it 'matches on every attribute given, not just one' do + stub_request(:get, search_url).with(query: hash_including({})) + .to_return(json_response([{ id: 1, name: 'Users', active: false }, { id: 2, name: 'Users', active: true }])) + + expect(proxy.find_by(name: 'Users', active: true).id).to eq(2) + end + + # What a caller is promised: a record carrying both values comes back. + # The spec here asserted the query string instead - that "Users Support" + # went out - which a stub answers whatever it is handed, so nothing could + # see that an instance without Elasticsearch matches that term through a + # SQL LIKE per column and so finds neither of them. + it 'finds a record by two string attributes' do + stub_request(:get, search_url).with(query: hash_including({})) + .to_return(json_response([{ id: 1, name: 'Users', note: 'Other' }, { id: 2, name: 'Users', note: 'Support' }])) + + expect(proxy.find_by(name: 'Users', note: 'Support').id).to eq(2) + end + + # The fence for the above: one value goes out, never the values joined. + # Joined, the term is one no single column holds. + it 'searches a single value rather than joining them' do + stub = stub_request(:get, search_url) + .with(query: hash_including('query' => 'Support')) + .to_return(json_response([])) + + proxy.find_by(name: 'Users', note: 'Support') + expect(stub).to have_been_requested + end + + it 'searches the longest value, as the most selective of them' do + stub = stub_request(:get, search_url) + .with(query: hash_including('query' => 'a-very-specific-note')) + .to_return(json_response([])) + + proxy.find_by(name: 'Users', note: 'a-very-specific-note') + expect(stub).to have_been_requested + end + + # A non-string went to the search engine as the word it prints as, so + # `find_by(name: 'Users', active: true)` searched for "Users true" and + # matched nothing. + it 'keeps a non-string value out of the search term, and still matches on it' do + stub = stub_request(:get, search_url) + .with(query: hash_including('query' => 'Users')) + .to_return(json_response([{ id: 1, name: 'Users', active: false }, { id: 2, name: 'Users', active: true }])) + + expect(proxy.find_by(name: 'Users', active: true).id).to eq(2) + expect(stub).to have_been_requested + end + + it 'stops at the first match rather than walking the rest of the search' do + stub_request(:get, search_url).with(query: hash_including({})).to_return(json_response([{ id: 1, name: 'Users' }])) + + proxy.find_by(name: 'Users') + expect(a_request(:get, search_url).with(query: hash_including({}))).to have_been_made.once + end + + it 'rejects a lookup with no attribute at all' do + expect { proxy.find_by }.to raise_error(ArgumentError, /at least one attribute/) + end + + # find_by used to raise here, which left it working on four resources out + # of seven, and the caller writing all.detect by hand - the walk this makes. + context 'with a resource Zammad routes no search endpoint for' do + let(:states_url) { "#{ClientHelper::BASE_URL}api/v1/ticket_states" } + + before do + stub_request(:get, states_url).with(query: hash_including('page' => '1')) + .to_return(json_response([{ id: 1, name: 'new' }, { id: 2, name: 'open' }])) + stub_request(:get, states_url).with(query: hash_including('page' => '2')).to_return(json_response([])) + end + + it 'walks the records and answers with the one that matches' do + expect(client.ticket_states.find_by(name: 'open').id).to eq(2) + end + + it 'answers nil when none does' do + expect(client.ticket_states.find_by(name: 'closed')).to be_nil + end + + it 'never asks the search endpoint, which would answer 404' do + client.ticket_states.find_by(name: 'open') + expect(a_request(:get, "#{states_url}/search").with(query: hash_including({}))).not_to have_been_made + end + + it 'stops at the page the match is on' do + client.ticket_states.find_by(name: 'new') + expect(a_request(:get, states_url).with(query: hash_including('page' => '2'))).not_to have_been_made + end + + it 'matches on a value of any type' do + expect(client.ticket_states.find_by(id: 2).name).to eq('open') + end + end + + # A value that is not a string cannot be searched on - Zammad matches + # words, so it would go out as the word it prints as - and this used to + # raise for want of one. + context 'with no string value to search on' do + before do + stub_request(:get, url).with(query: hash_including('page' => '1')) + .to_return(json_response([{ id: 1, name: 'Users', active: false }, { id: 2, name: 'Support', active: true }])) + stub_request(:get, url).with(query: hash_including('page' => '2')).to_return(json_response([])) + end + + it 'walks the index and answers with the first record that matches' do + expect(proxy.find_by(active: true).id).to eq(2) + end + + it 'does not search for the word the value prints as' do + proxy.find_by(active: true) + expect(a_request(:get, search_url).with(query: hash_including({}))).not_to have_been_made + end + + it 'answers nil once the whole index has been read' do + expect(proxy.find_by(active: nil)).to be_nil + expect(a_request(:get, url).with(query: hash_including('page' => '2'))).to have_been_made + end + + it 'walks for a string value that is blank, which is nothing to search on either' do + expect(proxy.find_by(name: ' ', active: true)).to be_nil + expect(a_request(:get, search_url).with(query: hash_including({}))).not_to have_been_made + end + end + + # record[key] is nil for an attribute a record does not carry, so a nil + # value matched every record a misspelled name was asked of. + it 'does not match nil against an attribute the record does not carry' do + stub_request(:get, url).with(query: hash_including({})) + .to_return(json_response([{ id: 1, name: 'Users' }]), json_response([])) + + expect(proxy.find_by(nmae: nil)).to be_nil + end + + it 'does match nil against an attribute the record carries as nil' do + stub_request(:get, url).with(query: hash_including({})) + .to_return(json_response([{ id: 1, name: 'Users', note: nil }]), json_response([])) + + expect(proxy.find_by(note: nil).id).to eq(1) + end + end + + describe '#find_by!' do + let(:search_url) { "#{url}/search" } + + it 'returns the matching record' do + stub_request(:get, search_url).with(query: hash_including({})).to_return(json_response([{ id: 1, name: 'Users' }])) + + expect(proxy.find_by!(name: 'Users').id).to eq(1) + end + + it 'raises NotFoundError when nothing matched' do + stub_request(:get, search_url).with(query: hash_including({})).to_return(json_response([])) + + expect { proxy.find_by!(name: 'Nope') }.to raise_error(ZammadAPI::NotFoundError) + end + + it 'raises when the search answered with a record that does not match' do + stub_request(:get, search_url).with(query: hash_including({})) + .to_return(json_response([{ id: 1, name: 'Users Archive' }]), json_response([])) + + expect { proxy.find_by!(name: 'Users') }.to raise_error(ZammadAPI::NotFoundError) + end + + it 'names the query and the resource in the message' do + stub_request(:get, search_url).with(query: hash_including({})).to_return(json_response([])) + + expect { proxy.find_by!(name: 'Nope', active: true) } + .to raise_error("Can't find object by name and active (ZammadAPI::Resources::Group): no record matched") + end + + it 'does not put the values it searched for in the message' do + stub_request(:get, search_url).with(query: hash_including({})).to_return(json_response([])) + + expect { proxy.find_by!(name: 'secret-group') } + .to raise_error(ZammadAPI::NotFoundError) { |error| expect(error.message).not_to include('secret-group') } + end + end + + describe '#exists?' do + it 'is true when the record is there' do + stub_request(:get, "#{url}/1").with(query: hash_including({})).to_return(json_response({ id: 1 })) + + expect(proxy.exists?(1)).to be(true) + end + + it 'is false for a 404' do + stub_request(:get, "#{url}/404").with(query: hash_including({})) + .to_return(json_response({ error: 'not found' }, status: 404)) + + expect(proxy.exists?(404)).to be(false) + end + + it 'does not swallow an authorization failure' do + stub_request(:get, "#{url}/1").with(query: hash_including({})) + .to_return(json_response({ error: 'no' }, status: 403)) + + expect { proxy.exists?(1) }.to raise_error(ZammadAPI::AuthorizationError) + end + end + + describe '#destroy' do + it 'deletes the record without fetching it first' do + stub = stub_request(:delete, "#{url}/1").to_return(status: 200, body: '') + + expect(proxy.destroy(1)).to be(true) + expect(stub).to have_been_requested + expect(a_request(:get, "#{url}/1")).not_to have_been_made + end + + it 'raises NotFoundError for an unknown id' do + stub_request(:delete, "#{url}/404").to_return(json_response({ error: 'not found' }, status: 404)) + + expect { proxy.destroy(404) }.to raise_error(ZammadAPI::NotFoundError) + end + end + + # What a collection over this endpoint fetches per request when nothing asks + # for another size: as many as the endpoint serves. Read off the resource + # rather than written out, so that these stubs follow the declaration. + def default_per_page = ZammadAPI::Resources::Group.page_limit + + describe '#all' do + it 'returns a collection' do + expect(proxy.all).to be_a(ZammadAPI::Collection) + end + + it 'defaults to the collection page size' do + stub = stub_request(:get, url) + .with(query: { 'expand' => 'true', 'page' => '1', 'per_page' => default_per_page.to_s }) + .to_return(json_response([])) + + proxy.all.to_a + expect(stub).to have_been_requested + end + + it 'takes no arguments' do + expect { proxy.all(active: true) }.to raise_error(ArgumentError) + end + end + + describe '#order' do + it 'returns a sorted collection of every record' do + stub = stub_request(:get, url) + .with(query: { 'expand' => 'true', 'page' => '1', 'per_page' => default_per_page.to_s, 'sort_by' => 'name', 'order_by' => 'desc' }) + .to_return(json_response([])) + + proxy.order(name: :desc).to_a + expect(stub).to have_been_requested + end + + it 'is the order of the collection all hands back' do + expect(proxy.order(:name).inspect).to eq(proxy.all.order(:name).inspect) + end + + it 'refuses a resource whose index endpoint does not sort' do + expect { unit_client.tickets.order(:created_at) } + .to raise_error(ArgumentError, %r{api/v1/tickets is always served in the same order}) + end + + # where took a sort and refused nearly everything else, which is why it + # went: the name promised a filter an index endpoint does not have. + it 'has no where to reach for instead' do + expect(proxy).not_to respond_to(:where) + end + end + + describe 'enumerating a proxy directly' do + def stub_page(page, records, per_page: default_per_page) + stub_request(:get, url) + .with(query: { 'expand' => 'true', 'page' => page.to_s, 'per_page' => per_page.to_s }) + .to_return(json_response(records)) + end + + # The walk confirms a short page with one more request, so a collection + # that fits in a single page needs the empty page after it. + def stub_last_page(page, records, per_page: default_per_page) + stub_page(page, records, per_page: per_page) + stub_page(page + 1, [], per_page: per_page) + end + + it 'is Enumerable' do + expect(proxy).to be_a(Enumerable) + end + + it 'yields every record from #each' do + stub_last_page(1, [{ id: 1, name: 'Users' }, { id: 2, name: 'Support' }]) + + expect(proxy.map(&:name)).to eq(%w[Users Support]) + end + + it 'walks pages, like the collection does' do + stub_page(1, Array.new(default_per_page) { { id: it + 1 } }) + stub_page(2, [{ id: default_per_page + 1 }]) + + expect(proxy.map(&:id).size).to eq(default_per_page + 1) + end + + # Forwarded to the collection rather than left to Enumerable#first, which + # would take one record off the front of a page sized for walking. + it 'reads one sized page for #first, without walking everything' do + stub_page(1, [{ id: 1 }], per_page: 1) + + expect(proxy.first.id).to eq(1) + expect(a_request(:get, url).with(query: hash_including({ 'page' => '2' }))).not_to have_been_made + end + + it 'returns an Enumerator from #each without a block' do + expect(proxy.each).to be_a(Enumerator) + end + + it 'supports a lazy chain' do + stub_page(1, [{ id: 1, active: true }, { id: 2, active: false }]) + + expect(proxy.lazy.select(&:active).first(1).map(&:id)).to eq([1]) + end + + it 'forwards #page to the collection' do + stub = stub_request(:get, url) + .with(query: hash_including({ 'page' => '3' })) + .to_return(json_response([])) + + proxy.page(3).to_a + expect(stub).to have_been_requested + end + + it 'forwards the page size #page was given' do + stub = stub_page(1, [], per_page: 5) + + proxy.page(1, per_page: 5).to_a + expect(stub).to have_been_requested + end + + it 'forwards #find_each' do + stub_last_page(1, [{ id: 1 }], per_page: 5) + + ids = [] + proxy.find_each(batch_size: 5) { ids << it.id } + expect(ids).to eq([1]) + end + + it 'forwards #in_batches' do + stub_last_page(1, [{ id: 1 }], per_page: 5) + + sizes = [] + proxy.in_batches(of: 5) { sizes << it.size } + expect(sizes).to eq([1]) + end + + it 'forwards #pluck' do + stub_last_page(1, [{ id: 1, name: 'Users' }]) + + expect(proxy.pluck(:name)).to eq(['Users']) + end + + it 'forwards #size' do + stub_last_page(1, [{ id: 1 }]) + + expect(proxy.size).to eq(1) + end + + it 'forwards #length' do + stub_last_page(1, [{ id: 1 }]) + + expect(proxy.length).to eq(1) + end + + it 'forwards #take, so it costs what #first costs' do + stub_page(1, [{ id: 1 }, { id: 2 }], per_page: 2) + + expect(proxy.take(2).map(&:id)).to eq([1, 2]) + end + + it 'forwards #first' do + stub_page(1, [{ id: 1, name: 'Users' }], per_page: 1) + + expect(proxy.first.name).to eq('Users') + end + + it 'forwards #empty?' do + stub_request(:get, url).with(query: hash_including({})).to_return(json_response([])) + + expect(proxy).to be_empty + end + + it 'keeps #find as a lookup by id rather than Enumerable#find' do + stub_request(:get, "#{url}/1").with(query: hash_including({})).to_return(json_response({ id: 1, name: 'Users' })) + + expect(proxy.find(1).name).to eq('Users') + end + + it 'leaves the block form to #detect' do + stub_page(1, [{ id: 1, name: 'Users' }, { id: 2, name: 'Support' }]) + + expect(proxy.detect { it.name == 'Support' }.id).to eq(2) + end + + it 'does not pretend to be an array, so it is not flattened away' do + expect([proxy].flatten).to eq([proxy]) + end + end + + describe '#search' do + it 'refuses a resource Zammad routes no search endpoint for' do + expect { client.ticket_states.search('open') } + .to raise_error(ZammadAPI::Error, /routes no search endpoint for ZammadAPI::Resources::TicketState/) + end + + it 'refuses a search of ticket articles, which Zammad indexes but does not route' do + expect { client.ticket_articles.search('hello') } + .to raise_error(ZammadAPI::Error, /routes no search endpoint/) + end + + it 'requests the search endpoint' do + stub = stub_request(:get, "#{url}/search") + .with(query: { 'expand' => 'true', 'page' => '1', 'per_page' => ZammadAPI::ResourceProxy::SEARCH_MAX_PER_PAGE.to_s, 'query' => 'support', 'with_total_count' => 'true' }) + .to_return(json_response([])) + + proxy.search('support').to_a + expect(stub).to have_been_requested + end + + # The other things a search endpoint narrows by, named on the call that + # searches rather than passed to where on what it returned. + context 'with keywords the search endpoint reads' do + let(:users_search) { "#{ClientHelper::BASE_URL}api/v1/users/search" } + + before { stub_request(:get, /search/).with(query: hash_including({})).to_return(json_response([])) } + + it 'sends ids' do + client.users.search('x', ids: [1, 2]).to_a + expect(a_request(:get, users_search).with(query: hash_including('query' => 'x', 'ids' => %w[1 2]))).to have_been_made + end + + it 'sends role_ids, group_ids and permissions' do + client.users.search('x', role_ids: [2], group_ids: [3], permissions: ['ticket.agent']).to_a + + expect(a_request(:get, users_search).with(query: hash_including('role_ids' => ['2'], 'group_ids' => ['3'], 'permissions' => ['ticket.agent']))) + .to have_been_made + end + + # A list of group ids names no access, which Zammad reads as full. The + # Hash is how any other access is asked for, and it has to arrive as the + # pairs User::Search walks: `group_ids[3][]=read`. + # + # Read off the URL Faraday built rather than asked of WebMock, which + # takes a Hash keyed by numbers for an Array and reports + # `group_ids[][0]=read` for a request that was never sent that way. + # + # Every pair naming a group, and not only the three that were written. + # Looked for as a substring, they were found in a query that named a + # fourth group beside them as well, and a group nobody asked for is a + # set of agents the search then keeps. + it 'sends group_ids as a map of group to access, the way Rails reads a nested parameter back' do + sent = nil + recorder = Class.new(Faraday::Middleware) do + define_method(:on_request) { |env| sent = URI.decode_www_form(env.url.query) } + end + + unit_client(middleware: ->(builder) { builder.use(recorder) }) + .users.search('x', group_ids: { 3 => %w[read change], 4 => 'full' }).to_a + + expect(sent.select { |name, _| name.start_with?('group_ids') }) + .to contain_exactly(['group_ids[3][]', 'read'], ['group_ids[3][]', 'change'], ['group_ids[4]', 'full']) + end + + it 'sends a condition the way Rails reads a nested parameter back' do + client.tickets.search('x', condition: { 'ticket.state_id' => { operator: 'is', value: [1] } }).to_a + + expect(a_request(:get, "#{ClientHelper::BASE_URL}api/v1/tickets/search") + .with(query: hash_including('condition' => { 'ticket.state_id' => { 'operator' => 'is', 'value' => ['1'] } }))) + .to have_been_made + end + + it 'accepts a keyword spelled as a string' do + expect(client.users.search('x', 'ids' => [1])).to be_a(ZammadAPI::Collection) + end + + it 'keeps the term the search was given' do + client.users.search('smith', ids: [1]).to_a + expect(a_request(:get, users_search).with(query: hash_including('query' => 'smith'))).to have_been_made + end + + # A collection is lazy: nothing is sent until it is enumerated. It held + # the caller's own Array, Hash and String until then, so changing one of + # them afterwards changed a search that had already been written and + # checked. + context 'when what it was given changes before the collection is read' do + it 'sends the ids it was given' do + ids = [1] + search = client.users.search('x', ids: ids) + ids << 2 + search.to_a + + expect(a_request(:get, users_search).with(query: hash_including('ids' => ['1']))).to have_been_made + end + + it 'sends the term it was given' do + term = +'smith' + search = client.users.search(term) + term << ' jones' + search.to_a + + expect(a_request(:get, users_search).with(query: hash_including('query' => 'smith'))).to have_been_made + end + + it 'sends the condition it was given, at every depth' do + condition = { 'ticket.state_id' => { operator: 'is', value: [1] } } + search = client.tickets.search('x', condition: condition) + condition['ticket.state_id'][:value] << 2 + condition['ticket.owner_id'] = { operator: 'is', value: [3] } + search.to_a + + expect(a_request(:get, "#{ClientHelper::BASE_URL}api/v1/tickets/search") + .with(query: hash_including('condition' => { 'ticket.state_id' => { 'operator' => 'is', 'value' => ['1'] } }))) + .to have_been_made + end + + it 'carries the copy through page and order' do + ids = [1] + search = client.users.search('x', ids: ids).order(:login).page(2) + ids << 2 + search.to_a + + expect(a_request(:get, users_search).with(query: hash_including('ids' => ['1'], 'page' => '2', 'sort_by' => 'login'))) + .to have_been_made + end + + it 'leaves what it was given writable' do + ids = [1] + client.users.search('x', ids: ids) + + expect(ids).not_to be_frozen + end + end + end + + # Zammad drops a parameter it does not know, so these would come back + # unnarrowed with nothing to say so. + context 'with a keyword the search endpoint would drop' do + it 'refuses an attribute name' do + expect { proxy.search('support', name: 'Users') } + .to raise_error(ArgumentError, %r{search does not take name on api/v1/groups: this search endpoint narrows by the term, and by condition, ids, and drops}) + end + + it 'says where an attribute value goes instead' do + expect { proxy.search('support', name: 'Users') } + .to raise_error(ArgumentError, /Put an attribute value in the term - search\('state\.name:open'\)/) + end + + it 'refuses a sort, and names order' do + expect { proxy.search('support', sort_by: 'name') } + .to raise_error(ArgumentError, /search does not take sort_by.*sort with search\(term\)\.order\(\.\.\.\)/) + end + + it 'refuses to replace the search term' do + expect { proxy.search('login failure', query: 'anything') }.to raise_error(ArgumentError, /search does not take query/) + end + + %i[page per_page expand only_total_count].each do |owned| + it "refuses #{owned}, which the collection controls itself" do + expect { proxy.search('support', owned => 1) }.to raise_error(ArgumentError, /search does not take #{owned}/) + end + end + + it 'makes no request' do + expect { proxy.search('support', name: 'Users') }.to raise_error(ArgumentError) + expect(a_request(:any, /zammad\.test/)).not_to have_been_made + end + end + + # model_search_render hands role_ids, group_ids and permissions to the + # search of every model, and only User::Search reads them. A ticket + # search given group_ids was sent as written and answered with tickets + # from every group the client can read. + context 'with a keyword only the user search reads' do + it 'refuses group_ids on tickets' do + expect { client.tickets.search('printer', group_ids: [2]) } + .to raise_error(ArgumentError, %r{search does not take group_ids on api/v1/tickets: this search endpoint narrows by the term, and by condition, ids, and drops}) + end + + it 'says how tickets are narrowed by group instead' do + expect { client.tickets.search('printer', group_ids: [2]) } + .to raise_error(ArgumentError, /or in a condition - search\(term, condition: \{'ticket\.group_id' => \{operator: 'is', value: \[2\]\}\}\)/) + end + + it 'refuses role_ids and permissions on organizations' do + expect { client.organizations.search('acme', role_ids: [2], permissions: ['ticket.agent']) } + .to raise_error(ArgumentError, /search does not take role_ids, permissions on/) + end + + it 'refuses them on groups' do + expect { proxy.search('support', group_ids: [1]) }.to raise_error(ArgumentError, /search does not take group_ids on/) + end + + it 'makes no request' do + expect { client.tickets.search('printer', group_ids: [2]) }.to raise_error(ArgumentError) + expect(a_request(:any, /zammad\.test/)).not_to have_been_made + end + + it 'still takes all three on users, and names them among what that search narrows by' do + expect(client.users.search('smith', role_ids: [2], group_ids: [3], permissions: ['ticket.agent'])).to be_a(ZammadAPI::Collection) + expect { client.users.search('smith', active: true) } + .to raise_error(ArgumentError, /and by condition, ids, role_ids, group_ids, permissions, and drops/) + end + + it 'still takes condition and ids on every search' do + expect(client.tickets.search('printer', ids: [1], condition: { 'ticket.group_id' => { operator: 'is', value: [2] } })) + .to be_a(ZammadAPI::Collection) + end + end + + context 'with a resource a caller declared' do + let(:role_class) do + Class.new(ZammadAPI::Resources::Base) do + def self.name = 'Role' + + path 'api/v1/roles' + searchable true + end + end + + it 'takes condition and ids, which every search reads' do + expect(client.resource(role_class).search('agent', ids: [1])).to be_a(ZammadAPI::Collection) + end + + it 'refuses a keyword it did not declare' do + expect { client.resource(role_class).search('agent', permissions: ['admin']) } + .to raise_error(ArgumentError, %r{search does not take permissions on api/v1/roles}) + end + + it 'takes a keyword it declared' do + role_class.search_filters :permissions + + expect(client.resource(role_class).search('agent', permissions: ['admin'])).to be_a(ZammadAPI::Collection) + end + end + + # Every one of these is refused at the call that wrote it, rather than + # when the collection is first read some lines away. + context 'with a keyword it cannot send' do + it 'refuses a nil value, which no query string can spell' do + expect { client.users.search('x', ids: nil) }.to raise_error(ArgumentError, /query parameter ids is nil/) + end + + # Zammad narrows by a keyword only where it is `present?`, so each of + # these was sent and answered with everything matching the term - for + # `ids: allowed_ids` with nothing allowed, where none was asked for. + { + ids: [], + role_ids: [], + permissions: [], + group_ids: {}, + condition: {} + }.each do |name, value| + it "refuses #{name}: #{value.inspect}, which Zammad reads as no #{name} at all" do + expect { client.users.search('smith', name => value) } + .to raise_error(ArgumentError, %r{search was given #{name}: #{Regexp.escape(value.inspect)} on api/v1/users}) + end + end + + it 'refuses a keyword given as a blank String' do + expect { client.users.search('smith', ids: ' ') }.to raise_error(ArgumentError, /search was given ids: " "/) + end + + # `present?` is false for it, so Zammad skips the filter. + it 'refuses one that holds only a Unicode space' do + expect { client.users.search('smith', permissions: "\u3000") }.to raise_error(ArgumentError, /search was given permissions:/) + end + + it 'refuses one that is blank in UTF-16, the way it does one in UTF-8' do + expect { client.users.search('smith', permissions: "\u3000".encode('UTF-16LE')) }.to raise_error(ArgumentError, /search was given permissions:/) + end + + it 'takes one given in UTF-16 that is not blank' do + expect(client.users.search('smith', permissions: 'admin'.encode('UTF-16LE'))).to be_a(ZammadAPI::Collection) + end + + # Sent as `permissions=`, which is as blank as a String with nothing in + # it: the check is of what is sent, not of the class it was given as. + it 'refuses one given as a value whose text is empty' do + expect { client.users.search('smith', permissions: :'') }.to raise_error(ArgumentError, /search was given permissions: :""/) + end + + # Nothing is written for an empty Hash, so the request went out with no + # condition at all. + it 'refuses a condition that holds nothing but empty Hashes' do + expect { client.tickets.search('printer', condition: { 'ticket.state_id' => {} }) } + .to raise_error(ArgumentError, /search was given condition: \{"ticket.state_id" => \{\}\}/) + end + + it 'refuses group_ids naming a group with nothing under it' do + expect { client.users.search('smith', group_ids: { 2 => {} }) }.to raise_error(ArgumentError, /search was given group_ids:/) + end + + it 'says what the search would have come back with' do + expect { client.users.search('smith', ids: []) } + .to raise_error(ArgumentError, /everything matching the term, not narrowed to nothing/) + end + + it 'names every empty keyword at once' do + expect { client.users.search('smith', ids: [], role_ids: []) }.to raise_error(ArgumentError, /search was given ids: \[\], role_ids: \[\] on/) + end + + it 'makes no request for one' do + stub = stub_request(:get, /search/).with(query: hash_including({})) + + expect { client.users.search('smith', ids: []).to_a }.to raise_error(ArgumentError) + expect(stub).not_to have_been_requested + end + + # What is nested in a condition is a selector, and Zammad's to read. + it 'still takes a condition whose value is empty' do + expect(client.tickets.search('x', condition: { 'ticket.tags' => { operator: 'contains all', value: [] } })).to be_a(ZammadAPI::Collection) + end + + # An empty list is written, as `condition[ticket.tags][value][]`, so + # the condition reaches Zammad. + it 'still takes a condition that holds nothing but an empty list' do + expect(client.tickets.search('x', condition: { 'ticket.tags' => { value: [] } })).to be_a(ZammadAPI::Collection) + end + + it 'still takes a value that is not empty for being false or zero' do + expect(client.users.search('smith', ids: [0])).to be_a(ZammadAPI::Collection) + end + + it 'refuses two spellings of one keyword rather than dropping a value' do + expect { client.users.search('x', 'ids' => [1], :ids => [2]) } + .to raise_error(ArgumentError, /ids was given twice, as "ids" and as :ids/) + end + + it 'refuses two spellings of one key nested inside a condition' do + expect { client.tickets.search('x', condition: { 'state_id' => 1, :state_id => 2 }) } + .to raise_error(ArgumentError, /parameter condition\[state_id\] was given twice/) + end + + # A group of conditions and a condition share `operator`, which is what + # lets a query string keep them apart. Two elements that share nothing + # would reach Zammad as one, so the search says so here. + it 'refuses a list of conditions a query string cannot keep apart' do + expect { client.tickets.search('x', condition: { conditions: [{ name: 'ticket.state_id' }, { operator: 'AND' }] }) } + .to raise_error(ArgumentError, /query parameter condition\[conditions\]\[1\] has no plain value under a key the element before it has/) + end + + # Read off the URL Faraday built, in the order it was written: WebMock + # sorts a query before it compares one, and the order is the point. + # Rails begins the second element at its `operator`, so that has to + # come before the conditions it holds, or the group is read into the + # condition before it. + it 'takes a condition that holds a group of conditions, and sends the group as an element of its own' do + nested = { operator: 'OR', conditions: [{ name: 'ticket.state_id', operator: 'is', value: [2] }, { operator: 'AND', conditions: [{ name: 'ticket.group_id', operator: 'is', value: [1] }] }] } + sent = nil + recorder = Class.new(Faraday::Middleware) do + define_method(:on_request) { |env| sent = URI.decode_www_form(env.url.query).map(&:first) } + end + stub_request(:get, /search/).with(query: hash_including({})).to_return(json_response([])) + + search = unit_client(middleware: ->(builder) { builder.use(recorder) }).tickets.search('x', condition: nested) + expect(search).to be_a(ZammadAPI::Collection) + + search.to_a + expect(sent.grep(/\Acondition\[conditions\]/)).to eq( + [ + 'condition[conditions][][name]', 'condition[conditions][][operator]', 'condition[conditions][][value][]', + 'condition[conditions][][operator]', 'condition[conditions][][conditions][][name]', + 'condition[conditions][][conditions][][operator]', 'condition[conditions][][conditions][][value][]' + ] + ) + end + + it 'still accepts a condition whose keys only look alike' do + expect(client.tickets.search('x', condition: { 'ticket.state_id' => { operator: 'is' }, 'ticket.group_id' => { operator: 'is' } })) + .to be_a(ZammadAPI::Collection) + end + end + + it 'sorts through order on the collection it returns' do + stub = stub_request(:get, "#{url}/search") + .with(query: hash_including('query' => 'support', 'sort_by' => 'name', 'order_by' => 'asc')) + .to_return(json_response([])) + + proxy.search('support').order(:name).to_a + expect(stub).to have_been_requested + end + + it 'requires a term' do + expect { proxy.search }.to raise_error(ArgumentError) + end + + it 'rejects an empty term' do + expect { proxy.search(' ') }.to raise_error(ArgumentError, /non-empty query string/) + end + + # Zammad asks `blank?`, which counts Unicode spaces, and answers a blank + # term with every record. + ["\u00A0", "\u3000", "\u3000".encode('UTF-16LE')].each do |blank| + it "rejects #{blank.inspect}, which Zammad reads as no term" do + expect { proxy.search(blank) }.to raise_error(ArgumentError, /non-empty query string/) + end + end + + it "says that '*' asks for every record" do + expect { proxy.search('') }.to raise_error(ArgumentError, /Search for '\*' to ask for every record/) + end + + # How Zammad's own interface lists every user or organization. + it "sends '*', which asks for every record in so many words" do + stub = stub_request(:get, "#{url}/search").with(query: hash_including('query' => '*')).to_return(json_response([])) + + proxy.search('*').to_a + expect(stub).to have_been_requested + end + + it 'rejects a term that is not a string' do + expect { proxy.search(42) }.to raise_error(ArgumentError, /non-empty query string/) + end + end + + describe '#inspect' do + it 'names the resource' do + expect(proxy.inspect).to eq('#') + end + end +end diff --git a/spec/unit/zammad_api/resources/base_spec.rb b/spec/unit/zammad_api/resources/base_spec.rb new file mode 100644 index 0000000..d3287b8 --- /dev/null +++ b/spec/unit/zammad_api/resources/base_spec.rb @@ -0,0 +1,1513 @@ +# frozen_string_literal: true + +RSpec.describe ZammadAPI::Resources::Base do + let(:client) { unit_client } + let(:url) { "#{ClientHelper::BASE_URL}api/v1/groups" } + + describe 'the path DSL' do + it 'exposes the declared path' do + expect(ZammadAPI::Resources::Group.resource_path).to eq('api/v1/groups') + end + + it 'raises for a resource that declares none' do + anonymous = Class.new(described_class) do + def self.name + 'Anonymous' + end + end + expect { anonymous.resource_path }.to raise_error(ZammadAPI::Error, /does not declare an API path/) + end + + it 'does not leak a path between sibling resources' do + expect(ZammadAPI::Resources::User.resource_path).to eq('api/v1/users') + end + end + + describe 'attributes' do + subject(:group) { client.groups.new(name: 'Support', 'note' => 'from a string key') } + + it 'reads an attribute' do + expect(group.name).to eq('Support') + end + + it 'symbolizes string keys supplied by the caller' do + expect(group.note).to eq('from a string key') + end + + it 'starts without changes' do + expect(group).not_to be_changed + end + + it 'records a change as old and new value' do + group.name = 'Other' + expect(group.changes).to eq(name: %w[Support Other]) + end + + it 'reports being changed' do + group.name = 'Other' + expect(group).to be_changed + end + + it 'reflects the change when read back' do + group.name = 'Other' + expect(group.name).to eq('Other') + end + + it 'records a change for a previously unset attribute' do + group.active = true + expect(group.changes).to eq(active: [nil, true]) + end + + it 'keeps the original value when an attribute is written twice' do + group.name = 'First' + group.name = 'Second' + expect(group.changes).to eq(name: %w[Support Second]) + end + + it 'drops the change when the value returns to the original' do + group.name = 'Other' + group.name = 'Support' + expect(group.changes).to be_empty + end + + it 'is not changed once the value returns to the original' do + group.name = 'Other' + group.name = 'Support' + expect(group).not_to be_changed + end + + it 'still reads the reassigned value after the change is dropped' do + group.name = 'Other' + group.name = 'Support' + expect(group.name).to eq('Support') + end + + it 'drops the change when an attribute the record carries is set back to its nil original' do + carrying_nil = client.groups.new(name: 'Support', note: nil) + carrying_nil.note = 'Renamed' + carrying_nil.note = nil + expect(carrying_nil.changes).to be_empty + end + + # An attribute the record does not carry is not an attribute whose value + # is nil: Zammad reduces the object it serializes for a permission-scoped + # client, so the key being absent says nothing about what is stored. Read + # as a nil original, writing nil to one compared equal, staged nothing and + # was still merged into the attributes - the write was dropped without a + # word and the record went on reporting a key Zammad never sent it. + it 'stages a write of an attribute the record does not carry' do + group.active = nil + expect(group.changes).to eq(active: [nil, nil]) + end + + it 'keeps that write staged when it is written twice' do + group.active = true + group.active = nil + expect(group.changes).to eq(active: [nil, nil]) + end + + it 'keeps the attributes it reports in step with the changes it staged' do + group.active = nil + expect(group.key?(:active)).to be(group.changes.key?(:active)) + end + end + + describe 'attribute state a record hands out' do + subject(:group) { client.groups.new(name: 'Support', preferences: { 'note' => 'keep' }) } + + it 'cannot be written through #attributes, which would not stage a change' do + expect { group.attributes[:name] = 'Sneaky' }.to raise_error(FrozenError) + end + + it 'cannot be written through a nested value' do + expect { group.attributes[:preferences][:note] = 'Sneaky' }.to raise_error(FrozenError) + end + + it 'cannot be written through #changes, which would decide what save sends' do + group.name = 'Renamed' + expect { group.changes[:name] = %w[a b] }.to raise_error(FrozenError) + end + + it 'still records a change through the writer' do + group.name = 'Renamed' + expect(group.changes).to eq(name: %w[Support Renamed]) + end + + it 'does not report a change that was never staged' do + group.to_h[:name] = 'Sneaky' + expect(group).not_to be_changed + end + + it 'keeps a value the caller mutates after assigning it' do + note = +'Mutable' + group.note = note + note << ' changed' + + expect(group.note).to eq('Mutable') + end + + it 'freezes attributes adopted from a response' do + stub_request(:post, url).with(query: hash_including({})) + .to_return(json_response({ id: 7, preferences: { note: 'from the server' } }, status: 201)) + + group.save! + expect { group.attributes[:preferences][:note] << '!' }.to raise_error(FrozenError) + end + end + + describe '#save' do + context 'with a new record' do + subject(:group) { client.groups.new(name: 'Support') } + + before do + stub_request(:post, url) + .with(query: { 'expand' => 'true' }, body: '{"name":"Support"}') + .to_return(json_response({ id: 7, name: 'Support', note: nil }, status: 201)) + end + + it 'returns true' do + expect(group.save).to be(true) + end + + it 'posts to the collection path' do + group.save + expect(a_request(:post, url).with(query: hash_including({}))).to have_been_made + end + + it 'adopts the attributes from the response' do + group.save + expect(group.id).to eq(7) + end + + it 'is no longer a new record' do + group.save + expect(group).to be_persisted + end + + it 'clears the staged changes' do + group.name = 'Support' + group.save + expect(group.changes).to be_empty + end + end + + context 'with an existing record' do + subject(:group) { client.groups.find(1) } + + before do + stub_request(:get, "#{url}/1").with(query: hash_including({})) + .to_return(json_response({ id: 1, name: 'Users', note: 'old', active: true })) + end + + it 'sends only the changed attributes' do + stub = stub_request(:put, "#{url}/1") + .with(query: { 'expand' => 'true' }, body: '{"note":"new"}') + .to_return(json_response({ id: 1, name: 'Users', note: 'new', active: true })) + + group.note = 'new' + group.save + expect(stub).to have_been_requested + end + + it 'returns true' do + stub_request(:put, "#{url}/1").with(query: hash_including({})) + .to_return(json_response({ id: 1, note: 'new' })) + + group.note = 'new' + expect(group.save).to be(true) + end + + it 'sends nothing at all when nothing changed' do + stub = stub_request(:put, "#{url}/1").with(query: hash_including({})) + .to_return(json_response({ id: 1 })) + + expect(group.save).to be(true) + expect(stub).not_to have_been_requested + end + + it 'saves again once something changes' do + stub_request(:put, "#{url}/1").with(query: hash_including({}), body: '{"note":"new"}') + .to_return(json_response({ id: 1, note: 'new' })) + + group.save + group.note = 'new' + + expect(group.save).to be(true) + expect(group.note).to eq('new') + end + end + + it 'raises ParseError when the response is not an object' do + stub_request(:post, url).with(query: hash_including({})) + .to_return(json_response([], status: 201)) + + expect { client.groups.new(name: 'x').save } + .to raise_error(ZammadAPI::ParseError, /expected a JSON object, got Array/) + end + + context 'when Zammad rejects the attributes' do + subject(:group) { client.groups.new } + + before do + stub_request(:post, url).with(query: hash_including({})) + .to_return(json_response({ error: 'Name is required' }, status: 422)) + end + + it 'returns false instead of raising' do + expect(group.save).to be(false) + end + + it 'leaves the validation error in #error' do + group.save + expect(group.error).to be_a(ZammadAPI::ValidationError) + end + + it 'carries the message Zammad reported' do + group.save + expect(group.error.server_message).to eq('Name is required') + end + + it 'leaves the record unsaved' do + group.save + expect(group).to be_new_record + end + + it 'keeps the staged changes, so the attributes can be corrected and resent' do + group.name = 'Support' + group.save + expect(group.changes).to eq({ name: [nil, 'Support'] }) + end + end + + context 'when the failure is not a validation error' do + it 'still raises for a 403' do + stub_request(:post, url).with(query: hash_including({})) + .to_return(json_response({ error: 'no' }, status: 403)) + + expect { client.groups.new(name: 'x').save }.to raise_error(ZammadAPI::AuthorizationError) + end + + it 'still raises for a 500' do + stub_request(:post, url).with(query: hash_including({})) + .to_return(json_response({}, status: 500)) + + expect { client.groups.new(name: 'x').save }.to raise_error(ZammadAPI::ServerError) + end + end + + it 'clears a previous error once the record saves' do + stub_request(:post, url).with(query: hash_including({})) + .to_return(json_response({ error: 'Name is required' }, status: 422), json_response({ id: 7, name: 'Support' })) + + group = client.groups.new + group.save + group.name = 'Support' + + expect(group.save).to be(true) + expect(group.error).to be_nil + end + + context 'when the save after a rejected one fails some other way' do + subject(:group) { ZammadAPI::Resources::Group.from_response(unit_transport, id: 1, name: 'Users') } + + before do + stub_request(:put, "#{url}/1").with(query: hash_including({})).to_return( + json_response({ error: 'Name is required' }, status: 422), + json_response({ error: 'not yours' }, status: 403) + ) + group.name = '' + group.save + group.name = 'Support' + end + + it 'records the first rejection' do + expect(group.error).to be_a(ZammadAPI::ValidationError) + end + + it 'clears it rather than reporting it as the second failure' do + expect { group.save }.to raise_error(ZammadAPI::AuthorizationError) + expect(group.error).to be_nil + end + end + end + + describe '#save!' do + subject(:group) { client.groups.new(name: 'Support') } + + it 'returns true' do + stub_request(:post, url).with(query: hash_including({})).to_return(json_response({ id: 7 }, status: 201)) + + expect(group.save!).to be(true) + end + + it 'raises ValidationError when Zammad rejects the record' do + stub_request(:post, url).with(query: hash_including({})) + .to_return(json_response({ error: 'Name is required' }, status: 422)) + + expect { group.save! }.to raise_error(ZammadAPI::ValidationError, /Name is required/) + end + + it 'does not record the error, because it was raised' do + stub_request(:post, url).with(query: hash_including({})) + .to_return(json_response({ error: 'Name is required' }, status: 422)) + + expect { group.save! }.to raise_error(ZammadAPI::ValidationError) + expect(group.error).to be_nil + end + end + + describe '#assign_attributes' do + subject(:group) { client.groups.new(name: 'Support') } + + it 'stages every attribute as a change' do + group.assign_attributes(name: 'Renamed', note: 'Why') + expect(group.changes).to eq(name: %w[Support Renamed], note: [nil, 'Why']) + end + + it 'accepts string keys' do + group.assign_attributes('name' => 'Renamed') + expect(group.name).to eq('Renamed') + end + + it 'does not save' do + group.assign_attributes(name: 'Renamed') + expect(a_request(:any, /zammad\.test/)).not_to have_been_made + end + + it 'returns the record, so it can be chained' do + expect(group.assign_attributes(name: 'Renamed')).to be(group) + end + + it 'drops a change that restores the original value' do + group.assign_attributes(name: 'Renamed') + group.assign_attributes(name: 'Support') + expect(group).not_to be_changed + end + end + + describe '#update' do + subject(:group) { ZammadAPI::Resources::Group.from_response(unit_transport, id: 1, name: 'Users', note: 'old') } + + it 'sends only the assigned attributes' do + stub = stub_request(:put, "#{url}/1") + .with(query: { 'expand' => 'true' }, body: '{"note":"new"}') + .to_return(json_response({ id: 1, name: 'Users', note: 'new' })) + + group.update(note: 'new') + expect(stub).to have_been_requested + end + + it 'returns true when the record was stored' do + stub_request(:put, "#{url}/1").with(query: hash_including({})).to_return(json_response({ id: 1, note: 'new' })) + + expect(group.update(note: 'new')).to be(true) + end + + it 'adopts the attributes from the response' do + stub_request(:put, "#{url}/1").with(query: hash_including({})) + .to_return(json_response({ id: 1, name: 'Renamed by Zammad' })) + + group.update(note: 'new') + expect(group.name).to eq('Renamed by Zammad') + end + + it 'returns false and records the error when Zammad rejects the attributes' do + stub_request(:put, "#{url}/1").with(query: hash_including({})) + .to_return(json_response({ error: 'Note is too long' }, status: 422)) + + expect(group.update(note: 'new')).to be(false) + expect(group.error.server_message).to eq('Note is too long') + end + + it 'keeps the staged changes after a rejection, so they can be corrected' do + stub_request(:put, "#{url}/1").with(query: hash_including({})) + .to_return(json_response({ error: 'Note is too long' }, status: 422)) + + group.update(note: 'new') + expect(group.changes).to eq(note: %w[old new]) + end + + it 'creates a record that has not been saved yet' do + stub = stub_request(:post, url).with(query: hash_including({}), body: '{"name":"Support"}') + .to_return(json_response({ id: 7, name: 'Support' }, status: 201)) + + expect(client.groups.new.update(name: 'Support')).to be(true) + expect(stub).to have_been_requested + end + end + + describe '#update!' do + subject(:group) { ZammadAPI::Resources::Group.from_response(unit_transport, id: 1, note: 'old') } + + it 'returns true' do + stub_request(:put, "#{url}/1").with(query: hash_including({})).to_return(json_response({ id: 1 })) + + expect(group.update!(note: 'new')).to be(true) + end + + it 'raises when Zammad rejects the attributes' do + stub_request(:put, "#{url}/1").with(query: hash_including({})) + .to_return(json_response({ error: 'Note is too long' }, status: 422)) + + expect { group.update!(note: 'new') }.to raise_error(ZammadAPI::ValidationError, /Note is too long/) + end + end + + describe '#reload' do + subject(:group) { ZammadAPI::Resources::Group.from_response(transport, id: 1, name: 'Users') } + + let(:transport) { unit_transport } + + before do + stub_request(:get, "#{url}/1").with(query: { 'expand' => 'true' }) + .to_return(json_response({ id: 1, name: 'Renamed' })) + end + + it 'refetches the attributes' do + expect(group.reload.name).to eq('Renamed') + end + + it 'discards unsaved changes' do + group.name = 'Local' + expect(group.reload.changes).to be_empty + end + + it 'returns itself' do + expect(group.reload).to be(group) + end + + it 'raises for a record that was never saved' do + expect { ZammadAPI::Resources::Group.new(transport).reload } + .to raise_error(ZammadAPI::Error, /has not been saved, so there is nothing to reload/) + end + + it 'raises ParseError when the response is not an object' do + stub_request(:get, "#{url}/1").with(query: { 'expand' => 'true' }) + .to_return(json_response([])) + + expect { group.reload } + .to raise_error(ZammadAPI::ParseError, /expected a JSON object, got Array/) + end + + it 'raises ParseError when the response is not JSON' do + stub_request(:get, "#{url}/1").with(query: { 'expand' => 'true' }) + .to_return(status: 200, body: 'Gateway Timeout', headers: { 'Content-Type' => 'text/html' }) + + expect { group.reload } + .to raise_error(ZammadAPI::ParseError, /expected a JSON object, got String/) + end + + it 'keeps the previous attributes when the response cannot be decoded' do + stub_request(:get, "#{url}/1").with(query: { 'expand' => 'true' }) + .to_return(json_response([])) + + expect { group.reload }.to raise_error(ZammadAPI::ParseError) + expect(group.name).to eq('Users') + end + end + + describe '.member_path' do + it 'builds the path of one record' do + expect(ZammadAPI::Resources::Group.member_path(1)).to eq('api/v1/groups/1') + end + + # ResourceProxy#find, #destroy and every instance method that reaches an + # endpoint go through here, so the escaping rule is applied once. + it 'escapes an id that would otherwise leave its segment' do + expect(ZammadAPI::Resources::Group.member_path('1/../users')).to eq('api/v1/groups/1%2F..%2Fusers') + end + + it 'refuses an id that navigates' do + expect { ZammadAPI::Resources::Group.member_path('..') }.to raise_error(ArgumentError) + end + end + + describe '#destroy' do + subject(:group) { ZammadAPI::Resources::Group.from_response(unit_transport, id: 1) } + + it 'deletes the record' do + stub = stub_request(:delete, "#{url}/1").to_return(status: 200, body: '') + expect(group.destroy).to be(true) + expect(stub).to have_been_requested + end + + it 'raises for a record that was never saved' do + expect { client.groups.new.destroy }.to raise_error(ZammadAPI::Error, /has not been saved, so there is nothing to destroy/) + end + + # `destroy` asked only whether the record was already destroyed, so one + # built with an id it was simply handed issued a real DELETE for a record + # it does not stand for. The constructor refuses that id now, so there is + # no such record left to destroy. + it 'sends nothing for a record built with an id it was never saved with' do + stub = stub_request(:delete, "#{url}/99") + + expect { client.groups.new(id: 99, name: 'X').destroy } + .to raise_error(ZammadAPI::Error, /is what addresses this record/) + expect(stub).not_to have_been_requested + end + + context 'when the record is gone' do + before do + stub_request(:delete, "#{url}/1").to_return(status: 200, body: '') + group.destroy + end + + it 'reports the record as destroyed' do + expect(group).to be_destroyed + end + + it 'no longer reports it as persisted' do + expect(group).not_to be_persisted + end + + it 'says so in inspect' do + expect(group.inspect).to include('destroyed=true') + end + + it 'refuses a save rather than letting it 404' do + expect { group.save }.to raise_error(ZammadAPI::Error, /was destroyed, there is nothing to save/) + end + + # `reload` re-read a record that no longer exists and cleared the flag on + # the way back, so the record came back reporting itself as persisted and + # its next save issued a PUT against the deleted path. + it 'refuses a reload rather than resurrecting the record' do + expect { group.reload } + .to raise_error(ZammadAPI::Error, /was destroyed, there is nothing to reload/) + end + + it 'stays destroyed after a refused reload' do + expect { group.reload }.to raise_error(ZammadAPI::Error) + + expect(group).to be_destroyed + expect(group).not_to be_persisted + end + + it 'refuses a second destroy rather than surfacing Zammad\'s 404' do + expect { group.destroy } + .to raise_error(ZammadAPI::Error, /was destroyed, there is nothing to destroy/) + end + end + + context 'with state staged before it was destroyed' do + subject(:group) { ZammadAPI::Resources::Group.from_response(unit_transport, id: 1, name: 'Users') } + + before do + stub_request(:delete, "#{url}/1").to_return(status: 200, body: '') + group.name = 'Support' + end + + it 'drops a change that can never be sent' do + group.destroy + + expect(group).not_to be_changed + expect(group.changes).to be_empty + end + + # Readable as Zammad last served them. The staged write above was never + # sent, and dropping the change set without it left the record reporting + # "Support" while `changed?` was false and `changes` was empty - so + # nothing was left to tell a local edit apart from a value the server + # gave, in the one state where it can never be saved. + it 'keeps the attributes readable, so a destroyed record can still be reported on' do + group.destroy + + expect(group.id).to eq(1) + expect(group.name).to eq('Users') + end + + it 'does not report a write Zammad never saw' do + group.destroy + + expect(group.attributes).to eq({ id: 1, name: 'Users' }) + expect(group.inspect).not_to include('Support') + end + + it 'refuses the association readers, which would request a record that is gone' do + group.destroy + + # The guarantee, not the mechanism that was expected to deliver it. + # This compared the proxy against the one from before the destroy, + # which clearing the memo satisfied - while `related` went on + # rebuilding a working proxy on the very next call. It passed for as + # long as the behaviour it is named for was broken. + expect { group.related }.to raise_error(ZammadAPI::Error, /was destroyed/) + end + + it 'drops the failure of a save that is over' do + stub_request(:put, "#{url}/1").with(query: hash_including({})) + .to_return(json_response({ error: 'Name is required' }, status: 422)) + group.save + + expect(group.error).to be_a(ZammadAPI::ValidationError) + group.destroy + expect(group.error).to be_nil + end + end + + # `update` stages before it saves, and `save!` is where the destroyed + # check used to live. That order left a destroyed record holding a change + # set that can never be sent - the state destroy clears the staged changes + # to prevent - so the refusal happens before anything is written. + context 'when an update is attempted after it was destroyed' do + before do + stub_request(:delete, "#{url}/1").to_return(status: 200, body: '') + group.destroy + end + + it 'refuses the update' do + expect { group.update(name: 'Renamed') }.to raise_error(ZammadAPI::Error, /was destroyed/) + end + + it 'refuses the raising update' do + expect { group.update!(name: 'Renamed') }.to raise_error(ZammadAPI::Error, /was destroyed/) + end + + it 'leaves nothing staged behind the refusal' do + begin + group.update(name: 'Renamed') + rescue ZammadAPI::Error + nil + end + + expect(group).not_to be_changed + expect(group.changes).to be_empty + end + + it 'leaves the attributes as they were' do + begin + group.update(name: 'Renamed') + rescue ZammadAPI::Error + nil + end + + expect(group.key?(:name)).to be(false) + end + end + + # `update` refused a destroyed record, and the writers it is built on did + # not: a write left the record changed and reading a value Zammad never + # saw, and the save after it was the first thing to object. + context 'when an attribute is written after it was destroyed' do + subject(:group) { ZammadAPI::Resources::Group.from_response(unit_transport, id: 1, name: 'A') } + + before do + stub_request(:delete, "#{url}/1").to_return(status: 200, body: '') + group.destroy + end + + it 'refuses a named writer' do + expect { group.name = 'Z' }.to raise_error(ZammadAPI::Error, /Group 1 was destroyed, there is nothing to change/) + end + + it 'refuses []=' do + expect { group[:name] = 'Z' }.to raise_error(ZammadAPI::Error, /was destroyed/) + end + + it 'refuses assign_attributes' do + expect { group.assign_attributes(name: 'Z') }.to raise_error(ZammadAPI::Error, /was destroyed/) + end + + it 'refuses a writer for an attribute the record never carried' do + expect { group.note = 'Z' }.to raise_error(ZammadAPI::Error, /was destroyed/) + end + + it 'leaves nothing staged behind the refusal' do + expect { group.name = 'Z' }.to raise_error(ZammadAPI::Error) + expect(group).not_to be_changed + end + + it 'leaves the record reading as it last was in Zammad' do + expect { group.assign_attributes(note: 'n', name: 'Z') }.to raise_error(ZammadAPI::Error) + expect(group.to_h).to eq({ id: 1, name: 'A' }) + end + + it 'still refuses the id for the reason an id is refused' do + expect { group.assign_attributes(id: 9) }.to raise_error(ZammadAPI::Error, /cannot be staged/) + end + end + end + + # The attributes are frozen and replaced on write, so a copy never saw the + # original's next write. The change set is written in place, and was shared. + describe 'a copy made with dup or clone' do + let(:original) { client.groups.find(1) } + + before do + stub_request(:get, "#{url}/1").with(query: { expand: 'true' }).to_return(json_response({ id: 1, name: 'A', note: 'n' })) + end + + %i[dup clone].each do |copier| + context "with #{copier}" do + let(:copy) { original.public_send(copier) } + + it 'does not mark the original as changed when the copy is written' do + copy.name = 'X' + expect(original).not_to be_changed + end + + it 'does not stage the write on the original' do + copy.name = 'X' + expect(original.changes).to eq({}) + end + + it 'stages the write on the copy' do + copy.name = 'X' + expect(copy.changes).to eq({ name: %w[A X] }) + end + + it 'sends nothing when the original is saved after the copy was written' do + copy.name = 'X' + original.save + expect(a_request(:put, "#{url}/1")).not_to have_been_made + end + + it 'does not stage a write to the original on the copy' do + copy + original.name = 'Y' + expect(copy.changes).to eq({}) + end + + it 'carries over what was staged when it was made' do + original.name = 'Y' + expect(copy.changes).to eq({ name: %w[A Y] }) + end + + it 'keeps those two change sets apart afterwards' do + original.name = 'Y' + copy.note = 'other' + expect(original.changes.keys).to eq([:name]) + end + + it 'is still the same Zammad record' do + expect(copy).to eq(original) + end + + it 'gets association readers of its own, not the ones bound to the original' do + expect(copy.related).not_to be(original.related) + end + end + end + end + + describe 'equality' do + it 'treats two separately fetched records as the same record' do + stub_request(:get, "#{url}/1").with(query: hash_including({})).to_return(json_response({ id: 1, name: 'Users' })) + + first_fetch = client.groups.find(1) + second_fetch = client.groups.find(1) + + expect(first_fetch).not_to equal(second_fetch) + expect(first_fetch).to eq(second_fetch) + end + + it 'tells records of different resources with the same id apart' do + group = ZammadAPI::Resources::Group.from_response(unit_transport, id: 1) + user = ZammadAPI::Resources::User.from_response(unit_transport, id: 1) + + expect(group).not_to eq(user) + end + + # An id is only unique within one installation. A script that reads two + # of them holds a group 1 from each, and they are two records. + context 'with records of two Zammad instances' do + let(:here) { ZammadAPI::Resources::Group.from_response(unit_transport, id: 1) } + let(:there) { ZammadAPI::Resources::Group.from_response(unit_transport(url: 'http://other.test/'), id: 1) } + + it 'tells the same id apart' do + expect(here).not_to eq(there) + end + + it 'keeps both through uniq' do + expect([here, there].uniq.size).to eq(2) + end + + it 'keeps both as members of a Set' do + expect(Set[here, there].size).to eq(2) + end + + it 'does not answer for one with the value stored under the other' do + expect({ here => :handled }[there]).to be_nil + end + end + + context 'with a record read through two clients for one instance' do + let(:record) { ZammadAPI::Resources::Group.from_response(unit_transport, id: 1) } + + it 'is the same record through a client with other options' do + other = ZammadAPI::Resources::Group.from_response(unit_transport(timeout: 5, http_token: 'another'), id: 1) + + expect(record).to eq(other) + expect(record.hash).to eq(other.hash) + end + + it 'is the same record through an on_behalf_of scope' do + scoped = ZammadAPI::Resources::Group.from_response(unit_transport.with_on_behalf_of('agent@example.com'), id: 1) + + expect([record, scoped].uniq.size).to eq(1) + end + + it 'is the same record whether or not the url was written with its trailing slash' do + other = ZammadAPI::Resources::Group.from_response(unit_transport(url: ClientHelper::BASE_URL.chomp('/')), id: 1) + + expect(record).to eq(other) + end + end + + it 'identifies a record by its id once its first save assigns one' do + stub_request(:post, url).with(query: hash_including({})).to_return(json_response({ id: 7, name: 'Support' })) + group = client.groups.new(name: 'Support') + + expect(group).not_to eq(ZammadAPI::Resources::Group.from_response(unit_transport, id: 7)) + group.save! + expect(group).to eq(ZammadAPI::Resources::Group.from_response(unit_transport, id: 7)) + end + end + + describe '#to_json' do + it 'renders the attributes rather than the object' do + group = ZammadAPI::Resources::Group.from_response(unit_transport, id: 1, name: 'Users') + + expect(group.to_json).to eq('{"id":1,"name":"Users"}') + end + end + + describe '#inspect' do + it 'shows the id, state and attributes' do + group = ZammadAPI::Resources::Group.from_response(unit_transport, id: 1, name: 'Users') + expect(group.inspect) + .to eq('#') + end + end + + describe '.from_response' do + it 'builds a persisted record' do + expect(ZammadAPI::Resources::Group.from_response(unit_transport, id: 1)).to be_persisted + end + end + + # A plain class-level ivar is not inherited, so a subclass used to inherit + # every association, the page limit and the searchability, and lose only the + # API path - raising "does not declare an API path" from a class that + # plainly did. + describe 'a resource subclassed by a caller' do + subject(:subclass) { Class.new(ZammadAPI::Resources::Ticket) { def self.name = 'MyTicket' } } + + it 'inherits the API path' do + expect(subclass.resource_path).to eq('api/v1/tickets') + end + + it 'inherits the member path built from it' do + expect(subclass.member_path(7)).to eq('api/v1/tickets/7') + end + + it 'inherits searchability' do + expect(subclass.searchable?).to be(true) + end + + it 'inherits the filters its parent\'s search reads' do + expect(Class.new(ZammadAPI::Resources::User).search_filter_names).to eq(%i[role_ids group_ids permissions]) + end + + it 'has no search filters of its own unless it or a parent declares some' do + expect(subclass.search_filter_names).to eq([]) + end + + it 'takes filter names as strings too' do + subclass.search_filters 'role_ids' + + expect(subclass.search_filter_names).to eq([:role_ids]) + end + + it 'inherits the page limit' do + expect(subclass.page_limit).to eq(100) + end + + it 'inherits whether the index endpoint sorts' do + expect(subclass.sortable?).to be(false) + end + + it 'inherits the associations, as it always did' do + expect(subclass.associations.keys).to eq(ZammadAPI::Resources::Ticket.associations.keys) + end + + it 'lets a subclass declare a path of its own' do + own = Class.new(ZammadAPI::Resources::Ticket) { path 'api/v1/my_tickets' } + + expect(own.resource_path).to eq('api/v1/my_tickets') + end + + # An override has to win even when it is the falsey value, which is why + # the lookup asks whether the ivar is defined rather than whether it is + # truthy. + it 'lets a subclass declare itself unsearchable' do + own = Class.new(ZammadAPI::Resources::Ticket) { searchable false } + + expect(own.searchable?).to be(false) + end + end + + # Declared as bare constants, a misspelled override was silently ignored and + # the resource kept Base's default: SEARCHEABLE = true left the resource + # unsearchable, and every find_by on it raised "Zammad routes no search + # endpoint" with no hint that the declaration was the problem. + describe 'the endpoint declarations' do + it 'refuses a misspelled declaration at load' do + expect { Class.new(described_class) { searcheable true } } + .to raise_error(NoMethodError, /searcheable/) + end + + it 'defaults to unsearchable, so an unrouted /search is refused at the call site' do + expect(Class.new(described_class).searchable?).to be(false) + end + + it 'defaults to the generic index page limit' do + expect(Class.new(described_class).page_limit).to eq(described_class::DEFAULT_MAX_PER_PAGE) + end + + it 'defaults to an index endpoint that sorts, as the generic ones do' do + expect(Class.new(described_class).sortable?).to be(true) + end + + it 'records a declared page limit' do + expect(Class.new(described_class) { max_per_page 25 }.page_limit).to eq(25) + end + + it 'records a declaration that the index endpoint does not sort' do + expect(Class.new(described_class) { sortable false }.sortable?).to be(false) + end + + it 'declares tickets and users unsortable, whose controllers hardcode the order' do + expect([ZammadAPI::Resources::Ticket, ZammadAPI::Resources::User].map(&:sortable?)).to eq([false, false]) + end + end + + # The id is what addresses the record. Staged, it took effect for every path + # that builds a path from the attributes and not at all for the record those + # paths then reported on: `group.id = 99; group.destroy` sent DELETE to group + # 99 and left the record saying group 1 was the one destroyed. + # The parent is resolved before MEMO_LOCK is taken, because resolving it may + # build the parent's own proxy through this same method and a Mutex is not + # reentrant. Folded back inside the lock this raises + # `ThreadError: deadlock; recursive locking`, and a caller subclassing a + # resource is the case that lock exists to cover in the first place. + describe 'the association proxy of a subclass whose parent has none yet' do + it 'builds without deadlocking on the memo lock' do + leaf = Class.new(Class.new(ZammadAPI::Resources::Group)) + + expect(leaf.related_class).to be_a(Class) + end + end + + # `record[:x] = v` reached method_missing as `:[]=`, which the writer branch + # took for an attribute called `[]`: it staged the index as the value, lost + # the write, and sent `{"[]": "x"}` on the next save. + describe '#[]=' do + subject(:group) { ZammadAPI::Resources::Group.from_response(unit_transport, id: 1, name: 'Users') } + + it 'stages the attribute it names' do + group[:note] = 'x' + + expect(group.changes).to eq({ note: [nil, 'x'] }) + end + + it 'reads back through the matching reader' do + group[:note] = 'x' + + expect(group[:note]).to eq('x') + end + + it 'takes a string key the way the reader does' do + group['note'] = 'x' + + expect(group[:note]).to eq('x') + end + + it 'refuses what the named writer refuses' do + expect { group[:id] = 9 }.to raise_error(ZammadAPI::Error, /cannot be staged as an attribute/) + end + + it 'invents no attribute from the operator itself' do + group[:note] = 'x' + + expect(group.attributes.keys).not_to include(:[]) + end + + it 'is claimed by a record that stages writes' do + expect(group).to respond_to(:[]=) + end + + it 'is claimed under either spelling' do + # rubocop:disable-next Performance/StringIdentifierArgument -- the String spelling is the point + expect(group.respond_to?('[]=')).to be(true) + end + + # The production case for recognising a writer by name rather than by a + # trailing `=`: on a record that stages writes, an operator reached the + # writer branch and invented an attribute from its stem. + it 'invents no attribute from a comparison operator' do + expect { group.public_send(:<=, 5) }.to raise_error(NoMethodError) + + expect(group.attributes.keys).not_to include(:<) + end + + it 'stages nothing for a comparison operator' do + expect { group.public_send(:<=, 5) }.to raise_error(NoMethodError) + + expect(group).not_to be_changed + end + end + + describe 'writing the id' do + subject(:group) { ZammadAPI::Resources::Group.from_response(unit_transport, id: 1, name: 'Users') } + + it 'is refused' do + expect { group.id = 99 }.to raise_error(ZammadAPI::Error, /is what addresses this record/) + end + + it 'points at the lookup that was meant' do + expect { group.id = 99 }.to raise_error(ZammadAPI::Error, /look up the record you meant with find\(99\)/) + end + + it 'is refused through assign_attributes too' do + expect { group.assign_attributes(id: 99) }.to raise_error(ZammadAPI::Error, /is what addresses this record/) + end + + # The message exists to name the id the caller passed, and the pre-check + # that runs for these two paths dropped it - so a serializer or a form + # binder, which reach the writer this way, were told to call find(nil). + it 'names the id that was passed through assign_attributes' do + expect { group.assign_attributes(id: 99) }.to raise_error(ZammadAPI::Error, /find\(99\)/) + end + + it 'names the id that was passed through update' do + expect { group.update(id: 99) }.to raise_error(ZammadAPI::Error, /find\(99\)/) + end + + it 'names the attribute it refused' do + expect { group.id = 99 }.to raise_error(ZammadAPI::Error, /Group#id cannot be staged/) + end + + # Checked before anything is written, not on the way past: refusing + # mid-loop staged the keys that came first and left the record dirty with + # half a change set, which is the state `update` takes its own guard one + # line early to avoid. + it 'stages nothing at all when one key in the hash is refused' do + expect { group.assign_attributes(name: 'X', id: 99, note: 'Y') }.to raise_error(ZammadAPI::Error) + + expect(group).not_to be_changed + expect(group.changes).to be_empty + end + + it 'leaves the attributes it had already reached alone' do + expect { group.assign_attributes(name: 'X', id: 99, note: 'Y') }.to raise_error(ZammadAPI::Error) + + expect(group.name).to eq('Users') + end + + it 'stages nothing through update either' do + expect { group.update(name: 'X', id: 99) }.to raise_error(ZammadAPI::Error) + + expect(group).not_to be_changed + end + + # A record that claimed a writer and then raised when it was called would + # defeat the point of asking, and lead a serializer or form binder straight + # into the exception it was checking to avoid. + it 'does not claim a writer it would refuse' do + expect(group).not_to respond_to(:id=) + end + + it 'still claims the writers it honours' do + expect(group).to respond_to(:name=) + end + + it 'leaves the record addressing what it did before' do + expect { group.id = 99 }.to raise_error(ZammadAPI::Error) + + expect(group.id).to eq(1) + expect(group).not_to be_changed + end + + # The constructor was the one door that did not make this refusal, and + # the only one whose value reached the wire: a new record is sent in full, + # so `new(id: 5).save` POSTed the id nothing had checked. + it 'is refused by the constructor too' do + expect { client.groups.new(id: 5) }.to raise_error(ZammadAPI::Error, /is what addresses this record/) + end + + it 'still lets a record Zammad served carry one' do + expect(ZammadAPI::Resources::Group.from_response(unit_transport, id: 5).id).to eq(5) + end + end + + # The third way a record ends up persisted without an id, and the one that + # has nothing to do with a save: Zammad serves a reduced object where the + # authenticated user may not see the whole record, which is the same thing + # #write_attribute is written around. Such a record used to be told it "was + # saved, but the response carried no id" - sending the caller to look at a + # save that never happened, when what they need is which user the client + # authenticates as. + describe 'a record Zammad served without an id' do + subject(:group) { ZammadAPI::Resources::Group.from_response(unit_transport, name: 'Users') } + + it 'refuses a reload it cannot address' do + expect { group.reload }.to raise_error(ZammadAPI::Error, /was loaded without an id/) + end + + it 'points at what this client may read' do + expect { group.destroy }.to raise_error(ZammadAPI::Error, /check what this client may read/) + end + + it 'does not claim a save that never happened' do + expect { group.reload }.to raise_error(ZammadAPI::Error) { |error| expect(error.message).not_to include('was saved') } + end + + it 'does not tell the caller to save a record Zammad already holds' do + expect { group.destroy }.to raise_error(ZammadAPI::Error) { |error| expect(error.message).not_to include('save it first') } + end + + it 'refuses a save it cannot address' do + group.name = 'Support' + + expect { group.save! }.to raise_error(ZammadAPI::Error, /was loaded without an id/) + end + + it 'still says the record was saved where a save is what left it this way' do + stub_request(:post, url).with(query: hash_including({})).to_return(status: 201, body: 'proxy') + new_group = client.groups.new(name: 'Support') + begin + new_group.save + rescue ZammadAPI::ParseError + nil + end + + expect { new_group.reload }.to raise_error(ZammadAPI::Error, /was saved, but the response carried no id/) + end + end + + # What makes a record persisted is that Zammad answered 2xx, not that the + # answer parsed. Decoded first, a create whose 201 carried an HTML error + # page from an intervening proxy raised ParseError with the record still + # looking new - so the ticket existed in Zammad and a retried save POSTed a + # second one. Marked persisted, the record has no id to be addressed by + # either, and nothing staged to send, so the retry has to say so rather than + # take the "nothing to send" short circuit and report success. + describe 'a create whose success body cannot be parsed' do + subject(:group) { client.groups.new(name: 'Support') } + + before { stub_request(:post, url).with(query: hash_including({})).to_return(status: 201, body: 'proxy') } + + it 'still reports the parse failure' do + expect { group.save }.to raise_error(ZammadAPI::ParseError) + end + + it 'does not leave the record looking unsaved' do + begin + group.save + rescue ZammadAPI::ParseError + nil + end + + expect(group.new_record?).to be(false) + end + + it 'does not create a second record when the save is retried' do + 2.times do + group.save + rescue ZammadAPI::Error + nil + end + + expect(a_request(:post, url).with(query: hash_including({}))).to have_been_made.once + end + + it 'refuses the retried save rather than reporting it stored' do + begin + group.save + rescue ZammadAPI::ParseError + nil + end + + expect { group.save }.to raise_error(ZammadAPI::Error, /carried no id/) + end + + it 'refuses to reload a record it cannot address' do + begin + group.save + rescue ZammadAPI::ParseError + nil + end + + expect { group.reload }.to raise_error(ZammadAPI::Error, /carried no id/) + end + + it 'does not tell the caller to save a record that was already saved' do + begin + group.save + rescue ZammadAPI::ParseError + nil + end + + expect { group.destroy }.to raise_error(ZammadAPI::Error, /was saved/) + end + + # An update keeps only what Zammad had served the record with. A record + # being created was served nothing, and what it sent is all there is to + # read from it. + it 'goes on reading everything it sent, written after it was built or not' do + group.note = 'Second line' + begin + group.save + rescue ZammadAPI::ParseError + nil + end + + expect(group.attributes).to eq(name: 'Support', note: 'Second line') + end + end + + # The same argument for what was staged. Zammad answered 2xx, so it applied + # the changes, and they used to stay staged because the body did not parse: + # the next save sent all of them again. For a ticket's `article` that is a + # second article and a second e-mail, from a save that was about the title. + describe 'an update whose success body cannot be parsed' do + subject(:ticket) { client.tickets.find(1) } + + let(:ticket_url) { "#{ClientHelper::BASE_URL}api/v1/tickets/1" } + let(:article) { { body: 'Reset link sent.', type: 'email', to: 'customer@example.com' } } + + before do + stub_request(:get, ticket_url).with(query: hash_including({})).to_return(json_response({ id: 1, title: 'Help', note: nil })) + stub_request(:put, ticket_url).with(query: hash_including({})) + .to_return({ status: 200, body: 'proxy' }, json_response({ id: 1, title: 'Renamed' })) + + ticket.article = article + begin + ticket.save + rescue ZammadAPI::ParseError + nil + end + end + + it 'still reports the parse failure' do + other = client.tickets.find(1) + other.note = 'x' + stub_request(:put, ticket_url).with(query: hash_including({})).to_return(status: 200, body: 'proxy') + + expect { other.save }.to raise_error(ZammadAPI::ParseError) + end + + it 'no longer holds the changes Zammad acknowledged as staged' do + expect(ticket.changed?).to be(false) + expect(ticket.changes).to eq({}) + end + + it 'does not send the acknowledged changes again with the next save' do + ticket.title = 'Renamed' + ticket.save + + expect(a_request(:put, ticket_url).with(query: hash_including({}), body: { title: 'Renamed' })).to have_been_made.once + expect(a_request(:put, ticket_url).with(query: hash_including({}), body: hash_including('article' => anything))).to have_been_made.once + end + + it 'sends nothing for a save with nothing new staged' do + expect(ticket.save).to be(true) + expect(a_request(:put, ticket_url).with(query: hash_including({}))).to have_been_made.once + end + + it 'goes on reading the values it sent for the attributes Zammad serves' do + other = client.tickets.find(1) + other.title = 'Sent' + stub_request(:put, ticket_url).with(query: hash_including({})).to_return(status: 200, body: 'proxy') + begin + other.save + rescue ZammadAPI::ParseError + nil + end + + expect(other.title).to eq('Sent') + expect(other.attributes).to eq(id: 1, title: 'Sent', note: nil) + end + + # `article` is not an attribute of a ticket. It is a command in the body + # of the PUT, and Zammad never serves it back. Settled into the baseline + # with the attributes, it was remembered as the ticket's own state, and + # the same article assigned again compared equal to it. + it 'does not keep a key Zammad never served the record with' do + expect(ticket.key?(:article)).to be(false) + expect(ticket.attributes).to eq(id: 1, title: 'Help', note: nil) + end + + it 'stages the same article when it is assigned again' do + ticket.article = article + + expect(ticket.changes).to eq(article: [nil, article]) + end + + it 'sends the same article again when it is assigned again, as a second reply' do + ticket.article = article + ticket.save + + expect(a_request(:put, ticket_url).with(query: hash_including({}), body: { article: article })).to have_been_made.twice + end + + it 'stages a value written back to what it was before the save, which Zammad no longer holds' do + other = client.tickets.find(1) + other.title = 'Sent' + stub_request(:put, ticket_url).with(query: hash_including({})).to_return(status: 200, body: 'proxy') + begin + other.save + rescue ZammadAPI::ParseError + nil + end + + other.title = 'Help' + + expect(other.changes).to eq(title: %w[Sent Help]) + end + + it 'is brought up to date by a reload' do + stub_request(:get, ticket_url).with(query: hash_including({})).to_return(json_response({ id: 1, title: 'Help', article_count: 2 })) + ticket.reload + + expect(ticket.key?(:article)).to be(false) + expect(ticket.article_count).to eq(2) + end + + it 'keeps a change Zammad rejected staged, to be corrected and sent again' do + other = client.tickets.find(1) + other.title = '' + stub_request(:put, ticket_url).with(query: hash_including({})) + .to_return(json_response({ error: 'Title is required' }, status: 422)) + + expect(other.save).to be(false) + expect(other.changes).to eq(title: ['Help', '']) + end + + # What Zammad acknowledged is what the request carried. The baseline used + # to be taken from the record once the answer was in, so a write that + # landed while the request was out - from a logger or a middleware of the + # caller's that reaches the record, or from another thread - was settled + # along with it, for a value that was never sent. + context 'when the record is written to while the request is out' do + subject(:other) { client.tickets.find(1) } + + before do + stub_request(:put, ticket_url).with(query: hash_including({})).to_return do + other.title = 'C' + { status: 200, body: 'proxy' } + end + + other.title = 'B' + begin + other.save + rescue ZammadAPI::ParseError + nil + end + end + + it 'sent the value that was staged when the request left' do + expect(a_request(:put, ticket_url).with(query: hash_including({}), body: { title: 'B' })).to have_been_made.once + end + + it 'reads the value Zammad was sent, not the one written since' do + expect(other.title).to eq('B') + end + + it 'has nothing staged, as after a response it could read' do + expect(other.changes).to eq({}) + end + + it 'stages the later value when it is written again' do + other.title = 'C' + + expect(other.changes).to eq(title: %w[B C]) + end + end + + # The interval before that one: between the attributes being held and the + # request being built from them. Nothing of the caller's runs there on one + # thread, so the path being built stands in for a second thread writing to + # the record. The body used to be read from the change set at that point, + # so the PUT carried "C" and the record was settled on "B". + context 'when the record is written to before the request is built' do + subject(:other) { client.tickets.find(1) } + + before do + stub_request(:put, ticket_url).with(query: hash_including({})).to_return(status: 200, body: 'proxy') + + other.title = 'B' + allow(ZammadAPI::Resources::Ticket).to receive(:member_path).and_wrap_original do |original, id| + other.title = 'C' + original.call(id) + end + begin + other.save + rescue ZammadAPI::ParseError + nil + end + end + + it 'sent the value that was held when the save began' do + expect(a_request(:put, ticket_url).with(query: hash_including({}), body: { title: 'B' })).to have_been_made.once + end + + it 'reads the value it sent, with nothing staged' do + expect(other.title).to eq('B') + expect(other.changes).to eq({}) + end + end + + # Settling the record on what it sent is a write to its foreign keys like + # any other, and what the association proxy resolved from a value written + # meanwhile is not the answer for the one the record is put back on. + context 'when an association is resolved from a key written while the request is out' do + subject(:other) { client.tickets.find(1) } + + let(:related) { other.related } + + before do + stub_request(:get, ticket_url).with(query: hash_including({})).to_return(json_response({ id: 1, customer_id: 3 })) + [9, 10].each do |id| + stub_request(:get, "#{ClientHelper::BASE_URL}api/v1/users/#{id}").with(query: hash_including({})).to_return(json_response({ id: id })) + end + stub_request(:put, ticket_url).with(query: hash_including({})).to_return do + other.customer_id = 10 + related.customer + { status: 200, body: 'proxy' } + end + + other.customer_id = 9 + begin + other.save + rescue ZammadAPI::ParseError + nil + end + end + + it 'is back on the key it sent' do + expect(other.customer_id).to eq(9) + end + + it 'resolves the association from the key it sent, on a proxy held from before' do + expect(related.customer.id).to eq(9) + end + end + + # The same write under a response that can be read, which is what the + # above is held to: the attributes it carries replace the record's. + it 'drops a write made while the request was out where the response can be read, too' do + other = client.tickets.find(1) + stub_request(:put, ticket_url).with(query: hash_including({})).to_return do + other.title = 'C' + json_response({ id: 1, title: 'B' }) + end + other.update!(title: 'B') + + expect(other.title).to eq('B') + expect(other.changes).to eq({}) + end + end +end diff --git a/spec/unit/zammad_api/resources/ticket_article_attachment_spec.rb b/spec/unit/zammad_api/resources/ticket_article_attachment_spec.rb new file mode 100644 index 0000000..5145926 --- /dev/null +++ b/spec/unit/zammad_api/resources/ticket_article_attachment_spec.rb @@ -0,0 +1,152 @@ +# frozen_string_literal: true + +RSpec.describe ZammadAPI::Resources::TicketArticleAttachment do + let(:transport) { unit_transport } + let(:download_url) { "#{ClientHelper::BASE_URL}api/v1/ticket_attachment/42/9/3" } + + describe 'built from an article' do + subject(:attachment) { article.attachments.first } + + let(:article) do + ZammadAPI::Resources::TicketArticle.from_response( + transport, + id: 9, + ticket_id: 42, + attachments: [{ id: 3, filename: 'note.txt', size: '12' }] + ) + end + + it 'carries the attachment id' do + expect(attachment.id).to eq(3) + end + + it 'is the same attachment as another read of it' do + expect(attachment).to eq(article.attachments.first) + end + + it 'is not the attachment with that id on another Zammad instance' do + elsewhere = ZammadAPI::Resources::TicketArticle + .from_response(unit_transport(url: 'http://other.test/'), article.to_h) + .attachments.first + + expect(attachment).not_to eq(elsewhere) + expect([attachment, elsewhere].uniq.size).to eq(2) + end + + it 'carries the filename' do + expect(attachment.filename).to eq('note.txt') + end + + it 'is given the ticket id, which the attachment endpoint needs' do + expect(attachment.ticket_id).to eq(42) + end + + it 'is given the article id' do + expect(attachment.article_id).to eq(9) + end + + it 'returns an empty list when the article has no attachments' do + bare = ZammadAPI::Resources::TicketArticle.from_response(transport, id: 9) + expect(bare.attachments).to eq([]) + end + + # This metadata comes off a response body like any other, and an element + # that is not an object reached `raw.merge` and died there as a bare + # NoMethodError from inside the gem - past the `rescue ZammadAPI::Error` + # every caller is told to write. + it 'refuses metadata that is not a list' do + article = ZammadAPI::Resources::TicketArticle.from_response(transport, id: 9, attachments: 'none') + + expect { article.attachments } + .to raise_error(ZammadAPI::ParseError, /expected a JSON array of objects, got String/) + end + + it 'refuses a list holding something that is not an object' do + article = ZammadAPI::Resources::TicketArticle.from_response(transport, id: 9, attachments: [3]) + + expect { article.attachments } + .to raise_error(ZammadAPI::ParseError, /got an array holding Integer/) + end + + it 'names the article in the refusal' do + article = ZammadAPI::Resources::TicketArticle.from_response(transport, id: 9, attachments: 'none') + + expect { article.attachments } + .to raise_error(ZammadAPI::ParseError, /ZammadAPI::Resources::TicketArticle/) + end + end + + describe '#download' do + subject(:attachment) { described_class.new(transport, id: 3, ticket_id: 42, article_id: 9) } + + it 'requests the attachment endpoint' do + stub = stub_request(:get, download_url).to_return(status: 200, body: 'contents') + attachment.download + expect(stub).to have_been_requested + end + + it 'returns the file contents' do + stub_request(:get, download_url).to_return(status: 200, body: 'contents') + expect(attachment.download).to eq('contents') + end + + it 'returns binary data undisturbed' do + png = "\x89PNG\r\n\x1A\n\x00\xFF".b + stub_request(:get, download_url) + .to_return(status: 200, body: png, headers: { 'Content-Type' => 'image/png' }) + + expect(attachment.download).to eq(png) + end + + it 'uses binary encoding' do + stub_request(:get, download_url).to_return(status: 200, body: 'contents') + expect(attachment.download.encoding).to eq(Encoding::BINARY) + end + + it 'raises when the attachment is gone' do + stub_request(:get, download_url).to_return(json_response({ error: 'not found' }, status: 404)) + expect { attachment.download }.to raise_error(ZammadAPI::NotFoundError) + end + + it 'raises a helpful error when the metadata is incomplete' do + expect { described_class.new(transport, id: 3).download }.to raise_error(KeyError) + end + + it 'escapes a traversal in an id instead of reaching another endpoint' do + stub = stub_request(:get, "#{ClientHelper::BASE_URL}api/v1/ticket_attachment/1%2F..%2F..%2F..%2Fapi%2Fv1%2Fusers/9/3") + .to_return(status: 200, body: 'contents') + escaping = described_class.new(transport, id: 3, ticket_id: '1/../../../api/v1/users', article_id: 9) + + escaping.download + + expect(stub).to have_been_requested + expect(a_request(:get, "#{ClientHelper::BASE_URL}api/v1/users/9/3")).not_to have_been_made + end + + it 'escapes the article id and the attachment id too' do + stub = stub_request(:get, "#{ClientHelper::BASE_URL}api/v1/ticket_attachment/42/9%2F..%2Fx/3%2F..%2Fy") + .to_return(status: 200, body: 'contents') + + described_class.new(transport, id: '3/../y', ticket_id: 42, article_id: '9/../x').download + + expect(stub).to have_been_requested + end + end + + it 'is read-only' do + attachment = described_class.new(transport, id: 3) + expect { attachment.filename = 'other.txt' }.to raise_error(NoMethodError, /read-only/) + end + + it 'does not claim a writer it would refuse' do + expect(described_class.new(transport, id: 3)).not_to respond_to(:filename=) + end + + describe '#inspect' do + it 'summarizes the attachment' do + attachment = described_class.new(transport, id: 3, filename: 'note.txt', size: '12') + expect(attachment.inspect) + .to eq('#') + end + end +end diff --git a/spec/unit/zammad_api/resources/ticket_spec.rb b/spec/unit/zammad_api/resources/ticket_spec.rb new file mode 100644 index 0000000..ea42c82 --- /dev/null +++ b/spec/unit/zammad_api/resources/ticket_spec.rb @@ -0,0 +1,216 @@ +# frozen_string_literal: true + +RSpec.describe ZammadAPI::Resources::Ticket do + subject(:ticket) { described_class.from_response(unit_transport, id: 42, title: 'Help') } + + let(:articles_url) { "#{ClientHelper::BASE_URL}api/v1/ticket_articles/by_ticket/42" } + let(:article_url) { "#{ClientHelper::BASE_URL}api/v1/ticket_articles" } + + describe '#articles' do + it 'requests the articles of this ticket' do + stub = stub_request(:get, articles_url).with(query: { 'expand' => 'true' }).to_return(json_response([])) + ticket.articles + expect(stub).to have_been_requested + end + + it 'returns article records' do + stub_request(:get, articles_url).with(query: hash_including({})) + .to_return(json_response([{ id: 1, body: 'first' }, { id: 2, body: 'second' }])) + + expect(ticket.articles.map(&:body)).to eq(%w[first second]) + end + + it 'returns persisted articles' do + stub_request(:get, articles_url).with(query: hash_including({})).to_return(json_response([{ id: 1 }])) + + expect(ticket.articles.first).to be_persisted + end + + it 'raises ParseError when the response is not a list' do + stub_request(:get, articles_url).with(query: hash_including({})).to_return(json_response({ id: 1 })) + + expect { ticket.articles }.to raise_error(ZammadAPI::ParseError, /expected a JSON array, got Hash/) + end + end + + describe 'once destroyed' do + let(:ticket_url) { "#{ClientHelper::BASE_URL}api/v1/tickets/42" } + + before do + stub_request(:delete, ticket_url).with(query: hash_including({})).to_return(json_response({})) + ticket.destroy + end + + # Each of these says what the caller gets, not which ivar was cleared. + # `destroy` dropped the `related` memo and was taken to have closed this, + # but the reader rebuilt one on the next call, so every path below went + # on reaching a ticket that is gone. + it 'refuses the articles reader rather than fetching a deleted ticket' do + expect { ticket.articles }.to raise_error(ZammadAPI::Error, /was destroyed/) + end + + it 'refuses the related proxy' do + expect { ticket.related }.to raise_error(ZammadAPI::Error, /was destroyed/) + end + + it 'refuses to add an article rather than POSTing a dead ticket_id' do + expect { ticket.add_article(body: 'hello') }.to raise_error(ZammadAPI::Error, /was destroyed/) + end + + it 'makes no request at all when an article is refused' do + stub = stub_request(:post, article_url).with(query: hash_including({})) + begin + ticket.add_article(body: 'hello') + rescue ZammadAPI::Error # rubocop:disable Lint/SuppressedException + end + + expect(stub).not_to have_been_requested + end + end + + describe '#add_article' do + it 'creates the article for this ticket' do + stub = stub_request(:post, article_url) + .with(query: { 'expand' => 'true' }, body: '{"body":"hello","ticket_id":42}') + .to_return(json_response({ id: 9, body: 'hello', ticket_id: 42 }, status: 201)) + + ticket.add_article(body: 'hello') + expect(stub).to have_been_requested + end + + it 'returns the created article' do + stub_request(:post, article_url).with(query: hash_including({})) + .to_return(json_response({ id: 9, body: 'hello' }, status: 201)) + + expect(ticket.add_article(body: 'hello')).to be_a(ZammadAPI::Resources::TicketArticle) + end + + it 'returns a persisted article' do + stub_request(:post, article_url).with(query: hash_including({})) + .to_return(json_response({ id: 9 }, status: 201)) + + expect(ticket.add_article(body: 'hello')).to be_persisted + end + + # The article goes to the ticket it was added to, whatever the attributes + # say. Given `ticket_id` under both spellings, the Symbol was replaced and + # the String, coming later in the Hash, replaced it again when the article + # symbolized its keys - so the POST named the caller's ticket. + context 'when the attributes name a ticket of their own' do + before do + stub_request(:post, article_url).with(query: hash_including({})) + .to_return(json_response({ id: 9, ticket_id: 42 }, status: 201)) + end + + def posted_ticket_ids + ids = [] + expect(a_request(:post, article_url).with(query: hash_including({})) { |request| ids << JSON.parse(request.body)['ticket_id'] }) + .to have_been_made.once + ids + end + + it 'uses its own id over a Symbol key' do + ticket.add_article(ticket_id: 9, body: 'hello') + expect(posted_ticket_ids).to eq([42]) + end + + it 'uses its own id over a String key' do + ticket.add_article('body' => 'hello', 'ticket_id' => 9) + expect(posted_ticket_ids).to eq([42]) + end + + it 'uses its own id over both spellings at once' do + ticket.add_article(:ticket_id => 1, 'ticket_id' => 9, :body => 'hello', :type => 'note') + expect(posted_ticket_ids).to eq([42]) + end + + it 'sends ticket_id once' do + ticket.add_article(:ticket_id => 1, 'ticket_id' => 9, :body => 'hello') + + expect(a_request(:post, article_url).with(query: hash_including({}), body: '{"body":"hello","ticket_id":42}')).to have_been_made + end + + it 'leaves the Hash it was given as it was' do + attributes = { :ticket_id => 1, 'ticket_id' => 9, :body => 'hello' } + ticket.add_article(attributes) + + expect(attributes).to eq(:ticket_id => 1, 'ticket_id' => 9, :body => 'hello') + end + end + + # An article belongs to a ticket by id. Unchecked, this POSTed + # `ticket_id: null` and left the caller reading Zammad's 422 to work out + # that the ticket had never been saved. + context 'when the ticket has not been saved' do + subject(:ticket) { described_class.new(unit_transport, title: 'Help') } + + it 'refuses locally' do + expect { ticket.add_article(body: 'hello') }.to raise_error(ZammadAPI::Error, /has no id, save it first/) + end + + it 'sends nothing' do + stub = stub_request(:post, article_url).with(query: hash_including({})) + + begin + ticket.add_article(body: 'hello') + rescue ZammadAPI::Error + nil + end + + expect(stub).not_to have_been_requested + end + end + end + + # The name the method had in 1.x: a noun that sends a POST, one letter away + # from the reader beside it. + describe '#article' do + around do |example| + enabled = Warning[:deprecated] + Warning[:deprecated] = true + example.run + ensure + Warning[:deprecated] = enabled + end + + before do + stub_request(:post, article_url).with(query: hash_including({})) + .to_return(json_response({ id: 9, body: 'hello', ticket_id: 42 }, status: 201)) + end + + it 'still adds the article' do + added = nil + + expect { added = ticket.article(body: 'hello') }.to output.to_stderr + expect(added.id).to eq(9) + end + + it 'warns, naming the replacement' do + expect { ticket.article(body: 'hello') } + .to output(/ZammadAPI::Resources::Ticket#article is deprecated and will be removed in 3\.0: use #add_article instead/).to_stderr + end + + it 'names the line that made the call' do + expect { ticket.article(body: 'hello') }.to output(/#{Regexp.escape(__FILE__)}:#{__LINE__}: warning: /).to_stderr + end + + it 'says nothing unless deprecation warnings are on' do + Warning[:deprecated] = false + expect { ticket.article(body: 'hello') }.not_to output.to_stderr + end + + it 'does not warn for add_article' do + expect { ticket.add_article(body: 'hello') }.not_to output.to_stderr + end + + # It reads like the attribute a ticket is created with, and with a + # default it sent a POST naming nothing but the ticket. 1.x required the + # attributes. + it 'requires the attributes, as 1.x did, and sends nothing without them' do + ticket.article = { body: 'reply' } + + expect { ticket.article }.to raise_error(ArgumentError, /wrong number of arguments/) + expect(a_request(:post, article_url).with(query: hash_including({}))).not_to have_been_made + end + end +end diff --git a/spec/unit/zammad_api/response_error_spec.rb b/spec/unit/zammad_api/response_error_spec.rb new file mode 100644 index 0000000..97ac85c --- /dev/null +++ b/spec/unit/zammad_api/response_error_spec.rb @@ -0,0 +1,197 @@ +# frozen_string_literal: true + +RSpec.describe ZammadAPI::ResponseError do + def response(status, body, headers = {}) + ZammadAPI::Response.new( + status: status, + headers: headers, + body: body, + raw_body: body.is_a?(String) ? body : JSON.generate(body), + json: !body.is_a?(String) + ) + end + + describe 'hierarchy' do + { + ZammadAPI::ConfigurationError => ZammadAPI::Error, + ZammadAPI::UnknownResourceError => ZammadAPI::Error, + ZammadAPI::ParseError => ZammadAPI::Error, + ZammadAPI::ConnectionError => ZammadAPI::TransportError, + ZammadAPI::TimeoutError => ZammadAPI::TransportError, + ZammadAPI::ClientError => described_class, + ZammadAPI::ServerError => described_class, + ZammadAPI::AuthenticationError => ZammadAPI::ClientError, + ZammadAPI::AuthorizationError => ZammadAPI::ClientError, + ZammadAPI::NotFoundError => ZammadAPI::ClientError, + ZammadAPI::ValidationError => ZammadAPI::ClientError, + ZammadAPI::RateLimitError => ZammadAPI::ClientError + }.each do |error_class, parent| + it "#{error_class} descends from #{parent}" do + expect(error_class.ancestors).to include(parent) + end + end + + it 'roots every error at ZammadAPI::Error' do + expect(ZammadAPI::TransportError.ancestors).to include(ZammadAPI::Error) + end + + it 'roots ZammadAPI::Error at StandardError' do + expect(ZammadAPI::Error.ancestors).to include(StandardError) + end + end + + describe '.build' do + { + 401 => ZammadAPI::AuthenticationError, + 403 => ZammadAPI::AuthorizationError, + 404 => ZammadAPI::NotFoundError, + 422 => ZammadAPI::ValidationError, + 429 => ZammadAPI::RateLimitError, + 400 => ZammadAPI::ClientError, + 408 => ZammadAPI::ClientError, + 418 => ZammadAPI::ClientError, + 500 => ZammadAPI::ServerError, + 502 => ZammadAPI::ServerError, + 503 => ZammadAPI::ServerError + }.each do |status, error_class| + it "maps #{status} to #{error_class}" do + result = described_class.build(response(status, {}), operation: 'find object') + expect(result).to be_an_instance_of(error_class) + end + end + + it 'falls back to the base class without a response' do + expect(described_class.build(nil, operation: 'find object')).to be_an_instance_of(described_class) + end + end + + describe '#message' do + it "uses the body's error key" do + error = described_class.build( + response(404, { error: 'User not found' }), + operation: 'find object', + resource_class: ZammadAPI::Resources::User + ) + expect(error.message).to eq("Can't find object (ZammadAPI::Resources::User): User not found") + end + + it 'prefers error_human, which Zammad intends for end users' do + error = described_class.build( + response(422, { error: 'Validation failed', error_human: 'Name is required' }), + operation: 'save object' + ) + expect(error.message).to eq("Can't save object: Name is required") + end + + it 'falls back to the status when the body is not JSON' do + error = described_class.build( + response(502, 'Bad Gateway'), + operation: 'find object', + resource_class: ZammadAPI::Resources::User + ) + expect(error.message).to eq("Can't find object (ZammadAPI::Resources::User): HTTP 502") + end + + it 'falls back to the status when the body has no error key' do + error = described_class.build(response(400, { foo: 'bar' }), operation: 'find object') + expect(error.message).to eq("Can't find object: HTTP 400") + end + + it 'falls back to the status when the error value is empty' do + error = described_class.build(response(500, { error: '' }), operation: 'find object') + expect(error.message).to eq("Can't find object: HTTP 500") + end + + it 'reports a missing response' do + expect(described_class.build(nil, operation: 'find object').message) + .to eq("Can't find object: no response") + end + + it 'omits the resource class when none was supplied' do + error = described_class.build(response(404, { error: 'nope' }), operation: 'find object') + expect(error.message).to eq("Can't find object: nope") + end + end + + describe 'accessors' do + subject(:error) do + described_class.build( + response(404, { error: 'nope' }, 'x-request-id' => 'abc'), + operation: 'find object', + resource_class: ZammadAPI::Resources::User + ) + end + + it 'exposes the status' do + expect(error.status).to eq(404) + end + + it 'exposes the decoded body' do + expect(error.body).to eq({ error: 'nope' }) + end + + it 'exposes the headers' do + expect(error.headers).to eq('x-request-id' => 'abc') + end + + it 'exposes the operation' do + expect(error.operation).to eq('find object') + end + + it 'exposes the resource class' do + expect(error.resource_class).to eq(ZammadAPI::Resources::User) + end + + it 'exposes the server message' do + expect(error.server_message).to eq('nope') + end + + it 'returns nil accessors without a response' do + bare = described_class.build(nil, operation: 'find object') + expect([bare.status, bare.body, bare.headers, bare.server_message]).to eq([nil, nil, {}, nil]) + end + + # A NotFoundError this gem raises itself - find_by! finding nothing - used + # to answer nil here, so `retry if e.status == 404` stopped retrying for + # the one NotFoundError that did not come from Zammad. + it 'reports the status its class is the name for, without a response' do + bare = ZammadAPI::NotFoundError.new(operation: 'find object by name', detail: 'no record matched') + expect(bare.status).to eq(404) + end + + it 'still has no body or headers to report without a response' do + bare = ZammadAPI::NotFoundError.new(operation: 'find object by name', detail: 'no record matched') + expect([bare.body, bare.headers]).to eq([nil, {}]) + end + + it 'leaves a generic ResponseError without a status' do + expect(described_class.new(operation: 'find object').status).to be_nil + end + end + + describe ZammadAPI::RateLimitError do + it 'exposes Retry-After as an integer' do + error = ZammadAPI::ResponseError.build( + ZammadAPI::Response.new(status: 429, headers: { 'retry-after' => '30' }, body: {}, raw_body: '{}', json: true), + operation: 'find object' + ) + expect(error.retry_after).to eq(30) + end + + it 'returns nil when the header is absent' do + error = ZammadAPI::ResponseError.build( + ZammadAPI::Response.new(status: 429, headers: {}, body: {}, raw_body: '{}', json: true), + operation: 'find object' + ) + expect(error.retry_after).to be_nil + end + + it 'returns nil when the header is not a number' do + error = ZammadAPI::ResponseError.build( + ZammadAPI::Response.new(status: 429, headers: { 'retry-after' => 'later' }, body: {}, raw_body: '{}', json: true), + operation: 'find object' + ) + expect(error.retry_after).to be_nil + end + end +end diff --git a/spec/unit/zammad_api/response_spec.rb b/spec/unit/zammad_api/response_spec.rb new file mode 100644 index 0000000..e7f7fd9 --- /dev/null +++ b/spec/unit/zammad_api/response_spec.rb @@ -0,0 +1,158 @@ +# frozen_string_literal: true + +RSpec.describe ZammadAPI::Response do + def build(status: 200, body: { a: 1 }, raw_body: '{"a":1}', headers: {}, json: !body.is_a?(String)) + described_class.new(status: status, headers: headers, body: body, raw_body: raw_body, json: json) + end + + describe '#success?' do + [200, 201, 204, 299].each do |status| + it "is true for #{status}" do + expect(build(status: status)).to be_success + end + end + + [199, 300, 400, 500].each do |status| + it "is false for #{status}" do + expect(build(status: status)).not_to be_success + end + end + end + + describe '#json?' do + it 'is true when the body was decoded' do + expect(build).to be_json + end + + it 'is false when the body is the untouched raw body' do + raw = '' + expect(build(body: raw, raw_body: raw)).not_to be_json + end + + it 'reports what the decoder recorded, not whether the two bodies differ' do + expect(build(body: '"a string"', raw_body: '"a string"', json: true)).to be_json + end + end + + describe '#decoded' do + it 'returns an object body when one is expected' do + expect(build(body: { a: 1 }).decoded(:object, operation: 'find object')).to eq(a: 1) + end + + it 'returns an array body when one is expected' do + expect(build(body: [{ a: 1 }]).decoded(:array, operation: 'get list')).to eq([{ a: 1 }]) + end + + it 'raises when an object was expected but a list arrived' do + expect { build(body: []).decoded(:object, operation: 'find object') } + .to raise_error(ZammadAPI::ParseError, "Can't find object: expected a JSON object, got Array") + end + + it 'raises when a list was expected but an object arrived' do + expect { build(body: {}).decoded(:array, operation: 'get list') } + .to raise_error(ZammadAPI::ParseError, "Can't get list: expected a JSON array, got Hash") + end + + it 'raises when the body was never JSON' do + expect { build(body: '', raw_body: '').decoded(:object, operation: 'find object') } + .to raise_error(ZammadAPI::ParseError, /got String/) + end + + it 'names the resource class in the message' do + expect { build(body: []).decoded(:object, operation: 'find object', resource_class: ZammadAPI::Resources::User) } + .to raise_error(/\(ZammadAPI::Resources::User\)/) + end + + it 'accepts an empty list' do + expect(build(body: []).decoded(:array, operation: 'get list')).to eq([]) + end + + # An unexpanded search answers with ids. Passing them on stored an Integer + # as a record's attributes, and the first reader died with a TypeError + # from deep inside the gem. + it 'raises for a list of scalars rather than building records from them' do + expect { build(body: [1, 2, 3]).decoded(:array, operation: 'get list') } + .to raise_error(ZammadAPI::ParseError, "Can't get list: expected a JSON array of objects, got an array holding Integer") + end + + it 'raises for a list that is only partly objects' do + expect { build(body: [{ id: 1 }, 'nope']).decoded(:array, operation: 'get list') } + .to raise_error(ZammadAPI::ParseError, /an array holding String/) + end + + # `find` cannot tell "no offender" from "the offender is nil", so a null + # passed as an object and the first read of it died with NoMethodError. + it 'raises for a list holding a null' do + expect { build(body: [nil]).decoded(:array, operation: 'get list') } + .to raise_error(ZammadAPI::ParseError, "Can't get list: expected a JSON array of objects, got an array holding NilClass") + end + + it 'raises for a null among the objects of a list' do + expect { build(body: [{ id: 1 }, nil, { id: 3 }]).decoded(:array, operation: 'get list') } + .to raise_error(ZammadAPI::ParseError, /an array holding NilClass/) + end + + it 'names the resource class when a list element has the wrong shape' do + expect { build(body: [1]).decoded(:array, operation: 'get list', resource_class: ZammadAPI::Resources::User) } + .to raise_error(/\(ZammadAPI::Resources::User\)/) + end + end + + # A list is an array, and a search asked for its total answers with an + # object holding the array and the figure. A walk reads either. + describe '#decoded_list' do + it 'returns an array body, and no total' do + expect(build(body: [{ a: 1 }]).decoded_list(operation: 'get list')).to eq([[{ a: 1 }], nil]) + end + + it 'returns the records and the total of a counted list' do + expect(build(body: { records: [{ a: 1 }], total_count: 7 }).decoded_list(operation: 'get list')).to eq([[{ a: 1 }], 7]) + end + + it 'accepts a counted list with no records' do + expect(build(body: { records: [], total_count: 0 }).decoded_list(operation: 'get list')).to eq([[], 0]) + end + + it 'reports a negative total as none, and keeps the records' do + expect(build(body: { records: [{ a: 1 }], total_count: -1 }).decoded_list(operation: 'get list')).to eq([[{ a: 1 }], nil]) + end + + it 'reports a total that is not a number as none' do + expect(build(body: { records: [], total_count: '7' }).decoded_list(operation: 'get list')).to eq([[], nil]) + end + + it 'raises for records that are not objects' do + expect { build(body: { records: [1, 2], total_count: 2 }).decoded_list(operation: 'get list') } + .to raise_error(ZammadAPI::ParseError, "Can't get list: expected a JSON array of objects, got an array holding Integer") + end + + it 'raises for a null among the records of a counted list' do + expect { build(body: { records: [nil, { a: 1 }], total_count: 2 }).decoded_list(operation: 'get list') } + .to raise_error(ZammadAPI::ParseError, "Can't get list: expected a JSON array of objects, got an array holding NilClass") + end + + it 'raises for an object that holds no records' do + expect { build(body: { total_count: 2 }).decoded_list(operation: 'get list') } + .to raise_error(ZammadAPI::ParseError, "Can't get list: expected a JSON array, got Hash") + end + + it 'raises for records that are not a list' do + expect { build(body: { records: 'none', total_count: 0 }).decoded_list(operation: 'get list') } + .to raise_error(ZammadAPI::ParseError, /expected a JSON array, got Hash/) + end + + it 'raises when the body was never JSON' do + expect { build(body: '', raw_body: '').decoded_list(operation: 'get list') } + .to raise_error(ZammadAPI::ParseError, /got String/) + end + + it 'names the resource class in the message' do + expect { build(body: {}).decoded_list(operation: 'get list', resource_class: ZammadAPI::Resources::User) } + .to raise_error(/\(ZammadAPI::Resources::User\)/) + end + end + + it 'is immutable' do + expect(build).to be_frozen + end +end diff --git a/spec/unit/zammad_api/transport_spec.rb b/spec/unit/zammad_api/transport_spec.rb new file mode 100644 index 0000000..142f00d --- /dev/null +++ b/spec/unit/zammad_api/transport_spec.rb @@ -0,0 +1,1614 @@ +# frozen_string_literal: true + +require 'pp' + +RSpec.describe ZammadAPI::Transport do + let(:url) { "#{ClientHelper::BASE_URL}api/v1/groups" } + + describe 'authentication' do + it 'sends a Token header for an access token' do + stub = stub_request(:get, url).with(headers: { 'Authorization' => 'Token test-token' }).to_return(json_response([])) + unit_transport.get('api/v1/groups', operation: 'test') + expect(stub).to have_been_requested + end + + it 'sends a Bearer header for an OAuth2 token' do + stub = stub_request(:get, url).with(headers: { 'Authorization' => 'Bearer oauth' }).to_return(json_response([])) + unit_transport(http_token: nil, oauth2_token: 'oauth').get('api/v1/groups', operation: 'test') + expect(stub).to have_been_requested + end + + it 'sends basic auth for user and password' do + stub = stub_request(:get, url).with(basic_auth: %w[u p]).to_return(json_response([])) + unit_transport(http_token: nil, user: 'u', password: 'p').get('api/v1/groups', operation: 'test') + expect(stub).to have_been_requested + end + end + + describe 'default headers' do + it 'identifies the client' do + stub = stub_request(:get, url) + .with(headers: { 'User-Agent' => "zammad_api-ruby/#{ZammadAPI::VERSION}" }) + .to_return(json_response([])) + unit_transport.get('api/v1/groups', operation: 'test') + expect(stub).to have_been_requested + end + + it 'asks for JSON' do + stub = stub_request(:get, url).with(headers: { 'Accept' => 'application/json' }).to_return(json_response([])) + unit_transport.get('api/v1/groups', operation: 'test') + expect(stub).to have_been_requested + end + + it 'allows overriding the user agent' do + stub = stub_request(:get, url).with(headers: { 'User-Agent' => 'my-app/1.0' }).to_return(json_response([])) + unit_transport(user_agent: 'my-app/1.0').get('api/v1/groups', operation: 'test') + expect(stub).to have_been_requested + end + + # Net::HTTP refused it at the request, quoting the value. + it 'refuses a raw request header with a line break inside it, without quoting it' do + expect { described_class.stringify_headers('X-Api-Key' => "abc\r\nsecret") } + .to raise_error(ArgumentError, /\Aheader x-api-key holds a line break, which a header cannot carry/) { |error| + expect(error.message).not_to include('secret') + } + end + + it 'takes one that only ends in a line break, which Net::HTTP strips' do + expect(described_class.stringify_headers('X-Note' => "abc\n")).to eq('x-note' => "abc\n") + end + + it 'carries a header value given in UTF-16 as the same text in UTF-8' do + expect(described_class.stringify_headers('X-Note' => 'ä'.encode('UTF-16LE'))).to eq('x-note' => 'ä') + end + end + + describe 'base url handling' do + it 'keeps a sub-path prefix in front of the request path' do + stub = stub_request(:get, 'http://zammad.test/helpdesk/api/v1/groups').to_return(json_response([])) + unit_transport(url: 'http://zammad.test/helpdesk').get('api/v1/groups', operation: 'test') + expect(stub).to have_been_requested + end + end + + describe 'query parameters' do + it 'encodes scalars as strings' do + stub = stub_request(:get, url).with(query: { 'page' => '1', 'expand' => 'true' }).to_return(json_response([])) + unit_transport.get('api/v1/groups', operation: 'test', query: { page: 1, expand: true }) + expect(stub).to have_been_requested + end + + it 'escapes values that need it' do + stub = stub_request(:get, "#{url}/search").with(query: { 'query' => 'a b&c' }).to_return(json_response([])) + unit_transport.get('api/v1/groups/search', operation: 'test', query: { query: 'a b&c' }) + expect(stub).to have_been_requested + end + + it 'encodes arrays' do + stub = stub_request(:get, url).with(query: { 'ids' => %w[1 2] }).to_return(json_response([])) + unit_transport.get('api/v1/groups', operation: 'test', query: { ids: [1, 2] }) + expect(stub).to have_been_requested + end + + # `condition` is what Zammad's search endpoints narrow by, and it is + # nested. Rendered with to_s it went out as a Ruby inspect string, which + # Zammad dropped, answering an unnarrowed search. + it 'encodes a nested hash the way Rails reads it back' do + stub = stub_request(:get, "#{url}/search") + .with(query: { 'condition' => { 'ticket.state_id' => { 'operator' => 'is', 'value' => %w[1 2] } } }) + .to_return(json_response([])) + unit_transport.get( + 'api/v1/groups/search', + operation: 'test', + query: { condition: { 'ticket.state_id' => { operator: 'is', value: [1, 2] } } } + ) + expect(stub).to have_been_requested + end + + it 'stringifies the scalars inside a nested hash' do + expect(described_class.stringify_query(condition: { open: { active: true, limit: 5 } })) + .to eq({ 'condition' => { 'open' => { 'active' => 'true', 'limit' => '5' } } }) + end + + # Faraday's escaping raised Encoding::CompatibilityError for one. + it 'sends a value given in UTF-16 as the same text in UTF-8' do + stub = stub_request(:get, "#{url}/search").with(query: { 'query' => 'ä b' }).to_return(json_response([])) + unit_transport.get('api/v1/groups/search', operation: 'test', query: { query: 'ä b'.encode('UTF-16LE') }) + expect(stub).to have_been_requested + end + + it 'leaves a value in an encoding ASCII is a part of as it was' do + value = "caf\xC3\xA9".b + + expect(described_class.stringify_query(q: value)['q']).to be(value) + end + + it 'refuses a value that cannot be converted to UTF-8, without quoting it' do + broken = "\xD8\x00".dup.force_encoding('UTF-16BE') + + expect { described_class.stringify_query(token: broken) } + .to raise_error(ArgumentError, /\Aquery parameter token was given as UTF-16BE text that cannot be converted to UTF-8/) + end + + it 'raises on a nil value rather than dropping the parameter' do + expect { unit_transport.get('api/v1/groups', operation: 'test', query: { page: 1, note: nil }) } + .to raise_error(ArgumentError, /query parameter note is nil/) + end + + it 'names the path to a nil buried in a nested value' do + expect { described_class.stringify_query(condition: { state: { value: nil } }) } + .to raise_error(ArgumentError, /parameter condition\[state\]\[value\] is nil/) + end + + it 'refuses two spellings of one parameter rather than sending whichever came last' do + expect { described_class.stringify_query(state_id: 1, 'state_id' => 2) } + .to raise_error(ArgumentError, /parameter state_id was given twice/) + end + + it 'refuses the collision whichever order it arrives in' do + expect { described_class.stringify_query('state_id' => 2, state_id: 1) } + .to raise_error(ArgumentError, /parameter state_id was given twice/) + end + + it 'names both spellings, so the caller does not have to guess the other' do + expect { described_class.stringify_query(state_id: 1, 'state_id' => 2) } + .to raise_error(ArgumentError, /as :state_id and as "state_id"/) + end + + # `condition` is a Hash the search endpoints read, and two spellings inside + # it collapsed exactly the way two at the top level did. + it 'refuses a collision nested inside a structured parameter' do + expect { described_class.stringify_query(condition: { 'state_id' => 1, state_id: 2 }) } + .to raise_error(ArgumentError, /parameter condition\[state_id\] was given twice/) + end + + it 'still sends a structured parameter whose keys only look alike' do + expect(described_class.stringify_query(condition: { 'ticket.state_id' => { operator: 'is' } })) + .to eq({ 'condition' => { 'ticket.state_id' => { 'operator' => 'is' } } }) + end + + it 'still accepts two parameters that only look alike' do + expect(described_class.stringify_query(state_id: 1, state_ids: [2])) + .to eq({ 'state_id' => '1', 'state_ids' => ['2'] }) + end + + it 'names the index of a nil inside an array' do + expect { described_class.stringify_query(ids: [1, nil]) } + .to raise_error(ArgumentError, /query parameter ids\[1\] is nil/) + end + + it 'makes no request for a query it rejects' do + stub = stub_request(:get, url).with(query: hash_including({})).to_return(json_response([])) + + expect { unit_transport.get('api/v1/groups', operation: 'test', query: { note: nil }) } + .to raise_error(ArgumentError) + expect(stub).not_to have_been_requested + end + + # A query string does not mark where an element of a list ends. Rails + # begins a new one where a pair names a place the element it is filling + # has taken already, so a list is refused where it would not be read + # back as the list it was: the request would carry something the caller + # did not write, to an endpoint that narrows by it. + describe 'a list a query string cannot carry' do + it 'refuses a Hash that shares no key with the one before it, which Rails would read into it' do + expect { described_class.stringify_query(condition: { conditions: [{ a: 1 }, { b: 2 }] }) } + .to raise_error(ArgumentError, /query parameter condition\[conditions\]\[1\] has no plain value under a key the element before it has as well/) + end + + it 'refuses one that shares a key holding only a list' do + expect { described_class.stringify_query(list: [{ value: [1] }, { value: [2] }]) } + .to raise_error(ArgumentError, /Rails would read the two as one/) + end + + it 'refuses a Hash with nothing in it, which is not written at all' do + expect { described_class.stringify_query(list: [{ a: 1 }, {}]) } + .to raise_error(ArgumentError, /query parameter list\[1\] is a Hash with no value in it.*one element short/) + end + + it 'refuses a list directly inside a list' do + expect { described_class.stringify_query(list: [[1, 2], [3]]) } + .to raise_error(ArgumentError, /query parameter list\[0\] is a list directly inside a list/) + end + + it 'says where such a structure can be sent as it is' do + expect { described_class.stringify_query(list: [{ a: 1 }, { b: 2 }]) } + .to raise_error(ArgumentError, /put it in the JSON body of a raw request, such as client\.post/) + end + + it 'takes a group of conditions beside a condition, which share an operator' do + conditions = [{ name: 'ticket.state_id', operator: 'is', value: [2] }, { operator: 'AND', conditions: [{ name: 'a', operator: 'is', value: 1 }] }] + + expect(described_class.stringify_query(condition: { operator: 'OR', conditions: conditions }).dig('condition', 'conditions', 1, 'operator')).to eq('AND') + end + + it 'takes Hashes among plain values, each of which begins an element of its own' do + expect(described_class.stringify_query(list: [{ a: 1 }, 2, { b: 3 }])).to eq('list' => [{ 'a' => '1' }, '2', { 'b' => '3' }]) + end + + it 'makes no request for one' do + stub = stub_request(:get, url).with(query: hash_including({})).to_return(json_response([])) + + expect { unit_transport.get('api/v1/groups', operation: 'test', query: { list: [{ a: 1 }, { b: 2 }] }) }.to raise_error(ArgumentError) + expect(stub).not_to have_been_requested + end + end + + # A query string has no way to write a key with an empty name: `[]` + # inside a structure, which Rails reads as a list, and nothing but the + # value at the top level, which Rails drops. + describe 'a key with an empty name' do + it 'refuses one in a Hash inside a list, which Rails would read as a list' do + expect { described_class.stringify_query(list: [{ '' => '1' }]) } + .to raise_error(ArgumentError, /query parameter list\[0\] holds a key with an empty name.*list\[0\]\[\], which Rails reads as a list/) + end + + it 'refuses one in a Hash further down' do + expect { described_class.stringify_query(condition: { a: { '' => '1' } }) } + .to raise_error(ArgumentError, /query parameter condition\[a\] holds a key with an empty name/) + end + + it 'refuses one given as an empty Symbol' do + expect { described_class.stringify_query(condition: { '': '1' }) }.to raise_error(ArgumentError, /holds a key with an empty name/) + end + + it 'refuses one at the top level, which Rails drops' do + expect { described_class.stringify_query('' => '1') }.to raise_error(ArgumentError, /a query parameter has an empty name.*which Rails drops/) + end + + it 'still takes a Hash in a list with an ordinary key' do + expect(described_class.stringify_query(list: [{ 'a' => '1' }])).to eq('list' => [{ 'a' => '1' }]) + end + + it 'still takes a key that is a space' do + expect(described_class.stringify_query(condition: { ' ' => '1' })).to eq('condition' => { ' ' => '1' }) + end + end + + # Read off the URL Faraday built, in the order it was written: WebMock + # sorts a query before it compares one, and the order is the point. See + # the QueryEncoder specs for why this is the order Rails needs. + it 'writes the query with the encoder that keeps a list of Hashes apart' do + sent = nil + recorder = Class.new(Faraday::Middleware) do + define_method(:on_request) { |env| sent = URI.decode_www_form(env.url.query).map(&:first) } + end + stub_request(:get, "#{url}/search").with(query: hash_including({})).to_return(json_response([])) + + unit_transport(middleware: ->(builder) { builder.use(recorder) }).get( + 'api/v1/groups/search', + operation: 'test', + query: { condition: { conditions: [{ name: 'a', operator: 'is', value: 1 }, { operator: 'AND', conditions: [{ name: 'b', operator: 'is', value: 2 }] }] } } + ) + + expect(sent.drop(3).first(2)).to eq(['condition[conditions][][operator]', 'condition[conditions][][conditions][][name]']) + end + end + + # The path is printed in the log, in the message of a timeout and in the + # operation a raw request is named by, and a raw request may carry its + # query in it. + describe '.redact_path' do + it 'leaves a path without a query as it is' do + expect(described_class.redact_path('api/v1/tickets/1')).to eq('api/v1/tickets/1') + end + + it 'blanks the value of a parameter named like a credential' do + expect(described_class.redact_path('api/v1/x?token=s3cret')).to eq('api/v1/x?token=[REDACTED]') + end + + it 'keeps every other parameter as it was written' do + expect(described_class.redact_path('api/v1/x?page=2&password=s3cret&q=a%20b')).to eq('api/v1/x?page=2&password=[REDACTED]&q=a%20b') + end + + it 'reads a name that was percent-encoded' do + expect(described_class.redact_path('api/v1/x?user%5Bpassword%5D=s3cret')).to eq('api/v1/x?user%5Bpassword%5D=[REDACTED]') + end + + it 'blanks a value whose name cannot be read' do + expect(described_class.redact_path('api/v1/x?%zz=s3cret')).to eq('api/v1/x?%zz=[REDACTED]') + end + + it 'keeps a parameter with no value' do + expect(described_class.redact_path('api/v1/x?expand&token=s3cret')).to eq('api/v1/x?expand&token=[REDACTED]') + end + + it 'blanks a value that holds a = of its own' do + expect(described_class.redact_path('api/v1/x?token=a=b')).to eq('api/v1/x?token=[REDACTED]') + end + end + + describe '.escape_path_segment' do + it 'leaves an ordinary id alone' do + expect(described_class.escape_path_segment(42)).to eq('42') + end + + it 'encodes a separator, so an id cannot walk out of its segment' do + expect(described_class.escape_path_segment('1/../../api/v1/users/1')) + .to eq('1%2F..%2F..%2Fapi%2Fv1%2Fusers%2F1') + end + + it 'encodes a query and fragment marker' do + expect(described_class.escape_path_segment('1?a=b#c')).to eq('1%3Fa%3Db%23c') + end + + it 'encodes a multibyte character one byte at a time' do + expect(described_class.escape_path_segment('ä')).to eq('%C3%A4') + end + + it 'raises for an id with nothing to send' do + expect { described_class.escape_path_segment('') }.to raise_error(ArgumentError, /record id is required/) + end + + it 'raises for a parent dot segment, which the unreserved set would carry through' do + expect { described_class.escape_path_segment('..') }.to raise_error(ArgumentError, /points at another endpoint/) + end + + it 'raises for a current-directory dot segment' do + expect { described_class.escape_path_segment('.') }.to raise_error(ArgumentError, /points at another endpoint/) + end + + it 'leaves an id that merely starts with dots alone' do + expect(described_class.escape_path_segment('..1')).to eq('..1') + end + + it 'encodes an already-encoded dot segment rather than passing it on' do + expect(described_class.escape_path_segment('%2e%2e')).to eq('%252e%252e') + end + end + + describe 'request bodies' do + it 'sends JSON with the matching content type' do + stub = stub_request(:post, url) + .with(body: '{"name":"Support"}', headers: { 'Content-Type' => 'application/json' }) + .to_return(json_response({ id: 1 }, status: 201)) + unit_transport.post('api/v1/groups', operation: 'test', body: { name: 'Support' }) + expect(stub).to have_been_requested + end + + it 'sends a body that is already a string as it is' do + stub = stub_request(:post, url) + .with(body: '{"name":"Raw"}', headers: { 'Content-Type' => 'application/json' }) + .to_return(json_response({ id: 1 }, status: 201)) + unit_transport.post('api/v1/groups', operation: 'test', body: '{"name":"Raw"}') + expect(stub).to have_been_requested + end + + # Faraday's JSON middleware raised JSON::GeneratorError from inside the + # stack and nothing mapped it, so it went past the rescue of + # ZammadAPI::Error every caller is told to write. + context 'with a body that cannot be encoded as JSON' do + let(:binary) { { data: "\xFF\xD8\xFF".b } } + + it 'raises a ZammadAPI::Error for bytes that are not text' do + expect { unit_transport.post('api/v1/groups', operation: 'save object', body: binary) } + .to raise_error(ZammadAPI::Error, /Can't save object: the request body cannot be encoded as JSON/) + end + + it 'raises a ZammadAPI::Error for a Float that JSON has no spelling for' do + expect { unit_transport.put('api/v1/groups/1', operation: 'save object', body: { weight: Float::NAN }) } + .to raise_error(ZammadAPI::Error, /NaN not allowed in JSON/) + end + + it 'says what to do about binary data' do + expect { unit_transport.post('api/v1/groups', operation: 'save object', body: binary) } + .to raise_error(ZammadAPI::Error, /Base64-encode binary data/) + end + + it 'names the resource it was sending' do + expect { unit_transport.post('api/v1/groups', operation: 'save object', body: binary, resource_class: ZammadAPI::Resources::Group) } + .to raise_error(ZammadAPI::Error, /save object \(ZammadAPI::Resources::Group\)/) + end + + it 'makes no request' do + expect { unit_transport.post('api/v1/groups', operation: 'save object', body: binary) }.to raise_error(ZammadAPI::Error) + expect(a_request(:any, /zammad\.test/)).not_to have_been_made + end + + it 'leaves no log line claiming a request that was never made' do + log = StringIO.new + expect { unit_transport(logger: Logger.new(log)).post('api/v1/groups', operation: 'save object', body: binary) } + .to raise_error(ZammadAPI::Error) + expect(log.string).to be_empty + end + + it 'is raised by a record save carrying such a value' do + group = unit_client.groups.new(name: 'Support', weight: Float::INFINITY) + expect { group.save }.to raise_error(ZammadAPI::Error, /Infinity not allowed in JSON/) + end + end + end + + describe 'response decoding' do + it 'decodes JSON with symbol keys' do + stub_request(:get, url).to_return(json_response({ id: 1, nested: { a: 'b' } })) + response = unit_transport.get('api/v1/groups', operation: 'test') + expect(response.body).to eq({ id: 1, nested: { a: 'b' } }) + end + + it 'exposes the raw body as well' do + stub_request(:get, url).to_return(json_response({ id: 1 })) + response = unit_transport.get('api/v1/groups', operation: 'test') + expect(response.raw_body).to eq('{"id":1}') + end + + it 'leaves non-JSON bodies untouched' do + stub_request(:get, url).to_return(status: 200, body: 'plain text', headers: { 'Content-Type' => 'text/plain' }) + response = unit_transport.get('api/v1/groups', operation: 'test') + expect(response.body).to eq('plain text') + end + + it 'keeps a malformed JSON body as a string instead of raising' do + stub_request(:get, url).to_return(status: 200, body: 'not json', headers: { 'Content-Type' => 'application/json' }) + response = unit_transport.get('api/v1/groups', operation: 'test') + expect(response.body).to eq('not json') + end + + it 'handles an empty body' do + stub_request(:get, url).to_return(status: 200, body: '', headers: { 'Content-Type' => 'application/json' }) + response = unit_transport.get('api/v1/groups', operation: 'test') + expect(response.body).to eq('') + end + + it 'downcases header names' do + stub_request(:get, url).to_return(json_response([], headers: { 'X-Request-Id' => 'abc' })) + response = unit_transport.get('api/v1/groups', operation: 'test') + expect(response.headers['x-request-id']).to eq('abc') + end + end + + describe 'error responses' do + it 'raises NotFoundError for 404' do + stub_request(:get, url).to_return(json_response({ error: 'nope' }, status: 404)) + expect { unit_transport.get('api/v1/groups', operation: 'find object') } + .to raise_error(ZammadAPI::NotFoundError, "Can't find object: nope") + end + + it 'raises AuthenticationError for 401' do + stub_request(:get, url).to_return(json_response({ error: 'authentication failed' }, status: 401)) + expect { unit_transport.get('api/v1/groups', operation: 'find object') } + .to raise_error(ZammadAPI::AuthenticationError) + end + + it 'raises ServerError with the status when a proxy returns HTML' do + stub_request(:get, url).to_return(status: 502, body: 'Bad Gateway', headers: { 'Content-Type' => 'text/html' }) + expect { unit_transport.get('api/v1/groups', operation: 'find object') } + .to raise_error(ZammadAPI::ServerError, "Can't find object: HTTP 502") + end + + it 'includes the resource class in the message' do + stub_request(:get, url).to_return(json_response({ error: 'nope' }, status: 404)) + expect { unit_transport.get('api/v1/groups', operation: 'find object', resource_class: ZammadAPI::Resources::Group) } + .to raise_error(/\(ZammadAPI::Resources::Group\)/) + end + end + + describe 'network failures' do + it 'wraps a read timeout' do + stub_request(:get, url).to_raise(Net::ReadTimeout) + expect { unit_transport.get('api/v1/groups', operation: 'find object') } + .to raise_error(ZammadAPI::TimeoutError, %r{Can't find object: request to api/v1/groups timed out}) + end + + it 'keeps a credential in a query written into the path out of the message' do + stub_request(:get, url).with(query: hash_including({})).to_raise(Net::ReadTimeout) + expect { unit_transport.get('api/v1/groups?token=path-s3cret', operation: 'find object') } + .to raise_error(ZammadAPI::TimeoutError, %r{request to api/v1/groups\?token=\[REDACTED\] timed out}) + end + + # Net::HTTP raises Net::OpenTimeout for it, and the default adapter wraps + # that into Faraday::ConnectionFailed with every other failure to connect, + # so it was reported as an unreachable host and skipped the rescue that is + # documented to catch it. + context 'when the connection is not established within open_timeout' do + before { stub_request(:get, url).to_raise(Net::OpenTimeout.new('execution expired')) } + + it 'raises TimeoutError, not ConnectionError' do + expect { unit_transport.get('api/v1/groups', operation: 'find object') } + .to raise_error(ZammadAPI::TimeoutError) + end + + it 'says it was the connection that timed out' do + expect { unit_transport.get('api/v1/groups', operation: 'find object') } + .to raise_error(%r{Can't find object: connecting to http://zammad\.test/ timed out \(execution expired\)}) + end + + it 'is still retried, as a read that never reached the server' do + expect { unit_transport(retries: 2, retry_interval: 0.01).get('api/v1/groups', operation: 'find object') } + .to raise_error(ZammadAPI::TimeoutError) + expect(a_request(:get, url)).to have_been_made.times(3) + end + end + + it 'reports the timeout WebMock simulates as one' do + stub_request(:get, url).to_timeout + expect { unit_transport.get('api/v1/groups', operation: 'find object') } + .to raise_error(ZammadAPI::TimeoutError) + end + + it 'reads a timeout out of a connection failure that only wraps one' do + stub_request(:get, url).to_raise(Faraday::ConnectionFailed.new(Errno::ETIMEDOUT.new)) + expect { unit_transport.get('api/v1/groups', operation: 'find object') } + .to raise_error(ZammadAPI::TimeoutError, /connecting to/) + end + + it 'wraps a refused connection' do + stub_request(:get, url).to_raise(Errno::ECONNREFUSED) + expect { unit_transport.get('api/v1/groups', operation: 'find object') } + .to raise_error(ZammadAPI::ConnectionError, /is unreachable/) + end + + it 'wraps a TLS failure' do + stub_request(:get, url).to_raise(OpenSSL::SSL::SSLError) + expect { unit_transport.get('api/v1/groups', operation: 'find object') } + .to raise_error(ZammadAPI::ConnectionError, /TLS handshake/) + end + + it 'names the instance it could not reach' do + stub_request(:get, url).to_raise(Faraday::ConnectionFailed.new('down')) + + expect { unit_transport.get('api/v1/groups', operation: 'test') } + .to raise_error(ZammadAPI::ConnectionError, %r{http://zammad\.test/ is unreachable}) + end + + context 'with an adapter that does not wrap socket errors' do + # The middleware seam raises from inside the stack, past the point where + # an adapter would normally translate the error into a Faraday one. + def raising(error) + unit_transport(middleware: lambda { |faraday| + faraday.use(Class.new(Faraday::Middleware) { define_method(:call) { |_env| raise error } }) + }) + end + + it 'wraps a bare Errno::ETIMEDOUT' do + expect { raising(Errno::ETIMEDOUT).get('api/v1/groups', operation: 'find object') } + .to raise_error(ZammadAPI::TimeoutError, /timed out/) + end + + it 'wraps a bare Timeout::Error' do + expect { raising(Timeout::Error).get('api/v1/groups', operation: 'find object') } + .to raise_error(ZammadAPI::TimeoutError) + end + + it 'wraps a bare Errno::ECONNREFUSED' do + expect { raising(Errno::ECONNREFUSED).get('api/v1/groups', operation: 'find object') } + .to raise_error(ZammadAPI::ConnectionError, /is unreachable/) + end + + it 'wraps a SocketError' do + expect { raising(SocketError).get('api/v1/groups', operation: 'find object') } + .to raise_error(ZammadAPI::ConnectionError) + end + + it 'leaves an unrelated Errno alone rather than calling it a network problem' do + expect { raising(Errno::ENOSPC).get('api/v1/groups', operation: 'find object') } + .to raise_error(Errno::ENOSPC) + end + end + + it 'raises a TransportError subclass so both can be rescued together' do + stub_request(:get, url).to_raise(Errno::ECONNREFUSED) + expect { unit_transport.get('api/v1/groups', operation: 'find object') } + .to raise_error(ZammadAPI::TransportError) + end + end + + describe 'retries' do + it 'retries an idempotent request after a server error' do + stub_request(:get, url).to_return({ status: 500 }, json_response([{ id: 1 }])) + response = unit_transport(retries: 2, retry_interval: 0.01).get('api/v1/groups', operation: 'test') + expect(response.status).to eq(200) + end + + it 'retries after a rate limit response' do + stub_request(:get, url).to_return({ status: 429 }, json_response([])) + response = unit_transport(retries: 1, retry_interval: 0.01).get('api/v1/groups', operation: 'test') + expect(response.status).to eq(200) + end + + # The retry middleware sleeps for whatever Retry-After says, and its own + # ceiling defaults to none: this held the calling thread for an hour per + # retry before raising the error it could have raised at once. + context 'when the server asks for a longer wait than the timeout' do + let(:transport) { unit_transport(retries: 2, retry_interval: 0.01, timeout: 2) } + + before do + stub_request(:get, url).to_return({ status: 429, headers: { 'Retry-After' => '3600' } }, json_response([])) + end + + it 'reports the response instead of waiting it out' do + expect { transport.get('api/v1/groups', operation: 'test') }.to raise_error(ZammadAPI::RateLimitError) + end + + it 'does not retry' do + expect { transport.get('api/v1/groups', operation: 'test') }.to raise_error(ZammadAPI::RateLimitError) + expect(a_request(:get, url)).to have_been_made.once + end + + it 'leaves the wait the server asked for readable from the error' do + expect { transport.get('api/v1/groups', operation: 'test') } + .to raise_error(ZammadAPI::RateLimitError) { |error| expect(error.retry_after).to eq(3600) } + end + end + + it 'does not wait out a long Retry-After on a 503 either' do + stub_request(:get, url).to_return({ status: 503, headers: { 'Retry-After' => '3600' } }, json_response([])) + + expect { unit_transport(retries: 2, retry_interval: 0.01, timeout: 2).get('api/v1/groups', operation: 'test') } + .to raise_error(ZammadAPI::ServerError) + expect(a_request(:get, url)).to have_been_made.once + end + + it 'still waits as long as the server asks, where that is within the timeout' do + stub_request(:get, url).to_return({ status: 429, headers: { 'Retry-After' => '0.2' } }, json_response([])) + + started = Process.clock_gettime(Process::CLOCK_MONOTONIC) + response = unit_transport(retries: 1, retry_interval: 0.01).get('api/v1/groups', operation: 'test') + + expect(response.status).to eq(200) + expect(Process.clock_gettime(Process::CLOCK_MONOTONIC) - started).to be >= 0.2 + end + + it 'gives up after the configured number of attempts' do + stub_request(:get, url).to_return(status: 500) + expect { unit_transport(retries: 1, retry_interval: 0.01).get('api/v1/groups', operation: 'test') } + .to raise_error(ZammadAPI::ServerError) + expect(a_request(:get, url)).to have_been_made.twice + end + + it 'does not retry POST, which could duplicate records' do + stub_request(:post, url).to_return(status: 500) + expect { unit_transport(retries: 2, retry_interval: 0.01).post('api/v1/groups', operation: 'test', body: { a: 1 }) } + .to raise_error(ZammadAPI::ServerError) + expect(a_request(:post, url)).to have_been_made.once + end + + # A ticket update carrying an article creates that article on every + # delivery, so repeating it sent the article - and its e-mail - twice. + it 'does not retry PUT, which Zammad does not always handle idempotently' do + stub_request(:put, "#{url}/1").to_return({ status: 504 }, json_response({ id: 1 })) + expect { unit_transport(retries: 2, retry_interval: 0.01).put('api/v1/groups/1', operation: 'test', body: { a: 1 }) } + .to raise_error(ZammadAPI::ServerError) + expect(a_request(:put, "#{url}/1")).to have_been_made.once + end + + it 'does not retry PUT after a timeout either' do + stub_request(:put, "#{url}/1").to_raise(Net::ReadTimeout).then.to_return(json_response({ id: 1 })) + expect { unit_transport(retries: 2, retry_interval: 0.01).put('api/v1/groups/1', operation: 'test', body: { a: 1 }) } + .to raise_error(ZammadAPI::TimeoutError) + expect(a_request(:put, "#{url}/1")).to have_been_made.once + end + + # Repeated after a lost answer, the second DELETE met a 404 and reported a + # record that had just been deleted as one that could not be found. + it 'does not retry DELETE, which would answer a lost success with a 404' do + stub_request(:delete, "#{url}/1").to_raise(Net::ReadTimeout).then.to_return(json_response({ error: 'gone' }, status: 404)) + expect { unit_transport(retries: 2, retry_interval: 0.01).delete('api/v1/groups/1', operation: 'test') } + .to raise_error(ZammadAPI::TimeoutError) + expect(a_request(:delete, "#{url}/1")).to have_been_made.once + end + + it 'does not retry a client error' do + stub_request(:get, url).to_return(json_response({ error: 'nope' }, status: 404)) + expect { unit_transport(retries: 2, retry_interval: 0.01).get('api/v1/groups', operation: 'test') } + .to raise_error(ZammadAPI::NotFoundError) + expect(a_request(:get, url)).to have_been_made.once + end + end + + # Most adapters wrap a socket failure into Faraday::ConnectionFailed, which + # was retried; the same failure raw was not, so how often a request was + # retried depended on which adapter the caller picked - through an option + # this gem offers. + describe 'retries through an adapter that does not wrap socket errors' do + before { BareSocketAdapter.attempts = [] } + + def bare_socket_transport(**overrides) + unit_transport(adapter: :bare_socket, retry_interval: 0.01, **overrides) + end + + it 'retries an unwrapped socket error as often as a wrapped one' do + expect { bare_socket_transport(retries: 2).get('api/v1/groups', operation: 'test') } + .to raise_error(ZammadAPI::ConnectionError) + expect(BareSocketAdapter.attempts.size).to eq(3) + end + + it 'still maps it to ConnectionError once the retries are spent' do + expect { bare_socket_transport(retries: 1).get('api/v1/groups', operation: 'test') } + .to raise_error(ZammadAPI::ConnectionError, /is unreachable/) + end + + it 'does not repeat a POST, which could duplicate records' do + expect { bare_socket_transport(retries: 2).post('api/v1/groups', operation: 'test', body: { a: 1 }) } + .to raise_error(ZammadAPI::ConnectionError) + expect(BareSocketAdapter.attempts).to eq([:post]) + end + + it 'retries every socket failure it maps to ConnectionError' do + expect(described_class::RETRIABLE_EXCEPTIONS).to include(*described_class::CONNECTION_ERRORS) + end + + it 'retries every socket failure it maps to TimeoutError' do + expect(described_class::RETRIABLE_EXCEPTIONS).to include(*described_class::TIMEOUT_ERRORS) + end + end + + describe 'the Faraday seam' do + it 'calls the middleware with the connection being built' do + seen = nil + unit_transport(middleware: ->(connection) { seen = connection }) + + expect(seen).to be_a(Faraday::Connection) + end + + it 'lets the middleware see a request this gem built' do + stub_request(:get, url).to_return(json_response([])) + + seen = nil + transport = unit_transport(middleware: lambda { |builder| + builder.use(Class.new(Faraday::Middleware) do + define_method(:on_request) { |env| seen = env.request_headers['User-Agent'] } + end) + }) + transport.get('api/v1/groups', operation: 'test') + + expect(seen).to eq("zammad_api-ruby/#{ZammadAPI::VERSION}") + end + + it 'lets the middleware see the response' do + stub_request(:get, url).to_return(json_response([{ id: 1 }])) + + seen = nil + transport = unit_transport(middleware: lambda { |builder| + builder.use(Class.new(Faraday::Middleware) do + define_method(:on_complete) { |env| seen = env.status } + end) + }) + transport.get('api/v1/groups', operation: 'test') + + expect(seen).to eq(200) + end + + # `c.response :json` is a reasonable thing to put through a documented + # seam, and Faraday then hands over a Hash rather than the bytes. `to_s` + # turned that into a Ruby inspect string, which JSON.parse refused, so + # every record built from the response died in Response#decoded with a + # ParseError naming Zammad for what the caller's own stack had done. + # + # Re-encoding the parsed structure was the other way out, and it is worse: + # `raw_body` is what an attachment download hands back as the file, so a + # re-encoding returns something Zammad never stored. The bytes are gone + # either way, so this names the cause while it is still visible. + context 'with middleware that decodes the body first' do + it 'refuses it when the stack is built, before anything is sent' do + expect { unit_transport(middleware: ->(builder) { builder.response(:json) }) } + .to raise_error(ZammadAPI::ConfigurationError, /decodes the response body before this gem can/) + end + + it 'names the middleware it found' do + expect { unit_transport(middleware: ->(builder) { builder.response(:json) }) } + .to raise_error(ZammadAPI::ConfigurationError, /Faraday::Response::Json/) + end + + it 'says which middleware to drop' do + expect { unit_transport(middleware: ->(builder) { builder.response(:json) }) } + .to raise_error(ZammadAPI::ConfigurationError, /c\.response :json/) + end + + it 'is catchable as the gem error every caller rescues' do + expect { unit_transport(middleware: ->(builder) { builder.response(:json) }) }.to raise_error(ZammadAPI::Error) + end + + # The check used to live in `decode`, which is one request too late: the + # POST went out, Zammad created the record, and only then did a + # "configuration" error come back - so a caller retrying it made a second. + it 'sends nothing before refusing' do + stub = stub_request(:post, url).with(query: hash_including({})) + + expect { unit_client(middleware: ->(builder) { builder.response(:json) }).groups.create(name: 'X') } + .to raise_error(ZammadAPI::ConfigurationError) + expect(stub).not_to have_been_requested + end + end + + # `c.response :raise_error` is in most Faraday stacks people have written + # before, so it is what a caller adds by habit. It sits below the retry + # middleware and raises for a 4xx or 5xx before this gem sees the + # response: a GET answered 503 left as Faraday::ServerError without being + # retried, and a 404 as Faraday::ResourceNotFound rather than the + # NotFoundError that `exists?` and every caller's rescue are written for. + context 'with middleware that raises for an error status first' do + let(:raising) { ->(builder) { builder.response(:raise_error) } } + + it 'refuses it when the stack is built' do + expect { unit_transport(middleware: raising) } + .to raise_error(ZammadAPI::ConfigurationError, /raises a Faraday error for a 4xx or 5xx response before this gem sees it/) + end + + it 'names the middleware it found' do + expect { unit_transport(middleware: raising) } + .to raise_error(ZammadAPI::ConfigurationError, /the configured middleware includes Faraday::Response::RaiseError/) + end + + it 'says which middleware to drop' do + expect { unit_transport(middleware: raising) }.to raise_error(ZammadAPI::ConfigurationError, /drop `c\.response :raise_error`/) + end + + it 'refuses it where it was added by class' do + expect { unit_transport(middleware: ->(builder) { builder.use(Faraday::Response::RaiseError) }) } + .to raise_error(ZammadAPI::ConfigurationError, /Faraday::Response::RaiseError/) + end + + # The stub is for the path `find(1)` asks, and answers with a group. One + # for the index, which this was, is not a request `find` makes, so the + # assertion below held whether or not the GET went out before the + # refusal. + it 'sends nothing before refusing' do + stub = stub_request(:get, "#{url}/1").with(query: hash_including({})).to_return(json_response({ id: 1, name: 'Users' })) + + expect { unit_client(middleware: raising).groups.find(1) }.to raise_error(ZammadAPI::ConfigurationError) + expect(stub).not_to have_been_requested + end + end + + # A subclass has a name of its own, and only the name was asked. It is how + # a caller adjusts what `raise_error` raises, and what it inherits is the + # handler that raises before this gem sees the response. + context 'with a subclass of a middleware it refuses' do + let(:subclass) { stub_const('QuietRaiseError', Class.new(Faraday::Response::RaiseError)) } + + it 'refuses it for what it inherits' do + expect { unit_transport(middleware: ->(builder) { builder.use(subclass) }) } + .to raise_error(ZammadAPI::ConfigurationError, /raises a Faraday error for a 4xx or 5xx response before this gem sees it/) + end + + it 'names the subclass and the middleware it inherits from' do + expect { unit_transport(middleware: ->(builder) { builder.use(subclass) }) } + .to raise_error(ZammadAPI::ConfigurationError, /includes QuietRaiseError, a subclass of Faraday::Response::RaiseError, which raises/) + end + + # `c.response :raise_error` is not the line that added it. + it 'says to drop the subclass rather than the spelling its parent has' do + expect { unit_transport(middleware: ->(builder) { builder.use(subclass) }) } + .to raise_error(ZammadAPI::ConfigurationError, /it does neither: drop it from the `middleware:` callable\./) + end + + it 'refuses one that was never given a name' do + expect { unit_transport(middleware: ->(builder) { builder.use(Class.new(Faraday::Response::RaiseError)) }) } + .to raise_error(ZammadAPI::ConfigurationError, /includes an anonymous class, a subclass of Faraday::Response::RaiseError,/) + end + + it 'refuses a subclass of the decoding middleware too' do + expect { unit_transport(middleware: ->(builder) { builder.use(Class.new(Faraday::Response::Json)) }) } + .to raise_error(ZammadAPI::ConfigurationError, /decodes the response body before this gem can/) + end + + it 'sends nothing before refusing' do + stub = stub_request(:get, "#{url}/1").with(query: hash_including({})).to_return(json_response({ id: 1, name: 'Users' })) + + expect { unit_client(middleware: ->(builder) { builder.use(subclass) }).groups.find(1) }.to raise_error(ZammadAPI::ConfigurationError) + expect(stub).not_to have_been_requested + end + end + + # The build-time check knows the two above by name; anything + # else that consumes the body is caught only once a response is in hand. + context 'with a decoder the build-time check does not know by name' do + subject(:transport) do + unit_transport(middleware: lambda { |builder| + builder.use(Class.new(Faraday::Middleware) do + def on_complete(env) = env.body = { id: 1 } + end) + }) + end + + before { stub_request(:get, url).to_return(json_response([{ id: 1 }])) } + + it 'builds, because nothing named is in the stack' do + expect { transport }.not_to raise_error + end + + it 'refuses the response rather than stringifying what it got' do + expect { transport.get('api/v1/groups', operation: 'test') } + .to raise_error(ZammadAPI::ConfigurationError, /decoded the response body before this gem could/) + end + + it 'names what it was handed instead of the body' do + expect { transport.get('api/v1/groups', operation: 'test') } + .to raise_error(ZammadAPI::ConfigurationError, /Faraday handed over Hash rather than the raw body/) + end + end + + it 'leaves a middleware that does not touch the body alone' do + stub_request(:get, url).to_return(json_response([{ id: 1, name: 'Users' }])) + + response = unit_transport(middleware: ->(builder) { builder.response(:logger, Logger.new(File::NULL)) }) + .get('api/v1/groups', operation: 'test') + + expect(response.body).to eq([{ id: 1, name: 'Users' }]) + end + + it 'uses the configured adapter' do + transport = unit_transport(adapter: :test) + expect(transport.instance_variable_get(:@connection).adapter.name).to include('Adapter::Test') + end + + it 'reports an unregistered adapter as a configuration error' do + expect { unit_transport(adapter: :nonsense) } + .to raise_error(ZammadAPI::ConfigurationError, /is not registered on Faraday::Adapter/) + end + + it 'does not leak a Faraday error out of the client constructor' do + expect { unit_client(adapter: :nonsense) }.to raise_error(ZammadAPI::ConfigurationError) + end + + # Only Faraday::Error used to be wrapped, so the failures that do not come + # from Faraday - the ones a caller is least equipped to place - escaped + # raw, past the `rescue ZammadAPI::ConfigurationError` the constructor is + # documented to need. + it 'reports a proxy that is not a url as a configuration error' do + expect { unit_transport(proxy: 'http://user:pa ss@host') } + .to raise_error(ZammadAPI::ConfigurationError, /URI::InvalidURIError/) + end + + it 'reports a middleware that raises as a configuration error' do + expect { unit_transport(middleware: ->(_) { raise NameError, 'boom' }) } + .to raise_error(ZammadAPI::ConfigurationError, /NameError: boom/) + end + + # The backtrace into the caller's own code is the one thing the message + # cannot carry, so the cause stays wherever it gives nothing away. + it 'keeps the error a middleware raised as the cause' do + failure = NameError.new('boom') + + expect { unit_transport(middleware: ->(_) { raise failure }) } + .to raise_error(ZammadAPI::ConfigurationError) { |error| expect(error.cause).to be(failure) } + end + + # The middleware is on a line of its own on purpose. A NameError's report + # quotes the source line it was raised on, so with the proxy written on + # that line the report would carry the password after all - and the cause + # would be dropped, rightly. + it 'keeps it beside a proxy that carries credentials, where the report does not quote them' do + failure = NameError.new('boom') + raising = ->(_) { raise failure } + + expect { unit_transport(proxy: 'http://user:s3cret@proxyhost:3128', middleware: raising) } + .to raise_error(ZammadAPI::ConfigurationError) { |error| expect(error.cause).to be(failure) } + end + + # Rendering a report is the error's own code, and this asks for it from + # inside the rescue that turns the error into a ConfigurationError. A + # `detailed_message` written without the `highlight:` keyword is all it + # takes: `full_message` passes it one and gets ArgumentError back. + context 'when the error a middleware raised cannot render its own report' do + let(:failure) do + Class.new(StandardError) do + def detailed_message = "unreadable: #{message}" + end.new('boom') + end + + it 'has a report that raises, which is what this is about' do + expect { failure.full_message(highlight: false) }.to raise_error(ArgumentError) + end + + it 'still reports a configuration error' do + expect { unit_transport(middleware: ->(_) { raise failure }) } + .to raise_error(ZammadAPI::ConfigurationError, /config could not be used to build a connection: .*: boom/) + end + + it 'drops the cause, which cannot be shown to quote nothing' do + expect { unit_transport(middleware: ->(_) { raise failure }) } + .to raise_error(ZammadAPI::ConfigurationError) { |error| expect(error.cause).to be_nil } + end + end + + it 'keeps the cause of an unregistered adapter' do + expect { unit_transport(adapter: :nonsense) } + .to raise_error(ZammadAPI::ConfigurationError) { |error| expect(error.cause).to be_a(Faraday::Error) } + end + + it 'does not relabel an error this gem raised itself' do + failure = ZammadAPI::NotFoundError.new(operation: 'test', resource_class: nil, detail: 'gone') + + expect { unit_transport(middleware: ->(_) { raise failure }) } + .to raise_error(ZammadAPI::NotFoundError) + end + end + + describe '#with_on_behalf_of' do + it 'sends the From header' do + stub = stub_request(:get, url).with(headers: { 'From' => 'agent@example.com' }).to_return(json_response([])) + unit_transport.with_on_behalf_of('agent@example.com').get('api/v1/groups', operation: 'test') + expect(stub).to have_been_requested + end + + it 'sends an integer user id, which Net::HTTP will not stringify itself' do + stub = stub_request(:get, url).with(headers: { 'From' => '42' }).to_return(json_response([])) + unit_transport.with_on_behalf_of(42).get('api/v1/groups', operation: 'test') + expect(stub).to have_been_requested + end + + it 'records the scope as the string the header carries' do + expect(unit_transport.with_on_behalf_of(42).on_behalf_of).to eq('42') + end + + it 'keeps an unscoped transport unscoped' do + expect(unit_transport.with_on_behalf_of(nil).on_behalf_of).to be_nil + end + + # Every way to a From header goes through here, not only + # Client#on_behalf_of, and a header with nothing in it is no scope. + ['', ' ', "\u00A0"].each do |blank| + it "refuses #{blank.inspect}, which Zammad reads as no From header" do + expect { unit_transport.with_on_behalf_of(blank) }.to raise_error(ArgumentError, /on_behalf_of needs the login/) + end + end + + # The blank check raised Encoding::CompatibilityError for text in an + # encoding ASCII is no part of, for an identifier that names someone too. + it 'refuses an identifier with a line break inside it' do + expect { unit_transport.with_on_behalf_of("agent\nadmin") }.to raise_error(ArgumentError, /on_behalf_of holds a line break/) + end + + it 'refuses a blank identifier given in UTF-16' do + expect { unit_transport.with_on_behalf_of(' '.encode('UTF-16LE')) }.to raise_error(ArgumentError, /on_behalf_of needs the login/) + end + + it 'holds an identifier given in UTF-16 as the same text in UTF-8' do + expect(unit_transport.with_on_behalf_of('bob'.encode('UTF-16LE')).on_behalf_of).to eq('bob').and(have_attributes(encoding: Encoding::UTF_8)) + end + + # `String#to_s` hands back the receiver, so the scoped transport held the + # caller's own String: a login buffer reused after the scope was taken + # changed who every later request was performed for. + context 'when the string it was given changes afterwards' do + let(:login) { +'agent@example.com' } + let(:scoped) { unit_transport.with_on_behalf_of(login) } + + before do + scoped + login.replace('admin@example.com') + end + + it 'goes on sending the scope it was given' do + stub = stub_request(:get, url).with(headers: { 'From' => 'agent@example.com' }).to_return(json_response([])) + scoped.get('api/v1/groups', operation: 'test') + + expect(stub).to have_been_requested + end + + it 'goes on reporting the scope it was given' do + expect(scoped.on_behalf_of).to eq('agent@example.com') + end + end + + it 'holds the scope frozen' do + expect(unit_transport.with_on_behalf_of(+'agent@example.com').on_behalf_of).to be_frozen + end + + it 'leaves the string it was given writable' do + login = +'agent@example.com' + unit_transport.with_on_behalf_of(login) + + expect(login).not_to be_frozen + end + + it 'returns a different transport' do + transport = unit_transport + expect(transport.with_on_behalf_of('someone')).not_to be(transport) + end + + it 'leaves the original transport unscoped' do + transport = unit_transport + transport.with_on_behalf_of('someone') + expect(transport.on_behalf_of).to be_nil + end + + it 'does not send a From header from the original transport' do + transport = unit_transport + transport.with_on_behalf_of('someone') + + stub_request(:get, url).to_return(json_response([])) + transport.get('api/v1/groups', operation: 'test') + + expect(a_request(:get, url).with { |request| request.headers.key?('From') }).not_to have_been_made + end + + it 'shares the underlying connection instead of rebuilding it' do + transport = unit_transport + scoped = transport.with_on_behalf_of('someone') + expect(scoped.instance_variable_get(:@connection)).to be(transport.instance_variable_get(:@connection)) + end + end + + # Left to Ruby, inspect printed the Faraday connection, whose proxy options + # carry the proxy password and whose middleware stack carries the token it + # was built with. + describe '#inspect' do + let(:transport) do + unit_transport(http_token: 'tok-s3cret', proxy: 'http://puser:pproxy-s3cret@proxy.test:8080') + end + + it 'names the instance and the authentication scheme' do + expect(unit_transport.inspect).to eq('#') + end + + it 'names an on_behalf_of scope' do + expect(unit_transport.with_on_behalf_of('agent@example.com').inspect).to include('on_behalf_of="agent@example.com"') + end + + it 'does not print the access token' do + expect(transport.inspect).not_to include('tok-s3cret') + end + + it 'does not print the proxy password' do + expect(transport.inspect).not_to include('pproxy-s3cret') + end + + it 'does not print a basic authentication password' do + basic = unit_transport(http_token: nil, user: 'u', password: 'pw-s3cret') + expect(basic.inspect).not_to include('pw-s3cret') + end + + it 'keeps both out of what pp prints too' do + expect(transport.pretty_inspect).not_to match(/tok-s3cret|pproxy-s3cret/) + end + end + + describe '#with_config' do + it 'applies the new configuration' do + expect(unit_transport.with_config(ZammadAPI::Config.new(**unit_config(timeout: 7))).config.timeout).to eq(7) + end + + it 'carries the on_behalf_of scope over' do + derived = unit_transport.with_on_behalf_of('agent@example.com') + .with_config(ZammadAPI::Config.new(**unit_config(timeout: 7))) + + expect(derived.on_behalf_of).to eq('agent@example.com') + end + + it 'keeps a subclass on its own kind, rather than reverting to a real one' do + recording = Class.new(described_class) + stub_const('RecordingTransport', recording) + + derived = recording.new(ZammadAPI::Config.new(**unit_config)).with_config(ZammadAPI::Config.new(**unit_config(timeout: 7))) + + expect(derived).to be_a(recording) + end + + it 'returns a different transport' do + transport = unit_transport + expect(transport.with_config(transport.config)).not_to be(transport) + end + end + + describe 'logging' do + subject(:log) { log_device.string } + + let(:log_device) { StringIO.new } + let(:logger) { Logger.new(log_device, level: Logger::DEBUG) } + + before do + stub_request(:post, url).to_return(json_response({ id: 1 }, status: 201)) + unit_transport(logger: logger, user: 'u', password: 'pw-s3cret', http_token: nil) + .post('api/v1/groups', operation: 'test', body: { login: 'jane', password: 'pw-s3cret' }) + end + + it 'logs the request' do + expect(log).to include('Zammad API request: POST api/v1/groups') + end + + it 'logs the response status' do + expect(log).to include('Zammad API response: POST api/v1/groups -> 201') + end + + it 'never logs a password from the payload' do + expect(log).not_to include('pw-s3cret') + end + + it 'marks the redacted payload value' do + expect(log).to include('password: "[REDACTED]"') + end + + it 'keeps non-sensitive payload values' do + expect(log).to include('login: "jane"') + end + + it 'stays silent by default' do + stub_request(:get, url).to_return(json_response([])) + + expect { unit_transport.get('api/v1/groups', operation: 'test') } + .to output('').to_stdout.and output('').to_stderr + end + + context 'with credential-bearing payload keys' do + subject(:log) { log_device.string } + + let(:log_device) { StringIO.new } + + before do + stub_request(:post, url).to_return(json_response({ id: 1 }, status: 201)) + unit_transport(logger: Logger.new(log_device, level: Logger::DEBUG)).post( + 'api/v1/groups', + operation: 'test', + body: { + login: 'jane', + keyboard_layout: 'de', + password_confirm: 'confirm-s3cret', + passwd: 'passwd-s3cret', + access_token: 'access-s3cret', + refresh_token: 'refresh-s3cret', + client_secret: 'client-s3cret', + api_key: 'api-key-s3cret', + apikey: 'apikey-s3cret', + key: 'key-s3cret' + } + ) + end + + it 'redacts a password_confirm' do + expect(log).not_to include('confirm-s3cret') + end + + it 'redacts an access_token' do + expect(log).not_to include('access-s3cret') + end + + it 'redacts a refresh_token' do + expect(log).not_to include('refresh-s3cret') + end + + it 'redacts an api_key' do + expect(log).not_to include('api-key-s3cret') + end + + it 'redacts an apikey, which nothing separates the word in' do + expect(log).not_to include('apikey-s3cret') + end + + it 'redacts a bare key' do + expect(log).not_to include('key-s3cret') + end + + it 'redacts a passwd' do + expect(log).not_to include('passwd-s3cret') + end + + # Matched as a word, so that a key merely containing the letters stays + # readable in the log rather than being blanked for nothing. + it 'leaves a key whose name only contains one of the words alone' do + expect(log).to include('keyboard_layout: "de"') + end + + it 'redacts a client_secret' do + expect(log).not_to include('client-s3cret') + end + + it 'still keeps a non-sensitive value' do + expect(log).to include('login: "jane"') + end + end + + # A body handed over as a String is the caller's own encoding. Redaction + # goes by key and found none in a String, so the payload line printed it + # as it stood. + context 'with a body handed over as a String' do + subject(:log) { log_device.string } + + let(:log_device) { StringIO.new } + let(:transport) { unit_transport(logger: Logger.new(log_device, level: Logger::DEBUG)) } + + before { stub_request(:post, url).to_return(json_response({ id: 1 }, status: 201)) } + + it 'redacts a credential in one that is JSON' do + transport.post('api/v1/groups', operation: 'test', body: '{"login":"jane","password":"string-s3cret"}') + + expect(log).not_to include('string-s3cret') + end + + it 'keeps what is not a credential readable, redacted by key like a Hash' do + transport.post('api/v1/groups', operation: 'test', body: '{"login":"jane","password":"string-s3cret"}') + + expect(log).to include('Zammad API payload: {"login" => "jane", "password" => "[REDACTED]"}') + end + + it 'redacts one nested in a JSON list' do + transport.post('api/v1/groups', operation: 'test', body: '[{"user":{"api_key":"string-s3cret"}}]') + + expect(log).not_to include('string-s3cret') + end + + it 'does not log one that is not JSON, and says how much was left out' do + transport.post('api/v1/groups', operation: 'test', body: 'login=jane&password=string-s3cret') + + expect(log).not_to include('string-s3cret') + expect(log).to include('Zammad API payload: "[33 bytes that are not a JSON object or array, not logged]"') + end + + it 'does not log a JSON value with no keys to go by' do + transport.post('api/v1/groups', operation: 'test', body: '"string-s3cret"') + + expect(log).not_to include('string-s3cret') + end + + it 'does not raise for bytes that are not text' do + expect { transport.post('api/v1/groups', operation: 'test', body: "\xFF\xFEstring-s3cret".b) }.not_to raise_error + expect(log).not_to include('string-s3cret') + end + + it 'still sends the body as it was given' do + transport.post('api/v1/groups', operation: 'test', body: '{"login":"jane","password":"string-s3cret"}') + + expect(a_request(:post, url).with(body: '{"login":"jane","password":"string-s3cret"}')).to have_been_made + end + end + + # A raw request may carry its query in the path. The `query:` Hash is + # redacted by key, and the same parameter written into the path was + # printed in full, in the request line and in the response line. + context 'with a query string written into the path' do + subject(:log) { log_device.string } + + let(:log_device) { StringIO.new } + let(:verify) { 'api/v1/users/password_reset_verify?token=path-s3cret&locale=de' } + + before do + stub_request(:get, "#{ClientHelper::BASE_URL}api/v1/users/password_reset_verify").with(query: hash_including({})).to_return(json_response({})) + unit_transport(logger: Logger.new(log_device, level: Logger::DEBUG)).get(verify, operation: 'test') + end + + it 'redacts a credential in it' do + expect(log).not_to include('path-s3cret') + end + + it 'marks it in the request line, and keeps the other parameters' do + expect(log).to include('Zammad API request: GET api/v1/users/password_reset_verify?token=[REDACTED]&locale=de') + end + + it 'marks it in the response line' do + expect(log).to include('Zammad API response: GET api/v1/users/password_reset_verify?token=[REDACTED]&locale=de -> 200') + end + + it 'still sends the query as it was given' do + expect(a_request(:get, "#{ClientHelper::BASE_URL}api/v1/users/password_reset_verify").with(query: { 'token' => 'path-s3cret', 'locale' => 'de' })) + .to have_been_made + end + end + + # A raw request takes headers of its own and the request line prints + # them. `Cookie` carries a session and matched none of the credential + # words, so it was written out in full. + context 'with credential-bearing headers' do + subject(:log) { log_device.string } + + let(:log_device) { StringIO.new } + + before do + stub_request(:get, url).to_return(json_response([])) + unit_transport(logger: Logger.new(log_device, level: Logger::DEBUG)).get( + 'api/v1/groups', + operation: 'test', + headers: { + 'Cookie' => '_zammad_session=cookie-s3cret', + 'Proxy-Authorization' => 'Basic proxy-s3cret', + 'X-CSRF-Token' => 'csrf-s3cret', + 'X-Request-Id' => 'request-123' + } + ) + end + + it 'redacts a Cookie' do + expect(log).not_to include('cookie-s3cret') + end + + it 'marks the redacted header, under the name it is sent as' do + expect(log).to include('"cookie" => "[REDACTED]"') + end + + it 'redacts a Proxy-Authorization' do + expect(log).not_to include('proxy-s3cret') + end + + it 'redacts a token header' do + expect(log).not_to include('csrf-s3cret') + end + + it 'keeps a header that carries no credential' do + expect(log).to include('"x-request-id" => "request-123"') + end + + it 'still sends the headers as they were given' do + expect(a_request(:get, url).with(headers: { 'Cookie' => '_zammad_session=cookie-s3cret', 'Proxy-Authorization' => 'Basic proxy-s3cret' })) + .to have_been_made + end + end + end + + # `request` documents that every failure leaves it as a ZammadAPI::Error. + # Faraday::SSLError was handled and its unwrapped counterpart was not, so a + # certificate mismatch through an adapter that does not wrap - an adapter + # this gem lets a caller choose - went straight past the rescue. + describe 'a TLS failure through an adapter that does not wrap it' do + before { BareTlsAdapter.attempts = [] } + + def bare_tls_transport(**overrides) + unit_transport(adapter: :bare_tls, retry_interval: 0.01, **overrides) + end + + it 'maps it to ConnectionError rather than letting it out raw' do + expect { bare_tls_transport.get('api/v1/groups', operation: 'test') } + .to raise_error(ZammadAPI::ConnectionError, /TLS handshake with .* failed/) + end + + it 'is catchable as the gem error every caller rescues' do + expect { bare_tls_transport.get('api/v1/groups', operation: 'test') } + .to raise_error(ZammadAPI::Error) + end + + # A rejected certificate is a fact about the instance, not a transient + # failure: retrying only delays the error by the backoff. + it 'does not retry it' do + expect { bare_tls_transport(retries: 2).get('api/v1/groups', operation: 'test') } + .to raise_error(ZammadAPI::ConnectionError) + expect(BareTlsAdapter.attempts.size).to eq(1) + end + + it 'keeps the unwrapped TLS error out of the retry list' do + expect(described_class::RETRIABLE_EXCEPTIONS).not_to include(*described_class::SSL_ERRORS) + end + end + + # The error Faraday or URI raises quotes the value it rejected, and for a + # proxy that value carries its credentials - into a message that lands in + # every log and exception report. + describe 'a connection that cannot be built from a credential-bearing proxy' do + let(:proxy) { 'http://user:pa ss@proxyhost:3128' } + + it 'reports it as a configuration error' do + expect { unit_transport(proxy: proxy) }.to raise_error(ZammadAPI::ConfigurationError) + end + + it 'keeps the proxy password out of the message' do + expect { unit_transport(proxy: proxy) } + .to raise_error(ZammadAPI::ConfigurationError) { |error| expect(error.message).not_to include('pa ss') } + end + + it 'still says which value was rejected' do + expect { unit_transport(proxy: proxy) } + .to raise_error(ZammadAPI::ConfigurationError, %r{http://\[REDACTED\]@proxyhost:3128}) + end + + # The message is not what a log or an error tracker prints. They print + # the report, and Ruby had attached the error being rescued as the cause: + # the redacted message went out with the original, password and all, + # right behind it. + it 'keeps the proxy password out of the whole report, not just the message' do + expect { unit_transport(proxy: proxy) } + .to raise_error(ZammadAPI::ConfigurationError) { |error| expect(error.full_message(highlight: false)).not_to include('pa ss') } + end + + it 'does not carry the error that quotes the password along as its cause' do + expect { unit_transport(proxy: proxy) } + .to raise_error(ZammadAPI::ConfigurationError) { |error| expect(error.cause).to be_nil } + end + + it 'still names the class of the error it replaced' do + expect { unit_transport(proxy: proxy) }.to raise_error(ZammadAPI::ConfigurationError, /URI::InvalidURIError/) + end + + # The error being replaced may be clean itself and still have the + # password one level down, and a report prints every level. + context 'when the error quotes the proxy only further down its own chain' do + let(:proxy) { 'http://user:s3cret@proxyhost:3128' } + + let(:wrapping) do + lambda do |_| + raise URI::InvalidURIError, "bad URI: #{proxy}" + rescue URI::InvalidURIError + raise ArgumentError, 'the proxy could not be used' + end + end + + it 'has nothing to redact in the message' do + expect { unit_transport(proxy: proxy, middleware: wrapping) } + .to raise_error(ZammadAPI::ConfigurationError, /ArgumentError: the proxy could not be used/) + end + + it 'keeps the password out of the whole report all the same' do + expect { unit_transport(proxy: proxy, middleware: wrapping) } + .to raise_error(ZammadAPI::ConfigurationError) { |error| expect(error.full_message(highlight: false)).not_to include('s3cret') } + end + end + + # A # ends the authority early, so the redaction found no credential in + # what was left of it and the message quoted the password in full. + context 'when the password carries a character that ends the authority' do + let(:proxy) { 'http://user:pa#ss-s3cret@proxyhost:3128' } + + it 'keeps the password out of the message' do + expect { unit_transport(proxy: proxy) } + .to raise_error(ZammadAPI::ConfigurationError) { |error| expect(error.message).not_to match(/pa#ss|s3cret/) } + end + + it 'still says which value was rejected' do + expect { unit_transport(proxy: proxy) } + .to raise_error(ZammadAPI::ConfigurationError, %r{http://\[REDACTED\]@proxyhost:3128}) + end + + it 'keeps the password out of the whole report' do + expect { unit_transport(proxy: proxy) } + .to raise_error(ZammadAPI::ConfigurationError) { |error| expect(error.full_message(highlight: false)).not_to match(/pa#ss|s3cret/) } + end + end + + context 'when it is the instance url that carries such a password' do + it 'keeps the password out of the message' do + expect { unit_transport(url: 'https://admin:pa#ss-s3cret@zammad.test/') } + .to raise_error(ZammadAPI::ConfigurationError) { |error| expect(error.message).not_to match(/pa#ss|s3cret/) } + end + end + + # The error quotes what it rejected through `inspect`, which escapes the + # backslash - so the text in the message stopped matching the configured + # value and the substring swap redacted nothing at all. + context 'when the value carries a backslash, which inspect escapes' do + let(:proxy) { 'http://user:secret@proxyhost/a\0b' } + + it 'still keeps the password out of the message' do + expect { unit_transport(proxy: proxy) } + .to raise_error(ZammadAPI::ConfigurationError) { |error| expect(error.message).not_to include('secret') } + end + end + + # URI turns away a URL holding a character outside ASCII, and quotes it + # through `dump`, which writes that character as an escape where + # `inspect` leaves it standing. Neither spelling that was looked for + # matched, so the password stayed in the message and in the cause. + context 'when the password carries a character outside ASCII, which dump escapes' do + let(:proxy) { 'http://user:pässwörd@proxyhost:3128' } + + it 'keeps the password out of the message' do + expect { unit_transport(proxy: proxy) } + .to raise_error(ZammadAPI::ConfigurationError) { |error| expect(error.message).not_to match(/ssw|user:/) } + end + + it 'still says which value was rejected' do + expect { unit_transport(proxy: proxy) } + .to raise_error(ZammadAPI::ConfigurationError, %r{URI must be ascii only "http://\[REDACTED\]@proxyhost:3128"}) + end + + it 'keeps the password out of the whole report' do + expect { unit_transport(proxy: proxy) } + .to raise_error(ZammadAPI::ConfigurationError) { |error| expect(error.full_message(highlight: false)).not_to match(/ssw|user:/) } + end + + it 'does not carry the error that quotes the password along as its cause' do + expect { unit_transport(proxy: proxy) } + .to raise_error(ZammadAPI::ConfigurationError) { |error| expect(error.cause).to be_nil } + end + + it 'keeps it out of the message where the instance url carries it' do + expect { unit_transport(url: 'https://admin:pässwörd@zammad.test/') } + .to raise_error(ZammadAPI::ConfigurationError) { |error| expect(error.full_message(highlight: false)).not_to match(/ssw|admin:/) } + end + end + + # `\0` in a gsub replacement String expands to the matched text, which is + # the unredacted value. + context 'when the value carries a sequence a gsub replacement would expand' do + let(:proxy) { 'http://user:secret@proxyhost/a\0b' } + + it 'does not put the credential back through the replacement' do + message = begin + unit_transport(proxy: proxy) + nil + rescue ZammadAPI::ConfigurationError => e + e.message + end + + expect(message.scan('user:secret')).to be_empty + end + end + end +end diff --git a/spec/zammad_api/client_spec.rb b/spec/zammad_api/client_spec.rb deleted file mode 100644 index 9f6b73f..0000000 --- a/spec/zammad_api/client_spec.rb +++ /dev/null @@ -1,110 +0,0 @@ -require 'spec_helper' -require 'logger' - -describe ZammadAPI::Client do - before(:all) do - WebMock.enable! - end - - after(:all) do - WebMock.disable! - end - - after do - WebMock.reset! - end - - let(:config) { Helper.config } - let(:instance) { described_class.new(config) } - - describe '.new' do - it 'raises ConfigurationError when url is missing' do - expect { described_class.new(config.merge(url: nil)) } - .to raise_error(ZammadAPI::ConfigurationError, 'missing url in config') - end - - it 'raises ConfigurationError when url scheme is unsupported' do - expect { described_class.new(config.merge(url: 'ftp://example.com')) } - .to raise_error(ZammadAPI::ConfigurationError, 'config url needs to start with http:// or https://') - end - - it 'raises ConfigurationError when user is missing' do - expect { described_class.new(config.merge(user: nil)) } - .to raise_error(ZammadAPI::ConfigurationError, 'missing user in config') - end - - it 'raises ConfigurationError when password is missing' do - expect { described_class.new(config.merge(password: nil)) } - .to raise_error(ZammadAPI::ConfigurationError, 'missing password in config') - end - - it 'does not require user/password when http_token is supplied' do - expect { described_class.new(url: config[:url], http_token: 'token') }.not_to raise_error - end - - it 'does not require user/password when oauth2_token is supplied' do - expect { described_class.new(url: config[:url], oauth2_token: 'token') }.not_to raise_error - end - end - - describe '#method_missing' do - it 'raises ResourceNotFoundError for unknown resources' do - expect { instance.does_not_exist }.to raise_error(ZammadAPI::ResourceNotFoundError, /Resource for DoesNotExist does not exist/) - end - - it 'attaches the underlying NameError as #cause' do - instance.does_not_exist - rescue ZammadAPI::ResourceNotFoundError => e - expect(e.cause).to be_a(NameError) - end - end - - describe '#perform_on_behalf_of' do - it 'performs a given block on behalft of a given user' do - on_behalf_of_identifier = 'some_login' - - stub_request(:get, /#{config[:url]}/) - .with(headers: { - 'From' => on_behalf_of_identifier - }) - .to_return(status: 200, body: '{}', headers: {}) - - instance.perform_on_behalf_of(on_behalf_of_identifier) do - instance.user.find(1) - end - end - - it "doesn't affect later requests outside of the block" do - # first perform request on behalf of a login - on_behalf_of_identifier = 'some_login' - - stub_request(:get, /#{config[:url]}/) - .with(headers: { - 'From' => on_behalf_of_identifier - }) - .to_return(status: 200, body: '{}', headers: {}) - - instance.perform_on_behalf_of(on_behalf_of_identifier) do - instance.user.find(1) - end - - # now without and check that - # the header isn't set anymore - stub = stub_request(:get, /#{config[:url]}/) - .to_return(status: 200, body: '{}', headers: {}) - - # this is kind of a hack/workaround to check if the - # header was not set/send since webmock doesn't support - # checks for not existing headers - request_pattern = stub.request_pattern - def request_pattern.matches?(request_signature) - return false if !super - return true if request_signature.headers.empty? - - !request_signature.headers.key?('From') - end - - instance.user.find(1) - end - end -end diff --git a/spec/zammad_api/errors_spec.rb b/spec/zammad_api/errors_spec.rb deleted file mode 100644 index b335088..0000000 --- a/spec/zammad_api/errors_spec.rb +++ /dev/null @@ -1,164 +0,0 @@ -require 'spec_helper' - -describe ZammadAPI do - describe ZammadAPI::Error do - it 'descends from RuntimeError' do - expect(described_class.ancestors).to include(RuntimeError) - end - end - - describe ZammadAPI::ConfigurationError do - it 'descends from ZammadAPI::Error' do - expect(described_class.ancestors).to include(ZammadAPI::Error) - end - - it 'descends from RuntimeError' do - expect(described_class.ancestors).to include(RuntimeError) - end - end - - describe ZammadAPI::ResourceNotFoundError do - it 'descends from ZammadAPI::Error' do - expect(described_class.ancestors).to include(ZammadAPI::Error) - end - - it 'descends from RuntimeError' do - expect(described_class.ancestors).to include(RuntimeError) - end - end - - describe ZammadAPI::ResponseError do - let(:fake_response) { Struct.new(:status, :body) } - - describe '.from' do - it 'returns a ClientError for 4xx responses' do - response = fake_response.new(404, '{}') - expect(described_class.from(response, operation: 'find object')).to be_a(ZammadAPI::ClientError) - end - - it 'returns a ClientError for 408 (Request Timeout)' do - response = fake_response.new(408, '{}') - expect(described_class.from(response, operation: 'find object')).to be_a(ZammadAPI::ClientError) - end - - it 'returns a ClientError for 429 (Too Many Requests)' do - response = fake_response.new(429, '{}') - expect(described_class.from(response, operation: 'find object')).to be_a(ZammadAPI::ClientError) - end - - it 'returns a ServerError for 5xx responses' do - response = fake_response.new(500, '{}') - expect(described_class.from(response, operation: 'find object')).to be_a(ZammadAPI::ServerError) - end - - it 'returns a ServerError for 502 (Bad Gateway)' do - response = fake_response.new(502, 'Bad Gateway') - expect(described_class.from(response, operation: 'find object')).to be_a(ZammadAPI::ServerError) - end - - it 'returns a base ResponseError when no response is supplied' do - result = described_class.from(nil, operation: 'find object') - expect(result.class).to eq(described_class) - end - end - - describe 'subclasses' do - it 'ClientError descends from ResponseError' do - expect(ZammadAPI::ClientError.ancestors).to include(described_class) - end - - it 'ServerError descends from ResponseError' do - expect(ZammadAPI::ServerError.ancestors).to include(described_class) - end - - it 'descends from ZammadAPI::Error' do - expect(described_class.ancestors).to include(ZammadAPI::Error) - end - - it 'descends from RuntimeError' do - expect(described_class.ancestors).to include(RuntimeError) - end - end - - describe '#message' do - it "uses the JSON body's 'error' key when present" do - response = fake_response.new(404, '{"error":"User not found"}') - error = described_class.from(response, operation: 'find object', resource_class: ZammadAPI::Resources::User) - expect(error.message).to eq("Can't find object (ZammadAPI::Resources::User): User not found") - end - - it 'preserves the original message format for the JSON-with-error case' do - response = fake_response.new(422, '{"error":"name can\'t be blank"}') - error = described_class.from(response, operation: 'save object', resource_class: ZammadAPI::Resources::Group) - expect(error.message).to eq("Can't save object (ZammadAPI::Resources::Group): name can't be blank") - end - - it 'falls back to HTTP status when the body is not JSON (issue #29 scenario)' do - response = fake_response.new(502, 'Bad Gateway') - error = described_class.from(response, operation: 'find object', resource_class: ZammadAPI::Resources::User) - expect(error.message).to eq("Can't find object (ZammadAPI::Resources::User): HTTP 502") - end - - it 'falls back to HTTP status when the body is empty' do - response = fake_response.new(500, '') - error = described_class.from(response, operation: 'destroy object', resource_class: ZammadAPI::Resources::User) - expect(error.message).to eq("Can't destroy object (ZammadAPI::Resources::User): HTTP 500") - end - - it "falls back to HTTP status when the JSON body has no 'error' key" do - response = fake_response.new(400, '{"foo":"bar"}') - error = described_class.from(response, operation: 'find object', resource_class: ZammadAPI::Resources::User) - expect(error.message).to eq("Can't find object (ZammadAPI::Resources::User): HTTP 400") - end - - it 'omits the resource_class segment when none is supplied' do - response = fake_response.new(404, '{"error":"nope"}') - error = described_class.from(response, operation: 'find object') - expect(error.message).to eq("Can't find object: nope") - end - - it 'does not attach the JSON parser error as cause (it is a symptom, not the cause)' do - response = fake_response.new(502, 'Bad Gateway') - error = described_class.from(response, operation: 'find object') - expect(error.cause).to be_nil - end - end - - describe 'accessors' do - let(:response) { fake_response.new(404, '{"error":"nope"}') } - let(:error) do - described_class.from(response, operation: 'find object', resource_class: ZammadAPI::Resources::User) - end - - it 'exposes the underlying response' do - expect(error.response).to be(response) - end - - it 'exposes the response status' do - expect(error.status).to eq(404) - end - - it 'exposes the response body' do - expect(error.body).to eq('{"error":"nope"}') - end - - it 'exposes the operation' do - expect(error.operation).to eq('find object') - end - - it 'exposes the resource_class' do - expect(error.resource_class).to eq(ZammadAPI::Resources::User) - end - - it 'returns nil for status when no response is supplied' do - error = described_class.from(nil, operation: 'find object') - expect(error.status).to be_nil - end - - it 'returns nil for body when no response is supplied' do - error = described_class.from(nil, operation: 'find object') - expect(error.body).to be_nil - end - end - end -end diff --git a/spec/zammad_api/json_helper_spec.rb b/spec/zammad_api/json_helper_spec.rb deleted file mode 100644 index 29eb956..0000000 --- a/spec/zammad_api/json_helper_spec.rb +++ /dev/null @@ -1,21 +0,0 @@ -require 'spec_helper' - -describe ZammadAPI::JsonHelper do - subject(:helper) do - Class.new { include ZammadAPI::JsonHelper }.new - end - - describe '#safe_json_parse' do - it 'parses valid JSON' do - expect(helper.safe_json_parse('{"key":"value"}')).to eq('key' => 'value') - end - - it 'returns empty hash for invalid JSON' do - expect(helper.safe_json_parse('not json')).to eq({}) - end - - it 'returns empty hash for HTML responses' do - expect(helper.safe_json_parse('Bad Gateway')).to eq({}) - end - end -end diff --git a/spec/zammad_api/resources/list_base_spec.rb b/spec/zammad_api/resources/list_base_spec.rb deleted file mode 100644 index c7018e3..0000000 --- a/spec/zammad_api/resources/list_base_spec.rb +++ /dev/null @@ -1,7 +0,0 @@ -require 'spec_helper' - -describe ZammadAPI::ListBase do - it 'is a Enumerable' do - expect(described_class.ancestors).to include(Enumerable) - end -end diff --git a/spec/zammad_api/transport_spec.rb b/spec/zammad_api/transport_spec.rb deleted file mode 100644 index 66032e5..0000000 --- a/spec/zammad_api/transport_spec.rb +++ /dev/null @@ -1,80 +0,0 @@ -require 'spec_helper' -require 'logger' - -describe ZammadAPI::Transport do - before(:all) do - WebMock.enable! - end - - after(:all) do - WebMock.disable! - end - - after do - WebMock.reset! - end - - let(:config) { Helper.config } - let(:logger) do - Logger.new($stderr).tap do |logger| - logger.level = Logger::ERROR - end - end - let(:instance) { described_class.new(config, logger) } - - context 'GET' do - it 'performs GET requests' do - stub_request(:get, "#{config[:url]}some/path") - .to_return(status: 200, body: '', headers: {}) - - instance.get(url: '/some/path') - end - end - - context 'on behalf of' do - it 'responds to #on_behalf_of' do - expect(instance).to respond_to(:on_behalf_of) - end - - it 'responds to #on_behalf_of=' do - expect(instance).to respond_to(:on_behalf_of=) - end - - it 'sets From header' do - on_behalf_of_identifier = 'some_login' - - instance.on_behalf_of = on_behalf_of_identifier - - stub_request(:get, "#{config[:url]}some/path") - .with(headers: { - 'From' => on_behalf_of_identifier - }) - .to_return(status: 200, body: '', headers: {}) - - instance.get(url: '/some/path') - end - - it 'unsets From header' do - on_behalf_of_identifier = 'some_login' - - instance.on_behalf_of = on_behalf_of_identifier - instance.on_behalf_of = nil - - stub = stub_request(:get, "#{config[:url]}some/path") - .to_return(status: 200, body: '', headers: {}) - - # this is kind of a hack/workaround to check if the - # header was not set/send since webmock doesn't support - # checks for not existing headers - request_pattern = stub.request_pattern - def request_pattern.matches?(request_signature) - return false if !super - return true if request_signature.headers.empty? - - !request_signature.headers.key?('From') - end - - instance.get(url: '/some/path') - end - end -end diff --git a/spec/zammad_api_spec.rb b/spec/zammad_api_spec.rb deleted file mode 100644 index 6616717..0000000 --- a/spec/zammad_api_spec.rb +++ /dev/null @@ -1,36 +0,0 @@ -require 'spec_helper' - -describe ZammadAPI do - it 'has a version number' do - expect(ZammadAPI::VERSION).not_to be_nil - end - - context 'failing authentication' do - Helper.auto_wizard - client = Helper.client(user: 'not_existing', password: 'not_existing') - - it 'user' do - expect { client.user.find(1) }.to raise_error(ZammadAPI::ClientError) do |error| - expect(error.status).to eq(401) - expect(error.operation).to eq('find object') - expect(error.resource_class).to eq(ZammadAPI::Resources::User) - end - end - - it 'organization' do - expect { client.organization.find(1) }.to raise_error(ZammadAPI::ClientError) - end - - it 'group' do - expect { client.group.find(1) }.to raise_error(ZammadAPI::ClientError) - end - - it 'ticket_priority' do - expect { client.ticket_priority.find(1) }.to raise_error(ZammadAPI::ClientError) - end - - it 'ticket_state' do - expect { client.ticket_state.find(1) }.to raise_error(ZammadAPI::ClientError) - end - end -end diff --git a/zammad_api.gemspec b/zammad_api.gemspec index 7b09454..ee07fb0 100644 --- a/zammad_api.gemspec +++ b/zammad_api.gemspec @@ -1,28 +1,59 @@ -lib = File.expand_path('lib', __dir__) -$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib) -require 'zammad_api/version' +# frozen_string_literal: true + +require_relative 'lib/zammad_api/version' Gem::Specification.new do |spec| - spec.name = 'zammad_api' - spec.version = ZammadAPI::VERSION.dup - spec.authors = ['Martin Edenhofer', 'Martin Gruner'] - spec.email = ['support@zammad.org'] + spec.name = 'zammad_api' + spec.version = ZammadAPI::VERSION + spec.authors = ['Martin Edenhofer', 'Martin Gruner', 'Mantas Masalskis'] + spec.email = ['support@zammad.org'] + + # Two versions meet in these lines, and only one of them is this gem's: 2.0 + # is the client, and v1.0 is the API that Zammad serves under /api/v1. + # + # A prerelease says so where the gem is listed, and stops saying so by itself + # once VERSION no longer carries a prerelease segment. + prerelease = Gem::Version.new(ZammadAPI::VERSION).prerelease? - spec.summary = 'Zammad API v1.0 client.' - spec.description = 'Ruby wrapper for the Zammad API v1.0.' - spec.homepage = 'https://github.com/zammad/zammad-api-client-ruby' - spec.licenses = ['AGPL-3.0-only', 'MIT'] - spec.required_ruby_version = '>= 3.0' # Same as TargetRubyVersion in .rubocop.yml. + spec.summary = "Version 2.0 of the Ruby client for the Zammad API#{' (prerelease)' if prerelease}." + spec.description = 'Version 2.0 of the Ruby client for the Zammad API v1.0, the one a Zammad serves under ' \ + '/api/v1. It is a breaking release: the README lists every call that changed since 1.x.' + spec.description += " This is a prerelease, #{ZammadAPI::VERSION}: install it with --pre." if prerelease + spec.homepage = 'https://github.com/zammad/zammad-api-client-ruby' + spec.licenses = ['AGPL-3.0-only', 'MIT'] - spec.metadata['allowed_push_host'] = 'https://rubygems.org' + # Keep in sync with TargetRubyVersion in .rubocop.yml and the CI matrix. + # + # 3.4 rather than 3.3, the one older line still maintained - for security + # fixes, until March 2027 - and for a single reason: the `it` block + # parameter, which lib/ uses throughout. Nothing else here needs 3.4. On + # Ruby 3.3.13, with every `it` rewritten to `_1`, the unit suite passed but + # for five examples that assert the format Hash#inspect has had since 3.4. + # So the floor is a choice of style over reach rather than a dependency, and + # lowering it is that rewrite, those five expectations and a CI entry. + spec.required_ruby_version = '>= 3.4' - spec.metadata['homepage_uri'] = spec.homepage - spec.metadata['source_code_uri'] = 'https://github.com/zammad/zammad-api-client-ruby' - spec.metadata['changelog_uri'] = 'https://github.com/zammad/zammad-api-client-ruby/blob/master/CHANGELOG.md' - spec.metadata['rubygems_mfa_required'] = 'true' + spec.metadata['allowed_push_host'] = 'https://rubygems.org' + spec.metadata['homepage_uri'] = spec.homepage + spec.metadata['source_code_uri'] = spec.homepage + spec.metadata['changelog_uri'] = "#{spec.homepage}/blob/master/CHANGELOG.md" + spec.metadata['bug_tracker_uri'] = "#{spec.homepage}/issues" + spec.metadata['documentation_uri'] = "https://rubydoc.info/gems/zammad_api/#{ZammadAPI::VERSION}" + spec.metadata['rubygems_mfa_required'] = 'true' - spec.files = Dir['{lib}/**/*'] - spec.require_paths = ['lib'] + # sig/vendor holds the declarations that exist only for this repository's own + # type checking - stand-ins for dependencies that ship none, and the internal + # ones in sig/vendor/internal.rbs - and must not be published. + spec.files = Dir['lib/**/*.rb', 'sig/**/*.rbs'].grep_v(%r{\Asig/vendor/}) + %w[ + CHANGELOG.md + LICENSE.AGPL.txt + LICENSE.MIT.txt + LICENSE.md + README.md + ] + spec.require_paths = ['lib'] + spec.extra_rdoc_files = ['README.md', 'CHANGELOG.md'] - spec.add_dependency 'faraday', '~> 2' + spec.add_dependency 'faraday', '~> 2.9' + spec.add_dependency 'faraday-retry', '~> 2.2' end From b5d40eb0c2acda9966c106d9125b82fc77e8fcd7 Mon Sep 17 00:00:00 2001 From: Mantas Date: Wed, 18 Nov 2026 10:09:23 +0200 Subject: [PATCH 02/11] feat: ship a test kit for code that calls this client Code that calls this gem had two ways to test itself. It could intercept HTTP at the socket, which ties a test to URLs and to Faraday, or stub the client's methods, which tests the stub. require 'zammad_api/test' gives a third: a stand-in Zammad behind a real client. ZammadAPI::Test.new answers from stubs instead of a network, and hands out a client through #client. Everything above the transport is the real thing - decoding, error mapping, records, change tracking, pagination - so a test goes down the path production does. A stub names a verb and a path and answers with a body and a status. Stubs for one request are consumed in order, and a later page of a list is answered the way an endpoint would answer it. Each request is recorded by value, with its query, body and headers, and #requests hands them back for assertions. A request nothing was stubbed for raises UnstubbedRequestError, and two stubs that describe one request equally well raise AmbiguousStubError. Both are StandardErrors outside ZammadAPI::Error, because they say the test is wrong, not that Zammad refused anything: inside the hierarchy, the `rescue ZammadAPI::Error` of the code under test would swallow a forgotten stub and report it as an API failure. --- lib/zammad_api/test.rb | 534 ++++++++++++++++++ spec/unit/zammad_api/test_spec.rb | 877 ++++++++++++++++++++++++++++++ 2 files changed, 1411 insertions(+) create mode 100644 lib/zammad_api/test.rb create mode 100644 spec/unit/zammad_api/test_spec.rb diff --git a/lib/zammad_api/test.rb b/lib/zammad_api/test.rb new file mode 100644 index 0000000..40a17c5 --- /dev/null +++ b/lib/zammad_api/test.rb @@ -0,0 +1,534 @@ +# frozen_string_literal: true + +require 'json' + +require_relative '../zammad_api' + +module ZammadAPI + # A stand-in Zammad, for testing code that calls this client. + # + # Stub the endpoints the code under test will reach, hand it {#client}, then + # assert against {#requests}. No HTTP stack is involved, so nothing has to be + # intercepted at the socket level and the responses come back through the + # same decoding, error mapping and record building as real ones. + # + # @example + # require 'zammad_api/test' + # + # zammad = ZammadAPI::Test.new + # zammad.stub(:get, 'api/v1/tickets/1', body: {id: 1, title: 'Help', state: 'open'}) + # zammad.stub(:put, 'api/v1/tickets/1', body: {id: 1, state: 'closed'}) + # + # TicketCloser.new(zammad.client).close(1) + # + # zammad.requests.last.verb # => :put + # zammad.requests.last.body # => {state: "closed"} + # + # @example An error path + # zammad.stub(:get, 'api/v1/tickets/9', status: 404, body: {error: 'not found'}) + # # the code under test sees ZammadAPI::NotFoundError + class Test + # Raised when the code under test reaches an endpoint that was not stubbed. + # + # The message lists what is stubbed, because the usual cause is a path that + # differs from the expected one. + # + # Deliberately outside {ZammadAPI::Error}: this says the test is wrong, not + # that Zammad refused something, and code under test is written to handle + # the latter. Inside the hierarchy, the `rescue ZammadAPI::Error` that this + # gem's own examples recommend swallowed a forgotten stub and reported it + # as an API failure - so a test asserting the error path passed green over + # a request it had never declared. + class UnstubbedRequestError < StandardError; end + + # Raised when two stubs describe one request equally well. + # + # Two stubs that name different query parameters can both match a request + # carrying all of them, and there is no honest way to rank them: a search + # stubbed once for its records and once for its count is matched by both + # when `count` sends the search term and +only_total_count+ together. The + # stand-in used to pick one, hand back the wrong body, consume the stub on + # the way past, and then report the endpoint as unstubbed - three + # confusing symptoms for one fixable declaration. + # + # Outside {ZammadAPI::Error} for the same reason as + # {UnstubbedRequestError}: it says the test is wrong, not that Zammad + # refused anything. + class AmbiguousStubError < StandardError; end + + # One request the code under test made. + # + # The verb is +verb+ rather than +method+, because a member named +method+ + # would shadow +Object#method+ on every recorded request. + # + # @!attribute [r] verb + # @return [Symbol] +:get+, +:post+, +:put+ or +:delete+ + # @!attribute [r] path + # @return [String] path relative to the instance URL + # @!attribute [r] query + # @return [Hash{String => String, Array}] query parameters as the + # client sent them, stringified the way the real transport sends them + # @!attribute [r] body + # @return [Hash, nil] the request payload + # @!attribute [r] headers + # @return [Hash{String => String}] the headers the call asked for, + # downcased and stringified the way the real transport sends them. + # Empty for a request that named none; the headers the client sets + # from its own configuration are not in here, and the +From+ scope has + # a member of its own below. + # @!attribute [r] on_behalf_of + # @return [String, nil] the +From+ scope in effect, stringified the way + # the +From+ header carries it + Request = Data.define(:verb, :path, :query, :body, :headers, :on_behalf_of) + + # @return [Config] the configuration the stand-in client reports + attr_reader :config + + # @param options [Hash] any option accepted by {Config}; the defaults are + # enough for a client that never opens a connection + def initialize(**options) + # Through the merge a client's own overrides go through, so that + # `Test.new(user: 'u', password: 'p')` replaces the stand-in token + # rather than being refused for naming a second way to authenticate. + @config = Config.new(**Config.merge_options({ url: 'https://zammad.test/', http_token: 'test-token' }, options)) + @stubs = {} + # The stub each scope of each endpoint last answered a first page with, + # which is the one a later page of the same read belongs to. See #take. + @served = {} + @requests = [] + @monitor = Mutex.new + @transport = Transport.new(self) + # Built once, and built straight onto the stand-in. Going through + # `Client.new` re-validated the config assembled one line above and then + # assembled a whole Faraday stack - auth, JSON, retries, adapter - only + # to swap it straight back out, which is the cost the comment here used + # to claim it was avoiding. A suite writing + # `let(:zammad) { ZammadAPI::Test.new }` paid it once per example. + @client = Client.build(@config, @transport) + end + + # A client that talks to this stand-in instead of to a Zammad. + # + # The same client every time; it holds no per-request state, and + # {Client#on_behalf_of} and {Client#with} return copies of their own. + # + # @return [Client] + attr_reader :client + + # Declares the response for one endpoint. + # + # Stubbing the same method and path again queues a second response: the + # first request gets the first, and the last stub answers every request + # after it. A collection read is one step of such a sequence however many + # pages it asks for, so three list stubs answer three reads in turn. A + # +query+ matches when every parameter it names is present in + # the request with that value, so a stub does not have to repeat the + # +expand+, +page+ and +per_page+ parameters the client adds itself. + # + # A stub that names a +query+ is more specific than one that does not, and + # answers ahead of it however they were declared. Queueing applies within + # a scope: two stubs carrying the same +query+ describe a sequence, while + # a scoped stub and a catch-all are two separate answers, each of which + # keeps answering. + # + # @param method [Symbol] +:get+, +:post+, +:put+ or +:delete+ + # @param path [String] path relative to the instance URL, leading slash + # optional + # @param status [Integer] HTTP status to answer with + # @param body [Hash, Array, String, nil] a Hash or Array is serialized to + # JSON bytes, anything else is served as it is. Whether those bytes are + # then decoded is decided by the content-type, the way a real response + # decides it - so a Hash served as +text/html+ comes back undecoded, and + # a JSON String served as +application/json+ comes back decoded. + # @param headers [Hash] response headers. Names and values are stringified + # and names downcased, the way a {Response} carries them. A Hash or Array + # body is given +content-type: application/json+ unless this says + # otherwise. + # @param query [Hash, nil] only answer requests carrying these parameters + # @return [self] + def stub(method, path, status: 200, body: nil, headers: {}, query: nil) + # Stringified here rather than on each request, so that a query the + # transport would refuse - a nil value - is reported against the line + # that wrote the stub instead of against whichever request reached it. + scope = query && ::ZammadAPI::Transport.stringify_query(query) + # A scope that names nothing matches every request, which is what a stub + # with no query at all is. Kept apart, the two were equally specific and + # `query: {}` collided with a catch-all as an ambiguous pair rather than + # joining it. + scope = nil if scope.nil? || scope.empty? + + # Refused here rather than stringified into something the wire could not + # carry, and for the same reason the query above is: the error names the + # line that wrote the stub. A nil `Content-Type` became `''`, which then + # beat the JSON default this method supplies and served a Hash body + # undecoded, so the test failed inside the code under test with nothing + # to say the stub was at fault. + headers.each do |name, value| + next if value.is_a?(String) || value.is_a?(Symbol) || value.is_a?(Numeric) + + raise ArgumentError, "header #{name} was stubbed as #{value.inspect}, and a response header is always text: pass a String" + end + + @monitor.synchronize do + (@stubs[key(method, path)] ||= []) << { + status: status, + body: body, + headers: response_headers(headers, body), + query: scope + } + end + self + end + + # Every request the code under test made, oldest first. + # + # @return [Array] + def requests = @monitor.synchronize { @requests.dup.freeze } + + # Forgets the stubs and the recorded requests. + # + # @return [self] + def reset + @monitor.synchronize do + @stubs.clear + @served.clear + @requests.clear + end + self + end + + # @return [Array] one +"GET api/v1/groups"+ per stubbed endpoint + def stubbed = @monitor.synchronize { @stubs.keys.map { |method, path| "#{method.to_s.upcase} #{path}" } } + + # Reads both collections under the monitor, and reaches for @stubs rather + # than {#stubbed} because the monitor is a plain Mutex and would deadlock + # on the way back in. The counts used to be read outside it, so printing a + # stand-in from a failure message or a debugger raced the thread under + # test appending to @requests - which is the one thing the monitor is here + # to prevent. + def inspect = @monitor.synchronize { "#<#{self.class.name} stubbed=#{@stubs.size} requests=#{@requests.size}>" } + + # Answers a request from the stubs, recording it first. + # + # This is the {Transport} interface, called by the client rather than by a + # test. + # + # @api private + # @return [Response] + # @raise [ResponseError] for a stubbed non-2xx status + # @raise [UnstubbedRequestError] when no stub matches + def answer(method, path, operation:, query: nil, body: nil, headers: nil, resource_class: nil, on_behalf_of: nil) + relative = ::ZammadAPI::Transport.relative_path(path) + # Through the real transport's own stringification, so that {Request#query} + # and {Request#headers} hold what a request would have carried rather + # than the raw Ruby values. A stand-in that records a different shape + # than the wire makes an assertion pass here and fail in production, or + # the other way round - and the header rules are where that matters + # most, because a reserved name or a non-text value is refused on the + # wire and would otherwise sail through here. + params = ::ZammadAPI::Transport.stringify_query(query || {}) + fields = ::ZammadAPI::Transport.stringify_headers(headers || {}) + # For the refusal alone: a body the wire could not carry is refused here + # too, before anything is recorded. What is recorded is the body as the + # test wrote it, which is what a test asserts against. + ::ZammadAPI::Transport.encode_body(body, operation: operation, resource_class: resource_class) + + stub = @monitor.synchronize do + @requests << Request.new(verb: method, path: relative, query: params, body: snapshot(body), headers: fields, on_behalf_of: on_behalf_of) + take(method, relative, params) + end + + raise UnstubbedRequestError, unstubbed_message(method, relative, params) if stub.nil? + + response = response_for(stub, params) + return response if response.success? + + raise ResponseError.build(response, operation: operation, resource_class: resource_class) + end + + private + + def key(method, path) = [method.to_sym, ::ZammadAPI::Transport.relative_path(path)] + + # The headers a stub answers with, downcased the way a {Response} carries + # them. + # + # A Hash or Array body is served as JSON, so it gets the content-type a + # real one would. {Transport#decode} always hands over a response whose + # headers name the type - it is what the decode branches on - while this + # set `json: true` directly and left the headers as written, so every + # stubbed response differed from the wire in a header a test can read. + # Code that branches on `response.headers['content-type']` passed against + # Zammad and failed against the stand-in, or the reverse, which is the + # divergence this kit exists to keep out. + # + # A caller's own content-type wins, so a test can still say the endpoint + # answered with something else. + def response_headers(headers, body) + # Values stringified as well as names. Only the name was normalised, so + # `headers: { 'X-Total-Count' => 7 }` reached the code under test as an + # Integer where the wire always carries "7": an assertion written the + # natural way passed against Zammad and failed here, or the reverse, and + # the one reader inside this gem had to tolerate both types to cope. + # Downcasing is what creates the collision, so it is refused here rather + # than merged: `{'Content-Type' => 'text/html', 'content-type' => + # 'application/json'}` kept whichever Hash order put last and dropped the + # other without a word - the same silent drop DuplicateKeys refuses for a + # query parameter, and here it decided whether the body was decoded. + normalized = DuplicateKeys + .normalize(headers, noun: 'header') { it.to_s.downcase } + .transform_values(&:to_s) + return normalized if !body.is_a?(Hash) && !body.is_a?(Array) + + { 'content-type' => 'application/json' }.merge(normalized) + end + + # A copy of the payload, frozen, for the record of what was sent. + # + # The caller's Hash used to be recorded by reference, so a test that built + # one payload, sent it, then changed it for a second call rewrote the + # first recorded request and asserted against a body that never went + # anywhere. `query` is already a fresh structure by the time it gets here, + # because the transport's stringification builds one; `body` is handed + # over untouched, and was the one shape left sharing state with the test. + def snapshot(value) = DeepCopy.frozen_copy(value) + + # Picks the stub that answers this request, and keeps the last one of its + # kind in place so that one stub can answer any number of requests while + # two describe a sequence. + # + # Sequencing runs within a query scope, not across the endpoint. Keying it + # on the last stub queued meant a query-scoped stub was consumed on its + # first use as soon as any other stub for the same verb and path existed + # behind it - the pair a `search(...).count` test needs - so the second + # count silently fell through to the records stub and walked the pages. + # + # A scope here is the exact set of parameters a stub names, not merely the + # fact that it names some. Grouped by whether a stub was scoped at all, + # two stubs carrying *different* scopes were read as a sequence and the + # first was consumed: stubbing a search once for its records and once for + # its count made `count` eat the records stub, hand back an Array where a + # count belonged, and then raise UnstubbedRequestError for a page that was + # stubbed all along. + # + # The most specific scope answers, counting the parameters it pins, so a + # stub written for one request still wins over a catch-all for the + # endpoint however they were declared. Scopes that tie are genuinely + # ambiguous and say so. + # + # A request for a later page does not move the sequence on. Every full + # read of a collection asks for the page after its last one, to learn + # that there is none, and that request used to take the next stub in the + # queue and serve it as the empty page {#paged_body} makes of it: with + # three list stubs A, B and C, three reads answered A, C and C, and B was + # never seen. The trailing request belongs to the read that made it, so it + # is answered by the stub that read's first page came from. + def take(method, path, params) + endpoint = key(method, path) + queued = @stubs[endpoint] + return nil if queued.nil? + + matching = queued.each_index.select { matches?(queued[it][:query], params) } + return nil if matching.empty? + + group = most_specific(queued, matching, method, path) + scope = queued[group.first][:query] + # The stub at the head of the queue is the fallback, for a later page + # that is the first thing asked: `page(3)` on a list nothing has read. + return @served[[endpoint, scope]] || queued[group.first] if later_page?(scope, params) + + @served[[endpoint, scope]] = group.one? ? queued[group.first] : queued.delete_at(group.first) + end + + # Whether a request asks for a page beyond the first of a list whose stub + # did not say what its pages hold. Such a stub is one page of records, so + # the request is the tail of a read rather than a read of its own. + def later_page?(scope, params) + return false if scope&.key?('page') + + ![nil, '1'].include?(params['page']) + end + + # The matching stubs that share the most specific scope, in the order they + # were declared. + # + # @raise [AmbiguousStubError] when two scopes are equally specific + def most_specific(queued, matching, method, path) + scopes = matching.group_by { queued[it][:query] } + depth = scopes.keys.to_h { [it, it.nil? ? 0 : it.size] } + best = depth.values.max + + winners = scopes.select { |scope, _| depth[scope] == best } + raise AmbiguousStubError, ambiguous_message(method, path, winners.keys) if winners.size > 1 + + winners.values.first + end + + def ambiguous_message(method, path, scopes) + rendered = scopes.map { "query: #{it.inspect}" }.join(' and ') + "#{method.to_s.upcase} #{path} is matched equally well by #{scopes.size} stubs (#{rendered}), " \ + 'and this stand-in will not guess which one you meant. Name the parameters that tell the requests apart ' \ + '- a count stub that also carries the search term is more specific than one that does not - or leave the ' \ + 'more general stub unscoped, which makes it a catch-all that answers only what the scoped ones do not.' + end + + # Both sides have been through the transport's own stringification, the + # stub's when it was declared. Comparing a raw value against a stringified + # one worked for a scalar - `1.to_s` is `"1"` either way - and could never + # match for an Array: `[1, 2].to_s` is `"[1, 2]"` while the recorded + # `["1", "2"].to_s` is `"[\"1\", \"2\"]"`. `ids`, `role_ids`, `group_ids` + # and `permissions` are all array-valued search parameters, so a stub + # scoped to any of them silently never answered and the request came back + # as unstubbed. + def matches?(expected, params) + return true if expected.nil? + + expected.all? { |name, value| params[name] == value } + end + + # The records a stub holds are one page of them, not the answer to every + # page. + # + # A collection walks until a page repeats, comes back short, or comes back + # empty. A stub that keeps serving the same records to every page trips + # the first of those, so the obvious way to stand in for a list endpoint - + # one `stub(:get, 'api/v1/groups', body: [...])` - made every full read of + # that collection raise PaginationError, and the only way to find that out + # was to hit it. Against a real Zammad the same code works, because page 2 + # comes back empty; the stand-in is what differed. + # + # So a stub that does not name a page answers one, and a request for any + # page after it gets an empty one. A stub that does name a page is left + # exactly as written - that is how a test says what the second page holds. + # + # A search stubbed with its total beside the records, the object Zammad + # answers `with_total_count` with, is a list as well: the page after it + # holds no records and reports the same total. Served again as written it + # was the repeated page above, for the one stub that says how many hits + # there are. + def paged_body(stub, params, body) + return body if !later_page?(stub[:query], params) + + case body + in Array then [] + in { records: Array, total_count: _ } then body.merge(records: []) + else body + end + end + + # Decoded by {Response.decode_body}, the rule {Transport#decode} reads, so + # that a stub answers the way the wire does. + # + # `json:` used to be set from the Ruby type of the stub's body, which made + # the content-type beside it decorative: a stub could say `text/html` and + # still hand back a decoded Hash with `json?` true, where Zammad gives the + # raw string and `decoded(:object)` raises ParseError. A test asserting + # that path passed here and failed in production, which is the divergence + # this kit exists to rule out. + # Paged after decoding, not before. Paging read the stub's body as written, + # which was the same thing only while a list could arrive as an Array - and + # once the content-type decided decoding, a list stubbed as a JSON string + # decoded to one and was never paged, so it answered every page with the + # same records and every full read of that collection raised + # PaginationError. Against Zammad the same code works, because page two + # comes back empty. + def response_for(stub, params) + raw = raw_body_for(stub[:body]) + body, json = Response.decode_body(stub[:headers]['content-type'], raw) + paged = paged_body(stub, params, body) + # Re-serialized only where paging replaced the body, so `raw_body` stays + # the bytes the stub was written with for every other response. + return build_response(stub, body, raw, json: json) if paged.equal?(body) + + build_response(stub, paged, JSON.generate(paged), json: json) + end + + # The bytes a stub's body would have arrived as. A Hash or Array is what a + # test writes when it means JSON, so that is what it is serialized to; + # anything else is already the body. + def raw_body_for(body) + case body + when Hash, Array then JSON.generate(body) + when nil then '' + else body.to_s + end + end + + # A copy, because the stub keeps serving after this response is built and + # Response is a value. Handing out the stub's own Hash made every response + # from one stub share it, so a test that wrote to `response.headers` - + # editing a content-type to check a decode path, say - rewrote the + # stand-in for every later request in the example. The real transport builds a fresh + # hash per response, and this exists to behave like it. + def build_response(stub, body, raw_body, json:) + Response.new(status: stub[:status], headers: stub[:headers].dup.freeze, body: body, raw_body: raw_body, json: json) + end + + # Where the endpoint is stubbed and only the query kept every stub from + # answering, the message says so, with the query the request carried + # and the scopes the stubs name. Listing the endpoint among what is + # stubbed, as it does for a wrong path, read as a contradiction: a read + # over stubs for pages 1 and 2 asks for page 3, and was told that + # `GET api/v1/users/search was not stubbed (stubbed: GET + # api/v1/users/search)`. + def unstubbed_message(method, path, params) + request = "#{method.to_s.upcase} #{path}" + scopes = @monitor.synchronize { @stubs[key(method, path)]&.map { it[:query] }&.uniq } + return unmatched_query_message(request, params, scopes) if scopes + + stubbed_endpoints = stubbed.empty? ? 'nothing is stubbed' : "stubbed: #{stubbed.join(', ')}" + "#{request} was not stubbed on this #{self.class.name} (#{stubbed_endpoints})" + end + + def unmatched_query_message(request, params, scopes) + message = "#{request} with query #{params.inspect} was not stubbed on this #{self.class.name}: " \ + "its stubs answer only #{scopes.map { "query: #{it.inspect}" }.join(', ')}." + return message if !params.key?('page') || !scopes.all? { it&.key?('page') } + + "#{message} A read asks for the page after the last one it was served, to learn that there are no more: " \ + 'stub that page as well, with body: [], or leave page out of the scope, and the stub serves its records as one ' \ + 'page and an empty page after it.' + end + + # Routes the client's requests to {Test#answer}, and carries the + # +on_behalf_of+ scope the way the real transport does. + # + # @api private + class Transport + include ::ZammadAPI::Transport::Verbs + + attr_reader :test, :on_behalf_of + + # The scope is stringified, copied and checked by the real transport's + # own rule, so that a recorded scope is what a request would have + # carried. Here rather than in {#with_on_behalf_of} alone, which left + # one built directly holding whatever it was given. + def initialize(test, on_behalf_of: nil) + @test = test + @on_behalf_of = ::ZammadAPI::Transport.stringify_on_behalf_of(on_behalf_of) + end + + def config = test.config + + def with_on_behalf_of(identifier) = self.class.new(test, on_behalf_of: identifier) + + # {Client#with} re-validates the options and hands them here. There is + # no connection to rebuild, and the derived client reports the derived + # config itself, so the stand-in keeps answering. + def with_config(_config) = self + + def request(method, path, operation:, query: nil, body: nil, headers: nil, resource_class: nil) + test.answer( + method, + path, + operation: operation, + query: query, + body: body, + headers: headers, + resource_class: resource_class, + on_behalf_of: on_behalf_of + ) + end + end + end +end diff --git a/spec/unit/zammad_api/test_spec.rb b/spec/unit/zammad_api/test_spec.rb new file mode 100644 index 0000000..9d639e8 --- /dev/null +++ b/spec/unit/zammad_api/test_spec.rb @@ -0,0 +1,877 @@ +# frozen_string_literal: true + +require 'zammad_api/test' + +RSpec.describe ZammadAPI::Test do + subject(:zammad) { described_class.new } + + let(:client) { zammad.client } + + describe '#client' do + it 'is a real client' do + expect(client).to be_a(ZammadAPI::Client) + end + + it 'opens no connection at all' do + zammad.stub(:get, 'api/v1/groups/1', body: { id: 1 }) + client.groups.find(1) + + expect(a_request(:any, //)).not_to have_been_made + end + + it 'reports the stand-in configuration' do + expect(client.config.url).to eq('https://zammad.test/') + end + + it 'reports the very configuration the stand-in was built with' do + expect(client.config).to be(zammad.config) + end + + # Going through Client.new assembled a Faraday stack - auth, JSON, + # retries, adapter - only for it to be swapped straight back out, once per + # stand-in. + it 'builds no HTTP stack on the way to the stand-in transport' do + allow(ZammadAPI::Transport).to receive(:new).and_call_original + + described_class.new + + expect(ZammadAPI::Transport).not_to have_received(:new) + end + + # The stand-in carries a token of its own, so credentials handed to it + # replace that one rather than being refused as a second scheme. + it 'accepts credentials of another kind in place of its own token' do + zammad = described_class.new(user: 'u', password: 'p') + expect(zammad.client.config.authentication_scheme).to eq(:basic) + end + + it 'accepts configuration overrides' do + expect(described_class.new(url: 'https://other.test/').client.config.url).to eq('https://other.test/') + end + + it 'is the same client every time, rather than a new HTTP stack per call' do + expect(zammad.client).to equal(zammad.client) + end + + describe 'a client derived with #with' do + it 'still answers from the stand-in instead of opening a connection' do + zammad.stub(:get, 'api/v1/groups/1', body: { id: 1, name: 'Support' }) + + expect(zammad.client.with(timeout: 5).groups.find(1).name).to eq('Support') + expect(a_request(:any, //)).not_to have_been_made + end + + it 'reports the derived option' do + expect(zammad.client.with(timeout: 5).config.timeout).to eq(5) + end + + it 'keeps an on_behalf_of scope' do + zammad.stub(:get, 'api/v1/groups/1', body: { id: 1 }) + zammad.client.on_behalf_of('agent@example.com').with(timeout: 5).groups.find(1) + + expect(zammad.requests.last.on_behalf_of).to eq('agent@example.com') + end + end + end + + describe '#stub' do + it 'answers a find with a record' do + zammad.stub(:get, 'api/v1/groups/1', body: { id: 1, name: 'Users' }) + + expect(client.groups.find(1).name).to eq('Users') + end + + it 'builds records that behave like fetched ones' do + zammad.stub(:get, 'api/v1/groups/1', body: { id: 1, name: 'Users' }) + + group = client.groups.find(1) + expect(group).to be_persisted + expect { group.attributes[:name] = 'x' }.to raise_error(FrozenError) + end + + it 'answers a collection with every page' do + zammad.stub(:get, 'api/v1/groups', body: [{ id: 1, name: 'Users' }, { id: 2, name: 'Support' }], query: { page: 1 }) + zammad.stub(:get, 'api/v1/groups', body: [], query: { page: 2 }) + + expect(client.groups.pluck(:name)).to eq(%w[Users Support]) + end + + it 'ignores a leading slash on the stub' do + zammad.stub(:get, '/api/v1/groups/1', body: { id: 1 }) + + expect(client.groups.find(1).id).to eq(1) + end + + # The real transport refuses this, so a stand-in that answered it would + # let a test pass over a request production never sends. + it 'refuses an absolute URL the way the real transport does' do + expect { client.get('https://other.example/collect') } + .to raise_error(ArgumentError, /a request path is relative to the instance URL/) + end + + it 'refuses a path that cannot be read as a URL the way the real transport does' do + expect { client.get('api/v1/tägs') }.to raise_error(ArgumentError, /cannot be read as one: it holds a character outside ASCII/) + expect(zammad.requests).to be_empty + end + + it 'records nothing for a path it refuses' do + expect { client.get('https://other.example/collect') }.to raise_error(ArgumentError) + expect(zammad.requests).to be_empty + end + + # The same for a body the wire could not carry: a stand-in that took it + # would let a test pass over a save production raises on. + it 'refuses a body that cannot be encoded as JSON, the way the real transport does' do + zammad.stub(:post, 'api/v1/groups', body: { id: 1 }) + + expect { client.groups.create(name: 'Support', weight: Float::NAN) } + .to raise_error(ZammadAPI::Error, /the request body cannot be encoded as JSON/) + expect(zammad.requests).to be_empty + end + + # And for a query a query string could not carry as it was written. + it 'refuses a list of Hashes Rails would read as one, the way the real transport does' do + zammad.stub(:get, 'api/v1/roles', body: []) + + expect { client.get('api/v1/roles', query: { list: [{ a: 1 }, { b: 2 }] }) } + .to raise_error(ArgumentError, /Rails would read the two as one/) + expect(zammad.requests).to be_empty + end + + it 'raises the mapped error class for a non-2xx status' do + zammad.stub(:get, 'api/v1/groups/1', status: 404, body: { error: 'not found' }) + + expect { client.groups.find(1) }.to raise_error(ZammadAPI::NotFoundError, /not found/) + end + + it 'raises a validation error that save reports as false' do + zammad.stub(:post, 'api/v1/groups', status: 422, body: { error: 'Name is required' }) + + group = client.groups.new(name: '') + expect(group.save).to be(false) + expect(group.error.server_message).to eq('Name is required') + end + + it 'serves a non-JSON body untouched, e.g. an attachment' do + zammad.stub(:get, 'api/v1/ticket_attachment/1/2/3', body: 'binary-ish') + + attachment = ZammadAPI::Resources::TicketArticleAttachment + .new(zammad.client.tickets.new.transport, id: 3, ticket_id: 1, article_id: 2) + + expect(attachment.download).to eq('binary-ish') + end + + it 'returns itself, so stubs can be chained' do + expect(zammad.stub(:get, 'api/v1/groups', body: [])).to be(zammad) + end + + it 'accepts string keys in the body' do + zammad.stub(:get, 'api/v1/groups/1', body: { 'id' => 1, 'name' => 'Users' }) + + expect(client.groups.find(1).name).to eq('Users') + end + + it 'exposes response headers' do + zammad.stub(:get, 'api/v1/groups', body: [], headers: { 'X-Total-Count' => '7' }) + + expect(client.get('api/v1/groups').headers['x-total-count']).to eq('7') + end + + # The stand-in exists so that the code under test cannot tell it from the + # real transport, and it carried its own copy of the verb loop - so a fifth + # verb added to one would have left the other unable to answer it. + it 'answers every verb the real transport answers' do + expect(ZammadAPI::Test::Transport.new(zammad)) + .to respond_to(*ZammadAPI::Transport::Verbs.instance_methods) + end + + # Transport#decode always hands over a response whose headers name the + # type - it is what the decode branches on - while this set `json: true` + # directly and left the headers as written. Code that branches on + # `response.headers['content-type']` passed against Zammad and failed + # against the stand-in, or the reverse. + it 'serves a JSON body with the content-type a real response carries' do + zammad.stub(:get, 'api/v1/groups', body: []) + + expect(client.get('api/v1/groups').headers['content-type']).to eq('application/json') + end + + it 'serves an object body with the same content-type' do + zammad.stub(:get, 'api/v1/groups/1', body: { id: 1 }) + + expect(client.get('api/v1/groups/1').headers['content-type']).to eq('application/json') + end + + it 'lets a test say the endpoint answered with something else' do + zammad.stub(:get, 'api/v1/groups', body: [], headers: { 'Content-Type' => 'application/json; charset=utf-8' }) + + expect(client.get('api/v1/groups').headers['content-type']).to eq('application/json; charset=utf-8') + end + + # The header used to be decorative: `json:` came from the Ruby type of the + # stub's body, so a stub could say `text/html` and still hand back a + # decoded Hash, where Zammad gives the raw string and `decoded` raises. + context 'when a stub declares a type that is not JSON' do + before { zammad.stub(:get, 'api/v1/groups/1', body: { id: 1 }, headers: { 'Content-Type' => 'text/html' }) } + + it 'does not decode the body' do + expect(client.get('api/v1/groups/1')).not_to be_json + end + + it 'hands back the raw body Zammad would have sent' do + expect(client.get('api/v1/groups/1').body).to eq('{"id":1}') + end + + it 'fails the way a real one would when a record is read from it' do + expect { client.groups.find(1) }.to raise_error(ZammadAPI::ParseError) + end + end + + # A nil Content-Type stringified to '', which then beat the JSON default + # this kit supplies and served a Hash body undecoded - so the test failed + # inside the code under test with nothing to say the stub was at fault. + it 'refuses two spellings of one header rather than dropping a value' do + expect { zammad.stub(:get, 'api/v1/groups', body: [], headers: { 'Content-Type' => 'text/html', 'content-type' => 'application/json' }) } + .to raise_error(ArgumentError, /header content-type was given twice/) + end + + it 'refuses a header value the wire could not carry' do + expect { zammad.stub(:get, 'api/v1/groups', body: [], headers: { 'Content-Type' => nil }) } + .to raise_error(ArgumentError, /header Content-Type was stubbed as nil/) + end + + it 'names what a response header has to be' do + expect { zammad.stub(:get, 'api/v1/groups', body: [], headers: { 'X-Total-Count' => [7] }) } + .to raise_error(ArgumentError, /a response header is always text: pass a String/) + end + + # Only the name used to be normalised, so a count written as an Integer + # reached the code under test as one, where the wire always carries "7". + it 'carries a header value as the String the wire would have sent' do + zammad.stub(:get, 'api/v1/groups', body: [], headers: { 'X-Total-Count' => 7 }) + + expect(client.get('api/v1/groups').headers['x-total-count']).to eq('7') + end + + # Paging read the stub's body as written, which was the same thing only + # while a list could arrive as an Array. Once the content-type decided + # decoding, a list stubbed as a JSON string decoded to one and was never + # paged, so it answered every page with the same records and every full + # read raised PaginationError - where Zammad answers page two empty. + it 'pages a list stubbed as a JSON string the way it pages an Array' do + zammad.stub(:get, 'api/v1/groups', body: '[{"id":1,"name":"a"},{"id":2,"name":"b"}]', headers: { 'Content-Type' => 'application/json' }) + + expect(client.groups.all.map(&:name)).to eq(%w[a b]) + end + + it 'answers a later page of a string-bodied list as an endpoint out of records would' do + zammad.stub(:get, 'api/v1/groups', body: '[{"id":1}]', headers: { 'Content-Type' => 'application/json' }) + + expect(client.get('api/v1/groups', query: { page: 2 }).body).to eq([]) + end + + it 'keeps the raw body of a page it did not replace' do + zammad.stub(:get, 'api/v1/groups/1', body: '{"id":1}', headers: { 'Content-Type' => 'application/json' }) + + expect(client.get('api/v1/groups/1').raw_body).to eq('{"id":1}') + end + + it 'decodes a string body a stub declares as JSON' do + zammad.stub(:get, 'api/v1/groups/1', body: '{"id":1,"name":"Users"}', headers: { 'Content-Type' => 'application/json' }) + + expect(client.groups.find(1).name).to eq('Users') + end + + it 'claims no content-type for a body it does not serve as JSON' do + zammad.stub(:get, 'api/v1/groups/1/avatar', body: 'binary') + + expect(client.get('api/v1/groups/1/avatar').headers).not_to have_key('content-type') + end + + # The stub keeps serving after a response is built, and Response is a + # value. Handing out the stub's own Hash made every response from one stub + # share it, so writing to `response.headers` in one example rewrote the + # stand-in for every later request in it. + it 'gives each response its own headers rather than the stub\'s' do + zammad.stub(:get, 'api/v1/groups', body: [], headers: { 'X-Total-Count' => '7' }) + + first = client.get('api/v1/groups') + second = client.get('api/v1/groups') + + expect(first.headers).not_to be(second.headers) + end + + it 'hands out headers a caller cannot write through' do + zammad.stub(:get, 'api/v1/groups', body: [], headers: { 'X-Total-Count' => '7' }) + + expect { client.get('api/v1/groups').headers['x-total-count'] = '999' }.to raise_error(FrozenError) + end + + describe 'a sequence' do + it 'serves stubs in the order they were declared' do + zammad.stub(:get, 'api/v1/groups/1', body: { id: 1, name: 'First' }) + zammad.stub(:get, 'api/v1/groups/1', body: { id: 1, name: 'Second' }) + + expect(client.groups.find(1).name).to eq('First') + expect(client.groups.find(1).name).to eq('Second') + end + + it 'keeps answering with the last one' do + zammad.stub(:get, 'api/v1/groups/1', body: { id: 1, name: 'First' }) + zammad.stub(:get, 'api/v1/groups/1', body: { id: 1, name: 'Second' }) + + 3.times { client.groups.find(1) } + expect(client.groups.find(1).name).to eq('Second') + end + + it 'reuses a single stub for any number of requests' do + zammad.stub(:get, 'api/v1/groups/1', body: { id: 1, name: 'Users' }) + + expect(Array.new(3) { client.groups.find(1).name }).to eq(%w[Users Users Users]) + end + end + + describe 'query matching' do + it 'matches a stub that names a subset of the parameters' do + zammad.stub(:get, 'api/v1/groups', body: [{ id: 1 }], query: { sort_by: 'name' }) + + expect(client.groups.order(:name).first.id).to eq(1) + end + + it 'does not answer a request without those parameters' do + zammad.stub(:get, 'api/v1/groups', body: [{ id: 1 }], query: { sort_by: 'name' }) + + expect { client.groups.all.to_a }.to raise_error(described_class::UnstubbedRequestError) + end + + it 'ignores the parameters the client adds itself' do + zammad.stub(:get, 'api/v1/groups', body: [], query: { sort_by: 'name' }) + + expect { client.groups.order(:name).to_a }.not_to raise_error + end + + it 'keeps answering when a catch-all for the same endpoint follows it' do + zammad.stub(:get, 'api/v1/groups/search', body: { total_count: 42 }, query: { only_total_count: true }) + zammad.stub(:get, 'api/v1/groups/search', body: [{ id: 1 }]) + + expect(Array.new(3) { client.groups.search('x').count }).to eq([42, 42, 42]) + end + + it 'leaves the catch-all answering the requests it does not match' do + zammad.stub(:get, 'api/v1/groups/search', body: { total_count: 42 }, query: { only_total_count: true }) + zammad.stub(:get, 'api/v1/groups/search', body: [], query: { page: 2 }) + zammad.stub(:get, 'api/v1/groups/search', body: [{ id: 1 }]) + + expect(client.groups.search('x').count).to eq(42) + expect(client.groups.search('x').map(&:id)).to eq([1]) + expect(client.groups.search('x').count).to eq(42) + end + + it 'matches an array-valued parameter' do + zammad.stub(:get, 'api/v1/users/search', body: [{ id: 1 }], query: { ids: [1, 2], page: 1 }) + zammad.stub(:get, 'api/v1/users/search', body: [], query: { ids: [1, 2], page: 2 }) + + expect(client.users.search('x', ids: [1, 2]).map(&:id)).to eq([1]) + end + + it 'reports a nil query value against the stub that wrote it' do + expect { zammad.stub(:get, 'api/v1/users/search', body: [], query: { ids: nil }) } + .to raise_error(ArgumentError, /query parameter ids is nil/) + end + + it 'does not match an array whose values differ' do + zammad.stub(:get, 'api/v1/users/search', body: [{ id: 1 }], query: { ids: [1, 2] }) + + expect { client.users.search('x', ids: [3]).to_a } + .to raise_error(described_class::UnstubbedRequestError) + end + + it 'answers ahead of a catch-all declared before it' do + zammad.stub(:get, 'api/v1/groups/search', body: [{ id: 1 }]) + zammad.stub(:get, 'api/v1/groups/search', body: { total_count: 42 }, query: { only_total_count: true }) + + expect(client.groups.search('x').count).to eq(42) + end + + it 'still sequences two stubs that share a scope' do + zammad.stub(:get, 'api/v1/groups', body: [{ id: 1 }], query: { sort_by: 'name' }) + zammad.stub(:get, 'api/v1/groups', body: [{ id: 2 }], query: { sort_by: 'name' }) + + expect(client.groups.all.order(:name).page(1, per_page: 1).map(&:id)).to eq([1]) + expect(client.groups.all.order(:name).page(1, per_page: 1).map(&:id)).to eq([2]) + expect(client.groups.all.order(:name).page(1, per_page: 1).map(&:id)).to eq([2]) + end + end + end + + describe 'an unstubbed request' do + it 'raises rather than returning something empty' do + expect { client.groups.find(1) }.to raise_error(described_class::UnstubbedRequestError) + end + + it 'names the request that was not stubbed' do + expect { client.groups.find(1) } + .to raise_error(%r{GET api/v1/groups/1 was not stubbed}) + end + + it 'says so when nothing at all is stubbed' do + expect { client.groups.find(1) }.to raise_error(/nothing is stubbed/) + end + + it 'lists what is stubbed, because a wrong path is the usual cause' do + zammad.stub(:get, 'api/v1/groups/2', body: { id: 2 }) + + expect { client.groups.find(1) }.to raise_error(%r{stubbed: GET api/v1/groups/2}) + end + + # Listing the endpoint among what is stubbed read as a contradiction. + context 'when the endpoint is stubbed for other queries' do + before do + zammad.stub(:get, 'api/v1/users/search', body: [{ id: 1 }], query: { page: 1 }) + zammad.stub(:get, 'api/v1/users/search', body: [{ id: 2 }], query: { page: 2 }) + end + + it 'names the query the request carried and the scopes its stubs answer' do + expect { client.users.search('x').to_a }.to raise_error( + described_class::UnstubbedRequestError, + %r{GET api/v1/users/search with query \{.*"page" => "3".*\} was not stubbed .*: its stubs answer only query: \{"page" => "1"\}, query: \{"page" => "2"\}\.} + ) + end + + it 'says that a read asks for the page after its last one' do + expect { client.users.search('x').to_a } + .to raise_error(described_class::UnstubbedRequestError, /A read asks for the page after the last one it was served/) + end + + it 'says nothing about pages where the scopes do not name one' do + zammad.reset.stub(:get, 'api/v1/users/search', body: [], query: { ids: [1] }) + + expect { client.users.search('x', ids: [2]).to_a } + .to raise_error(described_class::UnstubbedRequestError) { |error| expect(error.message).not_to include('page after') } + end + end + + it 'is outside ZammadAPI::Error, so code under test cannot rescue it as an API failure' do + expect(described_class::UnstubbedRequestError.ancestors).not_to include(ZammadAPI::Error) + expect(described_class::UnstubbedRequestError.ancestors).to include(StandardError) + end + + it 'escapes a rescue of the gem\'s errors, the way the examples write one' do + zammad.stub(:get, 'api/v1/groups/2', body: { id: 2 }) + + caller_with_a_rescue = lambda do + client.groups.find(1) + rescue ZammadAPI::Error + :handled_as_an_api_failure + end + + expect { caller_with_a_rescue.call }.to raise_error(described_class::UnstubbedRequestError) + end + end + + describe '#requests' do + before do + zammad.stub(:get, 'api/v1/groups/1', body: { id: 1, name: 'Users' }) + zammad.stub(:put, 'api/v1/groups/1', body: { id: 1, name: 'Renamed' }) + end + + it 'records the verb and path' do + client.groups.find(1) + + expect(zammad.requests.last.verb).to eq(:get) + expect(zammad.requests.last.path).to eq('api/v1/groups/1') + end + + it 'records only what a save actually sends' do + client.groups.find(1).update!(name: 'Renamed') + + expect(zammad.requests.last.body).to eq({ name: 'Renamed' }) + end + + # Recorded by reference, a test that built one payload, sent it, then + # changed it for a second call rewrote the first recorded request and + # asserted against a body that never went anywhere. + it 'records the body as it was sent, not as the test left it afterwards' do + zammad.stub(:post, 'api/v1/groups', body: { id: 2 }) + payload = { name: 'Support', note: { internal: 'yes' } } + client.post('api/v1/groups', body: payload) + + payload[:name] = 'Mutated' + payload[:note][:internal] = 'no' + + expect(zammad.requests.last.body).to eq({ name: 'Support', note: { internal: 'yes' } }) + end + + it 'hands out a recorded body that cannot be written through' do + zammad.stub(:post, 'api/v1/groups', body: { id: 2 }) + client.post('api/v1/groups', body: { name: 'Support' }) + + expect(zammad.requests.last.body).to be_frozen + end + + it 'records the query parameters the client sent' do + client.groups.find(1) + + expect(zammad.requests.last.query).to eq({ 'expand' => 'true' }) + end + + it 'records them stringified, the way the transport sends them' do + zammad.stub(:get, 'api/v1/groups', body: [{ id: 1 }]) + client.groups.all.page(2, per_page: 50).to_a + + expect(zammad.requests.last.query) + .to eq({ 'expand' => 'true', 'page' => '2', 'per_page' => '50' }) + end + + it 'rejects a nil query value the way the transport does' do + expect { client.get('api/v1/groups', query: { sort_by: nil }) } + .to raise_error(ArgumentError, /query parameter sort_by is nil/) + end + + it 'records requests oldest first' do + client.groups.find(1).update!(name: 'Renamed') + + expect(zammad.requests.map(&:verb)).to eq(%i[get put]) + end + + it 'records an on_behalf_of scope' do + client.on_behalf_of('agent@example.com').groups.find(1) + + expect(zammad.requests.last.on_behalf_of).to eq('agent@example.com') + end + + it 'records an integer user id the way the wire carries it' do + client.on_behalf_of(42).groups.find(1) + + expect(zammad.requests.last.on_behalf_of).to eq('42') + end + + it 'records the scope a client was given, not what its string became afterwards' do + login = +'agent@example.com' + scoped = client.on_behalf_of(login) + login.replace('admin@example.com') + scoped.groups.find(1) + + expect(zammad.requests.last.on_behalf_of).to eq('agent@example.com') + end + + it 'leaves on_behalf_of nil for an unscoped client' do + client.groups.find(1) + + expect(zammad.requests.last.on_behalf_of).to be_nil + end + + # The stand-in carries the scope by the real transport's rule, so it + # refuses one the wire would carry as no scope at all. + it 'refuses a blank scope reached through the transport, the way the real transport does' do + expect { client.instance_variable_get(:@transport).with_on_behalf_of(' ') } + .to raise_error(ArgumentError, /on_behalf_of needs the login/) + end + + it 'refuses one it is built with directly' do + expect { ZammadAPI::Test::Transport.new(zammad, on_behalf_of: ' ') }.to raise_error(ArgumentError, /on_behalf_of needs the login/) + end + + it 'holds one it is built with as the text the header carries' do + expect(ZammadAPI::Test::Transport.new(zammad, on_behalf_of: 7).on_behalf_of).to eq('7') + end + + # Through the real transport's own rules, so that a stand-in cannot accept + # a header the wire would refuse or record it in a shape the wire would + # not carry. + it 'records the headers a raw request asked for' do + zammad.stub(:get, 'api/v1/roles', body: []) + client.get('api/v1/roles', headers: { 'Accept-Language' => 'de-de' }) + + expect(zammad.requests.last.headers).to eq('accept-language' => 'de-de') + end + + it 'records a header value the way the wire would carry it' do + zammad.stub(:get, 'api/v1/roles', body: []) + client.get('api/v1/roles', headers: { 'X-Retry' => 3 }) + + expect(zammad.requests.last.headers).to eq('x-retry' => '3') + end + + it 'leaves the headers empty for a request that named none' do + client.groups.find(1) + + expect(zammad.requests.last.headers).to eq({}) + end + + it 'refuses a header the real transport would refuse' do + expect { client.get('api/v1/roles', headers: { 'Authorization' => 'Token other' }) } + .to raise_error(ArgumentError, /header authorization is set by this client/) + end + + it 'records a request that was not stubbed, so the failure can be inspected' do + expect { client.groups.find(2) }.to raise_error(described_class::UnstubbedRequestError) + expect(zammad.requests.map(&:path)).to eq(['api/v1/groups/2']) + end + + it 'hands out a frozen list' do + expect { zammad.requests << :nonsense }.to raise_error(FrozenError) + end + + it 'is recorded from several threads without losing any' do + threads = Array.new(4) { Thread.new { 5.times { client.groups.find(1) } } } + threads.each(&:join) + + expect(zammad.requests.size).to eq(20) + end + end + + describe '#reset' do + it 'forgets the stubs' do + zammad.stub(:get, 'api/v1/groups/1', body: { id: 1 }) + zammad.reset + + expect { client.groups.find(1) }.to raise_error(described_class::UnstubbedRequestError) + end + + it 'forgets the recorded requests' do + zammad.stub(:get, 'api/v1/groups/1', body: { id: 1 }) + client.groups.find(1) + + expect(zammad.reset.requests).to be_empty + end + end + + describe '#inspect' do + it 'reports the stubs and the requests' do + zammad.stub(:get, 'api/v1/groups', body: []) + client.groups.all.to_a + + expect(zammad.inspect).to eq('#') + end + + # The request count used to be read outside the monitor, so printing a + # stand-in from a failure message or a debugger raced a thread under test + # appending to it - which is the one thing the monitor is here to prevent. + it 'reads the recorded requests under the monitor' do + zammad.stub(:get, 'api/v1/groups', body: []) + writers = Array.new(4) { Thread.new { 25.times { client.groups.all.to_a } } } + readers = Array.new(4) { Thread.new { 25.times { zammad.inspect } } } + + expect { (writers + readers).each(&:join) }.not_to raise_error + expect(zammad.requests.size).to eq(100) + end + end + + # A collection walks until a page repeats, comes back short, or comes back + # empty. A stub that served the same records to every page tripped the + # first of those, so the obvious way to stand in for a list endpoint made + # every full read of it raise PaginationError - against a real Zammad the + # same code works, because page 2 comes back empty. + describe 'a list endpoint stubbed once' do + subject(:zammad) { described_class.new } + + let(:client) { zammad.client } + + before { zammad.stub(:get, 'api/v1/groups', body: [{ id: 1, name: 'a' }, { id: 2, name: 'b' }]) } + + it 'reads the whole collection without a second stub' do + expect(client.groups.all.map(&:id)).to eq([1, 2]) + end + + it 'counts it' do + expect(client.groups.all.count).to eq(2) + end + + it 'plucks from it' do + expect(client.groups.all.pluck(:name)).to eq(%w[a b]) + end + + it 'answers page 1 with the records it holds' do + expect(client.groups.all.page(1).map(&:id)).to eq([1, 2]) + end + + it 'answers a later page as an endpoint out of records would' do + expect(client.groups.all.page(2).map(&:id)).to eq([]) + end + + it 'stops walking rather than reporting the stand-in as a broken paginator' do + expect { client.groups.all.to_a }.not_to raise_error + end + end + + # The object a Zammad from 6.5.1 on answers a walked search with. It is a + # list too, so the page after it holds no records - and reports the same + # total, which is what a walk reads to tell that page from the end. + describe 'a search stubbed once with its total beside the records' do + subject(:zammad) { described_class.new } + + let(:client) { zammad.client } + + it 'reads the whole search without a second stub' do + zammad.stub(:get, 'api/v1/users/search', body: { records: [{ id: 1 }, { id: 2 }], total_count: 2 }) + + expect(client.users.search('smith').map(&:id)).to eq([1, 2]) + end + + it 'answers a later page with no records and the same total' do + zammad.stub(:get, 'api/v1/users/search', body: { records: [{ id: 1 }, { id: 2 }], total_count: 2 }) + + expect(client.get('api/v1/users/search', query: { query: 'smith', page: 2 }).body).to eq(records: [], total_count: 2) + end + + it 'answers page 1 as it was written' do + zammad.stub(:get, 'api/v1/users/search', body: { records: [{ id: 1 }, { id: 2 }], total_count: 2 }) + + expect(client.get('api/v1/users/search', query: { query: 'smith', page: 1 }).body).to eq(records: [{ id: 1 }, { id: 2 }], total_count: 2) + end + + # The stub holds two records and says there are five hundred hits, so the + # walk reads on, a page of two hundred at a time, until it has covered + # them: the page it was served, and two that hold nothing. + it 'is read on past, where the total says there are hits beyond the stub' do + zammad.stub(:get, 'api/v1/users/search', body: { records: [{ id: 1 }, { id: 2 }], total_count: 500 }) + + expect(client.users.search('smith').map(&:id)).to eq([1, 2]) + expect(zammad.requests.map { it.query['page'] }).to eq(%w[1 2 3]) + end + + it 'records the parameter a walked search asks for the total with' do + zammad.stub(:get, 'api/v1/users/search', body: []) + client.users.search('smith').to_a + + expect(zammad.requests.last.query).to include('with_total_count' => 'true') + end + + it 'leaves an object that is not a counted list as it was written' do + zammad.stub(:get, 'api/v1/settings', body: { records: 'none' }) + + expect(client.get('api/v1/settings', query: { page: 2 }).body).to eq(records: 'none') + end + end + + # Every full read asks for the page after its last one, and that request + # used to take the next stub in the queue and serve it as an empty page: + # three stubs answered three reads with the first, the third and the third. + describe 'a list endpoint stubbed as a sequence' do + subject(:zammad) { described_class.new } + + let(:client) { zammad.client } + + def names = client.groups.all.map(&:name) + + before do + %w[A B C].each { zammad.stub(:get, 'api/v1/groups', body: [{ id: 1, name: it }]) } + end + + it 'answers each read with the next stub' do + expect(Array.new(3) { names }).to eq([['A'], ['B'], ['C']]) + end + + it 'keeps answering with the last one' do + 3.times { names } + expect(names).to eq(['C']) + end + + it 'spends one stub on a read, however many pages the read asks for' do + names + expect(zammad.requests.map { it.query['page'] }).to eq(%w[1 2]) + expect(names).to eq(['B']) + end + + it 'answers the trailing page from the stub the read began with, not the next one' do + zammad.reset + zammad.stub(:get, 'api/v1/groups', body: [{ id: 1, name: 'A' }]) + zammad.stub(:get, 'api/v1/groups', status: 500, body: { error: 'down' }) + + expect(names).to eq(['A']) + expect { names }.to raise_error(ZammadAPI::ServerError) + end + + it 'does not spend a stub on a later page asked for first' do + expect(client.groups.all.page(3).to_a).to eq([]) + expect(names).to eq(['A']) + end + + it 'spends one stub on a read sized for a single record' do + expect(Array.new(3) { client.groups.first.name }).to eq(%w[A B C]) + end + + it 'starts over after a reset' do + names + zammad.reset + zammad.stub(:get, 'api/v1/groups', body: [{ id: 2, name: 'D' }]) + + expect(Array.new(2) { names }).to eq([['D'], ['D']]) + end + + it 'sequences a scoped list the same way' do + zammad.reset + %w[A B].each { zammad.stub(:get, 'api/v1/groups/search', body: [{ id: 1, name: it }], query: { query: 'x' }) } + + expect(Array.new(2) { client.groups.search('x').map(&:name) }).to eq([['A'], ['B']]) + end + end + + describe 'a list endpoint whose pages are stubbed by hand' do + subject(:zammad) { described_class.new } + + let(:client) { zammad.client } + + # A stub that names a page is left exactly as written - that is how a test + # says what the second page holds. + it 'serves each page as declared' do + zammad.stub(:get, 'api/v1/groups', body: [{ id: 1 }], query: { page: 1 }) + zammad.stub(:get, 'api/v1/groups', body: [{ id: 2 }], query: { page: 2 }) + zammad.stub(:get, 'api/v1/groups', body: [], query: { page: 3 }) + + expect(client.groups.all.map(&:id)).to eq([1, 2]) + end + + it 'keeps a body that is not a list alone' do + zammad.stub(:get, 'api/v1/groups/1', body: { id: 1, name: 'a' }) + + expect(client.groups.find(1).name).to eq('a') + end + end + + # Two stubs naming different parameters both match a request carrying all of + # them. Grouped only by whether they were scoped at all, they were read as a + # sequence and the first was consumed: the count ate the records stub, + # handed back an Array where a count belonged, and then reported the + # endpoint as unstubbed. + describe 'two stubs that describe one request equally well' do + subject(:zammad) { described_class.new } + + let(:client) { zammad.client } + + before do + zammad.stub(:get, 'api/v1/tickets/search', body: [{ id: 1 }], query: { query: 'foo' }) + zammad.stub(:get, 'api/v1/tickets/search', body: { total_count: 2 }, query: { only_total_count: true }) + end + + it 'refuses to guess which one was meant' do + expect { client.tickets.search('foo').count }.to raise_error(described_class::AmbiguousStubError) + end + + it 'names both scopes, so the fix is visible from the message' do + expect { client.tickets.search('foo').count } + .to raise_error(described_class::AmbiguousStubError, /only_total_count.*|.*only_total_count/) + end + + it 'says the test is wrong rather than that Zammad refused something' do + expect(described_class::AmbiguousStubError.ancestors).not_to include(ZammadAPI::Error) + end + + it 'answers the request a more specific stub names' do + zammad.reset + zammad.stub(:get, 'api/v1/tickets/search', body: [{ id: 1 }], query: { query: 'foo' }) + zammad.stub(:get, 'api/v1/tickets/search', body: { total_count: 2 }, query: { query: 'foo', only_total_count: true }) + + expect(client.tickets.search('foo').count).to eq(2) + end + + it 'leaves the less specific stub answering the requests it alone matches' do + zammad.reset + zammad.stub(:get, 'api/v1/tickets/search', body: [{ id: 1 }], query: { query: 'foo' }) + zammad.stub(:get, 'api/v1/tickets/search', body: { total_count: 2 }, query: { query: 'foo', only_total_count: true }) + + expect(client.tickets.search('foo').map(&:id)).to eq([1]) + end + end +end From 30e80861982874434d7bf5ec78c6e76819763f80 Mon Sep 17 00:00:00 2001 From: Mantas Date: Wed, 18 Nov 2026 10:09:40 +0200 Subject: [PATCH 03/11] feat: add RBS signatures and check them with Steep The gem ships signatures in sig/, so a typed project gets completion and checking for the client, the collections and the records without writing any of its own. ResourceProxy and Collection are generic over the resource they hold: client.tickets is a ResourceProxy[Resources::Ticket], and what it finds, yields and searches is a Ticket. Each resource declares the attributes Zammad serves for it, typed the way their JSON arrives. The declarations are signatures only. A record still answers through method_missing, so an attribute an administrator added works and is simply untyped. Three things keep the signatures honest. rake steep checks lib/ against them. rake rbs_published validates the published set without sig/vendor, which holds stand-ins for dependencies that ship no signatures and is kept out of the gem: a Faraday type named in a published signature would fail for every consumer and pass here. And spec/typed/usage.rb is a file written the way a caller writes one, checked as a second Steep target, where each line that must be a type error carries a steep:ignore that Steep reports once it silences nothing. With this commit the default rake task has everything it runs. --- Steepfile | 42 +++++ sig/vendor/faraday.rbs | 57 +++++++ sig/vendor/internal.rbs | 14 ++ sig/zammad_api.rbs | 3 + sig/zammad_api/associations.rbs | 37 +++++ sig/zammad_api/attribute_access.rbs | 39 +++++ sig/zammad_api/client.rbs | 66 ++++++++ sig/zammad_api/collection.rbs | 83 ++++++++++ sig/zammad_api/config.rbs | 92 +++++++++++ sig/zammad_api/deep_copy.rbs | 7 + sig/zammad_api/duplicate_keys.rbs | 9 ++ sig/zammad_api/errors.rbs | 74 +++++++++ sig/zammad_api/query_encoder.rbs | 13 ++ sig/zammad_api/resource_proxy.rbs | 60 +++++++ sig/zammad_api/resources/base.rbs | 101 ++++++++++++ sig/zammad_api/resources/resources.rbs | 210 +++++++++++++++++++++++++ sig/zammad_api/response.rbs | 26 +++ sig/zammad_api/test.rbs | 84 ++++++++++ sig/zammad_api/transport.rbs | 91 +++++++++++ spec/typed/sig/usage.rbs | 34 ++++ spec/typed/usage.rb | 78 +++++++++ 21 files changed, 1220 insertions(+) create mode 100644 Steepfile create mode 100644 sig/vendor/faraday.rbs create mode 100644 sig/vendor/internal.rbs create mode 100644 sig/zammad_api.rbs create mode 100644 sig/zammad_api/associations.rbs create mode 100644 sig/zammad_api/attribute_access.rbs create mode 100644 sig/zammad_api/client.rbs create mode 100644 sig/zammad_api/collection.rbs create mode 100644 sig/zammad_api/config.rbs create mode 100644 sig/zammad_api/deep_copy.rbs create mode 100644 sig/zammad_api/duplicate_keys.rbs create mode 100644 sig/zammad_api/errors.rbs create mode 100644 sig/zammad_api/query_encoder.rbs create mode 100644 sig/zammad_api/resource_proxy.rbs create mode 100644 sig/zammad_api/resources/base.rbs create mode 100644 sig/zammad_api/resources/resources.rbs create mode 100644 sig/zammad_api/response.rbs create mode 100644 sig/zammad_api/test.rbs create mode 100644 sig/zammad_api/transport.rbs create mode 100644 spec/typed/sig/usage.rbs create mode 100644 spec/typed/usage.rb diff --git a/Steepfile b/Steepfile new file mode 100644 index 0000000..d46d146 --- /dev/null +++ b/Steepfile @@ -0,0 +1,42 @@ +# frozen_string_literal: true + +target :lib do + signature 'sig' + check 'lib' + + # socket is here for SocketError and openssl for OpenSSL::SSL::SSLError, + # both of which Transport maps to ConnectionError; forwardable is here for + # the collection shorthands ResourceProxy delegates to Collection; uri is + # here for the parse Config makes to find credentials in the instance url. + # None of the four is named in the signatures the gem publishes - see + # SSL_ERRORS in sig/zammad_api/transport.rbs and sig/vendor/internal.rbs - so + # this does not add anything a consumer has to load. + library 'json', 'logger', 'timeout', 'socket', 'openssl', 'forwardable', 'uri' + + configure_code_diagnostics do |hash| + # Default keyword-argument hashes such as `attributes = {}` cannot be + # annotated without hurting readability. + hash[Steep::Diagnostic::Ruby::UnannotatedEmptyCollection] = nil + end +end + +# A file written the way a typed project that uses this gem writes one, checked +# against the same signatures as lib/. It is never run - see spec/typed/usage.rb +# for what it pins. +# +# sig/vendor is in here, although a consumer does not have it, because Steep +# hands a signature file to every target of a project whatever the target's +# own pattern says. Listing only the published directories left this target +# with sig/vendor/internal.rbs all the same and without the library it names, +# so its signatures failed to load and Steep then skips the source files of +# such a target without a word: the check passed having checked nothing. That +# the published signatures stand on their own is what `rake rbs_published` +# establishes. +target :usage do + signature 'sig', 'spec/typed/sig' + check 'spec/typed' + + # logger is the one library the published signatures name; forwardable is + # here for sig/vendor/internal.rbs. + library 'logger', 'forwardable' +end diff --git a/sig/vendor/faraday.rbs b/sig/vendor/faraday.rbs new file mode 100644 index 0000000..728de63 --- /dev/null +++ b/sig/vendor/faraday.rbs @@ -0,0 +1,57 @@ +# Minimal declarations for the parts of Faraday this gem uses. +# Faraday does not ship RBS signatures of its own. + +module Faraday + class Error < StandardError + end + + class ConnectionFailed < Error + end + + class TimeoutError < Error + end + + class SSLError < Error + end + + class RetriableResponse < Error + end + + class Response + def status: () -> Integer + def body: () -> untyped + def headers: () -> untyped + end + + class Request + def url: (String) -> void + def params: () -> Hash[String, untyped] + def body=: (untyped) -> void + def headers: () -> Hash[String, untyped] + end + + # Faraday.new yields the connection itself, which delegates the stack + # building methods below to its RackBuilder. + class Connection + def get: (String) ?{ (Request) -> void } -> Response + def post: (String) ?{ (Request) -> void } -> Response + def put: (String) ?{ (Request) -> void } -> Response + def delete: (String) ?{ (Request) -> void } -> Response + def public_send: (Symbol, *untyped) ?{ (Request) -> void } -> Response + + def request: (Symbol, *untyped) -> void + def response: (Symbol, *untyped) -> void + def adapter: (untyped, *untyped) -> void + def use: (untyped, *untyped) -> void + end + + # The encoder a connection writes its query with by default. An Array of + # pairs is written in the order it is given, where a Hash is sorted. + class NestedParamsEncoder + def self.encode: (untyped params) -> String? + def self.decode: (String? query) -> untyped + end + + def self.new: (**untyped) ?{ (Connection) -> void } -> Connection + def self.default_adapter: () -> Symbol +end diff --git a/sig/vendor/internal.rbs b/sig/vendor/internal.rbs new file mode 100644 index 0000000..620fdc7 --- /dev/null +++ b/sig/vendor/internal.rbs @@ -0,0 +1,14 @@ +# Declarations that hold only while this repository is type-checked, and are +# deliberately not part of what the gem publishes. +# +# ResourceProxy forwards the collection shorthands with Forwardable, so the +# type checker has to know the class extends it before it can see +# `def_delegators` on the singleton. Consumers never need that: the published +# signatures declare each forwarded method concretely, which is what a caller +# is checked against, and naming Forwardable there would make `rbs validate` +# fail for anyone who has not loaded the stdlib declarations for it. +module ZammadAPI + class ResourceProxy[R < Resources::Base] + extend Forwardable + end +end diff --git a/sig/zammad_api.rbs b/sig/zammad_api.rbs new file mode 100644 index 0000000..3a9109a --- /dev/null +++ b/sig/zammad_api.rbs @@ -0,0 +1,3 @@ +module ZammadAPI + VERSION: String +end diff --git a/sig/zammad_api/associations.rbs b/sig/zammad_api/associations.rbs new file mode 100644 index 0000000..44d58c9 --- /dev/null +++ b/sig/zammad_api/associations.rbs @@ -0,0 +1,37 @@ +module ZammadAPI + module Associations + # The readers are defined by the belongs_to and has_many declarations in + # lib/zammad_api/resources, onto a per-resource subclass of this one that + # has no name to declare. They are listed here so that callers get types + # and completion; every name is declared once and means the same target + # wherever it is declared, so the type of a given reader is accurate. The + # class is wider than any one resource, so a reader the record does not + # declare type-checks here and raises NoMethodError at runtime. + class Proxy + @record: Resources::Base + @cache: Hash[Symbol, untyped] + + def initialize: (Resources::Base record) -> void + def inspect: () -> String + + def created_by: () -> Resources::User? + def updated_by: () -> Resources::User? + def customer: () -> Resources::User? + def owner: () -> Resources::User? + def organization: () -> Resources::Organization? + def group: () -> Resources::Group? + def state: () -> Resources::TicketState? + def priority: () -> Resources::TicketPriority? + def ticket: () -> Resources::Ticket? + def articles: () -> Array[Resources::TicketArticle] + + private + + def belongs_to_target: (Symbol name, String class_name, Symbol foreign_key) -> untyped + def has_many_target: (Symbol name, String class_name, ^(String) -> String path) -> Array[untyped] + def forget_targets: () -> void + def refuse_destroyed!: (Symbol name) -> void + def resolve: (String class_name) -> untyped + end + end +end diff --git a/sig/zammad_api/attribute_access.rbs b/sig/zammad_api/attribute_access.rbs new file mode 100644 index 0000000..0189c51 --- /dev/null +++ b/sig/zammad_api/attribute_access.rbs @@ -0,0 +1,39 @@ +module ZammadAPI + module AttributeAccess + NON_ATTRIBUTE_SUFFIXES: Array[String] + # private_constant in the source; RBS has no way to say so. + ATTRIBUTE_WRITER: Regexp + + @attributes: Hash[Symbol, untyped] + + attr_reader attributes: Hash[Symbol, untyped] + + def []: (Symbol | String key) -> untyped + def []=: (Symbol | String key, untyped value) -> untyped + def fetch: (Symbol | String key, *untyped default) ?{ (Symbol) -> untyped } -> untyped + def key?: (Symbol | String key) -> bool + def to_h: () -> Hash[Symbol, untyped] + def id: () -> Integer? + def deconstruct_keys: (Array[Symbol]?) -> Hash[Symbol, untyped] + def ==: (untyped other) -> bool + def eql?: (untyped other) -> bool + def hash: () -> Integer + def as_json: (*untyped) -> Hash[Symbol, untyped] + def to_json: (?untyped state) -> String + def method_missing: (Symbol, *untyped) -> untyped + def respond_to?: (untyped name, ?bool include_private) -> bool + def respond_to_missing?: (Symbol, ?bool) -> bool + + private + + # Protected in the source, which RBS has no way to say: it is asked of + # the other record in `==`, and of nobody else. + def installation: () -> String? + def unknown_attribute_message: (Symbol name) -> String + def writable_attributes?: () -> bool + def attribute_writable?: (Symbol key) -> bool + def write_attribute: (Symbol, untyped) -> untyped + def frozen_attributes: (untyped) -> untyped + def deep_dup: (untyped) -> untyped + end +end diff --git a/sig/zammad_api/client.rbs b/sig/zammad_api/client.rbs new file mode 100644 index 0000000..ce64ff2 --- /dev/null +++ b/sig/zammad_api/client.rbs @@ -0,0 +1,66 @@ +module ZammadAPI + class Client + RESOURCES: Hash[Symbol, untyped] + DEPRECATED_RESOURCES: Hash[Symbol, Symbol] + CONVERSION_METHODS: Array[Symbol] + ENV_OPTIONS: Hash[String, Symbol] + + attr_reader config: Config + + @transport: Transport + @resources: Hash[untyped, ResourceProxy[untyped]] + + def self.from_env: (**untyped overrides) -> Client + def self.warn_deprecated_resource: (Symbol old_name, Symbol name) -> void + def self.build: (Config config, untyped transport) -> Client + + def initialize: (**untyped options) -> void + + def groups: () -> ResourceProxy[Resources::Group] + def organizations: () -> ResourceProxy[Resources::Organization] + def tickets: () -> ResourceProxy[Resources::Ticket] + def ticket_articles: () -> ResourceProxy[Resources::TicketArticle] + def ticket_priorities: () -> ResourceProxy[Resources::TicketPriority] + def ticket_states: () -> ResourceProxy[Resources::TicketState] + def users: () -> ResourceProxy[Resources::User] + + # The names these readers had in 1.x. Each warns in Ruby's `deprecated` + # category and answers what its plural answers. + %a{deprecated: use groups} def group: () -> ResourceProxy[Resources::Group] + %a{deprecated: use organizations} def organization: () -> ResourceProxy[Resources::Organization] + %a{deprecated: use tickets} def ticket: () -> ResourceProxy[Resources::Ticket] + %a{deprecated: use ticket_articles} def ticket_article: () -> ResourceProxy[Resources::TicketArticle] + %a{deprecated: use ticket_priorities} def ticket_priority: () -> ResourceProxy[Resources::TicketPriority] + %a{deprecated: use ticket_states} def ticket_state: () -> ResourceProxy[Resources::TicketState] + %a{deprecated: use users} def user: () -> ResourceProxy[Resources::User] + + # A class cannot carry its own type into the answer - RBS has no way to + # say "a proxy for whichever class this is" - so a proxy for a resource of + # your own is untyped until you say what it is: + # + # roles = client.resource(Role) #: ZammadAPI::ResourceProxy[Role] + def resource: (Symbol | String | Class name) -> ResourceProxy[untyped] + def resource_names: () -> Array[Symbol] + def me: () -> Resources::User + def version: () -> String? + + def get: (String path, ?query: Hash[untyped, untyped]?, ?headers: Hash[untyped, untyped]?) -> Response + def post: (String path, ?query: Hash[untyped, untyped]?, ?body: untyped, ?headers: Hash[untyped, untyped]?) -> Response + def put: (String path, ?query: Hash[untyped, untyped]?, ?body: untyped, ?headers: Hash[untyped, untyped]?) -> Response + def delete: (String path, ?query: Hash[untyped, untyped]?, ?headers: Hash[untyped, untyped]?) -> Response + + def with: (**untyped options) -> Client + def on_behalf_of: (String | Integer identifier) -> Client + | [T] (String | Integer identifier) { (Client) -> T } -> T + def inspect: () -> String + def method_missing: (Symbol, *untyped) -> untyped + def respond_to_missing?: (Symbol, ?bool) -> bool + + private + + def raw: (Symbol method, String path, ?query: Hash[untyped, untyped]?, ?body: untyped, ?headers: Hash[untyped, untyped]?) -> Response + def unknown_resource_message: (Symbol | String) -> String + def proxy_for: (untyped resource_class) -> ResourceProxy[untyped] + def setup: (Config config, untyped transport) -> self + end +end diff --git a/sig/zammad_api/collection.rbs b/sig/zammad_api/collection.rbs new file mode 100644 index 0000000..7909465 --- /dev/null +++ b/sig/zammad_api/collection.rbs @@ -0,0 +1,83 @@ +module ZammadAPI + # Generic over the resource it holds, so that what a walk yields is a + # Resources::Ticket rather than something untyped: `client.tickets.all` is a + # Collection[Resources::Ticket]. + class Collection[R < Resources::Base] + include Enumerable[R] + + # Both are private_constant in the source; RBS has no way to say so. + SORT_DIRECTIONS: Array[String] + SORT_ATTRIBUTE: Regexp + + @transport: Transport + @resource_class: untyped + @path: String + @operation: String + @query: Hash[Symbol, untyped] + @max_per_page: Integer + @sortable: bool + @unsortable_hint: String + @per_page: Integer + @page: Integer? + @search: bool + @widens: bool + + def initialize: ( + transport: Transport, + resource_class: untyped, + path: String, + operation: String, + max_per_page: Integer, + sortable: bool, + unsortable_hint: String, + ?query: Hash[Symbol, untyped], + ?per_page: Integer?, + ?page: Integer?, + ?search: bool, + ?widens: bool + ) -> void + + def each: () { (R) -> void } -> Collection[R] + | () -> Enumerator[R, Collection[R]] + def find_each: (?batch_size: Integer?) { (R) -> void } -> Collection[R] + | (?batch_size: Integer?) -> Enumerator[R, Collection[R]] + def in_batches: (?of: Integer?) { (Array[R]) -> void } -> Collection[R] + | (?of: Integer?) -> Enumerator[Array[R], Collection[R]] + def page: (Integer number, ?per_page: Integer?) -> Collection[R] + def first: () -> R? + | (Integer count) -> Array[R] + def take: (Integer count) -> Array[R] + def find: (?untyped ifnone) { (R) -> boolish } -> R? + | (*untyped) -> untyped + def order: (*(Symbol | String) attributes, **(Symbol | String) directions) -> Collection[R] + def pluck: (*(Symbol | String) keys) -> Array[untyped] + def count: (*untyped) ?{ (R) -> boolish } -> Integer + def size: (*untyped) ?{ (R) -> boolish } -> Integer + def length: (*untyped) ?{ (R) -> boolish } -> Integer + def empty?: () -> bool + def inspect: () -> String + + private + + def own_request_for_first?: (untyped count) -> bool + def find_by_id_message: (untyped) -> String + def resource_reader: () -> String + def sort_columns: (Array[untyped] attributes, Hash[untyped, untyped] directions) -> Hash[String, String] + def sort_attribute!: (untyped attribute) -> String + def sort_direction!: (String name, untyped direction) -> String + def sorted_by: () -> Hash[String, String] + def positive_integer!: (untyped, String) -> Integer + def page_size!: (untyped, String) -> Integer + def walk: () { (Array[R]) -> void } -> void + def page_after: (Integer page, Integer per_page, Integer received, Integer? total) -> [ Integer, Integer ] + def widened: (Integer covered, Integer? total) -> [ Integer, Integer ] + def each_distinct: () { (Resources::Base) -> void } -> void + def with: (?page: Integer?, ?per_page: Integer, ?query: Hash[Symbol, untyped], ?widens: bool) -> Collection[R] + def hits_past?: (Integer covered, Integer? total) -> bool + def fetch: (Integer, Integer) -> [ Array[R], Integer, Integer? ] + def page_query: (Integer page, Integer per_page) -> Hash[Symbol, untyped] + def page_digest: (Array[Hash[Symbol, untyped]] decoded) -> Integer + def total_count: () -> Integer? + def clamp_per_page: (untyped) -> Integer + end +end diff --git a/sig/zammad_api/config.rbs b/sig/zammad_api/config.rbs new file mode 100644 index 0000000..1306364 --- /dev/null +++ b/sig/zammad_api/config.rbs @@ -0,0 +1,92 @@ +module ZammadAPI + # Built with Data.define; the generated readers are declared explicitly. + # + # `middleware` is a block handed a Faraday::Connection, but it is declared + # untyped here: these signatures ship with the gem, while the Faraday + # declarations they would need live in sig/vendor, which does not. Naming + # Faraday here made `rbs validate` fail for every consumer with + # `Could not find Faraday::Connection`. + class Config < ::Data + DEFAULT_TIMEOUT: Integer + DEFAULT_OPEN_TIMEOUT: Integer + DEFAULT_RETRIES: Integer + DEFAULT_RETRY_INTERVAL: Float + REDACTED_ATTRIBUTES: Array[Symbol] + REDACTION: String + DEFAULT_USER_AGENT: String + SCHEME_PATTERN: Regexp + URL_PATTERN: Regexp + URL_SUFFIX_PATTERN: Regexp + URL_SCHEME_PATTERN: Regexp + URL_AUTHORITY_PATTERN: Regexp + CREDENTIAL_OPTIONS: Hash[Symbol, Array[Symbol]] + + def self.new: (**untyped) -> instance + def self.merge_options: (Hash[Symbol, untyped] options, Hash[Symbol, untyped] overrides) -> Hash[Symbol, untyped] + + attr_reader url: String + attr_reader user: String? + attr_reader password: String? + attr_reader http_token: String? + attr_reader oauth2_token: String? + attr_reader user_agent: String + attr_reader timeout: Numeric + attr_reader open_timeout: Numeric + attr_reader retries: Integer + attr_reader retry_interval: Numeric + attr_reader ssl_verify: bool + attr_reader proxy: String? + attr_reader adapter: Symbol? + attr_reader middleware: untyped + attr_reader logger: Logger + + def initialize: ( + url: untyped, + ?user: String?, + ?password: String?, + ?http_token: String?, + ?oauth2_token: String?, + ?user_agent: String, + ?timeout: untyped, + ?open_timeout: untyped, + ?retries: untyped, + ?retry_interval: untyped, + ?ssl_verify: bool, + ?proxy: String?, + ?adapter: (Symbol | String)?, + ?middleware: untyped, + ?logger: Logger? + ) -> void + + def redacted_url: () -> String + def redacted: (String value) -> String + def authentication_scheme: () -> Symbol + def with: (**untyped) -> Config + def inspect: () -> String + def to_s: () -> String + def pretty_print: (untyped printer) -> void + def to_h: () -> Hash[Symbol, untyped] + + private + + def redact_userinfo: (String) -> String + def normalize_proxy: (untyped) -> String? + def normalize_adapter: (untyped) -> Symbol? + def render: (Symbol, untyped) -> String + def normalize_url: (untyped) -> String + def inline_credentials?: (String) -> bool + def inline_credentials_message: (String) -> String + def validate_credentials!: () -> void + def multiple_credentials_message: (Array[Symbol] schemes) -> String + def positive_number?: (untyped) -> bool + def validate_numbers!: () -> void + def validate_user_agent!: () -> void + HEADER_OPTIONS: Array[Symbol] + def validate_header_options!: () -> void + def validate_ssl_verify!: () -> void + def validate_middleware!: () -> void + def validate_logger!: () -> void + def presence: (untyped) -> untyped + def immutable: (untyped) -> untyped + end +end diff --git a/sig/zammad_api/deep_copy.rbs b/sig/zammad_api/deep_copy.rbs new file mode 100644 index 0000000..09526b8 --- /dev/null +++ b/sig/zammad_api/deep_copy.rbs @@ -0,0 +1,7 @@ +module ZammadAPI + module DeepCopy + def self?.frozen_copy: (untyped value, ?symbolize_keys: bool) -> untyped + def self?.writable_copy: (untyped value) -> untyped + def self?.symbolize: (untyped key) -> untyped + end +end diff --git a/sig/zammad_api/duplicate_keys.rbs b/sig/zammad_api/duplicate_keys.rbs new file mode 100644 index 0000000..3f26306 --- /dev/null +++ b/sig/zammad_api/duplicate_keys.rbs @@ -0,0 +1,9 @@ +module ZammadAPI + module DuplicateKeys + def self.normalize: (Hash[untyped, untyped] hash, ?prefix: String?, ?noun: String) { (untyped key) -> untyped } -> Hash[untyped, untyped] + def self.message: (String noun, untyped path, untyped first, untyped second) -> String + + def normalize: (Hash[untyped, untyped] hash, ?prefix: String?, ?noun: String) { (untyped key) -> untyped } -> Hash[untyped, untyped] + def message: (String noun, untyped path, untyped first, untyped second) -> String + end +end diff --git a/sig/zammad_api/errors.rbs b/sig/zammad_api/errors.rbs new file mode 100644 index 0000000..2b255eb --- /dev/null +++ b/sig/zammad_api/errors.rbs @@ -0,0 +1,74 @@ +module ZammadAPI + class Error < StandardError + def self.subject_for: (String operation, Class? resource_class) -> String + end + + class ConfigurationError < Error + end + + class UnknownResourceError < Error + end + + class TransportError < Error + end + + class ConnectionError < TransportError + end + + class TimeoutError < TransportError + end + + class ParseError < Error + def self.build: (operation: String, expected: (Symbol | String), actual: (Class | String), ?resource_class: Class?) -> ParseError + end + + class PaginationError < Error + def self.build: (operation: String, page: Integer, ?resource_class: Class?) -> PaginationError + end + + class ResponseError < Error + STATUS_ERRORS: Hash[Integer, singleton(ResponseError)] + + attr_reader response: Response? + attr_reader operation: String + attr_reader resource_class: Class? + + @detail: String? + + def self.build: (Response? response, operation: String, ?resource_class: Class?) -> ResponseError + def self.error_class_for: (Response?) -> singleton(ResponseError) + + def initialize: (operation: String, ?response: Response?, ?resource_class: Class?, ?detail: String?) -> void + def status: () -> Integer? + def body: () -> untyped + def headers: () -> Hash[String, String] + def server_message: () -> String? + + private + + def build_message: () -> String + def detail: () -> String + end + + class ClientError < ResponseError + end + + class ServerError < ResponseError + end + + class AuthenticationError < ClientError + end + + class AuthorizationError < ClientError + end + + class NotFoundError < ClientError + end + + class ValidationError < ClientError + end + + class RateLimitError < ClientError + def retry_after: () -> Integer? + end +end diff --git a/sig/zammad_api/query_encoder.rbs b/sig/zammad_api/query_encoder.rbs new file mode 100644 index 0000000..7404b7e --- /dev/null +++ b/sig/zammad_api/query_encoder.rbs @@ -0,0 +1,13 @@ +module ZammadAPI + module QueryEncoder + def self?.encode: (untyped params) -> String? + def self?.decode: (String? query) -> untyped + def self?.lead_path: (Hash[untyped, untyped] element, untyped previous) -> Array[untyped]? + def self?.misread: (untyped element, untyped previous) -> Symbol? + def self?.written?: (untyped value) -> bool + def self?.hash_pairs: (String? prefix, Hash[untyped, untyped] hash, Array[untyped]? lead) -> Array[[ String, untyped ]] + def self?.value_pairs: (String path, untyped value, ?Array[untyped]? lead) -> Array[[ String, untyped ]] + def self?.array_pairs: (String path, Array[untyped] array) -> Array[[ String, untyped ]] + def self?.sorted_keys: (Hash[untyped, untyped] hash) -> Array[untyped] + end +end diff --git a/sig/zammad_api/resource_proxy.rbs b/sig/zammad_api/resource_proxy.rbs new file mode 100644 index 0000000..d166f80 --- /dev/null +++ b/sig/zammad_api/resource_proxy.rbs @@ -0,0 +1,60 @@ +module ZammadAPI + # Generic over the resource it is the entry point for: `client.tickets` is a + # ResourceProxy[Resources::Ticket], so `find` answers with a Ticket and a + # block over it is handed one. + class ResourceProxy[R < Resources::Base] + include Enumerable[R] + + SEARCH_MAX_PER_PAGE: Integer + SEARCH_FILTER_KEYS: Array[Symbol] + BLANK_TERM_MESSAGE: String + SEARCHABLE_UNSORTABLE_HINT: String + UNSORTABLE_HINT: String + + attr_reader resource_class: untyped + + @transport: Transport + + def initialize: (Transport, untyped resource_class) -> void + def new: (?Hash[untyped, untyped] attributes) -> R + def create: (?Hash[untyped, untyped] attributes) -> R + def find: (Integer | String id) -> R + def find_by: (**untyped) -> R? + def find_by!: (**untyped) -> R + def exists?: (Integer | String id) -> bool + def destroy: (Integer | String id) -> true + def all: () -> Collection[R] + def order: (*(Symbol | String) attributes, **(Symbol | String) directions) -> Collection[R] + + def each: () { (R) -> void } -> Collection[R] + | () -> Enumerator[R, Collection[R]] + def find_each: (?batch_size: Integer?) { (R) -> void } -> Collection[R] + | (?batch_size: Integer?) -> Enumerator[R, Collection[R]] + def in_batches: (?of: Integer?) { (Array[R]) -> void } -> Collection[R] + | (?of: Integer?) -> Enumerator[Array[R], Collection[R]] + def page: (Integer number, ?per_page: Integer?) -> Collection[R] + def pluck: (*(Symbol | String) keys) -> Array[untyped] + def count: (*untyped) ?{ (R) -> boolish } -> Integer + def size: () -> Integer + def length: () -> Integer + def empty?: () -> bool + def first: () -> R? + | (Integer count) -> Array[R] + def take: (Integer count) -> Array[R] + def search: (String term, ?condition: Hash[untyped, untyped], ?ids: Array[Integer | String], ?role_ids: Array[Integer | String], ?group_ids: Array[Integer | String] | Hash[Integer | String, String | Symbol | Array[String | Symbol]], ?permissions: Array[String]) -> Collection[R] + def inspect: () -> String + + private + + def collection: (String, String, ?query: Hash[Symbol, untyped], ?max_per_page: Integer, ?sortable: bool, ?search: bool) -> Collection[R] + def search_filters: (Hash[untyped, untyped] filters) -> Hash[Symbol, untyped] + def search_filter_keys: () -> Array[Symbol] + def unknown_search_filter_message: (Array[Symbol] unknown) -> String + def empty_search_filter?: (untyped value) -> bool + def empty_search_filter_message: (Hash[Symbol, untyped] empty) -> String + def searchable!: () -> void + def search_term_for: (Hash[Symbol, untyped]) -> String? + def path: () -> String + def member_path: (Integer | String id) -> String + end +end diff --git a/sig/zammad_api/resources/base.rbs b/sig/zammad_api/resources/base.rbs new file mode 100644 index 0000000..1e7bf7b --- /dev/null +++ b/sig/zammad_api/resources/base.rbs @@ -0,0 +1,101 @@ +module ZammadAPI + module Resources + class Base + include AttributeAccess + + DEFAULT_MAX_PER_PAGE: Integer + MEMO_LOCK: Thread::Mutex + + attr_reader error: ValidationError? + attr_reader transport: Transport + + # What Zammad stamps every record with. These four are columns of every + # table, and the two names beside them are what `expand` adds: the login + # of each user. A record that was built with `new` and not saved yet + # carries none of them, and reading one then raises NoMethodError - the + # types here, and on every resource, describe a record Zammad served. + attr_reader created_by_id: Integer + attr_reader updated_by_id: Integer + attr_reader created_at: String + attr_reader updated_at: String + attr_reader created_by: String + attr_reader updated_by: String + + @new_record: bool + @destroyed: bool + @saved: bool + @error: ValidationError? + @changes: Hash[Symbol, Array[untyped]] + @related: Associations::Proxy? + @baseline: Hash[Symbol, untyped] + self.@related_class: untyped + self.@belongs_to_foreign_keys: Array[Symbol]? + self.@declared_associations: Hash[Symbol, Hash[Symbol, untyped]]? + self.@path: String? + self.@searchable: bool? + self.@max_per_page: Integer? + self.@search_filters: Array[Symbol]? + self.@sortable: bool? + + def self.path: (String) -> void + def self.searchable: (bool) -> void + def self.max_per_page: (Integer) -> void + def self.search_filters: (*Symbol | String names) -> void + def self.sortable: (bool) -> void + def self.resource_path: () -> String + def self.searchable?: () -> bool + def self.search_filter_names: () -> Array[Symbol] + def self.page_limit: () -> Integer + def self.sortable?: () -> bool + def self.member_path: ((Integer | String) id) -> String + def self.fetch_one: (Transport transport, (Integer | String) id) -> Base + def self.from_response: (Transport, Hash[untyped, untyped] attributes) -> Base + def self.associations: () -> Hash[Symbol, Hash[Symbol, untyped]] + def self.belongs_to_foreign_keys: () -> Array[Symbol] + def self.related_class: () -> untyped + def self.declaration: [T] (Symbol name) { () -> T } -> T + | (Symbol name) -> untyped + def self.declared_associations: () -> Hash[Symbol, Hash[Symbol, untyped]] + def self.belongs_to: (Symbol name, class_name: String, ?foreign_key: Symbol) -> void + def self.has_many: (Symbol name, class_name: String, path: ^(String) -> String) -> void + + def initialize: (Transport, ?Hash[untyped, untyped]? attributes) -> void + def new_record?: () -> bool + def persisted?: () -> bool + def destroyed?: () -> bool + def changes: () -> Hash[Symbol, Array[untyped]] + def changed?: () -> bool + def related: () -> Associations::Proxy + def assign_attributes: (Hash[untyped, untyped] attributes) -> self + def save: () -> bool + def save!: () -> true + def update: (Hash[untyped, untyped] attributes) -> bool + def update!: (Hash[untyped, untyped] attributes) -> true + def reload: () -> self + def destroy: () -> true + def inspect: () -> String + + private + + def initialize_copy: (self source) -> void + def setup: (Transport, Hash[untyped, untyped] attributes) -> void + def mark_persisted!: () -> void + def raise_if_destroyed!: (String action) -> void + def raise_if_new!: (String operation) -> void + def writable_attributes?: () -> bool + def attribute_writable?: (Symbol key) -> bool + def refuse_unwritable!: (Symbol key, untyped value) -> void + def replace_attributes!: (Response, operation: String, ?sent: Hash[Symbol, untyped]?) -> void + def acknowledge_changes!: (Hash[Symbol, untyped] sent) -> void + def reset_pending_state!: () -> void + def forget_related_targets: () -> void + def write_attribute: (Symbol, untyped) -> untyped + def unsaved_attributes: (Hash[Symbol, untyped] held) -> Hash[Symbol, untyped] + def create_record: (Hash[Symbol, untyped] body) -> Response + def update_record: (Hash[Symbol, untyped] body) -> Response + def member_path: () -> String + def require_id!: () -> Integer + def no_id_message: () -> String + end + end +end diff --git a/sig/zammad_api/resources/resources.rbs b/sig/zammad_api/resources/resources.rbs new file mode 100644 index 0000000..c4e5b10 --- /dev/null +++ b/sig/zammad_api/resources/resources.rbs @@ -0,0 +1,210 @@ +module ZammadAPI + # The attributes declared on each resource are the ones every Zammad the + # gem supports serves for it: the columns of its table, as they have been + # since Zammad 5, typed the way their JSON arrives - a timestamp is a + # String, and `preferences` is a Hash with Symbol keys. + # + # They are declarations only. A record answers them through + # method_missing, from whatever the response carried, so nothing here makes + # an attribute exist: these say what a typed caller may rely on. + # + # What is left out, on purpose: + # + # - Attributes an administrator added. Reach one with `record[:name]`, or + # declare it in your own signatures by reopening the class: + # + # class ZammadAPI::Resources::Ticket + # attr_accessor escalation_reason: String? + # end + # + # - Columns that newer Zammad versions added, which an older instance does + # not serve. + # + # - The name `expand` adds for an association that may be empty, such as + # `organization` on a ticket or a user. Zammad leaves the key out rather + # than sending null, so the reader would raise rather than answer nil. + # `record[:organization]` is nil in that case, and `organization_id` is + # always there. + module Resources + class Group < Base + attr_accessor name: String + attr_accessor signature_id: Integer? + attr_accessor email_address_id: Integer? + attr_accessor assignment_timeout: Integer? + attr_accessor follow_up_possible: String + attr_accessor follow_up_assignment: bool + attr_accessor active: bool + attr_accessor note: String? + end + + class Organization < Base + attr_accessor name: String + attr_accessor shared: bool + attr_accessor domain: String? + attr_accessor domain_assignment: bool + attr_accessor active: bool + attr_accessor note: String? + end + + class TicketPriority < Base + attr_accessor name: String + attr_accessor default_create: bool + attr_accessor ui_icon: String? + attr_accessor ui_color: String? + attr_accessor active: bool + attr_accessor note: String? + end + + class TicketState < Base + attr_accessor name: String + attr_accessor state_type_id: Integer + attr_accessor next_state_id: Integer? + attr_accessor ignore_escalation: bool + attr_accessor default_create: bool + attr_accessor default_follow_up: bool + attr_accessor active: bool + attr_accessor note: String? + end + + class User < Base + # Narrowed from Base so Client#me returns the concrete user type. + def self.from_response: (Transport, Hash[untyped, untyped] attributes) -> User + + attr_accessor login: String + attr_accessor firstname: String? + attr_accessor lastname: String? + attr_accessor email: String? + attr_accessor organization_id: Integer? + attr_accessor image: String? + attr_accessor image_source: String? + attr_accessor web: String? + attr_accessor phone: String? + attr_accessor fax: String? + attr_accessor mobile: String? + attr_accessor department: String? + attr_accessor street: String? + attr_accessor zip: String? + attr_accessor city: String? + attr_accessor country: String? + attr_accessor address: String? + attr_accessor vip: bool + attr_accessor verified: bool + attr_accessor active: bool + attr_accessor note: String? + attr_accessor out_of_office: bool + attr_accessor out_of_office_start_at: String? + attr_accessor out_of_office_end_at: String? + attr_accessor out_of_office_replacement_id: Integer? + attr_accessor preferences: Hash[Symbol, untyped]? + + # Set by Zammad as the user signs in, so there is nothing to write. + attr_reader last_login: String? + attr_reader login_failed: Integer + attr_reader source: String? + + # Zammad takes a password and never serves one. + attr_writer password: String + end + + class Ticket < Base + attr_accessor title: String + attr_accessor group_id: Integer + attr_accessor state_id: Integer + attr_accessor priority_id: Integer + attr_accessor owner_id: Integer + attr_accessor customer_id: Integer + attr_accessor organization_id: Integer? + attr_accessor note: String? + attr_accessor pending_time: String? + attr_accessor type: String? + attr_accessor preferences: Hash[Symbol, untyped]? + + # The name `expand` puts beside each of the ids above that cannot be + # empty. Writing one is how a ticket is moved by name: + # `ticket.update(state: 'closed', group: 'Support')`. + attr_accessor group: String + attr_accessor state: String + attr_accessor priority: String + attr_accessor owner: String + attr_accessor customer: String + + # Kept by Zammad as the ticket moves, so there is nothing to write. + attr_reader number: String + attr_reader article_count: Integer? + attr_reader create_article_type_id: Integer? + attr_reader create_article_sender_id: Integer? + attr_reader first_response_at: String? + attr_reader first_response_escalation_at: String? + attr_reader first_response_in_min: Integer? + attr_reader first_response_diff_in_min: Integer? + attr_reader close_at: String? + attr_reader close_escalation_at: String? + attr_reader close_in_min: Integer? + attr_reader close_diff_in_min: Integer? + attr_reader update_escalation_at: String? + attr_reader update_in_min: Integer? + attr_reader update_diff_in_min: Integer? + attr_reader escalation_at: String? + attr_reader last_contact_at: String? + attr_reader last_contact_agent_at: String? + attr_reader last_contact_customer_at: String? + attr_reader last_owner_update_at: String? + + def articles: () -> Array[TicketArticle] + def add_article: (?Hash[untyped, untyped] attributes) -> TicketArticle + %a{deprecated: use add_article} def article: (Hash[untyped, untyped] attributes) -> TicketArticle + end + + class TicketArticle < Base + # Narrowed from Base so callers get the concrete article type. + def self.from_response: (Transport, Hash[untyped, untyped] attributes) -> TicketArticle + + # private_constant in the source; RBS has no way to say so. + ATTACHMENTS_OPERATION: String + + attr_accessor ticket_id: Integer + attr_accessor type_id: Integer + attr_accessor sender_id: Integer + attr_accessor from: String? + attr_accessor to: String? + attr_accessor cc: String? + attr_accessor subject: String? + attr_accessor reply_to: String? + attr_accessor in_reply_to: String? + attr_accessor content_type: String + attr_accessor body: String + attr_accessor internal: bool + attr_accessor preferences: Hash[Symbol, untyped]? + + # The name `expand` puts beside type_id and sender_id, which is also + # how an article is given either: `add_article(type: 'note')`. + attr_accessor type: String + attr_accessor sender: String + + attr_reader message_id: String? + attr_reader message_id_md5: String? + attr_reader origin_by_id: Integer? + + def attachments: () -> Array[TicketArticleAttachment] + + private + + def attachment: (untyped raw) -> TicketArticleAttachment + end + + class TicketArticleAttachment + include AttributeAccess + + @transport: Transport + + # What Zammad lists for each attachment of an article. + attr_reader filename: String + attr_reader size: String + attr_reader preferences: Hash[Symbol, untyped] + + def initialize: (Transport, ?Hash[untyped, untyped]? attributes) -> void + def download: () -> String + def inspect: () -> String + end + end +end diff --git a/sig/zammad_api/response.rbs b/sig/zammad_api/response.rbs new file mode 100644 index 0000000..ee9f3a4 --- /dev/null +++ b/sig/zammad_api/response.rbs @@ -0,0 +1,26 @@ +module ZammadAPI + # Built with Data.define; the generated readers are declared explicitly. + class Response < ::Data + attr_reader status: Integer + attr_reader headers: Hash[String, String] + attr_reader body: untyped + attr_reader raw_body: String + attr_reader json: bool + + def self.new: (status: Integer, headers: Hash[String, String], body: untyped, raw_body: String, json: bool) -> instance + SUCCESS_STATUSES: Range[Integer] + # private_constant in the source; RBS has no way to say so. + TOTAL_COUNT_HEADER: String + + def self.decode_body: (String?, String) -> [untyped, bool] + + def success?: () -> bool + def json?: () -> bool + def decoded: (Symbol shape, operation: String, ?resource_class: Class?) -> untyped + def decoded_list: (operation: String, ?resource_class: Class?) -> [ Array[Hash[Symbol, untyped]], Integer? ] + + private + + def array_of_objects!: (Array[untyped], operation: String, resource_class: Class?) -> Array[untyped] + end +end diff --git a/sig/zammad_api/test.rbs b/sig/zammad_api/test.rbs new file mode 100644 index 0000000..e478b6c --- /dev/null +++ b/sig/zammad_api/test.rbs @@ -0,0 +1,84 @@ +module ZammadAPI + class Test + # Both are deliberately outside ZammadAPI::Error: they say the test is + # wrong, not that Zammad refused anything, and the signature said + # otherwise - so a `rescue ZammadAPI::Error` type-checked as catching a + # forgotten stub that it does not in fact catch. + class UnstubbedRequestError < ::StandardError + end + + class AmbiguousStubError < ::StandardError + end + + class Request < ::Data + attr_reader verb: Symbol + attr_reader path: String + attr_reader query: Hash[String, untyped] + attr_reader body: untyped + attr_reader headers: Hash[String, String] + attr_reader on_behalf_of: String? + + def self.new: (**untyped) -> instance + end + + attr_reader config: Config + attr_reader client: Client + + @stubs: Hash[[Symbol, String], Array[Hash[Symbol, untyped]]] + @requests: Array[Request] + @served: Hash[[[Symbol, String], Hash[String, untyped]?], Hash[Symbol, untyped]] + @monitor: Thread::Mutex + @transport: Test::Transport + @client: Client + + def initialize: (**untyped options) -> void + def stub: (Symbol method, String path, ?status: Integer, ?body: untyped, ?headers: Hash[untyped, untyped], ?query: Hash[untyped, untyped]?) -> self + def requests: () -> Array[Request] + def reset: () -> self + def stubbed: () -> Array[String] + def inspect: () -> String + + def answer: ( + Symbol method, + String path, + operation: String, + ?query: Hash[untyped, untyped]?, + ?body: untyped, + ?headers: Hash[untyped, untyped]?, + ?resource_class: Class?, + ?on_behalf_of: String? + ) -> Response + + private + + def key: (Symbol method, String path) -> [Symbol, String] + def raw_body_for: (untyped body) -> String + def response_headers: (Hash[untyped, untyped] headers, untyped body) -> Hash[String, String] + def snapshot: (untyped) -> untyped + def take: (Symbol method, String path, Hash[String, untyped] params) -> Hash[Symbol, untyped]? + def later_page?: (Hash[String, untyped]? scope, Hash[String, untyped] params) -> bool + def most_specific: (Array[Hash[Symbol, untyped]] queued, Array[Integer] matching, Symbol method, String path) -> Array[Integer] + def ambiguous_message: (Symbol method, String path, Array[Hash[String, untyped]?] scopes) -> String + def matches?: (Hash[untyped, untyped]? expected, Hash[String, untyped] params) -> bool + def paged_body: (Hash[Symbol, untyped] stub, Hash[String, untyped] params, untyped body) -> untyped + def response_for: (Hash[Symbol, untyped] stub, Hash[String, untyped] params) -> Response + def build_response: (Hash[Symbol, untyped] stub, untyped body, String raw_body, json: bool) -> Response + def unstubbed_message: (Symbol method, String path, Hash[String, untyped] params) -> String + def unmatched_query_message: (String request, Hash[String, untyped] params, Array[Hash[String, untyped]?] scopes) -> String + + class Transport + include ::ZammadAPI::Transport::Verbs + + attr_reader test: Test + attr_reader on_behalf_of: String? + + def initialize: (Test test, ?on_behalf_of: (String | Integer)?) -> void + def config: () -> Config + def with_on_behalf_of: ((String | Integer)? identifier) -> Test::Transport + def with_config: (Config) -> Test::Transport + + + def request: (Symbol method, String path, operation: String, ?query: Hash[Symbol, untyped]?, ?body: untyped, ?headers: Hash[untyped, untyped]?, ?resource_class: Class?) -> Response + end + end +end diff --git a/sig/zammad_api/transport.rbs b/sig/zammad_api/transport.rbs new file mode 100644 index 0000000..ceb3d6c --- /dev/null +++ b/sig/zammad_api/transport.rbs @@ -0,0 +1,91 @@ +module ZammadAPI + # The Faraday connection and responses are untyped here rather than named: + # these signatures ship with the gem and the Faraday declarations they would + # need live in sig/vendor, which does not. See sig/zammad_api/config.rbs. + class Transport + # Included by Transport and by Test::Transport, which stands in for it. + module Verbs + def get: (String path, operation: String, ?query: Hash[Symbol, untyped]?, ?body: untyped, ?headers: Hash[untyped, untyped]?, ?resource_class: Class?) -> Response + def post: (String path, operation: String, ?query: Hash[Symbol, untyped]?, ?body: untyped, ?headers: Hash[untyped, untyped]?, ?resource_class: Class?) -> Response + def put: (String path, operation: String, ?query: Hash[Symbol, untyped]?, ?body: untyped, ?headers: Hash[untyped, untyped]?, ?resource_class: Class?) -> Response + def delete: (String path, operation: String, ?query: Hash[Symbol, untyped]?, ?body: untyped, ?headers: Hash[untyped, untyped]?, ?resource_class: Class?) -> Response + end + + include Verbs + + RETRIABLE_METHODS: Array[Symbol] + RETRIABLE_STATUSES: Array[Integer] + RETRIABLE_EXCEPTIONS: Array[untyped] + TIMEOUT_ERRORS: Array[untyped] + CONNECTION_ERRORS: Array[untyped] + # Untyped for the same reason as the Faraday ones above: naming + # OpenSSL::SSL::SSLError here would make the published signatures need + # openssl declarations that a consumer has not loaded. + SSL_ERRORS: Array[untyped] + # private_constant in the source; RBS has no way to say so. + REFUSED_MIDDLEWARE: Hash[String, [String, String]] + MISREAD_ELEMENTS: Hash[Symbol, String] + SENSITIVE_KEY_PATTERN: Regexp + REDACTED: String + UNRESERVED_IN_PATH: Regexp + DOT_SEGMENTS: Array[String] + ABSOLUTE_URL: Regexp + RESERVED_HEADERS: Hash[String, String] + + attr_reader config: Config + attr_reader on_behalf_of: String? + + @connection: untyped + + def self.redact_path: (untyped path) -> String + def self.redact_query_pair: (String pair) -> String + def self.stringify_query: (Hash[untyped, untyped]) -> Hash[String, untyped] + def self.stringify_query_hash: (Hash[untyped, untyped], String?) -> Hash[String, untyped] + def self.stringify_query_value: (String, untyped) -> untyped + def self.stringify_query_list: (String, Array[untyped]) -> Array[untyped] + def self.misread_element_message: (String, Symbol) -> String + def self.empty_query_name_message: (String? prefix) -> String + def self.stringify_headers: (Hash[untyped, untyped]) -> Hash[String, String] + BLANK: Regexp + def self.wire_text: (untyped value, String name) -> String + LINE_BREAK_ADVICE: String + def self.line_break?: (String text) -> bool + def self.stringify_on_behalf_of: ((String | Integer)? identifier) -> String? + def self.blank_on_behalf_of_message: (untyped identifier) -> String + def self.stringify_header_value: (String, untyped) -> String + def self.escape_path_segment: (untyped) -> String + def self.relative_path: (untyped) -> String + def self.refuse_unreadable_path!: (String relative) -> void + def self.unreadable_path_message: (String relative) -> String + def self.encode_body: (untyped body, operation: String, ?resource_class: Class?) -> String? + + def initialize: (Config) -> void + def with_on_behalf_of: ((String | Integer)? identifier) -> Transport + def with_config: (Config) -> Transport + def inspect: () -> String + + def request: (Symbol method, String path, operation: String, ?query: Hash[Symbol, untyped]?, ?body: untyped, ?headers: Hash[untyped, untyped]?, ?resource_class: Class?) -> Response + + private + + def timed_out?: (untyped error) -> bool + def perform: (Symbol, String, Hash[Symbol, untyped]?, untyped, String?, Hash[untyped, untyped]?) -> untyped + def build_connection: () -> untyped + def refuse_unusable_middleware!: (untyped connection) -> void + def refused_middleware: (Class klass) -> String? + def refused_middleware_message: (Class klass, String refused) -> String + def apply_authentication: (untyped) -> void + def retry_options: () -> Hash[Symbol, untyped] + def decode: (untyped) -> Response + def raw_body!: (untyped) -> String + def log_request: (Symbol, String, Hash[Symbol, untyped]?, untyped, Hash[String, String]?) -> void + def log_response: (Symbol, String, Response, Float) -> void + def redact: (untyped) -> untyped + def loggable_body: (untyped body) -> untyped + def unlogged_body: (String body) -> String + def reportable_cause: (StandardError error) -> StandardError? + def redact_config_values: (untyped message) -> String + def quoted_spellings: (String value) -> Array[String] + def logger: () -> Logger + end +end diff --git a/spec/typed/sig/usage.rbs b/spec/typed/sig/usage.rbs new file mode 100644 index 0000000..bae828d --- /dev/null +++ b/spec/typed/sig/usage.rbs @@ -0,0 +1,34 @@ +# The signatures a typed project writes for its own code. Not published with +# the gem: see spec/typed/usage.rb. +module TypedUsage + class Role < ZammadAPI::Resources::Base + attr_accessor name: String + end + + def self.title: (ZammadAPI::Client) -> String + def self.misspelled_reader: (ZammadAPI::Client) -> untyped + def self.logins: (ZammadAPI::Client) -> Array[String] + def self.block_parameter: (ZammadAPI::Client) -> untyped + def self.first_group: (ZammadAPI::Client) -> ZammadAPI::Resources::Group? + def self.first_tickets: (ZammadAPI::Client) -> Array[ZammadAPI::Resources::Ticket] + def self.found: (ZammadAPI::Client) -> ZammadAPI::Resources::Organization? + def self.newest_open: (ZammadAPI::Client) -> String? + def self.readers_of_group: (ZammadAPI::Client) -> Array[String] + def self.owners_of_group: (ZammadAPI::Client) -> Array[String] + def self.batches: (ZammadAPI::Client) -> Array[Integer] + def self.customer_email: (ZammadAPI::Client) -> String? + def self.article_bodies: (ZammadAPI::Client) -> Array[String] + def self.written: (ZammadAPI::Client) -> bool + def self.custom_attribute: (ZammadAPI::Client) -> [untyped, String?] + def self.role_names: (ZammadAPI::Client) -> Array[String] + def self.unsaved: (ZammadAPI::Client) -> String +end + +# An attribute an administrator added, declared by the project that uses it. +module ZammadAPI + module Resources + class Ticket + attr_accessor escalation_reason: String? + end + end +end diff --git a/spec/typed/usage.rb b/spec/typed/usage.rb new file mode 100644 index 0000000..c90fd91 --- /dev/null +++ b/spec/typed/usage.rb @@ -0,0 +1,78 @@ +# frozen_string_literal: true + +# Never run. `rake steep` checks this file against the signatures the gem +# publishes, the way a typed project that uses the gem is checked, so that the +# types a caller gets are pinned by something other than the signatures saying +# so. +# +# A line that ends in `steep:ignore` is one that has to be a type error. Steep +# reports an ignore comment that silences nothing, so each of them fails the +# check on the day its line stops being an error. That is how "a record is +# typed" is asserted here: against an untyped record a misspelled reader is no +# error at all, and the comment beside it would be the redundant one. +module TypedUsage + # A resource of the caller's own, reached through Client#resource. + class Role < ZammadAPI::Resources::Base + path 'api/v1/roles' + end + + def self.title(client) = client.tickets.find(1).title + + def self.misspelled_reader(client) + client.tickets.find(1).titel # steep:ignore NoMethod + end + + def self.logins(client) = client.users.map(&:login) + + def self.block_parameter(client) + client.users.each do |user| + user.loginn.upcase # steep:ignore NoMethod + end + end + + def self.first_group(client) = client.groups.first + + def self.first_tickets(client) = client.tickets.first(5) + + def self.found(client) = client.organizations.find_by(name: 'Zammad') + + def self.newest_open(client) + client.tickets.search('state.name:open').order(created_at: :desc).first&.number + end + + def self.readers_of_group(client) = client.users.search('smith', group_ids: { 2 => ['read'] }).map(&:login) + + def self.owners_of_group(client) = client.users.search('smith', group_ids: [2]).map(&:login) + + def self.batches(client) + sizes = [] #: Array[Integer] + client.tickets.in_batches(of: 50) { |tickets| sizes << tickets.sum { it.article_count || 0 } } + sizes + end + + def self.customer_email(client) = client.tickets.find(1).related.customer&.email + + def self.article_bodies(client) = client.tickets.find(1).articles.map(&:body) + + def self.written(client) + ticket = client.tickets.find(1) + ticket.title = 'Printer on fire' + ticket.title = 1 # steep:ignore ArgumentTypeMismatch + ticket.number = '1' # steep:ignore NoMethod + ticket.save + end + + # An attribute an administrator added is read by name, or declared by the + # project that knows about it - see usage.rbs. + def self.custom_attribute(client) + ticket = client.tickets.find(1) + [ticket[:anything_at_all], ticket.escalation_reason] + end + + def self.role_names(client) + roles = client.resource(Role) #: ZammadAPI::ResourceProxy[Role] + roles.map(&:name) + end + + def self.unsaved(client) = client.ticket_states.new(name: 'waiting').name +end From 75b98da4a36b8a624aeaffe14f043d76834b2967 Mon Sep 17 00:00:00 2001 From: Mantas Date: Wed, 18 Nov 2026 10:10:02 +0200 Subject: [PATCH 04/11] ci: drive a live Zammad end to end and publish by tag CI runs RuboCop, Steep and the unit specs on every supported stable Ruby, from the gemspec's floor to the current release: on pull requests, on pushes, and weekly, to catch what a new Ruby or a new Zammad breaks. A further job boots a Zammad and drives it with the gem. It waits for the instance to answer instead of sleeping, then runs script/check_connection.rb before the integration specs. The script stands alone - it does not load the spec suite - and walks the gem's surface against the instance: records, collections, sorting, search, tickets with their articles and attachments, acting on behalf of a user, and the error classes. A broken link between the gem and Zammad fails there, with a transcript that reads from top to bottom. A release is published by pushing a v* tag, through RubyGems trusted publishing, so no API key is stored in the repository. Before it publishes, the workflow refuses a tag that disagrees with ZammadAPI::VERSION or has no heading in the changelog, and runs the checks again. Dependabot groups its updates, so a week's bumps arrive as one pull request for the actions and one each for the runtime and the development gems. --- .github/dependabot.yml | 11 ++ .github/workflows/ci.yml | 174 ++++++++++++++--- .github/workflows/release.yml | 45 +++++ script/check_connection.rb | 339 ++++++++++++++++++++++++++++++++++ 4 files changed, 547 insertions(+), 22 deletions(-) create mode 100644 .github/workflows/release.yml create mode 100755 script/check_connection.rb diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 710ebe8..84471df 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -5,7 +5,18 @@ updates: directory: "/" schedule: interval: "weekly" + groups: + actions: + patterns: ["*"] - package-ecosystem: "bundler" directory: "/" schedule: interval: "weekly" + groups: + # Lint and type tooling churns often and never affects the shipped gem. + development: + dependency-type: "development" + patterns: ["*"] + runtime: + dependency-type: "production" + patterns: ["*"] diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 144eff7..152ea0a 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1,57 +1,187 @@ name: CI + on: push: branches: [master] pull_request: schedule: - # Run every on Friday to ensure everything works as expected. - - cron: '0 6 * * 5' + # Weekly, to catch breakage from new Ruby or Zammad releases. + - cron: '0 6 * * 5' + workflow_dispatch: + inputs: + zammad_ref: + description: 'Zammad git ref to run the integration specs against' + default: 'develop' + type: string + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + +permissions: + contents: read + jobs: lint: + name: RuboCop runs-on: ubuntu-latest - container: - image: zammad/zammad-ci:latest steps: - uses: actions/checkout@v7 - - name: Run lint actions - shell: bash - run: | - source /etc/profile.d/rvm.sh # ensure RVM is loaded - bundle update --bundler - bundle install -j $(nproc) - bundle exec rubocop - test: + - uses: ruby/setup-ruby@v1 + with: + ruby-version: '4.0' + bundler-cache: true + - run: bundle exec rubocop --format github + + types: + name: Steep + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + - uses: ruby/setup-ruby@v1 + with: + ruby-version: '4.0' + bundler-cache: true + - run: bundle exec steep check + # sig/vendor is always on the load path here but never in the gem, so + # the published set is checked on its own as well. + - run: bundle exec rake rbs_published + + unit: + name: Unit specs (Ruby ${{ matrix.ruby }}) + runs-on: ubuntu-latest + strategy: + fail-fast: false + matrix: + # Stable releases only, from required_ruby_version up to the current + # stable line. There is no 3.5: that line was abandoned after + # 3.5.0-preview1 and became 4.0. + # + # 'head' is absent. It could not install while the lockfile said + # `BUNDLED WITH 2.6.9`: bundler self-downgraded from head's 4.1.0.dev + # and died with NameError on the removed Pathname::SEPARATOR_PAT, and + # without the lockfile a fresh resolution pulled steep -> listen -> + # rb-inotify -> ffi, whose native gems require Ruby < 4.1.dev. The + # lockfile now names Bundler 4.0.20, which does not use that constant, + # so the first of those may be gone; head has not been retried since. + ruby: ['3.4', '4.0'] + env: + # The unit specs do not need the type-checking toolchain, and skipping it + # keeps this job fast. The `types` job installs it separately. + BUNDLE_WITHOUT: development + steps: + - uses: actions/checkout@v7 + - uses: ruby/setup-ruby@v1 + with: + ruby-version: ${{ matrix.ruby }} + bundler-cache: true + - name: Run unit specs + run: bundle exec rake spec:unit + env: + COVERAGE: 'true' + + integration: + name: Integration specs (live Zammad) runs-on: ubuntu-latest + # Booting Zammad costs far more runner time than the unit suite, so there + # is no point paying for it when the unit specs are already failing. + needs: unit + # A full Zammad boot takes many minutes; without a cap a hung boot would + # occupy a runner until the six hour default expires. + timeout-minutes: 45 container: image: zammad/zammad-ci:latest services: postgresql: - image: postgres:17 + image: postgres:18 env: POSTGRES_USER: zammad POSTGRES_PASSWORD: zammad redis: image: redis:7 + env: + ZAMMAD_REF: ${{ inputs.zammad_ref || 'develop' }} + TEST_USER: admin@example.com + TEST_PASSWORD: test steps: - uses: actions/checkout@v7 - - name: Set up Zammad + + - name: Report the toolchain shell: bash run: | - git clone --depth 1 https://github.com/zammad/zammad.git + source /etc/profile.d/rvm.sh + # The gem requires Ruby >= 3.4; fail here with a clear message rather + # than inside a confusing bundler resolution error. + ruby -v + ruby -e 'abort "zammad-ci image ships Ruby #{RUBY_VERSION}, this gem needs >= 3.4" if Gem::Version.new(RUBY_VERSION) < Gem::Version.new("3.4")' + + - name: Boot Zammad + shell: bash + run: | + # No `set -u`: /etc/profile.d/rvm.sh reads unset variables and aborts + # under nounset. + set -eo pipefail + git clone --depth 1 --branch "$ZAMMAD_REF" https://github.com/zammad/zammad.git cd zammad - source /etc/profile.d/rvm.sh # ensure RVM is loaded + source /etc/profile.d/rvm.sh bundle config set --local frozen 'true' bundle config set --local path 'vendor' - bundle install -j $(nproc) + bundle install -j "$(nproc)" bundle exec ruby .gitlab/configure_environment.rb + # Each workflow step runs in its own shell, so Zammad's generated + # environment has to be promoted to the job environment to survive. + sed -E 's/^export +//' .gitlab/environment.env \ + | grep -E '^[A-Za-z_][A-Za-z0-9_]*=' >> "$GITHUB_ENV" source .gitlab/environment.env RAILS_ENV=test bundle exec rake db:create cp contrib/auto_wizard_test.json auto_wizard.json bundle exec rake zammad:ci:test:start - - name: Run Ruby API integration tests + echo "TEST_URL=http://localhost:${RAILS_PORT:-3000}/" >> "$GITHUB_ENV" + + - name: Wait for Zammad to answer + shell: bash + run: | + probe="${TEST_URL%/}/api/v1/getting_started" + for attempt in $(seq 1 60); do + if curl -sSf --max-time 5 "$probe" >/dev/null 2>&1; then + echo "Zammad answered at $TEST_URL after ${attempt} attempt(s)" + exit 0 + fi + sleep 5 + done + echo "::error::Zammad never answered at $probe" + exit 1 + + - name: Install the gem's dependencies + shell: bash + run: | + source /etc/profile.d/rvm.sh + bundle install -j "$(nproc)" + + - name: Drive Zammad with this gem + shell: bash + run: | + source /etc/profile.d/rvm.sh + bundle exec ruby script/check_connection.rb + + - name: Run the integration specs + shell: bash + run: | + source /etc/profile.d/rvm.sh + bundle exec rake spec:integration + + - name: Collect Zammad logs on failure + if: failure() shell: bash run: | - source /etc/profile.d/rvm.sh # ensure RVM is loaded - bundle update --bundler - bundle install -j $(nproc) - bundle exec rspec + echo '--- zammad/log ---' + tail -n 200 zammad/log/*.log 2>/dev/null || echo 'no logs found' + + - name: Upload Zammad logs + if: failure() + uses: actions/upload-artifact@v7 + with: + name: zammad-logs + path: zammad/log/ + if-no-files-found: ignore + retention-days: 7 diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..63c96a2 --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,45 @@ +name: Release + +# Publishes to RubyGems via trusted publishing (OIDC), so no API key is +# stored in this repository. Configure the trusted publisher once at +# https://rubygems.org/gems/zammad_api/trusted_publishers +on: + push: + tags: ['v*'] + +permissions: + contents: read + +jobs: + release: + name: Build and publish + runs-on: ubuntu-latest + environment: rubygems + permissions: + contents: write # create the GitHub release and push the tag commit + id-token: write # request the OIDC token for trusted publishing + steps: + - uses: actions/checkout@v7 + - uses: ruby/setup-ruby@v1 + with: + ruby-version: '4.0' + bundler-cache: true + # The tag is what triggers this workflow, and nothing downstream reads + # it: the gem is built from the gemspec, so a tag that disagrees with + # ZammadAPI::VERSION publishes a gem under a version nobody tagged and + # leaves a GitHub release pointing at one that does not exist. + - name: Check the tag against the gem version and the changelog + run: | + tagged="${GITHUB_REF_NAME#v}" + declared="$(ruby -Ilib -rzammad_api/version -e 'print ZammadAPI::VERSION')" + if [ "$tagged" != "$declared" ]; then + echo "::error::tag ${GITHUB_REF_NAME} does not match ZammadAPI::VERSION ($declared)" + exit 1 + fi + if ! grep -q "^## \[${declared}\]" CHANGELOG.md; then + echo "::error::CHANGELOG.md has no '## [${declared}]' heading" + exit 1 + fi + - name: Verify the release candidate + run: bundle exec rake spec:unit rubocop steep rbs_published + - uses: rubygems/release-gem@v1 diff --git a/script/check_connection.rb b/script/check_connection.rb new file mode 100755 index 0000000..aef9884 --- /dev/null +++ b/script/check_connection.rb @@ -0,0 +1,339 @@ +#!/usr/bin/env ruby +# frozen_string_literal: true + +# End-to-end check that this gem can actually drive a live Zammad instance. +# +# Deliberately standalone: it does not load the spec suite, so it still +# reports usefully when the specs themselves are what is broken. CI runs it +# after booting Zammad and before the integration specs, so a broken +# gem-to-Zammad link fails fast with a readable transcript. +# +# TEST_URL=https://zammad.example/ \ +# TEST_USER=admin@example.com \ +# TEST_PASSWORD=test \ +# bundle exec ruby script/check_connection.rb + +$LOAD_PATH.unshift File.expand_path('../lib', __dir__) + +require 'zammad_api' +require 'faraday' +require 'json' +require 'securerandom' +require_relative 'live_target' + +# No default for the URL. This script creates and deletes records, and +# `http://localhost:3000/` is where a Zammad under development listens. +URL = LiveTarget.url || abort(LiveTarget.unset_message('This script')) + +LOGIN = ENV['TEST_USER'] || 'admin@example.com' +PASSWORD = ENV['TEST_PASSWORD'] || 'test' +SUFFIX = SecureRandom.hex(4) + +@failures = [] +@group = nil +@ticket = nil + +# Runs one named check, printing its result and recording any failure. +def check(name) + detail = yield + puts format(' ok %-42s %s', name: name, detail: detail) + true +rescue => e + @failures << name + puts format(' FAIL %-42s %s: %s', name: name, error: e.class, message: e.message) + false +end + +# A check whose failure makes every later check meaningless, so the run stops +# rather than burying the cause under cascading NoMethodErrors. +def check!(name, &block) + return if check(name, &block) + + puts "\nAborting: '#{name}' is a precondition for the remaining checks." + finish +end + +def section(title) + puts "\n#{title}" +end + +def parse_json(body) + JSON.parse(body) +rescue JSON::ParserError + {} +end + +def cleanup + return if @group.nil? && @ticket.nil? + + section 'Cleanup' + check('destroy the ticket') { CLIENT.tickets.destroy(@ticket.id) } if @ticket + check('destroy the group') { CLIENT.groups.destroy(@group.id) } if @group +end + +def finish + cleanup + puts + if @failures.empty? + puts 'All checks passed.' + exit 0 + end + + puts "#{@failures.size} check(s) failed:" + @failures.each { puts " - #{it}" } + exit 1 +end + +puts "Checking #{URL} with zammad_api #{ZammadAPI::VERSION} on Ruby #{RUBY_VERSION}" + +section 'Instance setup' + +# The auto wizard creates the admin account. An instance that is already +# configured reports failure here, which is fine as long as it is set up. +check!('auto wizard or already configured') do + wizard = parse_json(Faraday.new(url: URL).get('api/v1/getting_started/auto_wizard').body) + next 'auto wizard ran' if wizard['auto_wizard_success'] + + # A configured Zammad requires authentication even for + # /api/v1/getting_started, so the setup state cannot be read from there. + # An authenticated request answers the only question that matters. + ZammadAPI::Client.new(url: URL, user: LOGIN, password: PASSWORD, retries: 0) + .groups.all.page(1, per_page: 1).to_a + 'already set up' +end + +CLIENT = ZammadAPI::Client.new(url: URL, user: LOGIN, password: PASSWORD, timeout: 30) + +section 'Client' + +check('credentials are redacted') do + raise 'password leaked into inspect output' if CLIENT.config.inspect.include?(PASSWORD) + + 'password absent from inspect output' +end + +check('derived client re-validates options') do + CLIENT.with(timeout: 45) + CLIENT.with(timeout: -1) + raise 'expected ConfigurationError' +rescue ZammadAPI::ConfigurationError + 'invalid option rejected' +end + +section 'Records' + +check!('create a group') do + @group = CLIENT.groups.create(name: "smoke-#{SUFFIX}", note: 'created by check_connection.rb') + raise 'no id assigned' if @group.id.nil? + + "id=#{@group.id}" +end + +check('find it back') do + found = CLIENT.groups.find(@group.id) + raise "name mismatch: #{found.name}" if found.name != "smoke-#{SUFFIX}" + + found.name +end + +check('update only the changed attribute') do + @group.note = 'updated' + raise 'change not staged' if !@group.changed? + + @group.save + CLIENT.groups.find(@group.id).note +end + +check('reload discards local changes') do + @group.note = 'not saved' + @group.reload.note +end + +check('pattern match a record') do + case CLIENT.groups.find(@group.id) + in { name: String => name, active: true } then name + else raise 'record did not match the expected pattern' + end +end + +section 'Collections' + +check('iterate every group across pages') do + names = CLIENT.groups.all.map(&:name) + raise 'created group missing from .all' if !names.include?("smoke-#{SUFFIX}") + + "#{names.size} groups" +end + +check('fetch a single page') { "#{CLIENT.groups.all.page(1, per_page: 1).to_a.size} record" } + +check('lazy enumeration stops early') { CLIENT.groups.all.lazy.map(&:id).first(1).inspect } + +check('page by page') do + pages = 0 + CLIENT.groups.all.in_batches(of: 1) { pages += 1 } + "#{pages} page(s)" +end + +check('search') { "#{CLIENT.users.search(LOGIN).to_a.size} hits" } + +# These were never driven against a live Zammad, which is why nobody noticed +# that an attribute filter passed to an index endpoint never reached the query +# at all. +check('find_by returns a record that matches') do + found = CLIENT.groups.find_by(name: "smoke-#{SUFFIX}") + raise 'no record found' if found.nil? + raise "found the wrong record: #{found.name}" if found.name != "smoke-#{SUFFIX}" + + "id=#{found.id}" +end + +# Two string attributes, because one is the shape that works whatever the +# search term looks like. Joined into a single term - which is what this used +# to send - the query asks every string column to contain the whole of it, and +# on an instance searching through SQL LIKE rather than Elasticsearch no +# column does, so a record that exists comes back as nil. A stubbed unit spec +# cannot see that; it answers whatever term it is handed. +check('find_by matches on two string attributes') do + group = CLIENT.groups.find(@group.id) + found = CLIENT.groups.find_by(name: group.name, note: group.note) + raise 'no record found' if found.nil? + raise "found the wrong record: #{found.name}" if found.id != group.id + + "id=#{found.id}" +end + +check('find_by returns nil for no match') do + found = CLIENT.groups.find_by(name: "no-such-group-#{SUFFIX}") + raise "expected nil, got #{found.inspect}" if !found.nil? + + 'nil' +end + +check('find_by! raises for no match') do + CLIENT.groups.find_by!(name: "no-such-group-#{SUFFIX}") + raise 'expected NotFoundError' +rescue ZammadAPI::NotFoundError + 'raised' +end + +check('exists?') do + raise 'the created group is missing' if !CLIENT.groups.exists?(@group.id) + raise 'a made-up id exists' if CLIENT.groups.exists?(0) + + 'true and false' +end + +check('pluck') do + names = CLIENT.groups.all.pluck(:name) + raise 'created group missing' if !names.include?("smoke-#{SUFFIX}") + + "#{names.size} names" +end + +check('empty? on a search with no hits') do + raise 'expected empty' if !CLIENT.groups.search("no-such-group-#{SUFFIX}").empty? + + 'true' +end + +check('order sorts an index endpoint that sorts') do + "#{CLIENT.groups.order(name: :desc).page(1, per_page: 2).to_a.size} record(s)" +end + +check('order refuses an index served in a fixed order') do + CLIENT.tickets.order(:title).to_a + raise 'expected ArgumentError' +rescue ArgumentError => e + e.message.split('.').first +end + +check('order sorts a search') do + "#{CLIENT.groups.search("smoke-#{SUFFIX}").order(:name, id: :desc).to_a.size} hit(s)" +end + +check('search refuses a keyword the endpoint would drop') do + CLIENT.groups.search('smoke', name: "smoke-#{SUFFIX}").to_a + raise 'expected ArgumentError' +rescue ArgumentError => e + e.message.split(':').first +end + +section 'Tickets' + +check!('create a ticket with its first article') do + @ticket = CLIENT.tickets.create( + title: "smoke ticket #{SUFFIX}", + group: 'Users', + customer: LOGIN, + article: { subject: 'smoke', body: 'created by check_connection.rb', type: 'note' } + ) + "number=#{@ticket.number}" +end + +check('read its articles') { "#{@ticket.articles.size} article(s)" } + +check('add another article') do + CLIENT.tickets.find(@ticket.id).add_article(subject: 'second', body: 'another one', type: 'note').id +end + +check('article count grew') do + count = @ticket.articles.size + raise "expected 2 articles, got #{count}" if count != 2 + + count +end + +check('attachment metadata and download') do + CLIENT.tickets.find(@ticket.id).add_article( + subject: 'with attachment', + body: 'see attachment', + type: 'note', + attachments: [{ filename: 'smoke.txt', data: ['smoke test 123'].pack('m0'), 'mime-type': 'text/plain' }] + ) + attachment = @ticket.articles.last.attachments.first + raise 'no attachment returned' if attachment.nil? + + # Once: each call is a full attachment fetch, and this transcript is meant to + # be a fast read of a freshly booted Zammad. + contents = attachment.download + raise "unexpected content: #{contents.inspect}" if contents != 'smoke test 123' + + "#{attachment.filename} (#{contents.bytesize} bytes)" +end + +section 'On behalf of another user' + +check('sends the From header') do + CLIENT.on_behalf_of(LOGIN) { |scoped| scoped.tickets.find(@ticket.id).number } +end + +check('block form leaves the outer client unscoped') do + CLIENT.on_behalf_of(LOGIN) { |scoped| scoped.groups.find(@group.id) } + CLIENT.groups.find(@group.id).name +end + +section 'Errors' + +check('missing record raises NotFoundError') do + CLIENT.groups.find(0) + raise 'expected NotFoundError' +rescue ZammadAPI::NotFoundError => e + "status=#{e.status}" +end + +check('invalid attributes raise a ClientError') do + CLIENT.groups.create({}) + raise 'expected a ClientError' +rescue ZammadAPI::ClientError => e + "status=#{e.status}" +end + +check('bad credentials raise AuthenticationError') do + ZammadAPI::Client.new(url: URL, user: 'nobody', password: 'wrong', retries: 0).groups.find(1) + raise 'expected AuthenticationError' +rescue ZammadAPI::AuthenticationError => e + "status=#{e.status}" +end + +finish From 5522667a946f12be2ce29bee6f90682c9c6bdd4d Mon Sep 17 00:00:00 2001 From: Mantas Date: Wed, 18 Nov 2026 10:10:13 +0200 Subject: [PATCH 05/11] docs: document 2.0 and the way up from 1.x The README is rewritten around the 2.0 API: creating a client, the resources, records, collections, errors, timeouts and retries, logging, the test kit and the type signatures. A coverage table sets what 1.x and 2.0 model against what Zammad's API serves, and the text around it says how to reach the rest: a resource class of the caller's own, or a raw request. "Migrating from 1.x" lists every call that changed. It starts with the changes that do not announce themselves, where 1.x code keeps running and does something different. The changelog entry for 2.0.0.alpha1 carries the same changes as a list. "Staying on 1.x" is for those who do not move yet: the 1.x code lives on the 1-stable branch, it installs with a version constraint below 2, and it stays in maintenance mode, with fixes and no new features. examples/ holds nine runnable scripts, each built on Client.from_env: a quickstart, the ways to read a collection, pagination driven by hand, a CSV export, triage with pattern matching, onboarding a customer on behalf of a user, attachment downloads, error handling, and a worker pool sharing one client. The single 1.x example went with the rewrite. --- CHANGELOG.md | 837 ++++++++++++++++ README.md | 1596 +++++++++++++++++++++++++----- examples/README.md | 38 + examples/concurrent_sync.rb | 57 ++ examples/download_attachments.rb | 45 + examples/error_handling.rb | 77 ++ examples/manual_batches.rb | 142 +++ examples/onboard_customer.rb | 85 ++ examples/pagination.rb | 71 ++ examples/quickstart.rb | 53 + examples/ticket_report.rb | 54 + examples/triage_tickets.rb | 58 ++ 12 files changed, 2863 insertions(+), 250 deletions(-) create mode 100644 examples/README.md create mode 100755 examples/concurrent_sync.rb create mode 100755 examples/download_attachments.rb create mode 100755 examples/error_handling.rb create mode 100755 examples/manual_batches.rb create mode 100755 examples/onboard_customer.rb create mode 100755 examples/pagination.rb create mode 100755 examples/quickstart.rb create mode 100755 examples/ticket_report.rb create mode 100755 examples/triage_tickets.rb diff --git a/CHANGELOG.md b/CHANGELOG.md index 422138f..c5d867e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,840 @@ +# Changelog + +## [2.0.0.alpha1] - 2026-11-17 + +The first prerelease of 2.0, a breaking release that modernises the whole gem. See +[Migrating from 1.x](README.md#migrating-from-1x) for the complete before/after guide. + +Everything below is what changed since 1.4.0. It is published as an alpha so that it can +still change: names, defaults and behaviour may differ in 2.0.0. A prerelease has to be +asked for, with `gem install zammad_api --pre` or `gem 'zammad_api', '~> 2.0.0.alpha'`. + +### Breaking + +- Minimum Ruby version is now 3.4. 3.0 through 3.2 are end-of-life, and 3.3 is in security + maintenance until March 2027. The library needs nothing from 3.4 but the `it` block + parameter, so the floor is a choice rather than a dependency. +- `Client.new` takes keyword arguments, so a configuration Hash has to be splatted: + `Client.new(**config)`. A positional Hash raises `ArgumentError`. +- An unknown client option raises `ArgumentError: unknown keyword` instead of being + ignored, so an option that is misspelled or no longer supported is no longer silent. +- `logger:` takes a `Logger` rather than a boolean flag. `logger: true` used to turn on + debug output to `$stderr`; pass `Logger.new($stderr)` for the same thing. Any object + that responds to `debug` is accepted, and anything else raises `ConfigurationError`. +- `Collection#each` (`client.x.all`, `client.x.search`) now walks every page. Previously it + fetched a single page, so iterating stopped silently at 100 records for `all` and at + 10 for `search`. +- Collections are built up by chaining instead of by keyword arguments: + `all(per_page: 50)` is now `find_each(batch_size: 50)` or `page(1, per_page: 50)`, + `all(active: true)` is `search(...)` or `all.detect { ... }`, + `search(query: 'zammad')` is `search('zammad')`, + and `search(query: 'z', page: 2, per_page: 50)` is `search('z').page(2, per_page: 50)`. + `all` accepted those keywords and then discarded them, so its page size was always + 100 and its filters never reached the request; `search` did honour `page` and + `per_page`. All of them now raise `ArgumentError` rather than being accepted. +- `page(number, per_page)` with a block was replaced by `page(number, per_page: size)`, which + returns a new collection. `page_next` and `page_prev` were removed. +- `Collection#each_page` was renamed to `#in_batches`, which also takes the page size as + `in_batches(of: 500)`. +- `Collection#[]` was removed. It cost a request per index and ignored the page a + collection was limited to; use `first`, or `page(n, per_page: 1).first` for one record at an + offset. +- `Collection#per_page` and `#current_page` are no longer public. `inspect` reports both. +- There is no `per`. The page size belongs to the call that reads: `find_each(batch_size:)` + to walk, `in_batches(of:)` to batch, `page(number, per_page:)` for one page. Everything else + fetches as many records as the endpoint serves. +- A collection fetches the endpoint's own page size rather than a fixed 100 — 1000 on the + index endpoints, 100 on `/api/v1/tickets`, 200 on a search — so a walk spends roughly a + tenth of the round trips, each of which is a fresh TLS handshake under Faraday's default + adapter. `page(n)` without `per_page:` is a page of that size, so pin it with + `page(n, per_page: 100)` where a persisted page number has to keep meaning what it did. +- A `nil` query value raises `ArgumentError`. 1.x dropped the parameter, so a filter that + happened to be `nil` requested every record and the caller iterated all of them + believing they had been narrowed. +- `client.on_behalf_of = 'login'` and `client.perform_on_behalf_of` were replaced by + `client.on_behalf_of('login')`, which returns a new client and also accepts a block. +- `ZammadAPI::ResourceNotFoundError` is now `ZammadAPI::UnknownResourceError`, freeing the + 404 case to be `ZammadAPI::NotFoundError`. +- `record.save` reports a validation failure as `false` and leaves the error in + `record.error`, instead of raising. `record.save!` is the raising form. Every other + failure — an expired token, a missing record, an unreachable instance — still raises from + both, because no attribute the caller can fix would change the outcome. + `client..create` uses `save!`, so it keeps raising rather than returning a + record that looks created but is not. +- A resource's class-level memos — the association proxy class and the `belongs_to` + foreign keys — are built under a lock. They were plain `@x ||=`, so two threads building + clients or reading associations at once could each build a different anonymous proxy + class for one resource, and whichever write lost was still held by the records already + built from it. Harmless under CRuby's GVL, wrong on JRuby and TruffleRuby, which is not + the contract `README` writes down. +- `record[:x] = 1` stages the attribute it names. It reached the writer dispatch as `[]=` + and was taken for an attribute literally called `[]` whose value was the index, so the + write was lost without an error and the next `save` sent `{"[]": "x"}` to Zammad. Ruby's + operators end in `=` too, so `record <= 5` invented an attribute called `<` the same way; + a writer is now recognised only by a plain attribute name. +- `record.destroy` and `record.reload` refuse a record that was never saved, instead of + acting on an id it was merely built with. `client.groups.new(id: 99).destroy` reported + `new_record?` true and `persisted?` false and still sent `DELETE /api/v1/groups/99`. +- `record.id = ...` raises. The id is what addresses the record, so a staged one took + effect for every path that builds a URL from the attributes and not at all for the record + those paths then reported on: `group.id = 99; group.destroy` sent `DELETE` to group 99 + and left the record saying group 1 was the one destroyed. Zammad does not let an id be + set either, so no call that used to reach the server is lost. The constructor refuses it + too: `client.groups.new(id: 5)` raises, because a new record is sent in full, so the one + spelling that reached the wire was the one nothing checked. `Resource.from_response` is + how a body Zammad served becomes a record carrying its id. +- `record.destroy` marks the record `destroyed?`, and `persisted?` answers false for one. + 1.x left a destroyed record looking live, so a later `save` went out as a `PUT` to the + deleted id and came back a 404 one call after the mistake. +- `record.attributes` and `record.changes` are deeply frozen, and `record.to_h` returns a + deep copy rather than a shallow one. Writing through either reader used to change what a + record reported without staging anything, so the next `save` did not send it, and a + nested hash from `to_h` was shared with the record. +- The `record.attributes=` writer was removed. An unknown name is an ordinary attribute + now, so `record.attributes = {name: 'Support'}` stages a change called `attributes` + that `save` sends to Zammad. Use `assign_attributes` or `update`. +- `ZammadAPI::Error` descends from `StandardError` instead of `RuntimeError`. +- `ResponseError#response` returns a `ZammadAPI::Response`, not a Faraday object, and + `#body` is the decoded payload rather than a raw JSON string. +- No Faraday exception escapes any more: an unreachable host or a timeout raises + `ZammadAPI::ConnectionError` or `ZammadAPI::TimeoutError`, so a + `rescue Faraday::ConnectionFailed` stops matching. +- `ZammadAPI::ListBase`, `ListAll` and `ListSearch` were replaced by `ZammadAPI::Collection`. +- `ZammadAPI::Log` and `ZammadAPI::JsonHelper` were removed. Pass any `Logger` via `logger:`. +- `ZammadAPI::Dispatcher` was replaced by `ZammadAPI::ResourceProxy`. +- The resource readers on a client are plural: `client.tickets`, `client.users`, + `client.groups`, `client.organizations`, `client.ticket_articles`, + `client.ticket_priorities` and `client.ticket_states`. A resource is `Enumerable` over + every record of its kind, so `client.ticket.each` and `client.ticket.first(5)` read as if + they acted on one ticket; the singular dates from 1.x, when a resource was only a + dispatcher for `find` and `create`. The singular names still work, as deprecated aliases + that warn in Ruby's `deprecated` category — silent unless the application asks for + deprecation warnings, with `ruby -W:deprecated` or `Warning[:deprecated] = true` — and + will be removed in 3.0. `client.resource(:ticket)` is answered the same way, and + `client.resource_names` lists the plural names. +- The resource readers a client has are a fixed list. 1.x resolved `client.` to + `ZammadAPI::Resources::` through `const_get`, so a subclass of `Base` defined in + application code could be reached that way. `client.role` now raises + `UnknownResourceError`; hand the class over instead, with `client.resource(Role)`. +- The internal `new_instance` accessor was replaced by `new_record?` and `persisted?`, and + the instance-level `url` accessor by the class-level `resource_path`. Both old names now + raise `NoMethodError` as unknown attributes, naming the attributes the record does carry. +- A reader for an attribute the record does not carry raises `NoMethodError` instead of + answering `nil`. A typo read as `nil` and flowed on into whatever was written with it, + and `respond_to?` and `method` disagreed with the call throughout, so generic code that + asks before it calls was told the reader did not exist. `record[:x]`, + `record.fetch(:x, nil)` and `record.key?(:x)` are the readers for an attribute that may + legitimately be absent — which it may, because Zammad serves a reduced object where the + authenticated user may not see the whole record, and the message says so. +- `Collection#find` raises `ArgumentError` when given an id. `find` on a resource proxy is + the lookup by id; on a collection it is `Enumerable#find`, whose argument is an ifnone + callable — so `client.tickets.all.find(1)` answered with an `Enumerator`, made no request + and raised nothing. Use `client.tickets.find(1)`, or `detect { … }` for the block form. +- `TicketArticle#attachments` raises `ParseError` for attachment metadata that is not a + list of objects, where it used to die with a bare `NoMethodError` from inside the gem — + past the `rescue ZammadAPI::Error` every caller is told to write. +- `page(number, per_page: size)` raises `ArgumentError` when `size` is larger than the endpoint + serves, instead of quietly reducing it. A reduced page size moves the page: + `page(3, per_page: 500)` against `/api/v1/tickets` went out as `page=3&per_page=100` and + answered with records 201–300 rather than 1001–1500, so a job checkpointing a page + number re-read what it had already handled. `find_each(batch_size:)` and + `in_batches(of:)` are still reduced, because a batch size names how much to fetch per + request, not which records the call is about. +- `find_by` searches one string value — the longest. Zammad matches words, so + `find_by(active: true)` searched for `"true"` and found nothing. Every other value is + compared against the record, so `find_by(email: '…', active: true)` searches the email + and compares both, and a lookup with no string in it walks the index instead. The values are + never joined into a single term: an instance searching without Elasticsearch matches the + term literally, through a SQL `LIKE` over each string column, so + `find_by(firstname: 'Jane', lastname: 'Doe')` asked for one column containing + `"Jane Doe"` and reported a user that exists as `nil`. +- `search` raises `ZammadAPI::Error` on a resource Zammad routes no search endpoint for — + `ticket_states`, `ticket_priorities` and `ticket_articles`. Those endpoints answered 404, + which arrived as a `NotFoundError` about a record from a call that asked for a list, and + reached `find_by` the same way, so `find_by(…) || create(…)` raised instead of creating. + `find_by` walks those lists instead of searching them. +- Nothing reads an `x-total-count` response header any more, because Zammad has never sent + one — from any endpoint, in any version. `Response#reported_total` was built on it, and + two guards read that: `Collection#each` would have ended a walk one request early on the + reported figure, and a `has_many` reader would have refused a list it judged truncated. + Both were dead, and the one that could have acted was the one that could have been + wrong, since it ends a walk on a figure the records do not corroborate. Zammad reports a + total in the body instead, and only where asked: `only_total_count` — which is what + `Collection#count` uses on a search — or `with_total_count` on `/search`, and `full` on + the index endpoints that render through `model_index_render`. +- A record id of `.` or `..` raises `ArgumentError`. Both are made entirely of unreserved + characters, so escaping carried them through and `find('..')` resolved one path level + up — onto the index endpoint, or through a `has_many` path onto every article on the + instance offered as one ticket's. +- A configuration that names more than one way to authenticate raises `ConfigurationError`. + `http_token`, `oauth2_token` and `user` with `password` used to be accepted together, and + the first of them in that order was sent without a word about the others — which is what + let `from_env(user:, password:)` and `with(oauth2_token:)` keep sending an old token. A + client authenticates one way by construction now. `from_env` and `with` drop the + credentials an override replaces, so switching schemes through either still works, and an + environment that itself sets two schemes is refused until an argument says which is meant. +- `ticket.article(…)` is `ticket.add_article(…)`. A noun that sends a `POST` sat one letter + away from `ticket.articles`, which only reads. `article` still works, as a deprecated + alias that warns in Ruby's `deprecated` category the way the singular resource readers do, + and will be removed in 3.0. It requires its attributes, as it did in 1.x, so a bare + `ticket.article` raises `ArgumentError` rather than sending an article with no body. + +### Added + +- `Collection#first` and `#take` size their own request: `all.first` is one request for one + record and `all.first(5)` one request for five, where `Enumerable` took them off the + front of a page sized for walking. The request is sized rather than the collection + limited to a page, so a read still walks on where a page comes back shorter than it was + asked for — `first(5)` answers with five records if five exist. A collection `page` + already limited keeps its own size, because that size says which records it holds. +- `client.get`, `#post`, `#put` and `#delete` take `headers:`, for an endpoint that needs + one. Names are case-insensitive and two spellings of one header are refused rather than + merged; `Authorization` and `From` are refused outright, being what the client's + credentials and `on_behalf_of` are for. +- `Test::Request#headers` records the headers a request asked for, stringified and + downcased through the real transport's own rules, so a stand-in cannot accept a header + the wire would refuse. +- `client.get`, `client.post`, `client.put` and `client.delete` reach any endpoint of the + Zammad API, including the many this gem does not model. They return a + `ZammadAPI::Response` and keep authentication, timeouts, retries, credential redaction, + JSON decoding and the error classes. Previously the only way past the seven resource + classes was to build a Faraday connection by hand. +- Request and connection timeouts (`timeout`, `open_timeout`), on by default at 60 and + 10 seconds. 1.x waited as long as the server took, so a call that used to hang now + raises `TimeoutError`. +- Automatic retry with exponential backoff for a `GET` on connection failures, timeouts + and transient statuses. A write is never retried. `POST` would create a second record, + and `PUT` and `DELETE` are not safe to repeat against Zammad either: a ticket update + carrying an `article` adds that article, and sends its e-mail, once per delivery, and a + `DELETE` repeated after a lost answer comes back as a 404 for a record that was just + deleted, so `destroy` raised `NotFoundError` and left the record looking live. +- A specific error class per status: `AuthenticationError` (401), `AuthorizationError` + (403), `NotFoundError` (404), `ValidationError` (422) and `RateLimitError` (429, with + `#retry_after`). Network failures raise `ConnectionError` or `TimeoutError` instead of + leaking Faraday exceptions. +- `Collection#order`, `#page`, `#in_batches`, `#find_each`, `#count` and lazy + enumeration, plus `client.x.order(...)` as a shorthand for `all.order(...)`. +- `order` sorts on the server: `order(:name)`, `order(name: :desc)`, + `order(:active, name: :desc)`, read the way ActiveRecord reads them, and a second + `order` sorts within the first. Sorting is the one thing an index endpoint does besides + paging. `/api/v1/tickets` and `/api/v1/users` do not even do that — their controllers + hardcode id order — so `order` on those raises `ArgumentError` rather than handing back + records it would be calling sorted; a search sorts for every resource that can be + searched. +- `search` takes what a search endpoint narrows by besides the term as keywords: + `condition:` and `ids:` on every search, and `role_ids:`, `group_ids:` and `permissions:` + on users, the one search that reads them. Any other keyword raises `ArgumentError`, + because Zammad drops a parameter it does not know rather than refusing it, and the search + would come back unnarrowed with nothing to say so. That includes a user keyword on + another resource: `tickets.search('printer', group_ids: [2])` was sent as written and + answered with tickets from every group, where a `condition` on `ticket.group_id` is what + narrows them. A keyword with nothing in it raises too, an empty list, an empty Hash, a + Hash of nothing but empty Hashes, or a value that is sent as a blank String: Zammad reads + it as not given, so `search('smith', ids: [])` came back with + every user matching the term rather than none. A resource of your own declares what its search reads with + `search_filters`. `group_ids:` is a list of group ids, for the agents with `full` access + to them, or a Hash of group id to access, `group_ids: {2 => ['read']}`, for any other: + Zammad reads a group named without an access as `full`. `permissions:` is not an access + check: where Zammad searches through Elasticsearch, a permission no active role grants + leaves the search unnarrowed. `role_ids:` narrows on both paths and is not one either: it + matches a user holding a role that has been disabled. The README says what to check. +- There is no `where`. During the development of 2.0 there was one, which took `sort_by` + and `order_by` on a generic index, nothing at all on tickets and users, and the search + parameters on a search, and raised for everything else — an attribute filter above all, + since Zammad's index endpoints do not filter. The most familiar verb on a collection + refused nearly everything it was given, so the two things it did do have names of their + own: `order`, and the keywords of `search`. +- A resource proxy is `Enumerable` over `all`, so `client.tickets.each`, + `client.tickets.first(5)`, `client.tickets.map`, `#find_each`, `#in_batches`, `#page`, + `#pluck` and `#count` all work without naming `all`. `client.x.find(id)` keeps + its own meaning rather than becoming `Enumerable#find`; `detect` is the block form. +- `Collection#count` costs a single request on a search endpoint, which Zammad can count + without returning the records. +- `Collection#pluck(*attributes)`, for reading one or more attributes from every record. +- `client..find_by(**params)` and `#find_by!`, which look a record up by + attribute value, and `client..exists?(id)`. `find_by` answers on every + resource and for any kind of value: the first record that carries the values, `nil` if + it finds none. It fetches candidates and checks them itself, because Zammad's index + endpoints cannot filter — through a search where the resource has a search endpoint and + one of the values is a string, and by walking the index everywhere else, which is what + `ticket_states`, `ticket_priorities` and `ticket_articles` and a lookup such as + `find_by(active: true)` get. A walk costs a request per page until a record matches. It + returns a record that genuinely carries the attributes asked for, or nil; a record that + does not carry an attribute does not match it, not even for `nil`. What the search can + surface is Zammad's business, so `find_by(...) || create(...)` can still create a + duplicate — as writing the search out by hand would. Without Elasticsearch a search + reads only the string columns of a user, organization or group, and of a ticket only the + title, the number and its articles, so a lookup by anything else answers `nil` there; + the README lists what that covers and why `find_by` does not walk the index after a + miss. Every page of hits is read until + one matches, so a miss costs a request per page of hits: Zammad's search sorts by + `updated_at`, newest first, rather than by relevance, so the exact match can be on any + page. +- `ResponseError` accepts a `detail:` describing a failure that has no HTTP response of its + own, so `find_by!` reads as `no record matched` rather than `no response`. Such an error + still reports the status its class is the name for, so a `NotFoundError` raised without a + request answers `404` like every other one. +- The page size is clamped to what an endpoint serves (100 for `/api/v1/tickets`, 200 for + a search, 1000 for the other index endpoints). Asking for more used to end iteration + after the first page, because Zammad capped the response and the short page read as the + end of the list. A walk also learns the size the endpoint actually serves from its first + page, so an instance that pages smaller than those figures is still walked to the end + rather than truncated. +- `find_each(batch_size:)` and `in_batches(of:)` raise when the collection is already + limited to a page. `page(3, per_page: 50)` and a batch size are two ways of naming the same + thing, and re-sizing the page behind the caller would hand back different records. +- `ZammadAPI::PaginationError`, raised when an endpoint answers a page with the page + before it, instead of paging forever. +- `Base#reload`, `#persisted?`, `#[]`, `#fetch`, `#to_h` and a readable `#inspect`. +- `record.update(attributes)`, `record.update!(attributes)` and + `record.assign_attributes(attributes)`. Applying a hash of changes previously meant one + writer call per attribute before `save`. +- `ssl_verify`, `proxy`, `user_agent`, `retries` and `retry_interval` client options. + The default `User-Agent` is now `zammad_api-ruby/` rather than + `Zammad API Ruby`. +- `adapter` and `middleware` client options, the seam into the Faraday stack. Swapping in a + persistent-connection adapter or adding instrumentation previously meant that the HTTP + stack was closed to callers. A Faraday error while building the connection surfaces as + `ConfigurationError`, so Faraday stays an implementation detail. +- RBS signatures in `sig/`, verified by Steep in CI. +- `require 'zammad_api/test'` ships a stand-in Zammad for testing code that calls this + client: `ZammadAPI::Test#stub` declares responses, `#client` hands back a real client + wired to them, and `#requests` records what was sent. Responses travel the same decoding, + error mapping and record building as real ones, so a stubbed 404 raises `NotFoundError`. + An unstubbed request raises rather than answering with something empty. Consumers + previously had to intercept HTTP to test against this client at all. +- `respond_to?` now answers correctly for attribute readers and resource methods. +- Records implement `deconstruct_keys`, so they can be used with `case/in` pattern + matching, including against nested attributes. `Config` and `Response` are `Data` + objects and match as well. +- `Client#with(**options)` derives a new client with changed options. The options are + re-validated and any `on_behalf_of` scope is carried over. +- `Client.from_env` builds a client from `ZAMMAD_URL`, `ZAMMAD_TOKEN`, + `ZAMMAD_HTTP_TOKEN`, `ZAMMAD_OAUTH2_TOKEN`, `ZAMMAD_USER` and `ZAMMAD_PASSWORD`, with + passed-in options winning. Every example script used to repeat the same `ENV.fetch` pair. +- `Client#me`, the user the credentials authenticate as, and `Client#version`, the version + of the Zammad instance. +- `Response#decoded(:object | :array)` validates the shape of a response body in one + place, so an unexpected payload raises `ParseError` with a consistent message instead of + failing further downstream. +- `record.related` reaches the records a record points at: `ticket.related.customer`, + `ticket.related.group`, `ticket.related.articles`, `user.related.organization`, and + `created_by` / `updated_by` on everything. Following a foreign key used to mean + `client.users.find(ticket.customer_id)` by hand. The readers sit under `related` rather + than on the record because Zammad expands an association into a name under the plain + attribute, and `ticket.customer` has to keep returning that name rather than turning + into a request. `Resource.associations` lists what a resource declares. +- Records compare as the Zammad records they came from: two records of the same kind with + the same id are equal, and `#hash` agrees, so `uniq`, `Set`, `include?` and records as + Hash keys all work. They previously compared by object identity, so the same ticket + fetched twice was two unequal records. A record with no id stays equal only to itself, + which means its first save changes its hash and a record used as a Hash key before that + save has to be rehashed after it. +- `record.to_json` and `record.as_json` render a record's attributes. `to_json` previously + fell through to `Object#to_json`, which serialized a record as the string + `"#"`. +- `Collection#empty?`, and `#size` / `#length` as names for `#count`. `Enumerable` supplies + none of the three, so `client.tickets.all.empty?` used to raise `NoMethodError`. `empty?` + costs one request and asks for a single record rather than a whole page, except on a + collection limited to one page, where the page size decides which records that page holds. + A resource proxy forwards all three. +- `client.resource(SomeClass)` takes a subclass of `ZammadAPI::Resources::Base` and answers + with a proxy for it, so an endpoint this gem does not model gets records, pagination, + `find_by`, change tracking and `save` from a class that declares its `path`: `class Role < + ZammadAPI::Resources::Base; path 'api/v1/roles'; end`, then `client.resource(Role).each { + … }`. `Base` already supported being subclassed, and `searchable`, `max_per_page`, + `sortable`, `belongs_to` and `has_many` are there to say what else is true of the + endpoint; what was missing since `const_get` went was a public way to a proxy for one, + which left raw requests as the only way to the rest of the API. An association on such a + class can point at another by its full name, `class_name: 'Acme::Role'`. +- Typed records. `ResourceProxy` and `Collection` are generic over the resource they hold, + so `client.tickets` is a `ResourceProxy[Resources::Ticket]` and `find`, `first`, + `find_by`, the block of `each` and a search all answer with a `Ticket` where the + signatures said `untyped`. Each resource declares the attributes every supported Zammad + serves for it — the columns of its table, typed the way their JSON arrives — so + `ticket.title` is a `String` and `ticket.titel` is a type error. Attributes an + administrator added are read with `record[:name]` or declared by reopening the class in a + project's own signatures; the README's Type signatures section says what else is left + undeclared and why. `spec/typed/usage.rb` is checked by `rake steep` the way a caller's + code is, and pins these types from the outside. + +### Fixed + +- Credentials are no longer written to the debug log. The old transport logged + `user:password` on every client build; payload keys such as `password` and `token` are + now redacted, and `Config#inspect` redacts credentials. A `ConfigurationError` raised + while building the connection redacts the configured url and proxy out of the underlying + message too, including where that message quoted the value through `inspect` rather than + interpolating it — which is what `URI::InvalidURIError` does, for exactly the characters + that make a URL invalid — or through `dump`, which is how it quotes a URL holding a + character outside ASCII: a proxy password with an umlaut in it stayed in the message, and + in the error kept as its cause. +- The debug log redacts a body handed over as a String and a query string written into the + path. Redaction went by key, on a Hash or a list, so + `client.post(path, body: '{"password":"..."}')` was logged as it stood, and + `client.get('api/v1/users/password_reset_verify?token=...')` printed the token in the + request line and the response line. A String body is read for its keys where it is JSON + and replaced by its size where it is not. The path is redacted by parameter name, also + in the message of a timeout and in the operation a raw request is named by in every + error it raises. +- `on_behalf_of` no longer leaks: the old `perform_on_behalf_of` used `tap` without an + `ensure`, so an exception inside the block left the `From` header set on every later + request. +- `on_behalf_of` refuses an identifier that is `nil`, empty or blank with `ArgumentError`. + Zammad reads a `From` header with nothing in it as no header at all, and a `nil` sent + none, so `client.on_behalf_of(user&.login)` with no user handed back a client that + performed every request as the account it authenticates as, and read everything that + account can see, with no error. `Client#inspect` shows the scope of a client that has + one, where it printed as the client it was derived from. +- Zammad installations served from a sub-path (`https://example.com/zammad/`) now work. + Request paths are relative, so the prefix is no longer stripped. +- Query parameters are encoded by the HTTP layer, including arrays and characters that + need escaping. +- Nested attributes inside arrays are symbolized consistently. +- A malformed or non-JSON response body no longer degrades into an empty hash that + callers then iterate as key/value pairs. +- Unknown resource names no longer resolve to unrelated Ruby classes. +- Record ids are escaped everywhere they reach a path, including the attachment download + endpoint and `has_many` association paths, so an id carrying a traversal cannot redirect + a request onto another endpoint. +- A credential carrying an unencoded `@` is redacted whole. Redaction stopped at the first + `@`, so the tail of such a password survived into `Config#inspect` and into every + `ConnectionError` message. +- `Transport#with_config` keeps the transport's own class, so a stand-in written as a + `Transport` subclass survives `client.with(...)` instead of reverting to a real HTTP one. +- `save` on a persisted record with nothing staged sends no request. The empty `PUT` it + used to issue was applied by Zammad, bumping `updated_at` and `updated_by`. +- A nested query parameter is sent as a structure rather than as its Ruby `inspect`. + `condition`, which the search endpoints narrow by and which `search` takes, went out as + `condition=%7B%22ticket.state_id%22…`; Zammad could not parse it, dropped it, and + answered with an unnarrowed search. A `nil` is now refused at any depth, and the message + names the path to it. +- A `condition` that nests groups of conditions reaches Zammad as it was written. A list of + Hashes goes out as `list[][key]=value` pairs, and Rails begins a new element only at a + key the element before it has too. Faraday writes the keys of each Hash in alphabetical + order, so a group, `{operator: 'AND', conditions: [...]}`, after a condition went out + `conditions` first and was read into the condition before it, leaving a second element + that held only an operator. Zammad was handed a selector nobody wrote: it answered that + one with a 500, and the same two elements the other way round with every ticket. The + client writes the query itself now, and begins such an element with a key the two share. + A list no order can carry raises `ArgumentError`: one whose elements share no such key, + a list directly inside a list, and an empty Hash inside a list. Every other query is + written as it was. +- Bare socket failures are retried. `Errno::ECONNRESET` and the rest were mapped to + `ConnectionError` but were missing from the retriable list, so a transient failure + through an adapter that wraps it (net_http) was retried while the same failure through + an adapter that does not raised on the first attempt. +- A list body that is not made of objects raises `ParseError` instead of failing later. An + unexpanded search answering `[1, 2, 3]` stored an Integer as a record's attributes, and + the first reader died with `TypeError: no implicit conversion of Symbol into Integer`. + A `null` among the records is refused as well. It passed the check, which could not tell + a `nil` it had found from having found nothing, and a walk then raised `NoMethodError` + reading the ids of the page. +- `destroy` clears the staged changes and the last validation error, and refuses the + association readers. A destroyed record went on reporting `changed?` and a change set + that can never be sent, and `record.related` went on requesting a record that no longer + exists — dropping the memo was not enough on its own, because the reader rebuilt one on + the next call. `record.related`, `ticket.articles` and `ticket.add_article(…)` all raise + `ZammadAPI::Error` for a destroyed record now, rather than reaching the server for it. +- `Config#redacted_url` no longer mangles a URL whose query string contains an `@`. + `https://host?a=b@c` was rendered as `https://[REDACTED]@c`, a host that does not exist, + in every `ConnectionError` and `TimeoutError` message. +- The RBS signatures the gem ships validate on their own. They named Faraday types that + are declared only in `sig/vendor`, which is deliberately not published, so `rbs validate` + failed for every consumer with `Could not find Faraday::Connection`. +- `ZammadAPI::Test.new` no longer builds a Faraday stack it immediately discards, which a + suite using `let(:zammad) { ZammadAPI::Test.new }` paid for once per example. +- The trailing slash a base URL is normalised with lands on the path rather than at the end + of the string. `https://host/zammad?tenant=acme` became `https://host/zammad?tenant=acme/`, + which every request was then resolved against and every `ConnectionError` printed. +- `Config` refuses a URL with a scheme and no host, and one that is not a String. Both used + to be accepted: `'https://'` failed deep inside the adapter on the first request, and a + `URI` — what `URI(...)` hands back, and it prints as the URL — died as a `NoMethodError` + past the `ConfigurationError` the constructor is documented to raise. +- `user_agent: nil` falls back to the gem's own value instead of reaching Faraday as a nil + header, which Faraday filled in with its own — so the gem silently stopped identifying + itself in the instance log an operator greps to find its requests. A `user_agent` that is + not a String raises `ConfigurationError`. +- A line break inside `http_token`, `oauth2_token` or `user_agent` raises + `ConfigurationError` when the client is built, and one inside an `on_behalf_of` + identifier or a raw request's header raises `ArgumentError`. Each was taken and then + refused by Net::HTTP at the first request, with an `ArgumentError` that quoted the value, + the access token included. Neither message quotes it now. A line break at the end, as a + token read from a file has, is stripped by Net::HTTP and still taken. +- Proxy credentials are redacted whether or not the proxy URL carries a scheme. + `proxy: 'user:secret@proxy:8080'` — the shape an `http_proxy` setting is copied out of — + rendered in `Config#inspect` in full. +- A `proxy` that is not a URL, and a `middleware` callable that raises, are reported as + `ConfigurationError`. Only `Faraday::Error` was wrapped, so these escaped as + `URI::InvalidURIError` and as whatever the callable raised, past the + `rescue ZammadAPI::ConfigurationError` around building a client. +- The debug log redacts `api_key`, `apikey`, `passwd`, `pwd` and a bare `key` as well. The + pattern matched `private_key` but not the other key spellings, and `password` but not its + short forms, so those payload values were written out in full. +- `destroyed?` is sticky. `reload` re-read a record that no longer exists and cleared the + flag on the way back, so a destroyed record came back reporting itself as `persisted?` + and its next `save` issued a `PUT` against the deleted path; a second `destroy` surfaced + Zammad's 404 rather than saying the record was already gone. `save`, `reload` and + `destroy` now all refuse a destroyed record with the same local error. +- `record.fetch` refuses more than one fallback, the way `Hash#fetch` does. `fetch(:a, :b, + :c)` — a multi-key read this has never been — was answered with `:b`. +- A collection smaller than one page costs one request rather than two. The walk confirms + the end of a short page with another request, which could only ever come back empty; it + now stops on the total the endpoint reports alongside the page, and only falls back to + confirming when the endpoint reports none. The total has to be corroborated by the page + it arrived with — the page came back short of the size requested, and exactly as many + records were seen as the total names. It is the one stop condition not derived from the + records the endpoint served, and a total that under-reports (a count taken before + permission scoping, a stale cache, a proxy rewriting the header) ended the walk early: + 100 of 150 records came back, nothing was raised, and nothing told that result apart + from a complete one. +- The test kit records a request body by value. Held by reference, a test that built one + payload, sent it, then changed it for a second call rewrote the first recorded request + and asserted against a body that never went anywhere. `Test#inspect` also reads the + recorded requests under the monitor that guards them. +- A record is persisted because Zammad answered 2xx, not because the answer parsed. The + create response was decoded before the flag went down, so a 201 carrying something other + than a JSON object — an HTML error page from an intervening proxy — raised `ParseError` + with the record still looking new. The ticket existed in Zammad while the record here did + not, and a retried `save` POSTed a second one. What that leaves behind is a record that + is persisted and has no id, and `save`, `reload` and `destroy` all refuse it by name + rather than pretending: a record built by `new` has nothing staged, so the retried `save` + took the "nothing changed, nothing to send" short circuit and returned `true` without + making a single request, for a record that may or may not be in Zammad. +- A `ConfigurationError` raised while building the connection no longer quotes the proxy + credentials. `proxy: 'http://user:pa ss@host:3128'` came back as + `URI::InvalidURIError` with the whole URL, password included, in a message that lands in + every log and exception report — the case `Config#inspect` exists to prevent, reached by + another route. +- `Config` refuses a `proxy` that is not a String, an `adapter` that cannot be a Symbol, + and an `ssl_verify` that is not a boolean. A `URI` proxy was accepted and then died as a + `NoMethodError` inside `inspect`, so the object documented as safe to log raised at the + moment something logged it; `adapter: 1` and `adapter: true` escaped the constructor as + `NoMethodError`; and `ssl_verify: 'false'` — a plausible environment read — is the + truthy string `"false"`, so verification stayed on while the caller believed otherwise. +- An `OpenSSL::SSL::SSLError` that an adapter did not wrap is mapped to `ConnectionError` + like its Faraday counterpart. Unlisted, a certificate mismatch through such an adapter — + and this gem lets a caller choose one — escaped `request` raw, past every + `rescue ZammadAPI::Error`. It is not retried: a rejected certificate is a fact about the + instance, not a transient failure. +- A resource subclassed by a caller keeps its parent's API path. Class-level state is not + inherited, so `class MyTicket < Ticket; end` inherited all nine of Ticket's associations, + its page limit and its searchability, and lost only the path — `MyTicket.resource_path` + raised "does not declare an API path" from a class that plainly did. +- The test kit answers a later page of a singly-stubbed list endpoint the way an endpoint + out of records would. A stub that kept serving the same records to every page tripped the + repeated-page guard, so the obvious `stub(:get, 'api/v1/groups', body: [...])` made every + full read of that collection raise `PaginationError`. Against a real Zammad the same code + works, because page 2 comes back empty; the stand-in was what differed. A stub that names + a `page` is still served exactly as written. +- The test kit sequences stubs within an identical query scope rather than across every + scoped stub for an endpoint. Two stubs naming different parameters both match a request + carrying all of them, and they were read as a sequence: stubbing a search once for its + records and once for its count made `count` consume the records stub, hand back an Array + where a count belonged, and then report the endpoint as unstubbed. The most specific + scope now answers, and two that are equally specific raise + `ZammadAPI::Test::AmbiguousStubError` rather than one of them being picked. +- `Collection#count` reads the total from the header when a search endpoint ignores + `only_total_count`. The probe came back as the usual page of records and was thrown away, + so the answer cost 1 + N requests instead of N. +- `update` and `update!` refuse a destroyed record before staging anything. They assigned + first and saved second, and `save!` is where the destroyed check lives, so `update` on a + destroyed record raised and left it `changed?` with a change set that can never be + sent — the state `destroy` clears the staged changes to prevent. +- Writing an attribute the record does not carry is a change, and is sent. Zammad reduces + the object it serializes for a permission-scoped client, so a key being absent says + nothing about what is stored; read as a `nil` original, `group.note = nil` compared equal + to nil, staged nothing and was still merged into the attributes. The write was dropped + without a word, `save` returned `true` having sent no request, and the record went on + reporting a key Zammad never sent it, so `changes` and `attributes` disagreed. +- `ticket.add_article(...)` refuses a ticket that has not been saved instead of POSTing + `ticket_id: null` and leaving the caller to read Zammad's 422 for the reason. Every other + path in the gem that needs a stored id says so locally. +- The documentation no longer promises that a `has_many` reader refuses a partial list + with `ZammadAPI::PaginationError`. The check behind that promise read a total from an + `x-total-count` response header, which Zammad has never sent, so it never ran and was + removed — see the entry on that header under Breaking — while this entry, the README and + the comment on `has_many` went on describing it. A `has_many` list is read in a single + request because the association endpoints Zammad routes serve the whole thing: + `ticket_articles/by_ticket` renders every article of the ticket and reads no paging + parameter. Nothing in a response tells a whole list from the first page of one, so + there is no honest check to put in its place. +- The documented page sizes are sizes the endpoints actually serve. Every `find_each` and + `in_batches` example used `of: 500` against `client.tickets`, which caps at 100, so each + headline example did something other than what it showed. The clamp itself stands — a + batch size says how much to fetch at a time, not which records you get, which is why + `page` refuses an oversize size and a walk reduces it. +- A destroyed record reports the attributes Zammad last served, not a write that never + left the process. `destroy` dropped the staged change set and left the writes it + described standing, so `group.name = 'B'; group.destroy` answered `changed?` with false, + `changes` with `{}` and `name` with `"B"` — with nothing left to tell a local edit apart + from a value the server gave, in the one state where it can never be saved. +- A record Zammad served without an id is no longer told it "was saved". Zammad serves a + reduced object where the authenticated user may not see the whole record, so a plain read + can hand back a persisted record with no id; the message sent the caller to look at a + save that never happened instead of at what the client may read. +- `require 'zammad_api'` no longer depends on Faraday loading `net/http` for it. + `Timeout::Error` and `SocketError` are named in `Transport`'s class body and resolved + only because the default adapter pulled `timeout` and `socket` in transitively — so a + Faraday that stopped doing that, or a slimmer adapter, turned the require into a + `NameError` before a single request. +- `middleware:` that decodes the response body — `c.response :json` is the usual one — is + refused when the client is built, before anything is sent, with a `ConfigurationError` + naming it. Faraday's parsed Hash used to become a Ruby inspect string that `JSON.parse` + refused, which killed every record built from it with a `ParseError` naming Zammad for + what the caller's stack had done. This gem parses JSON itself and hands the undecoded + bytes to attachment downloads, so once a middleware has consumed the body there is + nothing faithful left to hand back. +- Two spellings of one query parameter raise instead of silently sending whichever Hash + order put last — at any depth, and in `search` at the call that wrote it as well as on + the wire. The same goes for two spellings of one response header in `ZammadAPI::Test`. Keys are normalised + in both places, so `search('x', 'ids' => [1], ids: [2])` and + `{state_id: 1, 'state_id' => 2}` each collapsed into one parameter and dropped the other + value without a word — including inside `condition`, the structured parameter the search + endpoints read. +- A stubbed response from `ZammadAPI::Test` carries `content-type` the way a real one does, + and is decoded by that header rather than by the Ruby type of the stub's body. Code that + branches on `response.headers['content-type']` passed against Zammad and failed against + the stand-in, or the reverse; and a stub declaring a non-JSON type still handed back a + decoded Hash, where Zammad gives the raw string and reading a record from it raises + `ParseError`. +- `record.fetch(:missing, default) { ... }` warns the way `Hash#fetch` warns, naming the + line that made the call. A bare `Kernel#warn` reports no source location, so the warning + identified neither the call site nor the library it came from. +- A raw request refuses an absolute URL with `ArgumentError`. Faraday lets one replace the + instance URL and still attaches the client's headers, so + `client.get('https://other.example/collect')` — a link taken from a response body, say — + sent the access token and the `on_behalf_of` scope to that host. The path is documented as + relative to the instance URL, and record ids were already held inside their segment; this + is the same escape one level up. The test kit refuses it too. +- A raw request refuses a path that cannot be read as a URL with `ArgumentError`. + `client.get('api/v1/tägs')` and `client.get(' api/v1/x')` raised `URI::InvalidURIError` + from inside the connection, which is neither a `ZammadAPI::Error` nor the `ArgumentError` + a path is documented to raise, after the debug log had already written a line for a + request that never left. A query string in the path that names one parameter as a value + and as a structure raised `TypeError` the same way. Both are refused before anything is + logged, with a message that does not quote the path. +- An instance `url` that carries credentials raises `ConfigurationError`. Faraday turns the + userinfo of a URL into a Basic `Authorization` header, and its authorization middleware + leaves a header that is already set alone, so with `url: 'https://old:pass@host/'` and + `http_token: 'new'` every request went out as the old account while `client.inspect` + reported `auth=http_token` — the token was never sent. Credentials belong in `user:` and + `password:`, or in one of the token options. +- `Client.from_env(**overrides)` and `Client#with` replace the credentials they override. A + credential is one of several options read in a fixed order, so a plain merge left the old + one in charge: with `ZAMMAD_TOKEN` set, `from_env(user: 'u', password: 'p')` still sent + the environment's token, and `client.with(oauth2_token: 'x')` on a token client went on + acting as the account the token belonged to, with no error. Naming one way to authenticate + now drops the others; overriding `password:` alone still keeps the `user` it pairs with. + `Config#with` does the same. +- `pp config` redacts credentials, and a transport no longer prints its connection. `Config` + is a `Data`, and `pp` — what IRB and the Rails console print a value with — has a printer + of its own for those that renders the members without going through `inspect`, so + `client.config` typed at a prompt showed the token, the password and a proxy's credentials + in full. `Transport` had no `inspect` at all, so Ruby's default printed the Faraday + connection it holds, proxy password and access token included, and every record holds its + transport. +- A proxy or instance URL whose password carries an unencoded `/`, `?` or `#` is redacted. + Each of those ends the authority early as far as URL syntax goes, so `proxy: + 'http://user:p#ss@proxy:3128'` left `user:p` as the authority, the redaction found no `@` + in it, and the password was printed by `Config#inspect` and quoted in the + `ConfigurationError` raised when the connection could not be built. Where a colon makes a + password possible, everything up to the last `@` of the whole value is blanked now. The + price is a URL with a port and an `@` further on, such as `https://host:8443/a@b`, which + renders with its host blanked: a colon cannot tell a port from a password, and that is the + mistake that leaks nothing. +- A wait before a retry is never longer than `timeout`. The retry middleware sleeps for + whatever a `Retry-After` header says and has no ceiling of its own by default, so a + maintenance page answering 503 or a rate limiter answering 429 with `Retry-After: 3600` + held the calling thread for an hour per retry — two by default — before raising the error, + whatever `timeout` and `retry_interval` said. A `Retry-After` within `timeout` is still + honoured; a longer one is not waited out, and the request fails at once with the error for + its status, `RateLimitError#retry_after` still carrying the figure. +- The test kit serves a sequence of list stubs one per read. Every full read of a collection + asks for the page after its last one, and that request took the next stub in the queue and + served it as an empty page: three stubs for `GET api/v1/groups` answered three reads with + the first, the third and the third, and the second was never seen. A request for a later + page is now answered by the stub its read began with and does not move the sequence on. +- An exceeded `open_timeout` raises `TimeoutError`. Net::HTTP reports it as + `Net::OpenTimeout`, which Faraday's default adapter wraps into `Faraday::ConnectionFailed` + with every other failure to connect, so it surfaced as `ConnectionError: … is unreachable + (execution expired)` and skipped the `rescue ZammadAPI::TimeoutError` documented to catch + it. +- A `dup` or `clone` of a record has a change set of its own. The attributes are frozen and + replaced on write, but the change set is written in place and the copy shared it: after + `copy = record.dup; copy.name = 'X'` the original reported `changed?` and a change to + `name` while still reading `name` as it was, and its next `save` sent the copy's value. + The copy also gets association readers of its own, rather than ones that read through the + original. +- An attribute write on a destroyed record raises. `update` and `update!` already refused + one, so as not to leave a change set that can never be sent, but the writers they are + built on did not ask: `group.destroy; group.name = 'Z'` left `changed?` true and `name` + reading `"Z"` on a record `destroy` promises to leave as it last was in Zammad, and the + `save` after it was the first thing to object. A named writer, `[]=` and + `assign_attributes` all refuse now, and stage nothing. +- A request body that cannot be encoded as JSON raises `ZammadAPI::Error`. Faraday's JSON + middleware raised `JSON::GeneratorError` from inside the stack and nothing mapped it, so + `client.post(path, body: {data: File.binread('a.png')})` with the bytes not + Base64-encoded, or any body holding `Float::NAN`, went past the `rescue ZammadAPI::Error` + callers are told to write — and so did a record `save` carrying such a value. The body is + encoded before the request is logged now, so a refused one leaves no line claiming a + request that was never made, and the test kit refuses it the same way. +- A walk no longer ends when the block empties the batch it was handed. The size of a page + was read after the block returned, so an `in_batches` consumer that worked its batch off + with `shift` looked like an empty page and the walk stopped after the first one, and a + batch the block shortened looked like the last. The records are counted before they are + handed over. +- A search is walked to its end where one of its pages comes back short. A walk stopped at + the first page shorter than the one before it, which is right for an index and not for a + search: Zammad has the search name the ids for a page and then loads the records by id, + so one deleted in between, or one Elasticsearch still lists after it was removed, is left + out and nothing fills its place. `search(...).each` then ended on that page with the + rest of the hits unread, and `find_by` answered `nil` for a record on a later one. Only + an empty page ends a search walk now, at the cost of one more request where the last page + of hits is part-filled. +- A search is read on past a page with nothing on it where Zammad says there are hits + behind it. A page comes back empty for the reason it comes back short, every id on it + having lost its record, and on the page of one that `first` and `empty?` ask for a single + stale hit does it: `search(term).first` answered `nil` and `empty?` answered `true` with + live hits behind a record deleted a moment before, and `each` ended on such a page. A + search that is walked sends `with_total_count` and ends on an empty page only once the + pages read cover the total reported beside it. The total never ends a walk on a page that + held records, because Elasticsearch stops counting at ten thousand hits. An empty page + still ends the walk where there is no total to go by: on a Zammad before 6.5.1, which + answers with the records alone, and past the ten thousandth hit on Elasticsearch. It can + also end the walk short of the total on an instance that serves a search in smaller pages + than were asked for, because the pages read are reckoned at the size asked for. The test + kit pages a search stubbed as `{records: [...], total_count: n}` the way it pages an + Array. +- `first`, `take` and `empty?` read on past stale search hits in pages that grow. They size + their request to the records they want, and held to that size, reading on past an empty + page cost a request for every stale hit in a row: 5000 requests for `empty?` behind 5000 + of them, on an instance whose Elasticsearch index has drifted from its database. Past an + empty page they now ask for the largest page that starts where the last one ended, + doubling up to the 200 a search serves, and the same read takes 34. No hit is passed over + or read twice. A batch size given to `in_batches` or `find_each` is left as it is. +- A `StopIteration` raised by the block a collection yields to is raised, not taken for the + end of the walk. The walk ran inside `Kernel#loop`, which rescues it, so a block calling + `next` on an enumerator of its own that ran out, as in `map { [it.id, labels.next] }`, + dropped the records and pages after that one and `map` answered with what it had. The + same block over an Array raises. +- A repeated page is recognised by the records on it rather than by their payload. A job + that writes to the records it is handed changes what they serialize as, so an endpoint + that ignores `page` served the same records with a different payload each time: the + guard never fired, and the job went round the same records, writing to them again, for + as long as it ran. Two consecutive pages holding the same ids, in any order, raise + `PaginationError` before the second is handed over. Records without an id are still + compared by payload. +- A search sends the term and the filters it was given. The collection `search` returns is + lazy and held the caller's own String, Array and Hash until it was enumerated, so + `search('printer', ids: ids)` followed by `ids << 7` searched for something the call was + never given, after the filters had been checked. `search` keeps a copy of its own, which + `page` and `order` carry on. +- A `related` kept in a variable follows its record. A save, a reload and a write to a + foreign key dropped the record's association proxy and built another on the next call, so + only a caller who asked the record again saw the change: after `related = ticket.related` + and `ticket.customer_id = 9`, `related.customer` went on answering with the user it had + resolved before, and the same after a reload. A record keeps one proxy now and empties + it. A kept one also refuses a destroyed record, as `related` does, where it used to + answer from its memo and request the articles of a ticket that is gone. A lookup that is + still on the wire when the foreign key is written, by a logger or a middleware that + reaches the record or by another thread, no longer leaves the record it fetched behind as + the answer for the new key. The proxy is emptied as well where a save answered with a 2xx + nothing could read puts the record back on what it sent: a key written while that request + was out, and an association read from it, left the record on the key it sent with the + other key's record still the answer. +- Records of two Zammad instances are no longer equal for sharing a class and an id. An id + is only unique within one installation, so a script reading two of them, such as a + migration or a sync, held ticket 1 of each as one record: `uniq` dropped one of the two, + and a Hash keyed by record answered for one instance with the other's value. `==`, + `eql?` and `hash` take in the `url` the record's client was configured with. Two clients + for one URL, and a client and its `on_behalf_of` scope, still hold the same record. +- An update Zammad acknowledged is not sent again. The staged changes were dropped only + once the response had decoded, so an update answered with a 2xx nothing could read, such + as a proxy's HTML page, raised `ParseError` with the whole change set still staged, and + the next `save` sent all of it again along with whatever had been staged since. For a + ticket's `article` that is a second article and a second e-mail. A 2xx now settles what + was sent before the body is read: the record holds the values it sent with nothing + staged, and `reload` brings in the rest. A save Zammad rejected keeps its changes staged, + as before. What is settled is what the request carried: a write that reaches the record + while the request is out, from a logger or a middleware that touches it or from another + thread, is dropped, as it is by a response that can be read, rather than settled as if + it had been sent. The body of the request is built from the same attributes it is then + settled on, read once, so a write from another thread cannot land between the two and be + sent without being settled. A key Zammad never served the record with is not kept either, which a + ticket's `article` is: kept, the same article assigned again compared equal to the first + and `save` reported `true` without sending the second reply. +- `ticket.add_article` adds to that ticket whatever its attributes say. A `ticket_id:` + among them was replaced by the ticket's own, but only under the Symbol spelling: given + `'ticket_id'` as well, the String key came later in the Hash and won when the article + symbolized its keys, so the article was posted to the ticket the caller's Hash named. + Both spellings are taken out before the ticket's id goes in. +- `on_behalf_of` keeps the user it was given. The scoped client held the caller's own + String, so a login buffer reused after `client.on_behalf_of(login)` changed who every + later request from that client was performed for. The scope is copied and frozen, in the + test kit's transport as well. +- A proxy password no longer reaches an exception report through `cause`. The + `ConfigurationError` for a connection that cannot be built had its message redacted, but + Ruby attached the error it replaced as the cause, and a report prints the whole chain: + `full_message`, a log formatter and an error tracker all showed `URI::InvalidURIError` + quoting the proxy URL in full. The cause is dropped where its report would print a + configured value that redaction changes, and kept everywhere else, so a `middleware:` + callable that raises still shows the backtrace into the caller's code. An error that + cannot render its report at all, such as one whose `detailed_message` takes no + `highlight:` keyword, is dropped as a cause too, rather than leaving in place of the + `ConfigurationError`. +- `middleware:` that adds `c.response :raise_error` is refused with a `ConfigurationError` + when the client is built, as `c.response :json` already is. It sits below the retry + middleware and raises for a 4xx or 5xx before this gem sees the response, so a `GET` + answered 503 was not retried and left as `Faraday::ServerError`, a 404 left as + `Faraday::ResourceNotFound`, which `exists?` does not rescue, and a 422 as an error + `save` does not turn into `false`. None of them is a `ZammadAPI::Error`. A subclass of + either middleware is refused as well: the stack was asked for the two by name, and + `class QuietRaiseError < Faraday::Response::RaiseError` has another. +- A `Cookie` header is redacted in the debug log, and so is `Proxy-Authorization`. A raw + request takes headers of its own and the request line prints them, and neither name + matched the words that mark a credential, so `client.get(path, headers: {'Cookie' => + ...})` wrote the session out in full. + +### Changed + +- `Response#headers` is frozen, and each response carries its own. Writing through it + changed nothing on the wire and, in `ZammadAPI::Test`, rewrote the stub for every later + request in the example. + +- `client..destroy(id)` deletes directly instead of fetching the record first. +- Resource dispatch is explicit rather than `method_missing` plus `const_get`. +- A resource declares what its endpoint does — `searchable true`, `max_per_page 100`, + `sortable false` — the way it already declared `path`, rather than by setting + `SEARCHABLE`, `MAX_PER_PAGE` and `INDEX_QUERY_KEYS`. A misspelled constant was silently + ignored and the resource kept Base's default, so `SEARCHEABLE = true` left the resource + unsearchable and every `find_by` on it raised "Zammad routes no search endpoint" with no + hint that the declaration was the problem; a misspelled declaration is a `NoMethodError` + at load. +- `client.` returns the same proxy each time rather than allocating one per call. + The proxies are built with the client and frozen, so a client stays immutable once built + and safe to share between threads without locking, as documented. Clients from `#with` + and `#on_behalf_of` get proxies of their own, so none is shared with the transport it was + derived from. +- The recursive copy behind frozen attributes, `to_h` and the test kit's recorded bodies + lives in one place (`ZammadAPI::DeepCopy`) instead of being written once per caller. +- Unit specs (`rake spec:unit`) run without a Zammad instance; the specs that need a live + server live in `spec/integration`. +- CI runs RuboCop, Steep and the unit specs on every supported stable Ruby, and publishes + releases through RubyGems trusted publishing. +- The integration job now waits for Zammad to answer before running specs, promotes + Zammad's generated CI environment into the job so it survives across steps, pins the + Zammad ref (overridable via `workflow_dispatch`), carries a timeout, and uploads Zammad's + logs on failure. It also runs `script/check_connection.rb` as a preflight, so a broken + gem-to-Zammad link fails in seconds with a readable transcript instead of 53 spec errors. +- The integration suite no longer depends on spec file order to run Zammad's auto wizard, + and tolerates an instance that is already set up. Its lifecycle examples are pinned to + definition order and say what is missing when only part of a file is run. +- `Test::UnstubbedRequestError` is a `StandardError` rather than a `ZammadAPI::Error`, so + a forgotten stub is not caught by the `rescue ZammadAPI::Error` in the code under test. +- The test kit matches array-valued query stubs, such as `query: {ids: [1, 2]}`, which + could never match before. + ## [1.4.0] - 2026-08-25 - Follow up - c3af2a9 - Fixes #29 - [JSON::ParserError on gateway timeout when proxy responds with HTML](https://github.com/zammad/zammad-api-client-ruby/issues/29) - Dependencies updated diff --git a/README.md b/README.md index 211469b..734313c 100644 --- a/README.md +++ b/README.md @@ -1,390 +1,1486 @@ -# Zammad API Client (Ruby) [![Gem Version](https://badge.fury.io/rb/zammad_api.svg)](https://badge.fury.io/rb/zammad_api) - -## API version support -This client supports Zammad API version 1.0. +# Zammad API Client (Ruby) + +[![Gem Version](https://badge.fury.io/rb/zammad_api.svg)](https://badge.fury.io/rb/zammad_api) +[![CI](https://github.com/zammad/zammad-api-client-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/zammad/zammad-api-client-ruby/actions/workflows/ci.yml) + +--- + +> [!IMPORTANT] +> ## 📣 2.0 is taking shape — tell us what you think +> +> **Version 2.0 is a breaking release, and it is not finished yet: this is `2.0.0.alpha1`, +> its first prerelease.** This is the moment when your feedback can still change it: names, +> defaults, what is missing, what reads wrong, and anything that makes upgrading from 1.x +> harder than it should be. +> +> **[→ Open an issue and tell us](https://github.com/zammad/zammad-api-client-ruby/issues/new)** +> +> Especially useful to hear: +> +> - Which 1.x calls in **your** code the [migration table](#migrating-from-1x) does not cover. +> - Endpoints you reach with [raw requests](#raw-requests) that should be modelled resources. +> - Anything the [test kit](#testing-code-that-uses-this-client) cannot stand in for. +> - Naming that made you look twice, and defaults you had to override every time. +> +> Rough notes are welcome — a half-formed "this felt off" is worth more to us now than a +> polished report after the release. + +--- + +Ruby client for the Zammad API v1.0. + +- Requires **Ruby 3.4** or later. +- Ships **RBS signatures** in `sig/`, so typed projects get completion and checking out of the box. +- Requests carry **timeouts** and **retry with backoff** for transient failures by default. +- Collections are **lazily paginated** `Enumerable`s, with a familiar + `order` / `page` / `in_batches` / `find_each` surface. +- Records support **pattern matching**, and clients are **immutable** and safe to share + between threads. +- **Your own resources** — `client.resource(Role)` gives a class you declare everything a + modelled one has — and **raw requests** reach the rest of the API, without giving up + authentication, retries or the error classes. +- A **test kit** (`zammad_api/test`) stands in for a Zammad, so your own tests need no + HTTP interception. + +> **Upgrading from 1.x?** See [Migrating from 1.x](#migrating-from-1x), which lists every +> call that changed. +> +> **Staying on 1.x?** See [Staying on 1.x](#staying-on-1x) for where its code lives and how +> to install it. ## Installation -Add this line to your application's Gemfile: +2.0 is a prerelease for now, `2.0.0.alpha1`, and a prerelease has to be asked for: ```ruby -gem 'zammad_api' +gem 'zammad_api', '~> 2.0.0.alpha' ``` -And then execute: +Or: - $ bundle +```sh +gem install zammad_api --pre +``` -Or install it yourself as: +`'~> 2.0'` does not match an alpha, and `gem install zammad_api` without `--pre` installs +1.x. - $ gem install zammad_api +### Staying on 1.x -## Available objects +1.x stays available for a project that is not ready for 2.0, or that runs on a Ruby older +than 3.4: 1.x needs Ruby 3.0 or later. -* user -* organization -* group -* ticket -* ticket_article -* ticket_state -* ticket_priority +Its code lives on the +[`1-stable`](https://github.com/zammad/zammad-api-client-ruby/tree/1-stable) branch, and +the [README there](https://github.com/zammad/zammad-api-client-ruby/blob/1-stable/README.md) +documents the 1.x API. To install it, keep the version below 2: -## Usage +```ruby +gem 'zammad_api', '~> 1.4' +``` -### Create instance +Or: -#### Username/email and password +```sh +gem install zammad_api -v '~> 1.4' +``` + +1.x is in maintenance mode, and will stay there for the foreseeable future: it still gets +fixes, while new features go into 2.0 only. Report a 1.x problem in the same +[issue tracker](https://github.com/zammad/zammad-api-client-ruby/issues), naming the +version, and open a pull request for it against `1-stable`. + +## Creating a client + +### Access token ```ruby client = ZammadAPI::Client.new( - url: 'http://localhost:3000/', - user: 'user', - password: 'some_pass' + url: 'https://zammad.example.com/', + http_token: 'your-access-token' ) ``` -#### Access token +### OAuth2 ```ruby client = ZammadAPI::Client.new( - url: 'http://localhost:3000/', - http_token: '12345678901234567890', + url: 'https://zammad.example.com/', + oauth2_token: 'your-oauth2-token' ) ``` -#### OAuth2 +### Username and password ```ruby client = ZammadAPI::Client.new( - url: 'http://localhost:3000/', - oauth2_token: '12345678901234567890', + url: 'https://zammad.example.com/', + user: 'user@example.com', + password: 'some_pass' ) ``` -## Resource management +A client authenticates one way. Passing more than one of these — a token beside a user and +password, say — raises `ZammadAPI::ConfigurationError` rather than quietly sending one of +them. + +### From the environment + +`from_env` reads `ZAMMAD_URL` and `ZAMMAD_TOKEN` (or `ZAMMAD_USER` and +`ZAMMAD_PASSWORD`, or `ZAMMAD_OAUTH2_TOKEN`), so a script needs no configuration of its +own. Anything passed in wins over the environment, credentials included — passing +`user:` and `password:` replaces a token the environment holds rather than sitting beside +it. An environment that itself sets more than one way to authenticate is refused, until an +argument says which is meant: + +```ruby +client = ZammadAPI::Client.from_env +client = ZammadAPI::Client.from_env(timeout: 300) +``` + +### Options + +| Option | Default | Description | +| ---------------- | ------------------ | ------------------------------------------------------------------ | +| `url` | *required* | Base URL. A sub-path such as `https://example.com/zammad/` works; credentials in it are refused. | +| `http_token` | `nil` | Zammad access token. | +| `oauth2_token` | `nil` | OAuth2 bearer token. | +| `user` | `nil` | Login for basic authentication. | +| `password` | `nil` | Password for basic authentication. | +| `timeout` | `60` | Seconds to wait for a response. | +| `open_timeout` | `10` | Seconds to wait for the connection. | +| `retries` | `2` | Retry attempts for a `GET` that failed transiently. `0` disables retrying. | +| `retry_interval` | `0.5` | Seconds before the first retry; doubles on each attempt. No wait is longer than `timeout`. | +| `ssl_verify` | `true` | Set to `false` only against a server with a self-signed certificate. | +| `proxy` | `nil` | Proxy URL. | +| `user_agent` | `zammad_api-ruby/` | Value of the `User-Agent` header. | +| `logger` | discards output | Any `Logger`; the client logs requests and responses at `debug`. | +| `adapter` | Faraday's default | Name of the Faraday adapter to use. | +| `middleware` | `nil` | Callable that receives the Faraday connection while it is built. | + +Credentials are never written to the log, and `client.config` redacts them however it is +printed — `inspect`, `to_s` or `pp`, which is what a console shows — so a configuration +object is safe to include in an error report. + +Credentials belong in the options above, not in the URL. `https://user:secret@host/` raises +`ZammadAPI::ConfigurationError`, because the HTTP stack would send those as basic +authentication in place of the token configured beside them. + +### Checking the connection + +```ruby +client.me.email # => "agent@example.com", the account the credentials belong to +client.version # => "6.4.0", the Zammad instance's version, for an administrator +``` + +`client.me` answers for any account, so it is the check that the client can reach Zammad +and authenticate. `client.version` is the version of the Zammad instance, and Zammad serves +it to administrators only: with an agent's or a customer's credentials it raises +`ZammadAPI::AuthorizationError`. `ZammadAPI::VERSION` is the version of this gem. + +### Adapter and middleware + +The HTTP stack is Faraday's, and these two options are the seam into it — for a +persistent-connection adapter, instrumentation, or a cache: + +```ruby +client = ZammadAPI::Client.new( + url: 'https://zammad.example.com/', + http_token: 'token', + adapter: :net_http_persistent, + middleware: ->(connection) { connection.use(MyInstrumentation) } +) +``` + +The callable runs last, after this gem's own middleware and before the adapter, so it sees +requests as the client finished building them and responses before anything else does. +Faraday stays an implementation detail either way: an unregistered adapter raises +`ZammadAPI::ConfigurationError`, not a Faraday error. + +Faraday's default adapter, `net_http`, opens and closes a connection around every +request, so a walk of N pages is N TCP connections and N TLS handshakes. That is the +default because it needs no extra gem; for anything that pages, downloads attachments in a +loop, or runs a worker pool, add `faraday-net_http_persistent` to your Gemfile and pass +`adapter: :net_http_persistent` as above. Nothing else changes — the option is the whole of +it. + +Two things the seam will not take, and it says so with a `ZammadAPI::ConfigurationError` +when the client is built. One is middleware that decodes the response body, +`connection.response :json`: this gem parses JSON itself, and hands the undecoded bytes +back as the file from `attachment.download`, so a stack that has already consumed the body +leaves nothing faithful to return. The other is `connection.response :raise_error`, which +raises a Faraday error for a 4xx or 5xx before this gem sees the response: nothing would be +retried, and a missing record would arrive as `Faraday::ResourceNotFound` rather than the +`ZammadAPI::NotFoundError` your code rescues. A subclass of either is refused for what it +inherits. + +## Available resources + +`groups`, `organizations`, `tickets`, `ticket_articles`, `ticket_priorities`, +`ticket_states`, `users` + +`client.resource_names` returns the current list. + +The names are plural because what each one hands back stands for every record of its kind: +`client.tickets.each` walks them all, and `client.tickets.find(1)` picks one out. The +singular names from 1.x — `client.ticket` and the rest — still work as deprecated aliases; +see [Migrating from 1.x](#the-client). + +Anything not in that list is reachable by [declaring a resource](#resources-this-gem-does-not-model) +for it, or with [raw requests](#raw-requests). + +### Coverage + +What each major version of this gem models, set against what Zammad's API serves. A check +is a class or a method of the gem's own; an empty box is something 2.0 does not model yet. + +| | 1.x | 2.0 | +| ------------------------------------------------ | :-: | :-: | +| **Records** | | | +| Tickets | ✅ | ✅ | +| Ticket articles | ✅ | ✅ | +| Article attachments | ✅ | ✅ | +| Ticket states | ✅ | ✅ | +| Ticket priorities | ✅ | ✅ | +| Users | ✅ | ✅ | +| Organizations | ✅ | ✅ | +| Groups | ✅ | ✅ | +| Text modules | | ⬜ | +| **Ticket features** | | | +| Tags | | ⬜ | +| Links | | ⬜ | +| Mentions | | ⬜ | +| Time accounting | | ⬜ | +| Checklists | | ⬜ | +| Shared drafts | | ⬜ | +| Merge | | ⬜ | +| History | | ⬜ | +| **Knowledge base** | | | +| Knowledge bases | | ⬜ | +| Categories | | ⬜ | +| Answers, and publishing them | | ⬜ | +| Answer attachments | | ⬜ | +| Search | | ⬜ | +| **Across resources** | | | +| Global search | | ⬜ | +| CSV imports (users, organizations, text modules) | | ⬜ | + +An empty box in the 2.0 column is not out of reach: [declare a resource](#resources-this-gem-does-not-model) +for an endpoint that serves records, or use [raw requests](#raw-requests) for one that does +not. The empty boxes are also where this gem grows next — +[open an issue](https://github.com/zammad/zammad-api-client-ruby/issues/new) for the one +you need, so we know what to model first. + +### Resources this gem does not model + +A resource is a class with a path. Declare one for an endpoint that serves records the way +the modelled ones do — an index, and a member under its id — and `client.resource` hands +you the same thing `client.tickets` is: + +```ruby +class Role < ZammadAPI::Resources::Base + path 'api/v1/roles' +end + +roles = client.resource(Role) + +roles.each { |role| puts role.name } # paginated, like any other +roles.find(2).update(note: 'Reviewed') # change tracking and save +roles.create(name: 'Auditor') +roles.find_by(name: 'Agent') +``` + +Say what else is true of the endpoint, where it differs from the defaults: -Individual resources can be created, modified, saved, and destroyed. +| Declaration | Default | Says | +| ------------------ | ------- | -------------------------------------------------------------------- | +| `path '…'` | *required* | The index endpoint, relative to the instance URL. | +| `searchable true` | `false` | Zammad routes `/search`, so `search` works and `find_by` uses it. | +| `search_filters :role_ids` | none | What that search narrows by besides the term, `condition:` and `ids:`. `search` refuses any other keyword. | +| `max_per_page 100` | `1000` | The largest page the index endpoint serves. | +| `sortable false` | `true` | The index endpoint is always served in the same order, so `order` refuses it. | +| `belongs_to :role, class_name: 'Role'` | — | A foreign key, read as a record through `record.related.role`. | +| `has_many :members, class_name: 'User', path: ->(id) { "…/#{id}" }` | — | A list served whole by an endpoint of its own. | -### Create object +`class_name` is a resource of this gem by its own name, `'User'`, or a class of yours by its +full name, `'Acme::Role'`. A subclass of a modelled resource works too, and inherits what +its parent declares: `class MyTicket < ZammadAPI::Resources::Ticket`. + +Use raw requests for an endpoint that is not shaped like that — an action, a report, a +setting. + +## Raw requests + +`get`, `post`, `put` and `delete` reach any endpoint of the Zammad API, without giving up +authentication, timeouts, retries, credential redaction, JSON decoding or the error +classes. Use them for the endpoints that are not a list of records, and for a one-off call +to one that is. + +```ruby +client.get('api/v1/roles').body +# => [{id: 1, name: "Admin", ...}, ...] + +client.post('api/v1/tags/add', query: {object: 'Ticket', o_id: 1, item: 'urgent'}) +client.put('api/v1/roles/2', body: {note: 'Updated'}) +client.delete('api/v1/tags/remove', query: {object: 'Ticket', o_id: 1, item: 'urgent'}) +``` + +All four take `headers:`, for an endpoint that needs one: + +```ruby +client.get('api/v1/tickets/1', headers: {'Accept-Language' => 'de-de'}) +``` + +Names are case-insensitive, and two spellings of one header are refused rather than merged. +`Authorization` and `From` are refused outright: the first is what the client's credentials +are for, the second is what `on_behalf_of` sets, and replacing either from a single request +would leave the client reporting something it no longer does. + +Each returns a `ZammadAPI::Response`, so the status and headers stay reachable: -With new and save: ```ruby -group = client.group.new( - name: 'Support', - note: 'Some note', -); +response = client.get('api/v1/tickets') +response.status # => 200 +response.headers['content-type'] +response.body # decoded JSON, or the raw body for anything else +response.raw_body # the bytes as they arrived +response.json? # => whether the body was decoded +``` + +Zammad reports the size of a result in the body rather than in a header, and only +where you ask for it: `only_total_count=true` or `with_total_count=true` on a `/search` +endpoint, and `full=true` on the index endpoints that render through +`model_index_render`. `count` on a search collection uses the first of those. + +Paths are relative to the instance URL, and a leading slash is ignored, so they can be +pasted straight from the Zammad documentation. An absolute URL raises `ArgumentError`: the +client's credentials only ever go to the instance it was configured for, so a link taken +from a response body has to be reduced to its path first. A path is written the way a URL +is, so a space or a character outside ASCII has to be percent-encoded, `t%C3%A4gs` for +`tägs`; one that cannot be read as a URL raises `ArgumentError` too, before anything is +sent or logged. A non-2xx response raises the same error class it would raise for a +modelled resource, and only a `GET` is retried. + +## Working with records + +### Create + +```ruby +group = client.groups.new(name: 'Support', note: 'Some note') group.save -group.id # id of record -group.name # 'Support' +group.id # => 42 +group.name # => "Support" ``` -With create: +Or in one call: + ```ruby -group = client.group.create( - name: 'Support', - note: 'Some note', -); +group = client.groups.create(name: 'Support', note: 'Some note') +``` + +### Fetch -group.id # id of record -group.name # 'Support' +```ruby +group = client.groups.find(42) +group.name # => "Support" +group[:name] # same, and nil rather than an error when it is absent +group.fetch(:name) # raises KeyError if the attribute is absent +group.key?(:name) # => true +group.to_h # every attribute, as a Hash you may modify ``` -### Fetch object +Or by attribute value: ```ruby -group = client.group.find(123) -puts group.inspect +client.users.find_by(email: 'someone@example.com') # => the record, or nil +client.users.find_by!(email: 'nobody@example.com') # raises NotFoundError +client.groups.exists?(42) # => true ``` -### Update object + +`find_by` answers with the first record that carries those values, and `nil` if it finds +none, on every resource and for any kind of value. Zammad cannot be asked that directly, +because its index endpoints cannot filter — see [Narrowing](#narrowing) — so `find_by` +fetches candidates and checks them itself. A record it returns genuinely carries the +attributes you asked for, compared exactly and against the value as Zammad stores it, so +`find_by(email: 'Someone@Example.com')` does not match a login Zammad downcased. What a +`nil` means depends on how the candidates were fetched: after a walk, that no record this +client can read carries the values; after a search, that no hit does, and a search reads +less than the whole record, as described below. + +There are two ways it fetches the candidates, and they cost differently: ```ruby -group = client.group.find(123) +client.users.find_by(email: 'someone@example.com', active: true) # searches the email, matches both +client.users.find_by(firstname: 'Jane', lastname: 'Doe') # searches "Jane", matches both +client.ticket_states.find_by(name: 'open') # no search endpoint: walks the list +client.users.find_by(organization_id: 5) # no string to search on: walks the index +``` + +A search is the cheap way, and is used wherever the resource has a search endpoint and one +of the values is a string. The term is one string value, because Zammad matches words: a +value of another type would go out as the word it prints as, so `active: true` would look +for records containing `"true"`. Every other value is matched against the hits. + +Everywhere else `find_by` walks the index, a page at a time, until a record matches. That +is one request for a list of ticket states. Against every user or ticket on an instance it +is a request per page until the match, and the whole index for a miss — the same walk +`all.detect { ... }` makes, so give `find_by` a string to search on where there is one. + +The values are never joined into one term. An instance searching without Elasticsearch +matches the term literally, through a SQL `LIKE` over each string column, so `"Jane Doe"` +would ask for a single column containing the whole of it and match nobody. + +`find_by` reads the hits a page at a time until one matches, so a match usually costs one +request and a miss costs one per page of hits. It cannot stop at the first page: Zammad's +search sorts by `updated_at`, newest first, rather than by relevance, so where a few +hundred records contain the term the one that carries it exactly can be on any page. + +What the search can surface is Zammad's business: a value the instance has not indexed, or +cannot index, is a record `find_by` will not find. `find_by(...) || create(...)` can +therefore still create a duplicate — as writing the search out by hand would. + +Which values those are depends on the instance. With Elasticsearch the term is looked for +in everything a record is indexed with. Without it, Zammad reads a fixed set of columns: + +| Resource | What a search without Elasticsearch reads | +| ----------------------------------- | -------------------------------------------------------------- | +| `users`, `organizations`, `groups` | The string columns of the record's own table. | +| `tickets` | The title and number, and the from, to, subject and body of the ticket's articles. | + +Neither reads a name `expand` adds for an association, which is not a column, and a ticket +search reads no other attribute of the ticket. So on such an instance these look for the +word in fields that do not hold the value. They find the record only where the word +happens to appear in one of those fields as well, and otherwise answer `nil` for a record +that exists: + +```ruby +client.tickets.find_by(state: 'open') # the state is not among what a ticket search reads +client.tickets.find_by(external_ref: 'SO-1001') # nor is a custom attribute of a ticket +client.users.find_by(organization: 'Acme') # a name expand adds, not a column +``` + +`find_by` does not walk the index after a search that found nothing. A miss is the ordinary +case for `find_by(email: ...) || create(...)` on an address that is new, and that walk would +read every user on the instance to confirm it, a thousand to the request. Nothing in a +response says which backend answered, so `find_by` cannot tell that miss from one caused by +a field the search does not read. You can, and the walk is one word away: + +```ruby +client.tickets.detect { it[:state] == 'open' } # walks the index: every ticket this client may read +client.tickets.search('printer', condition: {'ticket.state_id' => {operator: 'is', value: [2]}}) +``` + +The walk compares `it[:state]`, as `find_by` does, and not `it.state`. Every record the +client may read goes through the block, and a reader raises for an attribute the record in +hand does not carry, which would end the walk on that record rather than pass it over. A +user without an organization carries no `organization`, and Zammad serves a reduced record +where the client may not see the whole of one. What the walk cannot find is a record the +client may not read, or a value on a record it only sees reduced. + +Zammad records can carry administrator-defined custom attributes, so readers are resolved +against the attributes the record arrived with rather than declared ahead of time. A reader +for an attribute the record does not carry raises `NoMethodError`, naming what it does +carry — a typo is not worth a silent `nil` that flows on into whatever you write with it: + +```ruby +group.titel # NoMethodError: undefined attribute titel for ... +group[:titel] # => nil +group.fetch(:titel, nil) # => nil +group.key?(:titel) # => false +``` + +That matters beyond typos: Zammad serves a reduced object where the authenticated user may +not see the whole record, so an attribute that exists in Zammad can be missing here. The +message says so. Use `[]`, `fetch` with a default, or `key?` wherever an attribute may +legitimately be absent. + +`attributes` and `changes` are deeply frozen, because a record that let you write into +them would report a change it had never staged and would not send: + +```ruby +group.attributes[:name] = 'Support 2' # FrozenError +group.name = 'Support 2' # the way to stage a change +group.to_h # a deep copy, yours to modify +``` + +### Pattern matching + +Records implement `deconstruct_keys`, so they work with `case/in`: + +```ruby +case client.tickets.find(1) +in {state: 'closed'} + nil +in {state: String => state, priority: '3 high'} + escalate(state) +in {group: {name: 'Support'}} + notify_support +end +``` + +`Config` and `Response` are `Data` objects, so their members match too: + +```ruby +case client.config +in {http_token: String} + :token_auth +in {user: String, password: String} + warn 'prefer an access token over basic auth' +end +``` + +### Update + +```ruby +group = client.groups.find(42) group.name = 'Support 2' -group.save + +group.changed? # => true +group.changes # => {name: ["Support", "Support 2"]} + +group.save # sends only the changed attributes ``` -### Destroy object +A `save` on a persisted record with nothing staged sends no request at all and returns +`true`. Zammad applies an empty update, bumping `updated_at` and `updated_by`, so a no-op +save would otherwise rewrite the record's audit trail. + +Writing back the value a record was loaded with is not a change, so it stages nothing. +Writing an attribute the record does not carry always is one, even when the value is `nil`: +Zammad reduces the object it serializes for a permission-scoped client, so a key being +absent says nothing about what is stored, and `group.note = nil` is a request to store +`nil` rather than a write to drop. + +Or in one call: ```ruby -group = client.group.find(123) -group.destroy +group.update(name: 'Support 2', note: 'Renamed') # assigns, then saves +group.assign_attributes(name: 'Support 3') # assigns without saving ``` -## Collection management +### Saving and validation failures + +`save` returns whether the record was stored, and leaves a rejection in `error`: -A list of individual resources. +```ruby +group = client.groups.new(name: '') -### All +if group.save + puts group.id +else + warn group.error.server_message # => "Name is required" +end +``` + +Only a rejection of the attributes (HTTP 422) is reported that way. An expired token, a +missing record or an unreachable instance still raises, because those are not something +the calling code can correct by fixing an attribute. + +`save!` and `update!` raise on every failure, including validation, which is what you want +in a script: ```ruby -groups = client.group.all +group.save! # raises ZammadAPI::ValidationError +group.update!(name: '') # the same, in one call +``` + +`client.groups.create(...)` uses `save!`, so it raises rather than handing back a record +that looks created but is not. Use `new` plus `save` when you need to branch instead. -group1 = groups[0] -group1.note = 'Some note' -group1.save +### Associations -groups.each {|group| - p "group: #{group.name}" -} +Zammad expands an association into a name under the plain attribute, so those reads are +already loaded and free: + +```ruby +ticket = client.tickets.find(1) + +ticket.customer # => "customer@example.com" +ticket.state # => "open" +ticket.group # => "Users" +ticket.customer_id # => 7 ``` -### Search +`related` reaches the whole record behind one of those, which costs a request: + ```ruby -groups = client.group.search(query: 'some name') +ticket.related.customer.firstname # => "Nicole" +ticket.related.group.note +ticket.related.articles # => [TicketArticle, ...] +ticket.related.created_by.email + +client.users.find(7).related.organization +``` + +A `has_many` reader such as `articles` is the one list here that is read in a single +request and comes back as an Array rather than a paginating collection, because the +association endpoints Zammad routes serve the whole list: `ticket_articles/by_ticket` +renders every article of the ticket and takes no paging parameter. -group1 = groups[0] -group1.note = 'Some note' -group1.save +A ticket's articles are also reachable without `related`, and `add_article` writes one: -groups.each {|group| - p "group: #{group.name}" -} +```ruby +ticket.articles # the same list +ticket.add_article(body: 'Reset link sent.', type: 'note') # => the created TicketArticle ``` -### All with pagination (beta) +The readers live under `related` rather than on the record so that `ticket.customer` keeps +returning the name it always did — an attribute read that silently became an HTTP request +would be a poor trade. `belongs_to` targets are memoized, and `reload`, a save or a write +to the foreign key drops the memo; `has_many` lists are fetched each call, so an article +added in between shows up. A record hands out the same `related` every time, so one kept in +a variable follows the record too: after `related = ticket.related` and +`ticket.customer_id = 9`, `related.customer` is user 9. +`Ticket.associations` lists what a resource declares. + +### Comparing and serializing + +A record is the Zammad record it came from, not the object that happens to hold it, so two +records of the same kind carrying the same id, read from the same Zammad, are equal. That +makes `uniq`, `Set`, `include?` and records-as-Hash-keys behave: ```ruby -groups = client.group.all +client.tickets.find(1) == client.tickets.find(1) # => true + +[client.tickets.find(1), client.tickets.find(1)].uniq.size # => 1 +Set[client.tickets.find(1), client.tickets.find(1)].size # => 1 +seen = { client.tickets.find(1) => :handled } +seen[client.tickets.find(1)] # => :handled +``` -groups.page(1,3) {|group| - p "group: #{group.name}" +A record with no id is equal only to itself, because two unsaved records are two records +waiting to be created however alike their attributes are. One consequence: a record's first +save assigns its id and so changes its hash, and a record used as a Hash key before that +save has to be rehashed after it. - group.note = 'Some new note, inclued in page 1 with 3 per page' - group.save -} +Which Zammad a record came from is the `url` its client was configured with. A script that +reads two instances, such as a migration or a sync, therefore keeps ticket 1 of each apart, +while two clients for one URL, or a client and its `on_behalf_of` scope, hold the same +record. -groups.page(2,3) {|group| - p "group: #{group.name}" +`to_json` renders the attributes, so a record can be cached, queued or logged as it stands, +and nests inside a structure being generated: - group.note = 'Some new note, inclued in page 2 with 3 per page' - group.save -} +```ruby +client.groups.find(1).to_json # => "{\"id\":1,\"name\":\"Support\"}" +JSON.generate(group: client.groups.find(1)) ``` -### Search with pagination (beta) +`as_json` returns the same attributes as a Hash, for ActiveSupport and any encoder that +follows its convention. + +### Reload and destroy + ```ruby -groups = client.group.search(query: 'some name') +group.reload # re-reads from Zammad, discarding unsaved changes +group.destroy # => true -groups.page(1,3) {|group| - p "group: #{group.name}" +group.destroyed? # => true +group.persisted? # => false, so this is not the inverse of new_record? +group.save # raises: the record is gone, and a PUT would only 404 +group.update(...) # raises too, and stages nothing, so the record stays unchanged +group.name = 'X' # raises as well: a destroyed record reads as it last was in Zammad - group.note = 'Some new note, inclued in page 1 with 3 per page' - group.save -} +client.groups.destroy(42) # delete by id, without fetching first +``` -groups.page(2,3) {|group| - p "group: #{group.name}" +## Collections - group.note = 'Some new note, inclued in page 2 with 3 per page' - group.save -} +`all`, `order` and `search` return a lazily paginated `ZammadAPI::Collection`. No request +is made until you iterate, and pages are fetched as needed. + +A resource proxy is itself `Enumerable` over `all`, so `.all` is optional: + +```ruby +client.tickets.each { |ticket| puts ticket.title } +client.tickets.first(5) +client.tickets.pluck(:title) +client.tickets.find_each(batch_size: 50) { |ticket| archive(ticket) } ``` -## Perform actions on behalf of another user +`find` keeps its own meaning there — `client.tickets.find(1)` is a lookup by id, not +`Enumerable#find`. Use `detect` for the block form. + +```ruby +# Walks every page automatically. +client.tickets.all.each do |ticket| + puts ticket.title +end -As described in the [Zammad API documentation](https://docs.zammad.org/en/latest/api/intro.html#actions-on-behalf-of-other-users) it is possible to perfom actions on behalf other users. To use this feature you can set the attribute of the client accordingly: +# Stops after the first page, because Enumerable stops consuming. +first_five = client.tickets.all.first(5) -> **Note:** This feature requires Zammad 5.0 or later, since the client sends the standard HTTP `From` header instead of the deprecated `X-On-Behalf-Of` header (see [zammad/zammad#3113](https://github.com/zammad/zammad/issues/3113)). +# Lazy chains work as expected. +client.tickets.all.lazy.select { |t| t.state == 'open' }.first(10) + +# One array of records per request, e.g. for a bulk import. +client.tickets.all.in_batches(of: 50) do |tickets| + import(tickets) +end + +# Record by record, with the page size set inline. +client.tickets.all.find_each(batch_size: 50) do |ticket| + archive(ticket) +end +``` + +### Sorting + +`order` sorts on the server: + +```ruby +client.groups.order(:name) # ascending +client.organizations.order(name: :desc) +client.groups.order(:active, name: :desc) # by active, then by name descending +client.tickets.search('state.name:open').order(created_at: :desc) +``` + +An attribute on its own sorts ascending and a keyword says which way one runs, as in +ActiveRecord. A second `order` sorts within the first, so +`order(:active).order(name: :desc)` is the third line above. + +Not every endpoint sorts. `/api/v1/tickets` and `/api/v1/users` are always served in id +order — their controllers hardcode it and drop `sort_by` along with everything else they +do not read — so `order` on those raises `ArgumentError` rather than handing back records +it would be calling sorted. A search sorts for every resource that can be searched: ```ruby -client.on_behalf_of = 'some_login' +client.tickets.order(:title) +# ArgumentError: api/v1/tickets is always served in the same order and ignores sort_by, +# so order would hand back the records as they were. A search does sort: ... + +client.tickets.search('state.name:open').order(:title) ``` -All following actions with the client will be performed on behalf of the user with the `login` "some_login". +### Narrowing + +**Zammad's index endpoints do not filter.** `ApplicationController#model_index_render` +sorts and pages and drops every other parameter. Filtering by an attribute value exists +only on the `/search` endpoints, which is why a collection has no `where`: there is nothing +an index endpoint would do with what it was given. -To reset this back to regular requests just set `nil`: +Narrow by a value with [`find_by`](#fetch) for one record, or `search` for many: ```ruby -client.on_behalf_of = nil +client.users.find_by(email: 'someone@example.com') +client.tickets.search('state.name:open').first(10) ``` -It's possible to perform only a block of actions on behalf of another user via: +`search` also takes the other things a search endpoint narrows by, as keywords: +`condition:` and `ids:` on every search, and `role_ids:`, `group_ids:` and `permissions:` +on users, the one search that reads them: ```ruby -client.perform_on_behalf_of('some_login') do - # ticket is created on behalf of the user with - # the login "some_login" - client.ticket.create( - ... - ) +client.users.search('smith', role_ids: [2]) +client.users.search('smith', group_ids: [1], permissions: ['ticket.agent']) +client.users.search('smith', group_ids: {1 => ['read']}) +client.tickets.search('printer', condition: {'ticket.state_id' => {operator: 'is', value: [1, 2]}}) +client.tickets.search('printer', condition: {'ticket.group_id' => {operator: 'is', value: [2]}}) +``` + +A `condition` may nest groups of conditions, the form Zammad calls expert mode: + +```ruby +client.tickets.search('printer', condition: { + operator: 'OR', + conditions: [ + {name: 'ticket.state_id', operator: 'is', value: [2]}, + {operator: 'AND', conditions: [ + {name: 'ticket.group_id', operator: 'is', value: [1]}, + {name: 'ticket.priority_id', operator: 'is', value: [3]} + ]} + ] +}) +``` + +A query string does not mark where one element of a list ends, and Rails begins a new one +only at a key the element before it has too. The elements above all carry `operator`, and +the client writes that first, so they arrive as written. A list whose elements share no +such key, a list directly inside a list, an empty Hash inside a list and a key with an empty +name cannot be carried at all and raise `ArgumentError`; the JSON body of `client.post` takes +any structure. + +`group_ids:` narrows to the agents with access to a group, and its two forms ask for +different access. A list of ids names no access, and Zammad reads that as `full`: +`group_ids: [1]` leaves out an agent who may only read group 1. A Hash names the access +for each group — `read`, `create`, `change`, `overview` or `full`, one or several — and +an agent with `full` access always counts: `group_ids: {1 => ['read']}` is every agent +with `read` or `full` access to group 1. Access granted through a role counts like access +granted to the user, and an agent matching any one of the groups is kept. + +`permissions:` is not an access check. Zammad resolves it to the roles that grant one of +the permissions and adds those to `role_ids:`, so the two together keep a user with any +of the roles, not one with both. And where the instance searches through Elasticsearch, a +permission that no active role grants resolves to no role at all, and Zammad then leaves +the filter out: `permissions: ['ticket.agnet']`, or a permission nobody has been given, +comes back with every user matching the term. Without Elasticsearch the same search is +empty, and nothing in the response says which of the two answered. `role_ids:` narrows +on both. + +`role_ids:` is not an access check either. It asks who holds a role, and Zammad does not +ask whether the role still grants anything: a user matches a role that has been disabled, +and a user who has been deactivated matches as well, though neither can do what the role +allowed. So the hits are candidates. Where the result decides what someone may do, check +each one: the user's `active`, and the `active` and the permissions of the roles in +their `role_ids`, which `client.resource` reaches at `api/v1/roles`. + +Any other keyword raises `ArgumentError`. Zammad drops a parameter it does not know, so +`search('smith', active: true)` would come back unnarrowed with nothing to say so; an +attribute value goes in the term, a sort in `order`, and paging in `page`, `in_batches` or +`find_each`. A user keyword on another resource raises for the same reason: Zammad takes +`group_ids` on a ticket search and drops it, so tickets are narrowed by group with the +condition above. A `nil` value raises too: there is no query string that means "this field +is null". So does a keyword with nothing in it, such as `ids: []`, `condition: {}`, or a +condition that holds nothing but empty Hashes, which a query string does not write. Zammad +reads that as the keyword not having been given, so `search('smith', ids: allowed_ids)` +with no id allowed would come back with every user matching the term rather than none. + +Zammad routes a search endpoint per model, not for every model. `users`, `organizations`, +`tickets` and `groups` have one; `ticket_states`, `ticket_priorities` and `ticket_articles` +do not, and `search` on those raises `ZammadAPI::Error` rather than reaching a 404 that +would read as a missing record. `find_by` works on them all the same, by walking the list: + +```ruby +client.ticket_states.find_by(name: 'open') +client.ticket_priorities.select { it.active } +``` + +### Search + +```ruby +client.organizations.search('zammad').each do |organization| + puts organization.name end +``` + +A term with nothing in it, Unicode spaces included, raises `ArgumentError`: Zammad reads it +as no term at all and answers with every record, which a search for an empty form field +should not come back with. `search('*')` asks for every record in so many words, and is +sent; it is how Zammad's own interface lists users, and the keywords above still narrow it. -# further actions are performed regularly. +### Explicit pages + +```ruby +tickets = client.tickets.all + +tickets.page(2) # page 2 at the size the endpoint serves +tickets.page(2, per_page: 10) # records 11 to 20 ``` -## Examples +Collections are immutable: `order` and `page` return a new collection and leave the +original untouched. -Create a ticket: -```ruby -ticket = client.ticket.create( - title: 'a new ticket #1', - state: 'new', - group: 'Users', - priority: '2 normal', - customer: 'some_customer@example.com', - article: { - content_type: 'text/plain', # or text/html, if not given test/plain is used - body: 'some body', - # attachments can be optional, data needs to be base64 encoded - attachments: [ - 'filename' => 'some_file.txt', - 'data' => 'dGVzdCAxMjM=', - 'mime-type' => 'text/plain', - ], - }, -) +### Page size + +A request fetches as many records as the endpoint will serve — 100 for `/api/v1/tickets`, +200 for a search, 1000 for the other index endpoints — so a walk spends as few round trips +as it can. Three calls take another size, each for its own kind of work: -ticket.id # id of record -ticket.number # uniq number of ticket -ticket.title # 'a new ticket #1' -ticket.group # 'Support' -ticket.created_at # '2022-01-01T12:42:01Z' -# ... +```ruby +client.tickets.all.find_each(batch_size: 50) { |ticket| archive(ticket) } # walking +client.tickets.all.in_batches(of: 50) { |tickets| import(tickets) } # batching +client.tickets.all.page(2, per_page: 100) # one page ``` -List all new or open tickets: +`find_each` without a block is an Enumerator, so it is also how you read at a chosen page +size: `client.tickets.all.find_each(batch_size: 50).first(7)`. + +`page` and a batch size are two ways of naming the same thing, so combining them raises: +`page(3, per_page: 50)` already says which records the collection holds, and re-sizing it would +quietly hand back different ones. Size the page itself, or slice with `each_slice`. + +That cap is also the ceiling. `find_each` and `in_batches` are reduced to it: a +batch size is how much to fetch at a time, so a smaller one costs more requests and still +yields every record. `page` raises instead, because a page size also says *which* records +you get — `page(3, per_page: 500)` reduced to 100 hands back records 201 to 300 rather than 1001 +to 1500. So `in_batches(of: 500)` over tickets yields batches of 100, while +`page(3, per_page: 500)` over tickets is refused. +A walk learns the size the endpoint actually serves from the first page rather than trusting +that cap, so an instance that pages smaller than expected is walked to the end rather than +truncated at the first short page. +That keeps a walk complete: a page size the server silently shrank would otherwise end the +iteration at the first page. + +A search is walked until a page comes back empty, whatever the size of the pages before it. +Zammad has the search name the ids for a page and then loads those records, so a record +deleted in between, or one Elasticsearch still lists after it was removed, leaves the page +short with more hits behind it. A short page therefore ends the walk of an index and not of +a search, which costs a search one more request where its last page of hits is part-filled. + +A page can come back with nothing on it for the same reason, and on the page of one that +`first` and `empty?` ask for, one stale hit is enough — at the top of the result, since a +search serves the newest first. So a search that is walked asks Zammad for the size of the +whole result beside each page, with `with_total_count`, and an empty page ends the walk +only once the pages read have covered that many hits. The total is never what ends a walk +on a page that still held records. + +Three limits remain, and at each an empty page ends the walk whatever is behind it. A +Zammad before 6.5.1 does not report the total beside expanded records. Elasticsearch stops +counting at ten thousand hits, so past that many a page of stale hits reads as the end. And +the pages read are reckoned at the size that was asked for, 200 hits unless a batch size +says otherwise: an instance that serves a search in smaller pages than that has covered +fewer hits than the walk takes it to have. Asked for 200 and served 50, an empty first page +beside a total of 150 reads as the end, with the hits from the 51st on unread. On such an +instance `first`, `take` and `empty?` can also miss hits behind stale ones, since the +larger pages they ask for past an empty one (see below) are served from other positions +than the ones asked for. A hit served twice that way is handed back once. Zammad itself +serves a search 200 at a time. + +`first` and `take` size their own request rather than taking records off the front of one +sized for walking, so the cheap-looking call is cheap: + ```ruby -tickets = client.ticket.search(query: 'state.name:new OR state.name:open') +client.tickets.all.first # one request, for one record +client.tickets.all.first(5) # one request, for five +client.tickets.all.take(5) # the same, and the same cost +``` + +They size the request, not the collection, so they still read on where a page comes back +shorter than it was asked for — `first(5)` answers with five records if five exist, however +the endpoint chooses to page them. A collection `page` already limited keeps its own size, +since that size says which records it holds. + +On a search, the size is where the read starts and not what it is held to. Past a page with +nothing on it and hits still behind it, `first`, `take` and `empty?` ask for more at a +time, each page starting where the last one ended, up to the 200 a search serves and never +past the total it reported. Held to a page of one they paid a request for every stale hit +in a row, which is thousands of them where an Elasticsearch index has drifted from the +database. Held to the total, they stay inside an index whose result window was lowered +below the hits there are, which refuses a page reaching past it and is answered as no hits +at all. A batch size you chose, with `in_batches(of:)` or `find_each(batch_size:)`, is +never changed. + +### Reading single attributes + +```ruby +client.users.all.pluck(:email) # => ["a@example.com", ...] +client.tickets.all.pluck(:id, :title) # => [[1, "Help"], ...] +``` + +Zammad cannot be asked for a subset of the fields, so this shapes the result rather than +shrinking the request. + +### Counting + +`count` is one request on a search, which Zammad can answer without serving the records. +Every other endpoint has to be walked, because an index endpoint offers nothing cheaper: +`model_index_render` reads `sort_by`, `order_by` and the paging and drops every other +parameter, so it has no answer for `only_total_count` and no total to report. + +```ruby +client.tickets.search('state.name:open').count # one request +client.tickets.all.count # one request per page +``` + +`size` and `length` are `count`, and cost the same. `empty?` and `first` ask for a single +record rather than a page: + +```ruby +client.tickets.search('state.name:merged').empty? # one request, for one record +client.groups.all.size # => 12, having walked +``` + +A block or an argument is `Enumerable#count` counting matches, and walks either way: + +```ruby +client.tickets.all.count { it.state == 'open' } # walks every page +``` + +Nothing is cached, so every traversal of a collection fetches again. + +### `find` is a lookup, not a filter + +`find` on a resource takes an id. On a collection it is `Enumerable#find`, which takes a +block — and its argument is an ifnone callable, not an id, so passing one is refused rather +than answered with an Enumerator and no request: + +```ruby +client.tickets.find(1) # the lookup by id +client.tickets.all.detect { ... } # the block form +client.tickets.all.find { ... } # the same +client.tickets.all.find(1) # ArgumentError, naming both of the above +``` + +## Deriving clients + +A client is immutable. `with` returns a new one with some options changed, re-validating +them and carrying over any `on_behalf_of` scope: + +```ruby +bulk = client.with(timeout: 300, retries: 5) +bulk.tickets.all.each { |ticket| archive(ticket) } +``` + +Naming credentials replaces the ones the client has, whichever kind they were, so +`client.with(oauth2_token: '…')` on a client built with an access token authenticates with +the OAuth2 token alone. + +Because nothing is mutated after construction, one client — and any client derived from it — +is safe to use from several threads at once. -ticket[0].id # id of record -ticket[0].number # uniq number of ticket -ticket[0].title # 'title of ticket' -ticket[0].group # 'Support' -ticket[0].created_at # '2022-01-01T12:42:01Z' +## Acting on behalf of another user -tickets.each {|ticket| - p "ticket: #{ticket.number} - #{ticket.title}" -} +As described in the [Zammad API documentation](https://docs.zammad.org/en/latest/api/intro.html#actions-on-behalf-of-other-users), +actions can be performed on behalf of another user. `on_behalf_of` returns a **new** +client, so the original is unaffected and both are safe to use concurrently. + +```ruby +support = client.on_behalf_of('agent@example.com') +support.tickets.create(title: 'Help', group: 'Users', customer_id: 1) ``` -Get all articles of a ticket: +Or scoped to a block: + ```ruby -ticket = client.ticket.find(123) -articles = ticket.articles +client.on_behalf_of('agent@example.com') do |scoped| + scoped.tickets.find(1) +end +``` -articles[0].id # id of record -articles[0].from # creator of article -articles[0].to # recipients of article -articles[0].subject # article subject -articles[0].body # text of message -articles[0].content_type # text/plain or text/html of .body -articles[0].type # 'note' -articles[0].sender # 'Customer' -articles[0].created_at # '2022-01-01T12:42:01Z' +The identifier can be a login, an email address or a user id. This sends the standard +HTTP `From` header and requires Zammad 5.0 or later. + +An identifier that is `nil`, empty or blank raises `ArgumentError`. Zammad reads a `From` +header with nothing in it as no header at all, so `client.on_behalf_of(user&.login)` with +no user would otherwise perform every request as the account the client authenticates +as, and read everything that account can see. + +## Error handling + +Every error descends from `ZammadAPI::Error`. + +```text +ZammadAPI::Error +├── ZammadAPI::ConfigurationError invalid client options +├── ZammadAPI::UnknownResourceError no such resource, e.g. client.unicorn +├── ZammadAPI::ParseError unexpected response shape +├── ZammadAPI::PaginationError endpoint ignored the page parameter +├── ZammadAPI::TransportError +│ ├── ZammadAPI::ConnectionError unreachable host or TLS failure +│ └── ZammadAPI::TimeoutError exceeded timeout or open_timeout +└── ZammadAPI::ResponseError carries the HTTP response + ├── ZammadAPI::ClientError 4xx + │ ├── ZammadAPI::AuthenticationError 401 + │ ├── ZammadAPI::AuthorizationError 403 + │ ├── ZammadAPI::NotFoundError 404 + │ ├── ZammadAPI::ValidationError 422 + │ └── ZammadAPI::RateLimitError 429 + └── ZammadAPI::ServerError 5xx +``` -p "ticket: #{ticket.number} - #{ticket.title}" -articles.each {|article| - p "article: #{article.from} - #{article.subject}" -} +```ruby +begin + client.tickets.find(1) +rescue ZammadAPI::NotFoundError + nil +rescue ZammadAPI::RateLimitError => e + # The client already waited and retried, so this limit outlasted that. + reschedule(in: e.retry_after || 60) +rescue ZammadAPI::ResponseError => e + warn "#{e.status}: #{e.server_message}" + warn e.body.inspect +end ``` -Create an article for a ticket: +`ResponseError` exposes `status`, `body`, `headers`, `server_message`, `operation` and +`resource_class`. A proxy that returns an HTML error page instead of JSON produces a +`ServerError` describing the status, not a JSON parse failure. + +### Timeouts and retries + +A `GET` is retried on connection failures, timeouts and the transient statuses 429, 500, +502, 503 and 504, with exponential backoff. + +A `Retry-After` header on one of those responses is honoured: the client waits as long as +the server asked before the next attempt, up to `timeout` seconds. A longer one is not +waited out. The request fails at once with the error for its status, and +`RateLimitError#retry_after` carries the figure, so a job can reschedule itself rather +than hold a thread for however long a maintenance page suggests. + +A write is never retried. `POST` would create a second record, and `PUT` and `DELETE` are +not safe to repeat against Zammad either, whatever HTTP says about them: a ticket update +carrying an `article` adds that article — and sends its e-mail — once per delivery, and a +`DELETE` repeated after a lost answer comes back as a 404 for a record that was just +deleted. So a write that fails raises, and the code that knows what the request carried +decides whether to send it again: + ```ruby -ticket = client.ticket.find(123) +begin + ticket.update!(state: 'closed') +rescue ZammadAPI::TransportError, ZammadAPI::ServerError + ticket.reload # did it arrive? + retry if ticket.state != 'closed' +end +``` -article = ticket.article( - type: 'note', - subject: 'some subject 2', - body: 'some body 2', - # attachments can be optional, data needs to be base64 encoded - attachments: [ - 'filename' => 'some_file.txt', - 'data' => 'dGVzdCAxMjM=', - 'mime-type' => 'text/plain', - ], +```ruby +client = ZammadAPI::Client.new( + url: 'https://zammad.example.com/', + http_token: 'token', + timeout: 10, + retries: 5 ) +``` -article.id # id of record -article.from # creator of article -article.to # recipients of article -article.subject # article subject -article.body # text of message -article.content_type # text/plain or text/html of .body -article.type # 'note' -article.sender # 'Customer' -article.created_at # '2022-01-01T12:42:01Z' -article.attachments.each { |attachment| - attachment.filename # 'some_file.txt' - attachment.size # 1234 - attachment.preferences # { :"Mime-Type"=>"image/jpeg" } - attachment.download # content of attachment / extra REST call will be executed -} - -p "article: #{article.from} - #{article.subject}" -``` - -Create an article with html and inline images for a ticket: -```ruby -ticket = client.ticket.find(123) - -article = ticket.article( - type: 'note', - subject: 'some subject 2', - body: 'some body with an image Red dot', - content_type: 'text/html', # optional, default is text/plain +## Logging + +```ruby +client = ZammadAPI::Client.new( + url: 'https://zammad.example.com/', + http_token: 'token', + logger: Logger.new($stdout) ) +``` + +Requests, response statuses and durations are logged at `debug` level. Payload keys, query +parameters and headers that look like credentials (`password`, `token`, `secret`, `cookie`, +...) are redacted. That holds for a query string written into the path of a raw request, +in the log and in the message of an error the request raises, and for a body handed over +as a String where it is JSON. A String body that is not JSON is not logged, only its size. + +## Testing code that uses this client + +`zammad_api/test` ships a stand-in Zammad, so your own tests need no HTTP interception: + +```ruby +require 'zammad_api/test' -article.id # id of record -article.from # creator of article -article.to # recipients of article -article.subject # article subject -article.body # text of message -article.content_type # text/plain or text/html of .body -article.type # 'note' -article.sender # 'Customer' -article.created_at # '2022-01-01T12:42:01Z' -article.attachments.each { |attachment| - attachment.filename # '122.146472496@www.znuny.com' - attachment.size # 1167 - attachment.preferences # { :'Mime-Type'=>'image/jpeg', :'Content-ID'=>'122.146472496@www.znuny.com', :'Content-Disposition'=>'inline'} } - attachment.download # content of attachment / extra REST call will be executed -} +RSpec.describe TicketCloser do + let(:zammad) { ZammadAPI::Test.new } -p "article: #{article.from} - #{article.subject}" + it 'closes the ticket' do + zammad.stub(:get, 'api/v1/tickets/1', body: {id: 1, title: 'Help', state: 'open'}) + zammad.stub(:put, 'api/v1/tickets/1', body: {id: 1, state: 'closed'}) + + described_class.new(zammad.client).close(1) + + expect(zammad.requests.last.verb).to eq(:put) + expect(zammad.requests.last.body).to eq({state: 'closed'}) + end +end ``` -## Testing +`zammad.client` is a real `ZammadAPI::Client`, so responses come back through the same +decoding, error mapping and record building as real ones — a stub with `status: 404` +raises `NotFoundError`, and one with `status: 422` makes `save` return `false`. + +| Method | What it does | +| ------ | ------------ | +| `stub(verb, path, status:, body:, headers:, query:)` | Declares a response. Stubbing the same endpoint twice with the same scope describes a sequence; the last stub answers every later request. `query:` matches a subset, so it need not repeat `expand`, `page` or `per_page`. | +| `client` | A client wired to this stand-in. | +| `requests` | Every request made, oldest first, as `verb` / `path` / `query` / `body` / `headers` / `on_behalf_of`. | +| `reset` | Forgets the stubs and the recorded requests. | + +A `Hash` or `Array` body is served as JSON and gets `content-type: application/json` +unless `headers:` says otherwise — and it is that header, not the Ruby type, that decides +whether the body comes back decoded, exactly as it does on the wire. So a `Hash` stubbed +as `text/html` comes back as the raw string and reading a record from it raises +`ParseError`, which is what Zammad would do. Header names and values are stringified and +names downcased, the way a real `Response` carries them; a value that is not text, or two +spellings of one header name, are refused where the stub is written rather than turned +into something the wire could not send. + +`query` and `headers` are recorded through the real transport's own stringification, so +they hold what a request would have carried rather than the raw Ruby values — and a header +the wire would refuse is refused here too. `headers` names only what the call asked for; +the ones the client sets from its configuration are not in it, and an `on_behalf_of` scope +has a field of its own. + +A request that was not stubbed raises `ZammadAPI::Test::UnstubbedRequestError`, listing +what is stubbed, rather than answering with something empty. It is deliberately not a +`ZammadAPI::Error`: a forgotten stub means the test is wrong, not that Zammad refused +something, so a `rescue ZammadAPI::Error` in the code under test lets it through instead of +reporting it as an API failure. + +### Stubbing a list endpoint + +One stub is enough for a collection that fits in a page. The records it holds are one page +of them, so a request for any later page is answered the way an endpoint out of records +would answer it: -### Setup an (empty Zammad) test env +```ruby +zammad.stub(:get, 'api/v1/groups', body: [{id: 1, name: 'Users'}, {id: 2, name: 'Sales'}]) +client.groups.all.map(&:name) # => ["Users", "Sales"] ``` -git clone git@github.com:zammad/zammad.git -cd zammad -export RAILS_ENV="test" -export APP_RESTART_CMD="bundle exec rake zammad:ci:app:restart" -script/bootstrap.sh && echo '' > log/test.log -cp contrib/auto_wizard_test.json auto_wizard.json -bundle exec rake zammad:ci:test:start + +Stub the endpoint again to describe a list that changes between reads. A read is one step +of the sequence however many pages it asks for, so each read gets the next stub and the +last one answers every read after it: + +```ruby +zammad.stub(:get, 'api/v1/groups', body: [{id: 1, name: 'Users'}]) +zammad.stub(:get, 'api/v1/groups', body: [{id: 1, name: 'Users'}, {id: 2, name: 'Sales'}]) + +client.groups.all.count # => 1 +client.groups.all.count # => 2 ``` -### Execute client tests +Name a `page` to say what each one holds, and the stub is served exactly as written: -Run tests via `rake spec`. (Remember to export the vars above if you are running this in another shell.) +```ruby +zammad.stub(:get, 'api/v1/groups', body: first_hundred, query: {page: 1}) +zammad.stub(:get, 'api/v1/groups', body: [{id: 101}], query: {page: 2}) +``` -## Publishing +A search that is walked asks for its total with `with_total_count`, and an Array answers +it the way a Zammad before 6.5.1 does, with the records alone. To stand in for one that +reports the total, stub the object it answers with. It is paged like an Array: a later +page holds no records and the same total. -1. Update version in [version.rb](lib/zammad_api/version.rb). -2. Add release to [CHANGELOG.md](CHANGELOG.md) -3. Commit. -4. Test build. +```ruby +zammad.stub(:get, 'api/v1/users/search', body: {records: [{id: 1}, {id: 2}], total_count: 2}) ``` -> rake build -zammad_api 1.0.7 built to pkg/zammad_api-1.0.7.gem. + +### Scopes that overlap + +A stub naming `query:` answers ahead of one that does not, so a scoped stub and a catch-all +are two separate answers rather than a sequence: + +```ruby +zammad.stub(:get, 'api/v1/tickets/search', body: {total_count: 42}, query: {only_total_count: true}) +zammad.stub(:get, 'api/v1/tickets/search', body: [{id: 1}]) + +client.tickets.search('urgent').count # => 42, however often it is asked ``` -5. Release + +Two stubs whose scopes match a request equally well raise +`ZammadAPI::Test::AmbiguousStubError` rather than one of them being picked: `count` sends +the search term and `only_total_count` together, so a records stub scoped to +`{query: 'urgent'}` matches it just as well as the count stub does. Name what tells the +requests apart — here, the search term on the count stub too — or leave the more general +one unscoped as above. + +## Type signatures + +RBS signatures ship in `sig/` and are checked in CI with [Steep](https://github.com/soutaro/steep). +Add the gem to your own RBS collection to type-check calls into this client. + +Records are typed, not only the client. `client.tickets` is a +`ResourceProxy[Resources::Ticket]`, so `find`, `first`, `find_by`, the block of `each` and +a search all hand you a `Ticket`, and each resource declares the attributes every +supported Zammad serves for it: + +```ruby +ticket = client.tickets.find(1) + +ticket.title # String +ticket.organization_id # Integer? +ticket.related.customer&.email # String? +ticket.titel # a type error, where it used to be untyped +``` + +Three things are deliberately not declared, and each has a way through: + +- **Attributes an administrator added.** Read one with `ticket[:escalation_reason]`, or + declare it in your own signatures by reopening the class: + + ```rbs + class ZammadAPI::Resources::Ticket + attr_accessor escalation_reason: String? + end + ``` + +- **Columns only newer Zammad versions have**, which an older instance does not serve. + `record[:name]` reads those too. +- **The name `expand` adds for an association that may be empty**, such as `organization` + on a ticket or a user. Zammad leaves the key out rather than sending `null`, so a reader + would raise rather than answer `nil`; `ticket[:organization]` is `nil` in that case, and + `ticket.organization_id` is always there. + +A proxy for [a resource of your own](#resources-this-gem-does-not-model) is untyped until +you say what it holds, because a signature cannot carry a class into its own return type: + +```ruby +roles = client.resource(Role) #: ZammadAPI::ResourceProxy[Role] ``` -> rake release -zammad_api 1.0.7 built to pkg/zammad_api-1.0.7.gem. -Tag v1.0.7 has already been created. -Pushing gem to https://rubygems.org... -You have enabled multi-factor authentication. Please enter OTP code. -Code: ...... -Successfully registered gem: zammad_api (1.0.7) -Pushed zammad_api 1.0.7 to https://rubygems.org +The types describe a record Zammad served. One built with `new` carries only what it was +given until it is saved, and reading anything else from it raises `NoMethodError`, whatever +the signature says the type would be. + +## Examples + +Runnable scripts covering pagination, pattern matching, acting on behalf of a user, +attachments, error handling and threaded use live in [`examples/`](examples/README.md). + +## Development + +```sh +bin/setup # or: bundle install +bundle exec rake # unit specs, RuboCop and Steep ``` -## Contributing +| Task | What it does | +| ------------------------ | ----------------------------------------------------- | +| `rake spec:unit` | Unit specs; stubbed, no Zammad needed | +| `rake spec:integration` | Integration specs against a live Zammad | +| `rake check_connection` | Drives a live Zammad end to end and prints a transcript | +| `rake rubocop` | Style checks | +| `rake steep` | Type-check `lib/` against `sig/`, and `spec/typed/` the way a caller is checked | + +Set `COVERAGE=true` to produce a coverage report in `coverage/`. + +### Testing against a live Zammad + +The integration specs and `check_connection` need a reachable Zammad instance and **will +create and delete records**, so they run only where `TEST_URL` names one, and there is no +default: point it at something disposable. Without it, `rspec` runs the unit specs and +says the integration specs were left out, `rspec spec/integration` fails for having +nothing to run, and `rake spec:integration`, `rake spec` and `rake check_connection` stop +before running anything. + +```sh +export TEST_URL=https://zammad.example/ # a disposable Zammad, never one you keep data in +export TEST_USER=admin@example.com +export TEST_PASSWORD=test + +bundle exec rake check_connection # one linear pass, readable transcript +bundle exec rake spec:integration # the full spec suite +``` -Bug reports and pull requests are welcome on [GitHub](https://github.com/zammad/zammad-api-client-ruby). This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct. +`check_connection` walks the documented workflows in order — create, find, update, reload, +pattern match, paginate, search, ticket with articles, attachment download, acting on +behalf of a user, and each error class — printing `ok` or `FAIL` per step and cleaning up +after itself. It stops early if a precondition fails, so a broken instance produces one +clear line rather than a cascade. + +CI runs both against a Zammad booted from source: the `integration` job clones Zammad, +starts it, waits for it to answer, runs `check_connection` as a fast preflight, then runs +the integration specs. Trigger it by hand from the Actions tab (`workflow_dispatch`) to +test against a specific Zammad ref. + +## Migrating from 1.x + +Version 2.0 fixes long-standing behaviour that could not change without breaking +compatibility. Most calling code needs no edits, and almost everything that does raises +at the call site. Start with the handful of changes that do not. + +If this is not the time to move, [1.x stays available](#staying-on-1x). + +### Changes that do not announce themselves + +- **`record.attributes = {...}`** was a writer in 1.x. It is now an ordinary attribute + assignment, so it stages a change named `attributes` and `save` sends it to Zammad: + + ```ruby + group.attributes = {name: 'Support'} + group.changes # => {attributes: [nil, {name: "Support"}]} + ``` + + Use `assign_attributes(name: 'Support')`, or `update` to assign and save. + +- **`record.save`** returns `false` when Zammad rejects the attributes, where 1.x raised. + Code that relied on the exception carries on after a rejected save: + + ```ruby + ticket.state = 'closed' + ticket.save # false on a 422 in 2.0; nothing raises, and the ticket is still open + ``` + + Check what `save` returns and read `record.error`, or call `save!`, which raises + `ZammadAPI::ValidationError` as `save` used to. `update` and `update!` are the same pair. + +- **`collection.each`** walks every page, where 1.x read one and stopped: + `client.ticket.all.each { ... }`, as 1.x spelled it, touched the first 100 tickets. It + still runs in 2.0, through the deprecated singular reader (`client.tickets` is the new + name), and now touches every ticket the client can read, at a request per page. A loop written to handle the first + page, or one that writes to each record it is handed, does that to all of them now. + Limit it explicitly with `first(n)` or `page(1, per_page: n)`. + +- **`rescue Faraday::ConnectionFailed`** (and any other Faraday exception) no longer + matches. Transport failures are wrapped, so rescue `ZammadAPI::ConnectionError`, + `ZammadAPI::TimeoutError`, or `ZammadAPI::TransportError` for both. + +### The client + +| 1.x | 2.0 | Why | +| -------------------------------------- | ------------------------------------------------ | -------------------------------------------------------------------- | +| `Client.new(config_hash)` | `Client.new(**config_hash)` | Options are keyword arguments now, so a Hash has to be splatted | +| an unknown option was ignored | raises `ArgumentError: unknown keyword` | A typo'd option used to be dropped without a word | +| `logger: true` | `logger: Logger.new($stderr)` | The flag became an object, so you choose the device and level. Anything that answers `debug` is accepted; `true` raises `ConfigurationError` | +| `client.ticket`, `client.user`, … | `client.tickets`, `client.users`, … | A resource is `Enumerable` over every record now, so `client.ticket.each` read as if it acted on one ticket. The singular names still work and warn in Ruby's `deprecated` category; run with `RUBYOPT=-W:deprecated` to find them. They go in 3.0 | +| `client.on_behalf_of = 'login'` | `client.on_behalf_of('login')` → new client | The setter mutated the client and leaked across threads | +| `client.perform_on_behalf_of('x') { }` | `client.on_behalf_of('x') { \|scoped\| ... }` | The old block form left the header set if the block raised | +| `ZammadAPI::Resources::Role < Base` reached by `client.role` | `client.resource(Role)`, for a `Role < ZammadAPI::Resources::Base` of your own | The named readers are a fixed list, and a class is handed over rather than looked up by name. [Raw requests](#raw-requests) reach whatever is not a resource | + +### Collections + +| 1.x | 2.0 | Why | +| ---------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------- | +| `collection.each` stopped after one page | `each` walks every page | Iterating truncated silently at the page size: 100 for `all`, 10 for `search` | +| `collection.page(1, 3) { \|r\| ... }` | `collection.page(1, per_page: 3).each { ... }` | `page` now returns a collection instead of mutating and yielding | +| `collection.page_next` / `page_prev` | `collection.page(n)` or `in_batches` | Removed; they mutated shared state | +| `collection.each_page { ... }` | `collection.in_batches { ... }` | Ruby already has a name for this | +| `collection[3]` | `collection.page(4, per_page: 1).first` | An index that costs a request, and that ignored `page`, was a trap | +| `collection.find(1)` | `client.x.find(1)`, or `collection.detect { ... }` | On a collection `find` is `Enumerable#find`, whose argument is an ifnone callable — so an id answered with an Enumerator and made no request. It raises now | +| `client.x.all(per_page: 50)` | `client.x.all.page(1, per_page: 50)`, `find_each(batch_size: 50)` | `all` accepted the argument and discarded it; page size belongs to the call that reads | +| `client.x.all(active: true)` | `client.x.search(...)`, or `client.x.all.detect { ... }` | The filter never reached the request in 1.x, and could not have: Zammad's index endpoints do not filter, so 2.0 has no call that pretends to. `find_by(active: true)` answers with the first such record, by walking the index where it has no string to search on | +| `client.x.search(query: 'zammad')` | `client.x.search('zammad')` | The search term is the argument, not a keyword | +| `client.x.search(query: 'z', page: 2, per_page: 50)` | `client.x.search('z').page(2, per_page: 50)` | Search did honour those two; paging is the collection's job now | + +### Records + +| 1.x | 2.0 | Why | +| ----------------------------------- | ---------------------------------------------------- | -------------------------------------------------------------------- | +| `record.save` raised on a rejection | `save` → `false` with `record.error`; `save!` raises | Branching on a rejected attribute needed a begin/rescue | +| `record.attributes[:x] = 1` | `record.x = 1`, or `record.to_h` for a copy | Writing through the reader staged no change, so `save` never sent it | +| `record.attributes = {...}` | `record.assign_attributes(...)` / `record.update(...)` | The writer is gone, and the name now stages an attribute of its own | +| `record.id = 5` | `client.x.find(5)` | The id addresses the record, so a staged one deleted or updated a different record than it reported | +| `record.new_instance` | `record.new_record?` / `record.persisted?` | Internal flag is no longer public; the old name raises `NoMethodError`, naming the attributes the record does carry | +| `resource.url` (instance) | `Resource.resource_path` (class) | Clashed with an attribute named `url` | +| `record.unknown_attribute` → `nil` | raises `NoMethodError`; use `record[:x]`, `fetch(:x, nil)` or `key?(:x)` | A typo read as `nil` and flowed on into whatever was written with it. Zammad also serves a reduced object where the user may not see the whole record, and that is worth being told about | +| `client.x.new(id: 5)` | `client.x.find(5)` | The constructor was the one door that did not refuse a staged id — and the only one whose value reached Zammad, since a new record is sent in full | +| `client.users.find(ticket.customer_id)` | `ticket.related.customer` | Following a foreign key needed the client threaded through | +| `ticket.article(body: '…')` | `ticket.add_article(body: '…')` | A noun that sends a `POST`, one letter away from `ticket.articles`, which only reads. `article` still works and warns in Ruby's `deprecated` category; it goes in 3.0 | + +### Errors + +| 1.x | 2.0 | Why | +| ------------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------- | +| `ZammadAPI::Error < RuntimeError` | `ZammadAPI::Error < StandardError` | `RuntimeError` is for `raise "string"` | +| `ZammadAPI::ResourceNotFoundError` | `ZammadAPI::UnknownResourceError` | Renamed so it is not confused with a 404, now `NotFoundError` | +| `ClientError` for every 4xx | `AuthenticationError`, `NotFoundError`, `ValidationError`, … | All still `ClientError`, so existing rescues keep working | +| a Faraday exception for a dead host | `ZammadAPI::ConnectionError` / `TimeoutError` | Every failure this gem can raise descends from `ZammadAPI::Error` | +| `error.response` was a Faraday object | `ZammadAPI::Response` with `status`/`body`/`headers` | Faraday is no longer part of the public surface | +| `error.body` was a raw JSON string | decoded Hash, or the raw body for non-JSON | Saves every caller from parsing it again | + +### Removed constants, and the Ruby version + +| 1.x | 2.0 | Why | +| ------------------------------------------------ | -------------------------- | ------------------------------------------------------------ | +| `ZammadAPI::ListBase` / `ListAll` / `ListSearch` | `ZammadAPI::Collection` | One class instead of three | +| `ZammadAPI::Dispatcher` | `ZammadAPI::ResourceProxy` | Renamed; `client.` hands you one | +| `ZammadAPI::Log`, `ZammadAPI::JsonHelper` | removed | Pass any `Logger` as `logger:`; decoding moved into the transport | +| Ruby >= 3.0 | Ruby >= 3.4 | 3.0 through 3.3 are end-of-life or nearly so | + +### Defaults 1.x did not have + +A collection fetches as many records per request as the endpoint serves — 1000 on the index +endpoints, 100 on tickets, 200 on a search — rather than a fixed 100, so a walk spends +roughly a tenth of the round trips. `page(n)` without `per_page:` is a page of that size, so pin +it with `page(n, per_page: 100)` if a persisted page number has to keep meaning what it did. + +A request now times out after 60 seconds (10 to connect) where 1.x waited as long as the +server took, so a call that used to hang raises `ZammadAPI::TimeoutError`. A `GET` is +retried twice with exponential backoff on connection failures, timeouts and the transient +statuses, which means a genuinely broken endpoint takes a little longer to report itself; +a `POST`, `PUT` or `DELETE` is never retried. Both are options — see +[Timeouts and retries](#timeouts-and-retries). The `User-Agent` is now +`zammad_api-ruby/` rather than `Zammad API Ruby`. + +### What did not change + +`find`, `all`, `create` and `new` on a resource, `record.destroy`, attribute readers and +writers, `ticket.articles` and `attachment.download`. The resources themselves are reached +by their plural names now — `client.tickets` — and adding an article is +`ticket.add_article`; the old names still answer, with a deprecation warning. + +`record.save`, `record.changes` and `record.attributes` still exist and still mean what +they meant; the tables above only change how they behave at the edges. + +## License + +Dual licensed under the [AGPL-3.0-only](LICENSE.AGPL.txt) or [MIT](LICENSE.MIT.txt) +licenses. See [LICENSE.md](LICENSE.md). diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 0000000..4e7052b --- /dev/null +++ b/examples/README.md @@ -0,0 +1,38 @@ +# Examples + +Runnable scripts showing how the 2.0 API works in a real project. Each one is +self-contained and builds its client with `ZammadAPI::Client.from_env`, which +reads the credentials from the environment: + +```sh +export ZAMMAD_URL=https://zammad.example.com/ +export ZAMMAD_TOKEN=your-access-token + +ruby examples/quickstart.rb +``` + +`ZAMMAD_USER` and `ZAMMAD_PASSWORD` work instead of a token, as does +`ZAMMAD_OAUTH2_TOKEN`. + +> These scripts **create, modify and delete records**. Point them at a +> disposable instance. + +None of them set a timeout or a retry policy: requests time out after 60s and +a read that fails transiently is retried with backoff out of the box, so the +examples show what is left for your own code to do. A write is never repeated; +`error_handling.rb` shows what that leaves to you. + +| Script | What it does | API features it shows | +| ------ | ------------ | --------------------- | +| [`quickstart.rb`](quickstart.rb) | Creates a ticket, reads it back, adds an article, updates it | The basics end to end | +| [`pagination.rb`](pagination.rb) | Reads a collection every available way | `each`, `find_each`, `in_batches`, `page(n, per_page: m)`, `search`, `order`, `count`, `empty?`, `lazy`, `first(n)`, `detect`, collection immutability | +| [`manual_batches.rb`](manual_batches.rb) | Drives pagination by hand: pull-based, numbered, resumable | `in_batches` as an Enumerator (`next`, `with_index`), an explicit `page(n, per_page: m)` loop with a persisted cursor | +| [`ticket_report.rb`](ticket_report.rb) | Exports every ticket to CSV | Automatic pagination, `in_batches` batching, `fetch` for required attributes | +| [`triage_tickets.rb`](triage_tickets.rb) | Flags urgent tickets, nudges stale ones | `search`, `case/in` pattern matching on records, staged `changes` so only diffs are sent, `add_article` | +| [`onboard_customer.rb`](onboard_customer.rb) | Creates an organization, a user, and a welcome ticket raised as that user | `find_by`, `create`, `on_behalf_of` as a scoped client and as a block | +| [`download_attachments.rb`](download_attachments.rb) | Saves a ticket's attachments to disk | `articles`, attachment metadata, binary-safe `download` | +| [`error_handling.rb`](error_handling.rb) | Handles the failures that are yours to handle | The error hierarchy, `save` → `false` with `record.error`, rescuing by category, `client.with` for different retry settings | +| [`concurrent_sync.rb`](concurrent_sync.rb) | Syncs tickets with a worker pool sharing one client | Immutable clients are thread-safe; also sketches the Rails initializer pattern | + +The examples are linted along with the rest of the repository (`rake rubocop`), +so they cannot silently rot. diff --git a/examples/concurrent_sync.rb b/examples/concurrent_sync.rb new file mode 100755 index 0000000..b4ac7f5 --- /dev/null +++ b/examples/concurrent_sync.rb @@ -0,0 +1,57 @@ +#!/usr/bin/env ruby +# frozen_string_literal: true + +# Syncs tickets from a worker pool that shares a single client. +# +# A client is immutable once built, so one instance is safe to share between +# threads: no locking, no client per thread, and `on_behalf_of` scoping in one +# thread cannot leak into another. It is the same reason one client works as a +# Rails initializer constant used from every background worker: +# +# # config/initializers/zammad.rb +# ZAMMAD = ZammadAPI::Client.new( +# url: Rails.application.credentials.zammad_url, +# http_token: Rails.application.credentials.zammad_token, +# logger: Rails.logger +# ) +# +# ZAMMAD_URL=https://zammad.example.com/ ZAMMAD_TOKEN=... \ +# ruby examples/concurrent_sync.rb + +require 'zammad_api' + +WORKERS = 4 + +client = ZammadAPI::Client.from_env + +# Collect the work first; `first` stops paginating once it has enough. +queue = Queue.new +client.tickets.all.first(40).each { queue << it.id } +queue.close # so a worker draining an empty queue stops instead of blocking + +results = Queue.new + +workers = Array.new(WORKERS) do + Thread.new do + # Every worker shares this one client. Nothing about it is mutated by + # making a request, so there is nothing to synchronise. + while (id = queue.pop) + results << begin + client.tickets.find(id) + :ok + rescue ZammadAPI::Error => e + # Transient failures were already retried, so anything arriving here + # is worth reporting rather than trying again. + warn "ticket #{id}: #{e.class}" + :failed + end + end + end +end + +workers.each(&:join) + +tally = Hash.new(0) +tally[results.pop] += 1 until results.empty? + +puts "synced #{tally[:ok]}, failed #{tally[:failed]}" diff --git a/examples/download_attachments.rb b/examples/download_attachments.rb new file mode 100755 index 0000000..067fa89 --- /dev/null +++ b/examples/download_attachments.rb @@ -0,0 +1,45 @@ +#!/usr/bin/env ruby +# frozen_string_literal: true + +# Saves every attachment of a ticket to a directory. +# +# Shows walking articles, attachment metadata, and binary-safe downloads. +# +# ZAMMAD_URL=https://zammad.example.com/ ZAMMAD_TOKEN=... \ +# ruby examples/download_attachments.rb 12345 ./downloads + +require 'zammad_api' +require 'fileutils' + +client = ZammadAPI::Client.from_env + +ticket_id = Integer(ARGV.fetch(0) { abort "usage: #{$PROGRAM_NAME} TICKET_ID [DIRECTORY]" }) +directory = ARGV.fetch(1, "ticket-#{ticket_id}") + +ticket = client.tickets.find(ticket_id) +FileUtils.mkdir_p(directory) + +# The filename comes from the server, so `File.basename` strips any directory +# part that would otherwise let `../` escape the download directory. The ids +# keep two same-named attachments from overwriting each other. +def safe_filename(article_id, attachment) + name = File.basename(attachment.filename.to_s) + name = 'attachment' if name.empty? || name.start_with?('.') + "#{article_id}-#{attachment.id}-#{name}" +end + +saved = 0 + +ticket.articles.each do |article| + article.attachments.each do |attachment| + # `download` returns the bytes as ASCII-8BIT, so images and archives + # survive intact. + contents = attachment.download + File.binwrite(File.join(directory, safe_filename(article.id, attachment)), contents) + saved += 1 + + puts format('%-40s %8d bytes', file: attachment.filename, size: contents.bytesize) + end +end + +puts saved.zero? ? "Ticket ##{ticket.number} has no attachments." : "Saved #{saved} file(s) to #{directory}/" diff --git a/examples/error_handling.rb b/examples/error_handling.rb new file mode 100755 index 0000000..9200c7f --- /dev/null +++ b/examples/error_handling.rb @@ -0,0 +1,77 @@ +#!/usr/bin/env ruby +# frozen_string_literal: true + +# What to rescue, and what the client has already handled for you. +# +# Timeouts, connection failures and the transient statuses (429, 500, 502, +# 503, 504) are retried with backoff on a GET before any error reaches your +# code. A write is never repeated, because only you know whether sending it +# twice is safe. So what is left to handle is what only you can decide about: +# a missing record, a rejected attribute, bad credentials, a write that may or +# may not have arrived. +# +# ZAMMAD_URL=https://zammad.example.com/ ZAMMAD_TOKEN=... \ +# ruby examples/error_handling.rb + +require 'zammad_api' + +# Options are validated up front, before any request is made. +begin + ZammadAPI::Client.new(url: 'not-a-url', http_token: 'x') +rescue ZammadAPI::ConfigurationError => e + puts "rejected early: #{e.message}" +end + +client = ZammadAPI::Client.from_env + +# A missing record is a decision to make, not a failure to retry. +ticket = begin + client.tickets.find(0) +rescue ZammadAPI::NotFoundError + nil +end + +puts "missing ticket: #{ticket.inspect}" + +# A rejected attribute (422) makes `save` return false and leaves the reason +# on the record, so branching needs no begin/rescue. +group = client.groups.new(name: '') + +if group.save + puts "created group: #{group.id}" +else + puts "rejected save: #{group.error.status} #{group.error.server_message}" + puts " body #{group.error.body.inspect}" + puts " operation #{group.error.operation} on #{group.error.resource_class}" +end + +# `create` and `save!` raise instead, which is what a script wants. +begin + client.groups.create(name: '') +rescue ZammadAPI::ValidationError => e + puts "raised instead: #{e.class}" +end + +# Rescue by category where the exact class does not matter. +begin + client.tickets.find(0) +rescue ZammadAPI::ClientError => e # any 4xx + puts "client error: #{e.status}" +rescue ZammadAPI::ServerError => e # any 5xx, including an HTML proxy page + puts "server error: #{e.status}" +rescue ZammadAPI::TransportError => e # never reached the server, retries spent + puts "transport error: #{e.message}" +end + +# Or catch everything this gem raises in one place. +begin + client.tickets.find(0) +rescue ZammadAPI::Error => e + puts "any gem error: #{e.class}" +end + +# Where the defaults do not suit the job, change them once on a derived +# client instead of writing a retry loop around every call. +patient = client.with(retries: 5, retry_interval: 1) + +puts "derived client: #{patient.config.retries} retries, original still #{client.config.retries}" diff --git a/examples/manual_batches.rb b/examples/manual_batches.rb new file mode 100755 index 0000000..d9d72f6 --- /dev/null +++ b/examples/manual_batches.rb @@ -0,0 +1,142 @@ +#!/usr/bin/env ruby +# frozen_string_literal: true + +# Driving pagination yourself, for when the loop is not yours to own: a job +# that has to checkpoint and resume, or a producer feeding a queue. +# +# ZAMMAD_URL=https://zammad.example.com/ ZAMMAD_TOKEN=... \ +# ruby examples/manual_batches.rb + +require 'zammad_api' +require 'digest' +require 'fileutils' +require 'tmpdir' + +PER_PAGE = 50 + +client = ZammadAPI::Client.from_env +tickets = client.tickets.all + +# Where the loop in part 3 keeps its checkpoint. A page number says which +# tickets come next only together with the instance it was counted on, the +# user whose tickets they are - the index serves what that user may read - +# the list it pages and the size of the pages, so the file is named for all +# of them. Under one name for every run, a job stopped at page 4 of one +# Zammad had the next run against another start at page 4 there, with the +# first three pages never read - and remove the first job's checkpoint when +# it finished. The user costs a request to look up. +JOB = Digest::SHA256.hexdigest("#{client.config.url} #{client.me.id} api/v1/tickets #{PER_PAGE}")[0, 16] +CURSOR = File.join(Dir.tmpdir, "zammad_batch_cursor_#{JOB}") +NEXT_CURSOR = "#{CURSOR}.next".freeze + +# 1. Pull a page when you are ready for it ----------------------------------- +# +# `in_batches` without a block is an Enumerator: nothing is fetched until +# `next`, and each `next` costs exactly one request. + +puts '1. pulling two pages, leaving the rest unfetched' + +pages = tickets.in_batches(of: PER_PAGE) + +2.times do + puts " pulled #{pages.next.size} tickets" +rescue StopIteration + break +end + +# 2. Numbered batches -------------------------------------------------------- +# +# `with_index` is Ruby's own, and works for the same reason: an Enumerator. + +puts '2. every batch, numbered' + +tickets.in_batches(of: PER_PAGE).with_index do |batch, index| + puts " batch #{index}: #{batch.size} tickets" +end + +# 3. A resumable page loop --------------------------------------------------- +# +# Own the page number when the job has to survive being interrupted. The +# loop ends on a page with nothing on it, and not on a page short of +# PER_PAGE: that is the size asked for, and what counts is the size served. +# An instance that serves 25 where 50 were asked for hands back a "short" +# page every time, and a loop that stops on one has stopped after the first +# with the checkpoint cleared. `find_each` and `in_batches` learn the size +# from the first page; here one more request at the end does the same job. +# +# A page number is a position, not a record, so it only resumes where it left +# off while nothing before it goes away. Delete one ticket from a page already +# handled and every later ticket moves up a place: the next page then starts +# one ticket further on, and the ticket that moved into the handled page is +# never seen. New tickets are no trouble here, because this index is served in +# id order and they arrive at the end. +# +# So this loop is for a set that only grows. Where tickets can be deleted +# between two runs of the job, checkpoint the id of the last ticket handled +# instead, and skip up to it on the way back in: +# +# tickets.find_each.lazy.drop_while { it.id <= last_id }.each { ... } +# +# That reads the earlier pages again, so a ticket deleted while the job was +# down no longer moves the place it picks up from. +# +# It does nothing about a ticket deleted while a walk is under way, and +# neither does anything else here. `find_each` pages by position too: delete +# ticket 1 once page 1 has been read, and page 2 starts one ticket further +# on, with the ticket that moved up into page 1 never handed over. No way of +# reading an index that is paged by position rules that out, and walking +# again does not either: a second walk that tickets are deleted under can +# pass over the same ticket and turn up nothing new. What settles it is a +# walk nothing was deleted during, which the job has to be able to vouch +# for - by holding deletions off while it runs, say - and which turns up +# no ticket it has not handled. + +puts '3. resumable page loop' + +page = 1 + +if File.exist?(CURSOR) + # A checkpoint holds a page number or it holds nothing this loop can use. + # Said here, rather than left to `Integer` or to `page` to raise about. + page = Integer(File.read(CURSOR), exception: false) + abort " #{CURSOR} does not hold a page number. Remove it to start from page 1." if page.nil? || !page.positive? +end + +puts " starting at page #{page}" + +loop do + batch = tickets.page(page, per_page: PER_PAGE).to_a + break if batch.empty? + + puts " page #{page}: #{batch.size} tickets" + + # Checkpoint once the batch is safely handled, so an interrupted run + # repeats a batch rather than skipping one - on a set nothing is deleted + # from, see above. + # + # Written beside the checkpoint and renamed over it, which replaces it in + # one step. `File.write` on the checkpoint itself empties the file before + # it fills it, and a run stopped in between leaves a checkpoint with + # nothing in it, where the page before was still worth having. + File.write(NEXT_CURSOR, page + 1) + File.rename(NEXT_CURSOR, CURSOR) + + page += 1 +end + +FileUtils.rm_f([CURSOR, NEXT_CURSOR]) + +puts <<~NOTE + + Which to reach for: + + each / find_each the loop is yours and runs to completion + in_batches you want one whole response at a time + in_batches.next you want to pull batches as a consumer is ready + in_batches.with_index you want the batches numbered as they arrive + page(n, per_page: m) the page number must be persisted, retried or skipped, + and nothing is deleted from the set meanwhile + + Pacing is not on this list: the client already backs off and retries a 429, + so a manual sleep loop only duplicates it. +NOTE diff --git a/examples/onboard_customer.rb b/examples/onboard_customer.rb new file mode 100755 index 0000000..bcd9892 --- /dev/null +++ b/examples/onboard_customer.rb @@ -0,0 +1,85 @@ +#!/usr/bin/env ruby +# frozen_string_literal: true + +# Onboards a new customer: organization, user, and a welcome ticket raised as +# that user. +# +# Shows `find_by` for a lookup by attribute, `create`, and `on_behalf_of` both +# as a scoped client and as a block. +# +# ZAMMAD_URL=https://zammad.example.com/ ZAMMAD_TOKEN=... \ +# ruby examples/onboard_customer.rb "Acme Inc" jane@acme.test Jane Doe + +require 'zammad_api' + +client = ZammadAPI::Client.from_env + +company, email, firstname, lastname = ARGV +abort "usage: #{$PROGRAM_NAME} COMPANY EMAIL FIRSTNAME LASTNAME" if [company, email, firstname, lastname].any?(&:nil?) + +# Zammad stores an address trimmed and in lower case, and `find_by` matches a +# value exactly. Looked up as typed, Jane@Acme.Test misses the jane@acme.test +# Zammad holds: the check below then sees no user, and the script makes the +# organization before Zammad refuses the address as taken. +email = email.strip.downcase + +# `find_by` searches and then checks the hits itself, because Zammad's index +# endpoints cannot filter. It returns a record that genuinely carries the +# attribute, or nil - never an unrelated one. +# +# What the search surfaces is Zammad's business, so a value it has not indexed +# is a record this will not find, and the `||= create` below would then make a +# second organization. Searching by hand has the same gap. +organization = client.organizations.find_by(name: company) +user = client.users.find_by(email: email) + +# An address Zammad already knows is only this customer's if it sits in this +# organization. Reused regardless, a jane@acme.test who belongs to Contoso +# got Acme's welcome ticket and a report that all was well, with nothing +# having put that user in Acme. Moving a user is not this script's call +# either, so it stops, before anything is created. `[]` rather than a reader, +# because a user with no organization may not carry the attribute at all. +if user && (organization.nil? || user[:organization_id] != organization.id) + # Named where the response carries the name, by id where it carries only + # that, and "no organization" only for a user that has neither. + current = user[:organization] || (user[:organization_id] ? "organization id=#{user[:organization_id]}" : 'no organization') + + abort "#{email} is already a user (id=#{user.id}) of #{current}, not of #{company}. " \ + 'Nothing was created or changed. Move the user in Zammad first, if that is what is meant.' +end + +organization ||= client.organizations.create(name: company) + +puts "organization: #{organization.name} (id=#{organization.id})" + +user ||= client.users.create( + firstname: firstname, + lastname: lastname, + email: email, + organization_id: organization.id, + roles: ['Customer'] +) + +puts "user: #{user.firstname} #{user.lastname} <#{user.email}> (id=#{user.id})" + +# `on_behalf_of` returns a new client rather than mutating this one, so the +# admin client stays unscoped and both remain safe to use. +as_customer = client.on_behalf_of(user.email) + +ticket = as_customer.tickets.create( + title: "Welcome, #{firstname}!", + group: 'Users', + customer: user.email, + article: { + subject: 'Getting started', + body: "Hi #{firstname},\n\nyour account is ready.", + type: 'note' + } +) + +puts "ticket: ##{ticket.number} raised as #{user.email}" + +# The block form scopes a single operation. +own_tickets = client.on_behalf_of(user.email) { |scoped| scoped.tickets.all.count } + +puts "the customer can see #{own_tickets} ticket(s) of their own" diff --git a/examples/pagination.rb b/examples/pagination.rb new file mode 100755 index 0000000..a3332d1 --- /dev/null +++ b/examples/pagination.rb @@ -0,0 +1,71 @@ +#!/usr/bin/env ruby +# frozen_string_literal: true + +# Every way to read a collection, and what each one costs. +# +# Collections are lazy: nothing is fetched until you iterate, and only the +# pages you actually consume are fetched. A request carries as many records as +# the endpoint serves - 100 for tickets, 200 for a search, 1000 for the other +# index endpoints - unless a call asks for another size. +# +# ZAMMAD_URL=https://zammad.example.com/ ZAMMAD_TOKEN=... \ +# ruby examples/pagination.rb + +require 'zammad_api' + +client = ZammadAPI::Client.from_env +tickets = client.tickets.all # no request yet + +# Walk every record. Pages are fetched as the iteration reaches them, so only +# one page is ever held in memory. +seen = 0 +tickets.each { seen += 1 } +puts "each #{seen} tickets, one request per page" + +# The same walk with the page size chosen for the job at hand. +ids = [] +tickets.find_each(batch_size: 50) { ids << it.id } +puts "find_each #{ids.size} tickets, 50 per request" + +# One whole page per block call, for work that batches: an import, a bulk +# insert, a push onto a queue. +sizes = [] +tickets.in_batches(of: 50) { sizes << it.size } +puts "in_batches pages of #{sizes.inspect}" + +# Stop early and the remaining pages are never fetched. +puts "first(3) #{tickets.first(3).map(&:id).inspect}, one request, for three records" +puts "lazy.select #{tickets.lazy.select { it.state == 'open' }.first(2).map(&:id).inspect}" +puts "detect ##{tickets.detect { it.state == 'open' }&.number}, stops at the match" + +# One specific page, when you are driving the paging yourself. +puts "page(2, per_page: 10) #{tickets.page(2, per_page: 10).map(&:id).inspect}" + +# Narrowing by a value is `search`: Zammad's index endpoints sort and page and +# drop every other parameter, so there is no filter to pass them. Searches +# compose with all of the above. +puts "search #{client.tickets.search('state.name:open').first(5).size} open tickets" + +# `order` sorts on the server. A search sorts for every resource; of the index +# endpoints, the ticket and user ones are always served in id order. +newest = client.tickets.search('state.name:open').order(created_at: :desc).first +puts "search.order ##{newest&.number}, the most recently created open ticket" +puts "order #{client.groups.order(:name).first(3).map(&:name).inspect}" + +# Counting a search is one request, because Zammad can answer `only_total_count` +# without serving the records. An index endpoint has no answer for it and no +# total to report, so counting one means walking it. +puts "search.count #{client.tickets.search('state.name:open').count}, one request" +puts "empty? #{client.tickets.search('state.name:merged').empty?}, asks for a single record" + +# `search` and `page` return a new collection, so scoping one never disturbs +# the original. +puts "immutable #{tickets.page(2).equal?(tickets)}" + +puts <<~NOTE + + Upgrading from 1.x: `each` used to fetch a single page, so iterating a + collection silently stopped at 100 records. It now walks every page. Ask + for one page explicitly with `page(1, per_page: 100)` where that is what you + wanted. +NOTE diff --git a/examples/quickstart.rb b/examples/quickstart.rb new file mode 100755 index 0000000..f7c55c3 --- /dev/null +++ b/examples/quickstart.rb @@ -0,0 +1,53 @@ +#!/usr/bin/env ruby +# frozen_string_literal: true + +# The basics, end to end: create a ticket, read it back, add an article and +# update it. +# +# ZAMMAD_URL=https://zammad.example.com/ ZAMMAD_TOKEN=... \ +# ruby examples/quickstart.rb + +require 'zammad_api' + +client = ZammadAPI::Client.from_env + +# `me` answers for any account. `client.version` would name the Zammad +# version as well, but Zammad serves it to administrators only, and an +# agent's token is answered with ZammadAPI::AuthorizationError. +puts "connected to #{client.config.redacted_url} as #{client.me.email}" + +# Create a ticket together with its first article. +ticket = client.tickets.create( + title: 'Cannot log in', + group: 'Users', + customer: 'nicole.braun@zammad.org', + article: { + subject: 'Cannot log in', + body: "Hi,\n\nmy password stopped working.", + type: 'note' + } +) + +puts "created ##{ticket.number} - #{ticket.title}" + +# Read it back. Associations come expanded, so these are plain attribute +# reads rather than further requests. +ticket = client.tickets.find(ticket.id) +puts "state #{ticket.state}, priority #{ticket.priority}, group #{ticket.group}" + +# Add another article. +ticket.add_article(subject: 'Update', body: 'Reset link sent.', type: 'note') +puts "#{ticket.articles.size} article(s)" + +# Assignments are staged, and `save` sends only what changed. It answers +# false, with the reason in `error`, where Zammad rejects the change as +# invalid (a 422). Any other failure raises: a 403 as +# ZammadAPI::AuthorizationError, for one. +ticket.priority = '3 high' +puts "sending #{ticket.changes.inspect}" +abort "Zammad rejected the change: #{ticket.error.message}" if !ticket.save + +# Collections paginate themselves, and `first` stops as soon as it has enough. +client.tickets.search('state.name:open').first(5).each do |open_ticket| + puts "open: ##{open_ticket.number} #{open_ticket.title}" +end diff --git a/examples/ticket_report.rb b/examples/ticket_report.rb new file mode 100755 index 0000000..c6c3340 --- /dev/null +++ b/examples/ticket_report.rb @@ -0,0 +1,54 @@ +#!/usr/bin/env ruby +# frozen_string_literal: true + +# Exports every ticket to CSV. +# +# Shows automatic pagination with `in_batches`, and `fetch` for an attribute +# that has to be there. The defaults carry a long export on their own: a +# request times out after 60s, and transient failures are retried with +# backoff before any error reaches this script. +# +# ZAMMAD_URL=https://zammad.example.com/ ZAMMAD_TOKEN=... \ +# ruby examples/ticket_report.rb tickets.csv + +require 'zammad_api' +require 'csv' + +client = ZammadAPI::Client.from_env +destination = ARGV.fetch(0, 'tickets.csv') +exported = 0 + +# A spreadsheet reads a cell starting with =, +, -, @, tab or CR as a formula, +# and a ticket title is whatever the customer typed. An apostrophe keeps every +# exported cell text. +def csv_safe(value) + text = value.to_s + text.match?(/\A[=+\-@\t\r]/) ? "'#{text}" : text +end + +CSV.open(destination, 'w') do |csv| + csv << %w[id number title state priority group customer created_at] + + # Nothing is loaded until the block runs, and each call is one page. + client.tickets.all.in_batches(of: 100) do |tickets| + tickets.each do |ticket| + row = [ + ticket.fetch(:id), # raises KeyError if it is missing + ticket.number, + ticket.title, + ticket.state, # present because associations come expanded + ticket.priority, + ticket.group, + ticket.customer, + ticket.created_at + ] + + csv << row.map { csv_safe(it) } + end + + exported += tickets.size + warn "exported #{exported} tickets..." + end +end + +puts "Wrote #{exported} tickets to #{destination}" diff --git a/examples/triage_tickets.rb b/examples/triage_tickets.rb new file mode 100755 index 0000000..8402360 --- /dev/null +++ b/examples/triage_tickets.rb @@ -0,0 +1,58 @@ +#!/usr/bin/env ruby +# frozen_string_literal: true + +# Triages open tickets: flags the urgent ones, nudges the stale ones. +# +# Shows `search`, pattern matching against records, staged changes so only +# what was modified is sent, and adding an article. +# +# ZAMMAD_URL=https://zammad.example.com/ ZAMMAD_TOKEN=... \ +# ruby examples/triage_tickets.rb + +require 'zammad_api' +require 'time' + +STALE_AFTER = 7 * 24 * 60 * 60 # a week, in seconds + +client = ZammadAPI::Client.from_env +flagged = 0 +nudged = 0 + +# Oldest first: a search is served newest-updated first, so without the +# order the 200 read would be the freshest, and on an instance with more +# open tickets than that the stale ones would never be looked at. `first` +# stops paginating as soon as it has what it asked for. +client.tickets.search('state.name:open').order(updated_at: :asc).first(200).each do |ticket| + # Records implement `deconstruct_keys`, so case/in works on them. + case ticket + in { priority: '3 high', owner_id: 1 } # 1 is Zammad's "-", i.e. unassigned + puts "unassigned and high priority: ##{ticket.number} #{ticket.title}" + flagged += 1 + + in { updated_at: String => updated } if Time.now - Time.parse(updated) > STALE_AFTER + puts "stale: ##{ticket.number} #{ticket.title}" + + ticket.priority = '3 high' + # Sends the one changed attribute, nothing else. A change Zammad rejects + # as invalid (a 422) comes back as false rather than raising, so it is + # checked: an unchecked save carries on as if the priority had been + # raised. Any other failure, such as a 403, raises. + if !ticket.save + warn " could not raise the priority of ##{ticket.number}: #{ticket.error.message}" + next + end + + ticket.add_article( + subject: 'Automated follow-up', + body: "No activity for over #{STALE_AFTER / 86_400} days; priority raised.", + type: 'note', + internal: true + ) + nudged += 1 + + else + next + end +end + +puts "\n#{flagged} ticket(s) flagged, #{nudged} nudged." From 9c4526e1c356e53571f5bc935aa6add4bf89ab83 Mon Sep 17 00:00:00 2001 From: Mantas Date: Thu, 19 Nov 2026 00:18:20 +0200 Subject: [PATCH 06/11] fix: refuse a record where a record id belongs `Transport.escape_path_segment` turned whatever it was given into a path segment with `to_s`, which answers for every object. A record passed where its id belongs went into the path as it inspects: `client.tickets.exists?(ticket)` asked for `tickets/%23%3CZammadAPI%3A%3AResources%3A%3ATicket...%3E`, was told 404 about a path that names nothing, and answered false for a ticket that exists. `destroy(ticket)` raised NotFoundError for a record that was right there. An id is an Integer, a String or a Symbol, and anything else is refused with an ArgumentError before a request is made. The message names the class and does not quote the value, which for a record is every attribute it carries. nil is still told that an id is required. --- CHANGELOG.md | 6 ++++ lib/zammad_api/transport.rb | 31 +++++++++++++++++++-- sig/zammad_api/transport.rbs | 2 ++ spec/unit/zammad_api/resource_proxy_spec.rb | 20 +++++++++++++ spec/unit/zammad_api/transport_spec.rb | 29 +++++++++++++++++++ 5 files changed, 85 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c5d867e..24dcb4a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -795,6 +795,12 @@ asked for, with `gem install zammad_api --pre` or `gem 'zammad_api', '~> 2.0.0.a request takes headers of its own and the request line prints them, and neither name matched the words that mark a credential, so `client.get(path, headers: {'Cookie' => ...})` wrote the session out in full. +- A record passed where its id belongs is refused with an `ArgumentError`. Whatever was + given went into the request path through `to_s`, which answers for every object, so + `client.tickets.exists?(ticket)` asked for a path spelling out the record's `inspect`, was + told 404 about it and answered `false` for a ticket that exists, and `destroy(ticket)` + raised `NotFoundError` for one that was right there. An id is an `Integer`, a `String` or + a `Symbol`; the message names the class of anything else and does not quote it. ### Changed diff --git a/lib/zammad_api/transport.rb b/lib/zammad_api/transport.rb index 6c2ded2..6d4075d 100644 --- a/lib/zammad_api/transport.rb +++ b/lib/zammad_api/transport.rb @@ -156,6 +156,12 @@ module Verbs # untouched. DOT_SEGMENTS = ['.', '..'].freeze + # What a record id is written as: the Integer Zammad serves, or text - a + # String out of a request parameter, a Symbol for a named member such as + # `users/me`. Everything else has a `to_s` as well, and none of those + # names a record. + RECORD_ID_TYPES = [Integer, String, Symbol].freeze + # A request path that carries a scheme and an authority, and so names a # host of its own. Any scheme and either case, which is wider than the # two lowercase prefixes Faraday itself treats as absolute: what is @@ -508,15 +514,27 @@ def self.blank_on_behalf_of_message(identifier) # them inside the segment here, but a proxy that normalises a path before # routing it would undo that, and no Zammad record is named for one. # + # Anything that is not an id is refused rather than printed. `to_s` + # answers for every object, so a record where its id belongs was pasted + # in as it inspects: `exists?(ticket)` asked for + # `tickets/%23%3CZammadAPI%3A%3AResources%3A%3ATicket...%3E`, was told + # 404 about a path that names nothing, and answered false for a ticket + # that exists, while `destroy(ticket)` raised NotFoundError for one that + # was right there. The message names the class and does not quote the + # value, which for a record is every attribute it carries. + # # Public for the same reason as {.stringify_query}: {Test} builds the # paths it records with it. # # @api private - # @param value [Object] + # @param value [Integer, String, Symbol, nil] # @return [String] - # @raise [ArgumentError] when there is nothing to send, or when the id - # navigates instead of naming a record + # @raise [ArgumentError] when there is nothing to send, when the value + # is not an id at all, or when the id navigates instead of naming a + # record def self.escape_path_segment(value) + raise ArgumentError, not_a_record_id_message(value) if !value.nil? && RECORD_ID_TYPES.none? { value.is_a?(it) } + segment = value.to_s raise ArgumentError, 'a record id is required, and this one is empty' if segment.empty? raise ArgumentError, "#{segment.inspect} points at another endpoint rather than naming a record" if DOT_SEGMENTS.include?(segment) @@ -524,6 +542,13 @@ def self.escape_path_segment(value) segment.gsub(UNRESERVED_IN_PATH) { |character| character.bytes.map { format('%%%02X', it) }.join } end + # @api private + # @return [String] + def self.not_a_record_id_message(value) + "a record id is an Integer or a String, and this one is #{value.class}: it would go into the request path as " \ + 'that object prints, which names no record. To address a record you hold, pass its id.' + end + # Strips the leading slashes from a path so that it resolves against the # instance URL rather than against the host. # diff --git a/sig/zammad_api/transport.rbs b/sig/zammad_api/transport.rbs index ceb3d6c..3d8aaf1 100644 --- a/sig/zammad_api/transport.rbs +++ b/sig/zammad_api/transport.rbs @@ -29,6 +29,7 @@ module ZammadAPI REDACTED: String UNRESERVED_IN_PATH: Regexp DOT_SEGMENTS: Array[String] + RECORD_ID_TYPES: Array[Class] ABSOLUTE_URL: Regexp RESERVED_HEADERS: Hash[String, String] @@ -54,6 +55,7 @@ module ZammadAPI def self.blank_on_behalf_of_message: (untyped identifier) -> String def self.stringify_header_value: (String, untyped) -> String def self.escape_path_segment: (untyped) -> String + def self.not_a_record_id_message: (untyped value) -> String def self.relative_path: (untyped) -> String def self.refuse_unreadable_path!: (String relative) -> void def self.unreadable_path_message: (String relative) -> String diff --git a/spec/unit/zammad_api/resource_proxy_spec.rb b/spec/unit/zammad_api/resource_proxy_spec.rb index 1390e47..b824bce 100644 --- a/spec/unit/zammad_api/resource_proxy_spec.rb +++ b/spec/unit/zammad_api/resource_proxy_spec.rb @@ -88,6 +88,26 @@ expect { proxy.find('') }.to raise_error(ArgumentError, /record id is required/) expect(a_request(:any, /zammad\.test/)).not_to have_been_made end + + # A record where its id belongs went into the path as it inspects, and + # the 404 for that path was read as an answer about the record. + context 'with a record where its id belongs' do + let(:record) { ZammadAPI::Resources::Group.from_response(client.instance_variable_get(:@transport), { id: 1, name: 'Users' }) } + + it 'refuses exists? rather than answering false for a record that exists' do + expect { proxy.exists?(record) }.to raise_error(ArgumentError, /pass its id/) + expect(a_request(:any, /zammad\.test/)).not_to have_been_made + end + + it 'refuses find' do + expect { proxy.find(record) }.to raise_error(ArgumentError, /pass its id/) + end + + it 'refuses destroy rather than raising NotFoundError for a record that is there' do + expect { proxy.destroy(record) }.to raise_error(ArgumentError, /pass its id/) + expect(a_request(:any, /zammad\.test/)).not_to have_been_made + end + end end describe '#create' do diff --git a/spec/unit/zammad_api/transport_spec.rb b/spec/unit/zammad_api/transport_spec.rb index 142f00d..caabea5 100644 --- a/spec/unit/zammad_api/transport_spec.rb +++ b/spec/unit/zammad_api/transport_spec.rb @@ -355,6 +355,35 @@ it 'encodes an already-encoded dot segment rather than passing it on' do expect(described_class.escape_path_segment('%2e%2e')).to eq('%252e%252e') end + + it 'takes a Symbol, for a member that is named rather than numbered' do + expect(described_class.escape_path_segment(:me)).to eq('me') + end + + # `to_s` answers for every object, so a record where its id belongs was + # pasted into the path as it inspects and answered with a 404. + it 'raises for a record where its id belongs' do + record = ZammadAPI::Resources::Group.from_response(unit_transport, { id: 1, name: 'Users' }) + + expect { described_class.escape_path_segment(record) } + .to raise_error(ArgumentError, /record id is an Integer or a String, and this one is ZammadAPI::Resources::Group/) + end + + it 'does not quote what it refuses, which for a record is its attributes' do + record = ZammadAPI::Resources::Group.from_response(unit_transport, { id: 1, name: 'Users' }) + + expect { described_class.escape_path_segment(record) }.to raise_error(ArgumentError) { |error| expect(error.message).not_to include('Users') } + end + + [[1], { id: 1 }, 1.0, true, Object.new].each do |value| + it "raises for #{value.class}, which only prints as something" do + expect { described_class.escape_path_segment(value) }.to raise_error(ArgumentError, /this one is #{value.class}/) + end + end + + it 'still says that an id is missing for nil' do + expect { described_class.escape_path_segment(nil) }.to raise_error(ArgumentError, /record id is required/) + end end describe 'request bodies' do From a90353e53da51d4d1332bceff9d3c4f173e15325 Mon Sep 17 00:00:00 2001 From: Mantas Date: Thu, 19 Nov 2026 00:20:21 +0200 Subject: [PATCH 07/11] fix: refuse one attribute given under two spellings A record symbolizes the keys of the attributes it is given, and two keys that land on one name were merged in silence: `client.groups.new('name' => 'Support', name: 'Sales')` built a record holding `name: 'Sales'` alone, so an attribute Hash put together from form parameters and defaults lost a value to Hash order. `assign_attributes` wrote such an attribute twice and kept the last. `Ticket#add_article` took both spellings of `ticket_id` out by hand for this, and nothing else did. `DeepCopy.frozen_copy` refuses the pair with the ArgumentError `DuplicateKeys` raises for a query parameter and a header, at any depth. It compares the sizes of the Hash and its copy, so a Hash built from a response pays no call per key. `assign_attributes` copies its values before it writes the first of them, so a pair inside a later value leaves nothing staged. --- CHANGELOG.md | 7 ++++ lib/zammad_api/deep_copy.rb | 32 +++++++++++++++- lib/zammad_api/resources/base.rb | 21 ++++++++++- lib/zammad_api/resources/ticket.rb | 5 ++- sig/zammad_api/deep_copy.rbs | 1 + spec/unit/zammad_api/attribute_access_spec.rb | 24 ++++++++++++ spec/unit/zammad_api/resources/base_spec.rb | 37 +++++++++++++++++++ 7 files changed, 123 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 24dcb4a..16fdd5f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -801,6 +801,13 @@ asked for, with `gem install zammad_api --pre` or `gem 'zammad_api', '~> 2.0.0.a told 404 about it and answered `false` for a ticket that exists, and `destroy(ticket)` raised `NotFoundError` for one that was right there. An id is an `Integer`, a `String` or a `Symbol`; the message names the class of anything else and does not quote it. +- One attribute given under two spellings raises `ArgumentError` instead of keeping + whichever Hash order put last. A record symbolizes the keys of the attributes it is given, + so `client.groups.new('name' => 'Support', name: 'Sales')` built a record holding + `name: 'Sales'` alone, and an attribute Hash put together from form parameters and + defaults lost a value without a word. `create`, `assign_attributes`, `update` and a + writer handed a Hash refuse the pair the same way, at any depth, and nothing is staged + when they do. It is the refusal a query parameter and a header already had. ### Changed diff --git a/lib/zammad_api/deep_copy.rb b/lib/zammad_api/deep_copy.rb index cc7e8db..b038c40 100644 --- a/lib/zammad_api/deep_copy.rb +++ b/lib/zammad_api/deep_copy.rb @@ -1,5 +1,7 @@ # frozen_string_literal: true +require_relative 'duplicate_keys' + module ZammadAPI # Recursive copies of the plain JSON structures this gem passes around. # @@ -50,15 +52,43 @@ module DeepCopy # @param symbolize_keys [Boolean] whether Hash keys become Symbols, so # that caller-supplied attributes behave the same as decoded responses # @return [Object] a frozen copy + # @raise [ArgumentError] when symbolizing lands two keys of one Hash on + # one name def frozen_copy(value, symbolize_keys: false) case value - when Hash then value.to_h { |key, nested| [symbolize_keys ? symbolize(key) : key, frozen_copy(nested, symbolize_keys: symbolize_keys)] }.freeze + when Hash then frozen_hash(value, symbolize_keys) when Array then value.map { frozen_copy(it, symbolize_keys: symbolize_keys) }.freeze when String then value.dup.freeze else value end end + # The Hash branch of {frozen_copy}. + # + # Two keys that symbolize to one name are refused rather than merged. + # Symbolizing is what creates the collision, the way stringifying does + # for a query - see {DuplicateKeys} - and here it went unrefused: + # `client.groups.new('name' => 'Support', name: 'Sales')` built a record + # holding `name: 'Sales'` alone, and an attribute Hash put together from + # form parameters and defaults lost a value to Hash order without a word. + # {Resources::Ticket#add_article} had to take both spellings of + # `ticket_id` out by hand for it. + # + # Asked of the sizes, so that a Hash with no collision in it - every one + # built from a response - pays one comparison and no call per key. The + # walk that names the two spellings is made only once there is a pair to + # name. + # + # @api private + # @return [Hash] a frozen copy + # @raise [ArgumentError] + def frozen_hash(hash, symbolize_keys) + copy = hash.to_h { |key, nested| [symbolize_keys ? symbolize(key) : key, frozen_copy(nested, symbolize_keys: symbolize_keys)] } + DuplicateKeys.normalize(hash, noun: 'attribute') { symbolize(it) } if symbolize_keys && copy.size != hash.size + + copy.freeze + end + # A writable deep copy, for handing out something callers may treat as # their own. The inverse of {frozen_copy}. # diff --git a/lib/zammad_api/resources/base.rb b/lib/zammad_api/resources/base.rb index b82317e..4e929a0 100644 --- a/lib/zammad_api/resources/base.rb +++ b/lib/zammad_api/resources/base.rb @@ -3,6 +3,7 @@ require_relative '../associations' require_relative '../attribute_access' require_relative '../deep_copy' +require_relative '../duplicate_keys' require_relative '../errors' require_relative '../transport' @@ -342,6 +343,8 @@ def has_many(name, class_name:, path:) # @param transport [Transport] # @param attributes [Hash, nil] # @raise [Error] when an attribute cannot be staged, such as +id+ + # @raise [ArgumentError] when an attribute is named twice, as a String + # and as a Symbol, at any depth def initialize(transport, attributes = {}) given = attributes || {} # The same refusal the writers make, at the one door that did not make @@ -441,7 +444,21 @@ def related # @raise [Error] when an attribute cannot be staged, such as +id+, or # when the record was destroyed. Nothing is staged in either case, so # the record is left as it was. + # @raise [ArgumentError] when an attribute is named twice, as a String + # and as a Symbol. Nothing is staged then either. def assign_attributes(attributes) + # Two spellings of one attribute are refused before anything is + # written, for the reason the constructor refuses them - see + # {DeepCopy.frozen_hash}. Each key is written by its Symbol, so + # `assign_attributes('name' => 'A', name: 'B')` wrote the attribute + # twice and kept whichever Hash order put last. + # + # The values are copied here as well, which is where a pair inside + # one of them is refused. Left to the writes below, a value that + # names a nested key twice raised from the middle of them, with the + # attributes before it already staged. + staged = frozen_attributes(DuplicateKeys.normalize(attributes, noun: 'attribute', &:to_sym)) + # rubocop:disable Style/CombinableLoops -- combining them is the bug # Two passes on purpose: every key is checked before any of them is # written. Combined, `assign_attributes(name: 'X', id: 9, note: 'Y')` @@ -453,8 +470,8 @@ def assign_attributes(attributes) # direct writer's own guard and cannot assume a caller came through # here. That is a second Symbol comparison per attribute, which is not # worth a bypass to avoid. - attributes.each { |key, value| refuse_unwritable!(key.to_sym, value) } - attributes.each { |key, value| write_attribute(key.to_sym, value) } + staged.each { |key, value| refuse_unwritable!(key, value) } + staged.each { |key, value| write_attribute(key, value) } # rubocop:enable Style/CombinableLoops self end diff --git a/lib/zammad_api/resources/ticket.rb b/lib/zammad_api/resources/ticket.rb index 3f3810a..7f1c1f5 100644 --- a/lib/zammad_api/resources/ticket.rb +++ b/lib/zammad_api/resources/ticket.rb @@ -71,7 +71,10 @@ def add_article(attributes = {}) # String one standing beside it, and the article symbolizes its keys # in the order they come: given `ticket_id` under both spellings, the # String one came last and won, so `add_article` on ticket 7 POSTed - # an article naming whichever ticket the caller's Hash did. + # an article naming whichever ticket the caller's Hash did. An + # article refuses two spellings of one attribute now, and a String + # `ticket_id` left beside this ticket's would be refused as a pair + # the caller never wrote. own = attributes.reject { |key, _| key.to_s == 'ticket_id' } record = TicketArticle.new(transport, own.merge(ticket_id: require_id!)) record.save! diff --git a/sig/zammad_api/deep_copy.rbs b/sig/zammad_api/deep_copy.rbs index 09526b8..b5c7325 100644 --- a/sig/zammad_api/deep_copy.rbs +++ b/sig/zammad_api/deep_copy.rbs @@ -1,6 +1,7 @@ module ZammadAPI module DeepCopy def self?.frozen_copy: (untyped value, ?symbolize_keys: bool) -> untyped + def self?.frozen_hash: (Hash[untyped, untyped] hash, bool symbolize_keys) -> Hash[untyped, untyped] def self?.writable_copy: (untyped value) -> untyped def self?.symbolize: (untyped key) -> untyped end diff --git a/spec/unit/zammad_api/attribute_access_spec.rb b/spec/unit/zammad_api/attribute_access_spec.rb index a0397ed..28f2aea 100644 --- a/spec/unit/zammad_api/attribute_access_spec.rb +++ b/spec/unit/zammad_api/attribute_access_spec.rb @@ -37,6 +37,30 @@ def initialize(attributes) it 'leaves keys alone that cannot become symbols' do expect(record_class.new(1 => 'one').attributes).to eq(1 => 'one') end + + # Symbolizing is what makes two keys one, and the value that came first + # was dropped without a word. + context 'with one attribute under two spellings' do + it 'refuses the pair rather than keeping whichever came last' do + expect { record_class.new('name' => 'Support', name: 'Sales') } + .to raise_error(ArgumentError, /attribute name was given twice, as "name" and as :name/) + end + + it 'refuses a pair inside a nested Hash' do + expect { record_class.new(preferences: { 'locale' => 'de', locale: 'en' }) } + .to raise_error(ArgumentError, /attribute locale was given twice/) + end + + it 'refuses a pair inside a Hash in an Array' do + expect { record_class.new(notes: [{ 'body' => 'a', body: 'b' }]) } + .to raise_error(ArgumentError, /attribute body was given twice/) + end + + it 'takes the same name at two depths, which is two attributes' do + expect(record_class.new('name' => 'Support', preferences: { name: 'Sales' }).attributes) + .to eq(name: 'Support', preferences: { name: 'Sales' }) + end + end end describe 'reading' do diff --git a/spec/unit/zammad_api/resources/base_spec.rb b/spec/unit/zammad_api/resources/base_spec.rb index d3287b8..bbc729f 100644 --- a/spec/unit/zammad_api/resources/base_spec.rb +++ b/spec/unit/zammad_api/resources/base_spec.rb @@ -34,6 +34,23 @@ def self.name expect(group.note).to eq('from a string key') end + # A record built from a Hash put together across several merges held + # whichever spelling Hash order put last, and sent that. + it 'refuses one attribute under two spellings rather than keeping the last' do + expect { client.groups.new('name' => 'Support', name: 'Sales') } + .to raise_error(ArgumentError, /attribute name was given twice, as "name" and as :name/) + end + + it 'refuses two spellings on create before anything is sent' do + expect { client.groups.create('name' => 'Support', name: 'Sales') }.to raise_error(ArgumentError, /given twice/) + expect(a_request(:any, /zammad\.test/)).not_to have_been_made + end + + it 'refuses two spellings inside a value a writer is given' do + expect { group.preferences = { 'locale' => 'de', locale: 'en' } }.to raise_error(ArgumentError, /attribute locale was given twice/) + expect(group).not_to be_changed + end + it 'starts without changes' do expect(group).not_to be_changed end @@ -383,6 +400,26 @@ def self.name group.assign_attributes(name: 'Support') expect(group).not_to be_changed end + + # Each key is written by its Symbol, so the attribute was written twice + # and whichever spelling came last in the Hash was the one staged. + context 'with one attribute under two spellings' do + it 'refuses the pair' do + expect { group.assign_attributes('name' => 'A', name: 'B') } + .to raise_error(ArgumentError, /attribute name was given twice, as "name" and as :name/) + end + + it 'stages nothing' do + expect { group.assign_attributes(:note => 'Why', 'name' => 'A', :name => 'B') }.to raise_error(ArgumentError) + expect(group).not_to be_changed + end + + it 'stages nothing where the pair is inside a later value' do + expect { group.assign_attributes(note: 'Why', preferences: { 'locale' => 'de', locale: 'en' }) } + .to raise_error(ArgumentError, /attribute locale was given twice/) + expect(group).not_to be_changed + end + end end describe '#update' do From 884660fbd43c87795f015cabb7c384e848889f88 Mon Sep 17 00:00:00 2001 From: Mantas Date: Thu, 19 Nov 2026 00:21:38 +0200 Subject: [PATCH 08/11] fix: keep credentials out of a record's inspect `Resources::Base#inspect` printed every attribute as it stood, and a record can hold a credential: `client.users.new(login: 'x', password: 'hunter2')` is how a user is given a password. `inspect` is what IRB and `pp` show, what an RSpec failure diffs and what an exception report prints for a record it interpolates, so the password went wherever any of those did. `Config#inspect` and the debug log both blank such a value already. `inspect` blanks the value under a key `SENSITIVE_KEY_PATTERN` matches, at any depth. The log's `redact` moves from a private method of a transport to `Transport.redact` so that both print by one rule. `attributes`, `to_h` and `to_json` hand over the values as before. --- CHANGELOG.md | 5 +++ lib/zammad_api/resources/base.rb | 18 ++++++++++- lib/zammad_api/transport.rb | 33 ++++++++++++------- sig/zammad_api/transport.rbs | 2 +- spec/unit/zammad_api/resources/base_spec.rb | 36 +++++++++++++++++++++ spec/unit/zammad_api/transport_spec.rb | 30 +++++++++++++++++ 6 files changed, 111 insertions(+), 13 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 16fdd5f..d717d2f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -808,6 +808,11 @@ asked for, with `gem install zammad_api --pre` or `gem 'zammad_api', '~> 2.0.0.a defaults lost a value without a word. `create`, `assign_attributes`, `update` and a writer handed a Hash refuse the pair the same way, at any depth, and nothing is staged when they do. It is the refusal a query parameter and a header already had. +- A record's `inspect` blanks the value of an attribute that names a credential, by the + rule the debug log redacts a request with. The attributes were printed as they stood, so + `client.users.new(login: 'x', password: 'hunter2')` showed the password in IRB and under + `pp`, in an RSpec failure and in any exception report that interpolates the record. + `attributes`, `to_h` and `to_json` still hand the value over. ### Changed diff --git a/lib/zammad_api/resources/base.rb b/lib/zammad_api/resources/base.rb index 4e929a0..c4fc271 100644 --- a/lib/zammad_api/resources/base.rb +++ b/lib/zammad_api/resources/base.rb @@ -648,7 +648,23 @@ def destroy true end - def inspect = "#<#{self.class.name} id=#{id.inspect} new_record=#{new_record?}#{' destroyed=true' if destroyed?} attributes=#{attributes.inspect}>" + # Says which record this is and what it holds, with the value of an + # attribute that names a credential blanked. + # + # The attributes were printed as they stood, and a record can hold a + # credential: `client.users.new(login: 'x', password: 'hunter2')` is + # how a user is given one. Its `inspect` is what IRB and `pp` show, + # what an RSpec failure diffs and what an exception report prints for + # a record it interpolates, so the password staged for one request + # was written wherever any of those went. The log has blanked the same + # key in the same request all along, by {Transport.redact}, which is + # the rule applied here. + # + # Only what is printed. {#attributes}, {#to_h} and {#to_json} hand over + # the values, because sending them is what a record is for. + # + # @return [String] + def inspect = "#<#{self.class.name} id=#{id.inspect} new_record=#{new_record?}#{' destroyed=true' if destroyed?} attributes=#{Transport.redact(attributes).inspect}>" protected diff --git a/lib/zammad_api/transport.rb b/lib/zammad_api/transport.rb index 6d4075d..b93ee26 100644 --- a/lib/zammad_api/transport.rb +++ b/lib/zammad_api/transport.rb @@ -684,6 +684,25 @@ def self.redact_query_pair(pair) decoded && !SENSITIVE_KEY_PATTERN.match?(decoded) ? pair : "#{name}=#{REDACTED}" end + # A structure as it may be printed: with the value under every key that + # names a credential blanked, at any depth. See {SENSITIVE_KEY_PATTERN} + # for which keys those are. + # + # Public for {Resources::Base#inspect}. This was the log's own rule, and + # a record printed the same attributes with nothing applied to them. + # + # @api private + # @param value [Object] + # @return [Object] a copy where anything was blanked, or holds a Hash or + # an Array + def self.redact(value) + case value + when Hash then value.to_h { |key, nested| [key, SENSITIVE_KEY_PATTERN.match?(key.to_s) ? REDACTED : redact(nested)] } + when Array then value.map { redact(it) } + else value + end + end + # The bytes a request body goes out as. # # Encoded here rather than left to Faraday's JSON middleware, because a @@ -1122,7 +1141,7 @@ def raw_body!(body) def log_request(method, path, query, body, headers) logger.debug do - "Zammad API request: #{method.to_s.upcase} #{Transport.redact_path(path)}#{" query=#{redact(query).inspect}" if query}#{" headers=#{redact(headers).inspect}" if headers}" + "Zammad API request: #{method.to_s.upcase} #{Transport.redact_path(path)}#{" query=#{Transport.redact(query).inspect}" if query}#{" headers=#{Transport.redact(headers).inspect}" if headers}" end logger.debug { "Zammad API payload: #{loggable_body(body).inspect}" } if body end @@ -1142,24 +1161,16 @@ def log_response(method, path, response, started) # not - a form body, a file - nothing in it can be told from a # credential, and its size is logged in its place. def loggable_body(body) - return redact(body) if !body.is_a?(String) + return Transport.redact(body) if !body.is_a?(String) decoded = JSON.parse(body) - decoded.is_a?(Hash) || decoded.is_a?(Array) ? redact(decoded) : unlogged_body(body) + decoded.is_a?(Hash) || decoded.is_a?(Array) ? Transport.redact(decoded) : unlogged_body(body) rescue JSON::JSONError, EncodingError unlogged_body(body) end def unlogged_body(body) = "[#{body.bytesize} bytes that are not a JSON object or array, not logged]" - def redact(value) - case value - when Hash then value.to_h { |key, nested| [key, SENSITIVE_KEY_PATTERN.match?(key.to_s) ? REDACTED : redact(nested)] } - when Array then value.map { redact(it) } - else value - end - end - def logger = config.logger end end diff --git a/sig/zammad_api/transport.rbs b/sig/zammad_api/transport.rbs index 3d8aaf1..5bef0a1 100644 --- a/sig/zammad_api/transport.rbs +++ b/sig/zammad_api/transport.rbs @@ -40,6 +40,7 @@ module ZammadAPI def self.redact_path: (untyped path) -> String def self.redact_query_pair: (String pair) -> String + def self.redact: (untyped value) -> untyped def self.stringify_query: (Hash[untyped, untyped]) -> Hash[String, untyped] def self.stringify_query_hash: (Hash[untyped, untyped], String?) -> Hash[String, untyped] def self.stringify_query_value: (String, untyped) -> untyped @@ -82,7 +83,6 @@ module ZammadAPI def raw_body!: (untyped) -> String def log_request: (Symbol, String, Hash[Symbol, untyped]?, untyped, Hash[String, String]?) -> void def log_response: (Symbol, String, Response, Float) -> void - def redact: (untyped) -> untyped def loggable_body: (untyped body) -> untyped def unlogged_body: (String body) -> String def reportable_cause: (StandardError error) -> StandardError? diff --git a/spec/unit/zammad_api/resources/base_spec.rb b/spec/unit/zammad_api/resources/base_spec.rb index bbc729f..5ebd858 100644 --- a/spec/unit/zammad_api/resources/base_spec.rb +++ b/spec/unit/zammad_api/resources/base_spec.rb @@ -916,6 +916,42 @@ def self.name expect(group.inspect) .to eq('#') end + + # A record is printed by IRB, by pp, in an RSpec failure and in an + # exception report, and a user is given a password by staging one. + context 'with an attribute that names a credential' do + let(:user) { client.users.new(login: 'x', password: 'hunter2', preferences: { tokens: [{ access_token: 's3cret' }], locale: 'de' }) } + + it 'blanks a staged password' do + expect(user.inspect).to include('password: "[REDACTED]"').and include('login: "x"') + end + + it 'does not print the password anywhere' do + expect(user.inspect).not_to include('hunter2') + end + + it 'blanks a credential nested in another attribute' do + expect(user.inspect).not_to include('s3cret') + end + + it 'leaves what sits beside a nested credential readable' do + expect(user.inspect).to include('locale: "de"') + end + + it 'is what pp prints as well' do + expect(PP.pp(user, +'')).not_to include('hunter2') + end + + it 'blanks one that was written after the record was built' do + user.password = 'correct horse' + expect(user.inspect).not_to include('correct horse') + end + + it 'still hands the value over to what sends it' do + expect(user.attributes[:password]).to eq('hunter2') + expect(user.to_h[:password]).to eq('hunter2') + end + end end describe '.from_response' do diff --git a/spec/unit/zammad_api/transport_spec.rb b/spec/unit/zammad_api/transport_spec.rb index caabea5..312d11e 100644 --- a/spec/unit/zammad_api/transport_spec.rb +++ b/spec/unit/zammad_api/transport_spec.rb @@ -318,6 +318,36 @@ end end + describe '.redact' do + it 'blanks the value under a key that names a credential' do + expect(described_class.redact({ login: 'x', password: 'hunter2' })).to eq({ login: 'x', password: '[REDACTED]' }) + end + + it 'reads a String key the way it reads a Symbol' do + expect(described_class.redact({ 'api_key' => 'k' })).to eq({ 'api_key' => '[REDACTED]' }) + end + + it 'blanks one at any depth, through Hashes and Arrays' do + expect(described_class.redact({ users: [{ preferences: { access_token: 't', locale: 'de' } }] })) + .to eq({ users: [{ preferences: { access_token: '[REDACTED]', locale: 'de' } }] }) + end + + it 'blanks the whole of a structure held under such a key' do + expect(described_class.redact({ tokens: [{ name: 'a' }] })).to eq({ tokens: '[REDACTED]' }) + end + + it 'leaves what it was given as it was' do + attributes = { password: 'hunter2' } + described_class.redact(attributes) + + expect(attributes).to eq({ password: 'hunter2' }) + end + + it 'hands back anything that is not a structure' do + expect(described_class.redact('password')).to eq('password') + end + end + describe '.escape_path_segment' do it 'leaves an ordinary id alone' do expect(described_class.escape_path_segment(42)).to eq('42') From 551865d637a0b1bb04445f714bc316dbb20fccde Mon Sep 17 00:00:00 2001 From: Mantas Date: Thu, 19 Nov 2026 00:25:28 +0200 Subject: [PATCH 09/11] fix: have the test kit retry a read as the client does The real transport sends a GET again that was answered 429 or 5xx. `ZammadAPI::Test` raised for the first such answer. Stubbed 503 and then 200, `client.groups.find(1)` returns the group against Zammad and raised ServerError against the stand-in, and a single stubbed 503 was recorded as one request where the wire carries three. A test of code that leans on the retry passed or failed the other way round from production. `Test#answer` attempts a request up to `retries` more times. Each attempt is recorded and takes a stub of its own, and there is no wait between them. Whether a response is retried is asked of `Transport.retried?`, which reads the options the retry middleware is built with and has the middleware itself say whether it would wait, so a write is not repeated and a Retry-After longer than the timeout ends the attempts, as on the wire. `retry_options` becomes a class method for it. `ZammadAPI::Test.new(retries: 0)` raises for the first failure. --- CHANGELOG.md | 9 ++ README.md | 17 +++ lib/zammad_api/test.rb | 59 ++++++++-- lib/zammad_api/transport.rb | 87 ++++++++++----- sig/vendor/faraday.rbs | 16 +++ sig/zammad_api/test.rbs | 1 + sig/zammad_api/transport.rbs | 3 +- spec/unit/zammad_api/test_spec.rb | 149 +++++++++++++++++++++++++ spec/unit/zammad_api/transport_spec.rb | 56 ++++++++++ 9 files changed, 362 insertions(+), 35 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d717d2f..d91a2f9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -813,6 +813,15 @@ asked for, with `gem install zammad_api --pre` or `gem 'zammad_api', '~> 2.0.0.a `client.users.new(login: 'x', password: 'hunter2')` showed the password in IRB and under `pp`, in an RSpec failure and in any exception report that interpolates the record. `attributes`, `to_h` and `to_json` still hand the value over. +- The test kit sends a read again that the client would retry. It raised for the first + stubbed 429 or 5xx, where the real transport asks again: stubbed 503 and then 200, + `client.groups.find(1)` returns the group against Zammad and raised `ServerError` against + the stand-in, and a single stubbed 503 was recorded as one request where the wire carries + three. A `GET` is now attempted up to `retries` more times, each attempt recorded and + answered by the next stub, with no wait in between. Whether a response is retried is the + transport's own rule, so a write is not repeated and a `Retry-After` longer than + `timeout` ends the attempts. `ZammadAPI::Test.new(retries: 0)` raises for the first + failure, as before. ### Changed diff --git a/README.md b/README.md index 734313c..10296b9 100644 --- a/README.md +++ b/README.md @@ -1187,6 +1187,23 @@ the wire would refuse is refused here too. `headers` names only what the call as the ones the client sets from its configuration are not in it, and an `on_behalf_of` scope has a field of its own. +A read that is answered 429 or 5xx is sent again, as it is on the wire: a `GET`, up to +`retries` times, and never a write. Each attempt is in `requests` and takes the next stub +of a sequence, so a read that fails once and then succeeds is two stubs: + +```ruby +zammad.stub(:get, 'api/v1/tickets/1', status: 503) +zammad.stub(:get, 'api/v1/tickets/1', body: {id: 1, title: 'Help'}) + +zammad.client.tickets.find(1).title # => "Help" +zammad.requests.size # => 2 +``` + +A single failing stub answers every attempt, so the error is raised once the retries are +spent, with three requests recorded under the default of two retries. There is no wait +between attempts. A `Retry-After` longer than `timeout` ends them at once, as it does +against Zammad. `ZammadAPI::Test.new(retries: 0)` raises for the first failure. + A request that was not stubbed raises `ZammadAPI::Test::UnstubbedRequestError`, listing what is stubbed, rather than answering with something empty. It is deliberately not a `ZammadAPI::Error`: a forgotten stub means the test is wrong, not that Zammad refused diff --git a/lib/zammad_api/test.rb b/lib/zammad_api/test.rb index 40a17c5..92ef189 100644 --- a/lib/zammad_api/test.rb +++ b/lib/zammad_api/test.rb @@ -27,6 +27,11 @@ module ZammadAPI # @example An error path # zammad.stub(:get, 'api/v1/tickets/9', status: 404, body: {error: 'not found'}) # # the code under test sees ZammadAPI::NotFoundError + # + # @example A read the client retries + # zammad.stub(:get, 'api/v1/tickets/1', status: 503) + # zammad.stub(:get, 'api/v1/tickets/1', body: {id: 1, title: 'Help'}) + # # the code under test sees the ticket, and zammad.requests holds both attempts class Test # Raised when the code under test reaches an endpoint that was not stubbed. # @@ -131,6 +136,10 @@ def initialize(**options) # a scoped stub and a catch-all are two separate answers, each of which # keeps answering. # + # A +GET+ answered with a status the client retries - 429, 500, 502, 503 + # or 504 - is asked again, as it is on the wire, and each attempt takes + # the next stub of the sequence: see {#answer}. + # # @param method [Symbol] +:get+, +:post+, +:put+ or +:delete+ # @param path [String] path relative to the instance URL, leading slash # optional @@ -213,9 +222,28 @@ def inspect = @monitor.synchronize { "#<#{self.class.name} stubbed=#{@stubs.size # This is the {Transport} interface, called by the client rather than by a # test. # + # A request the real transport would send again is sent again here: a + # +GET+ answered 429 or 5xx, as many times as {Config#retries} allows. + # The first such answer used to be raised. Stubbed 503 and then 200, + # `client.groups.find(1)` returns the group on the wire and raised + # ServerError here, and a single stubbed 503 was recorded as one request + # where the wire carries three - so a test of code that leans on the + # retry passed or failed the other way round from production. + # + # Each attempt is recorded and takes a stub of its own, which is what + # makes "fails once, then answers" two stubs in a row. There is no wait + # between them: the backoff is the one part of a retry a test has no use + # for. Whether a response is retried at all is {Transport.retried?}, the + # real transport's own rule, so a +Retry-After+ longer than the timeout + # ends the attempts here as it does there. + # + # The count is this stand-in's, read from the options it was built + # with: `ZammadAPI::Test.new(retries: 0)` raises for the first failure. + # # @api private # @return [Response] - # @raise [ResponseError] for a stubbed non-2xx status + # @raise [ResponseError] for a stubbed non-2xx status, once the retries + # it is due are spent # @raise [UnstubbedRequestError] when no stub matches def answer(method, path, operation:, query: nil, body: nil, headers: nil, resource_class: nil, on_behalf_of: nil) relative = ::ZammadAPI::Transport.relative_path(path) @@ -232,15 +260,14 @@ def answer(method, path, operation:, query: nil, body: nil, headers: nil, resour # too, before anything is recorded. What is recorded is the body as the # test wrote it, which is what a test asserts against. ::ZammadAPI::Transport.encode_body(body, operation: operation, resource_class: resource_class) + request = Request.new(verb: method, path: relative, query: params, body: snapshot(body), headers: fields, on_behalf_of: on_behalf_of) - stub = @monitor.synchronize do - @requests << Request.new(verb: method, path: relative, query: params, body: snapshot(body), headers: fields, on_behalf_of: on_behalf_of) - take(method, relative, params) - end + response = attempt(request) + config.retries.times do + break if !::ZammadAPI::Transport.retried?(config, method, response) - raise UnstubbedRequestError, unstubbed_message(method, relative, params) if stub.nil? - - response = response_for(stub, params) + response = attempt(request) + end return response if response.success? raise ResponseError.build(response, operation: operation, resource_class: resource_class) @@ -248,6 +275,22 @@ def answer(method, path, operation:, query: nil, body: nil, headers: nil, resour private + # One delivery of a request: recorded, and answered by the stub whose + # turn it is. + # + # @return [Response] + # @raise [UnstubbedRequestError] when no stub matches + def attempt(request) + stub = @monitor.synchronize do + @requests << request + take(request.verb, request.path, request.query) + end + + raise UnstubbedRequestError, unstubbed_message(request.verb, request.path, request.query) if stub.nil? + + response_for(stub, request.query) + end + def key(method, path) = [method.to_sym, ::ZammadAPI::Transport.relative_path(path)] # The headers a stub answers with, downcased the way a {Response} carries diff --git a/lib/zammad_api/transport.rb b/lib/zammad_api/transport.rb index b93ee26..6a32554 100644 --- a/lib/zammad_api/transport.rb +++ b/lib/zammad_api/transport.rb @@ -738,6 +738,66 @@ def self.encode_body(body, operation:, resource_class: nil) 'attachment, and leave out a Float that is NaN or infinite.' end + # What the retry middleware is built with. + # + # +max_interval+ is what bounds a wait. The retry middleware sleeps for + # whatever a +Retry-After+ header says, and its own ceiling defaults to + # no ceiling at all: a maintenance page answering 503 with + # +Retry-After: 3600+ held the calling thread for an hour per retry, + # whatever +timeout+ and +retry_interval+ said, before raising the error + # it could have raised at once. + # + # +timeout+ is the bound, because it is already how long this client + # was told it may wait for an answer. A +Retry-After+ within it is + # honoured; a longer one is not waited out, and the response it came + # with is reported as the error it is, with the figure still readable + # from {RateLimitError#retry_after}. + # + # Public for {.retried?}, which {Test} asks. + # + # @api private + # @param config [Config] + # @return [Hash{Symbol => Object}] + def self.retry_options(config) + { + max: config.retries, + interval: config.retry_interval, + max_interval: config.timeout, + interval_randomness: 0.5, + backoff_factor: 2, + retry_statuses: RETRIABLE_STATUSES, + methods: RETRIABLE_METHODS, + exceptions: RETRIABLE_EXCEPTIONS + } + end + + # Whether a request answered with +response+ is one the retry middleware + # sends again, while it has attempts left. + # + # Public for {Test}, for the reason {.stringify_query} is: a stand-in + # that raised for the first 503 a +GET+ was answered with, where the + # wire asks again, made a test of code that leans on the retry pass or + # fail the other way round from production. + # + # The wait is asked of the middleware itself, built from the options + # above, and not worked out a second time here. It answers nil where a + # +Retry-After+ - or a +RateLimit-Reset+, or either as a date - asks + # for longer than it may wait, which is the one response with a + # retriable status that it does not send again. A copy of that reading + # is the kind that gets changed in one place. + # + # @api private + # @param config [Config] + # @param method [Symbol] + # @param response [Response] + # @return [Boolean] + def self.retried?(config, method, response) + options = retry_options(config) + return false if !options[:methods].include?(method) || !options[:retry_statuses].include?(response.status) + + !Faraday::Retry::Middleware.new(nil, options).calculate_sleep_amount(1, { response_headers: Faraday::Utils::Headers.new(response.headers) }).nil? + end + # @param config [Config] def initialize(config) @config = config @@ -885,7 +945,7 @@ def build_connection ) do |faraday| apply_authentication(faraday) faraday.request :json - faraday.request :retry, retry_options + faraday.request :retry, Transport.retry_options(config) # Last in the stack, so a caller's middleware sees the request as this # gem finished building it and the response before anything else does. config.middleware&.call(faraday) @@ -1002,31 +1062,6 @@ def apply_authentication(faraday) end end - # +max_interval+ is what bounds a wait. The retry middleware sleeps for - # whatever a +Retry-After+ header says, and its own ceiling defaults to - # no ceiling at all: a maintenance page answering 503 with - # +Retry-After: 3600+ held the calling thread for an hour per retry, - # whatever +timeout+ and +retry_interval+ said, before raising the error - # it could have raised at once. - # - # +timeout+ is the bound, because it is already how long this client - # was told it may wait for an answer. A +Retry-After+ within it is - # honoured; a longer one is not waited out, and the response it came - # with is reported as the error it is, with the figure still readable - # from {RateLimitError#retry_after}. - def retry_options - { - max: config.retries, - interval: config.retry_interval, - max_interval: config.timeout, - interval_randomness: 0.5, - backoff_factor: 2, - retry_statuses: RETRIABLE_STATUSES, - methods: RETRIABLE_METHODS, - exceptions: RETRIABLE_EXCEPTIONS - } - end - def decode(faraday_response) headers = faraday_response.headers.to_h.transform_keys { it.to_s.downcase }.freeze raw_body = raw_body!(faraday_response.body) diff --git a/sig/vendor/faraday.rbs b/sig/vendor/faraday.rbs index 728de63..a811cfb 100644 --- a/sig/vendor/faraday.rbs +++ b/sig/vendor/faraday.rbs @@ -52,6 +52,22 @@ module Faraday def self.decode: (String? query) -> untyped end + # The retry middleware, asked what it would do with a response. See + # ZammadAPI::Transport.retried?. + module Retry + class Middleware + def initialize: (untyped app, ?untyped options) -> void + def calculate_sleep_amount: (Integer retries, untyped env) -> Float? + end + end + + module Utils + # Response headers, read whatever the case of the name. + class Headers + def initialize: (?Hash[untyped, untyped] hash) -> void + end + end + def self.new: (**untyped) ?{ (Connection) -> void } -> Connection def self.default_adapter: () -> Symbol end diff --git a/sig/zammad_api/test.rbs b/sig/zammad_api/test.rbs index e478b6c..9215855 100644 --- a/sig/zammad_api/test.rbs +++ b/sig/zammad_api/test.rbs @@ -51,6 +51,7 @@ module ZammadAPI private + def attempt: (Request request) -> Response def key: (Symbol method, String path) -> [Symbol, String] def raw_body_for: (untyped body) -> String def response_headers: (Hash[untyped, untyped] headers, untyped body) -> Hash[String, String] diff --git a/sig/zammad_api/transport.rbs b/sig/zammad_api/transport.rbs index 5bef0a1..0da883f 100644 --- a/sig/zammad_api/transport.rbs +++ b/sig/zammad_api/transport.rbs @@ -61,6 +61,8 @@ module ZammadAPI def self.refuse_unreadable_path!: (String relative) -> void def self.unreadable_path_message: (String relative) -> String def self.encode_body: (untyped body, operation: String, ?resource_class: Class?) -> String? + def self.retry_options: (Config config) -> Hash[Symbol, untyped] + def self.retried?: (Config config, Symbol method, Response response) -> bool def initialize: (Config) -> void def with_on_behalf_of: ((String | Integer)? identifier) -> Transport @@ -78,7 +80,6 @@ module ZammadAPI def refused_middleware: (Class klass) -> String? def refused_middleware_message: (Class klass, String refused) -> String def apply_authentication: (untyped) -> void - def retry_options: () -> Hash[Symbol, untyped] def decode: (untyped) -> Response def raw_body!: (untyped) -> String def log_request: (Symbol, String, Hash[Symbol, untyped]?, untyped, Hash[String, String]?) -> void diff --git a/spec/unit/zammad_api/test_spec.rb b/spec/unit/zammad_api/test_spec.rb index 9d639e8..1a63c3b 100644 --- a/spec/unit/zammad_api/test_spec.rb +++ b/spec/unit/zammad_api/test_spec.rb @@ -663,6 +663,155 @@ # first of those, so the obvious way to stand in for a list endpoint made # every full read of it raise PaginationError - against a real Zammad the # same code works, because page 2 comes back empty. + # The real transport sends a GET again that was answered 429 or 5xx. The + # stand-in raised for the first such answer, so a test of code that leans + # on the retry passed or failed the other way round from production. + describe 'a read the client retries' do + def find = client.groups.find(1) + + context 'when it fails once and is then answered' do + before do + zammad.stub(:get, 'api/v1/groups/1', status: 503, body: { error: 'down' }) + zammad.stub(:get, 'api/v1/groups/1', body: { id: 1, name: 'Users' }) + end + + it 'answers with the record, as the wire does' do + expect(find.name).to eq('Users') + end + + it 'records both attempts' do + find + expect(zammad.requests.map(&:path)).to eq(%w[api/v1/groups/1 api/v1/groups/1]) + end + + it 'records the second attempt as the request the first was' do + find + expect(zammad.requests.last).to eq(zammad.requests.first) + end + end + + [429, 500, 502, 503, 504].each do |status| + it "asks again past a #{status}" do + zammad.stub(:get, 'api/v1/groups/1', status: status) + zammad.stub(:get, 'api/v1/groups/1', body: { id: 1 }) + + expect(find.id).to eq(1) + end + end + + context 'when it keeps failing' do + before { zammad.stub(:get, 'api/v1/groups/1', status: 503, body: { error: 'down' }) } + + it 'raises the error for the status once the retries are spent' do + expect { find }.to raise_error(ZammadAPI::ServerError, /down/) + end + + it 'records as many requests as the wire would carry' do + expect { find }.to raise_error(ZammadAPI::ServerError) + expect(zammad.requests.size).to eq(1 + zammad.config.retries) + end + end + + it 'follows the number of retries it was built with' do + zammad = described_class.new(retries: 4) + zammad.stub(:get, 'api/v1/groups/1', status: 500) + + expect { zammad.client.groups.find(1) }.to raise_error(ZammadAPI::ServerError) + expect(zammad.requests.size).to eq(5) + end + + it 'raises for the first failure where it was built without retries' do + zammad = described_class.new(retries: 0) + zammad.stub(:get, 'api/v1/groups/1', status: 503) + zammad.stub(:get, 'api/v1/groups/1', body: { id: 1 }) + + expect { zammad.client.groups.find(1) }.to raise_error(ZammadAPI::ServerError) + expect(zammad.requests.size).to eq(1) + end + + it 'does not ask again past a status the client does not retry' do + zammad.stub(:get, 'api/v1/groups/1', status: 404) + zammad.stub(:get, 'api/v1/groups/1', body: { id: 1 }) + + expect { find }.to raise_error(ZammadAPI::NotFoundError) + expect(zammad.requests.size).to eq(1) + end + + # A write is never repeated on the wire, so it is not repeated here. + it 'does not repeat a POST' do + zammad.stub(:post, 'api/v1/groups', status: 503) + zammad.stub(:post, 'api/v1/groups', status: 201, body: { id: 1 }) + + expect { client.groups.create(name: 'Users') }.to raise_error(ZammadAPI::ServerError) + expect(zammad.requests.size).to eq(1) + end + + it 'does not repeat a PUT' do + zammad.stub(:put, 'api/v1/groups/1', status: 504) + + expect { client.put('api/v1/groups/1', body: { name: 'Users' }) }.to raise_error(ZammadAPI::ServerError) + expect(zammad.requests.size).to eq(1) + end + + it 'does not repeat a DELETE' do + zammad.stub(:delete, 'api/v1/groups/1', status: 500) + + expect { client.groups.destroy(1) }.to raise_error(ZammadAPI::ServerError) + expect(zammad.requests.size).to eq(1) + end + + # The wire does not wait out a Retry-After longer than the timeout: it + # reports the response at once. + context 'when the answer asks for a longer wait than the timeout' do + before do + zammad.stub(:get, 'api/v1/groups/1', status: 429, headers: { 'Retry-After' => '3600' }) + zammad.stub(:get, 'api/v1/groups/1', body: { id: 1 }) + end + + it 'does not ask again' do + expect { find }.to raise_error(ZammadAPI::RateLimitError) + expect(zammad.requests.size).to eq(1) + end + + it 'leaves the wait readable from the error' do + expect { find }.to raise_error(ZammadAPI::RateLimitError) { |error| expect(error.retry_after).to eq(3600) } + end + end + + context 'when the answer asks for a wait within the timeout' do + before do + zammad.stub(:get, 'api/v1/groups/1', status: 429, headers: { 'Retry-After' => '30' }) + zammad.stub(:get, 'api/v1/groups/1', body: { id: 1 }) + end + + it 'asks again' do + expect(find.id).to eq(1) + end + + it 'does not wait first' do + started = Process.clock_gettime(Process::CLOCK_MONOTONIC) + find + + expect(Process.clock_gettime(Process::CLOCK_MONOTONIC) - started).to be < 5 + end + end + + it 'asks again for a page of a list, and reads the list from the stub after' do + zammad.stub(:get, 'api/v1/groups', status: 502) + zammad.stub(:get, 'api/v1/groups', body: [{ id: 1, name: 'A' }]) + + expect(client.groups.map(&:name)).to eq(['A']) + end + + it 'carries the scope of a client acting for another user on every attempt' do + zammad.stub(:get, 'api/v1/groups/1', status: 503) + zammad.stub(:get, 'api/v1/groups/1', body: { id: 1 }) + client.on_behalf_of('agent@example.com').groups.find(1) + + expect(zammad.requests.map(&:on_behalf_of)).to eq(%w[agent@example.com agent@example.com]) + end + end + describe 'a list endpoint stubbed once' do subject(:zammad) { described_class.new } diff --git a/spec/unit/zammad_api/transport_spec.rb b/spec/unit/zammad_api/transport_spec.rb index 312d11e..8a66a29 100644 --- a/spec/unit/zammad_api/transport_spec.rb +++ b/spec/unit/zammad_api/transport_spec.rb @@ -318,6 +318,62 @@ end end + # The question the test kit asks, so that it sends again what the wire + # sends again. + describe '.retried?' do + let(:config) { ZammadAPI::Config.new(**unit_config(retries: 2, timeout: 60)) } + + def response(status, headers = {}) + ZammadAPI::Response.new(status: status, headers: headers, body: nil, raw_body: '', json: false) + end + + described_class::RETRIABLE_STATUSES.each do |status| + it "is true for a GET answered #{status}" do + expect(described_class.retried?(config, :get, response(status))).to be(true) + end + end + + [200, 404, 422].each do |status| + it "is false for a GET answered #{status}" do + expect(described_class.retried?(config, :get, response(status))).to be(false) + end + end + + %i[post put delete].each do |verb| + it "is false for a #{verb.to_s.upcase}, which is never sent twice" do + expect(described_class.retried?(config, verb, response(503))).to be(false) + end + end + + it 'is false where Retry-After asks for longer than the timeout' do + expect(described_class.retried?(config, :get, response(429, 'retry-after' => '61'))).to be(false) + end + + it 'is true where Retry-After asks for no longer than the timeout' do + expect(described_class.retried?(config, :get, response(429, 'retry-after' => '60'))).to be(true) + end + + it 'reads a Retry-After that is a date' do + expect(described_class.retried?(config, :get, response(503, 'retry-after' => (Time.now + 3600).utc.strftime('%a, %d %b %Y %H:%M:%S GMT')))).to be(false) + end + + it 'reads a RateLimit-Reset the same way' do + expect(described_class.retried?(config, :get, response(429, 'ratelimit-reset' => '3600'))).to be(false) + end + + # What makes this the transport's own answer and not a second reading of + # the same rules: a stack that was answered this way made one request. + it 'agrees with what a request does' do + stub_request(:get, url).to_return({ status: 429, headers: { 'Retry-After' => '3600' } }, json_response([])) + transport = unit_transport(retries: 2, retry_interval: 0.01, timeout: 2) + + expect { transport.get('api/v1/groups', operation: 'test') }.to raise_error(ZammadAPI::RateLimitError) do |error| + expect(described_class.retried?(transport.config, :get, error.response)).to be(false) + end + expect(a_request(:get, url)).to have_been_made.once + end + end + describe '.redact' do it 'blanks the value under a key that names a credential' do expect(described_class.redact({ login: 'x', password: 'hunter2' })).to eq({ login: 'x', password: '[REDACTED]' }) From 6a0909d5611f29ac16a195b9c96f55e82fbc56c9 Mon Sep 17 00:00:00 2001 From: Mantas Date: Thu, 19 Nov 2026 00:29:48 +0200 Subject: [PATCH 10/11] fix: read an index that does not page in one request A walk learns the page size from the first page and asks for the next while pages come back that full. An index that serves every record in one response and reads no `page`, as `api/v1/object_manager_attributes` does, answers that with the same list, and the guard against an endpoint that ignores `page` raised PaginationError for it. A resource declared for such an endpoint could not be read: `to_a` raised with every record in hand, and a `find_by` that missed raised instead of answering nil, which broke `find_by(...) || create(...)`. The two responses look the same from an endpoint that serves only the first of many pages, so this is declared and not inferred. A resource says `paginated false`, and its index is read in one request that names no page. `in_batches(of:)` slices that response and `page` refuses such a collection. A search still pages, and whether the index sorts is still what `sortable` says. PaginationError says what to declare where an index repeated its first page. --- CHANGELOG.md | 11 ++ README.md | 23 +++ lib/zammad_api/collection.rb | 64 +++++++- lib/zammad_api/errors.rb | 17 ++- lib/zammad_api/resource_proxy.rb | 5 +- lib/zammad_api/resources/base.rb | 44 ++++++ sig/zammad_api/collection.rbs | 5 +- sig/zammad_api/errors.rbs | 4 +- sig/zammad_api/resource_proxy.rbs | 2 +- sig/zammad_api/resources/base.rbs | 3 + spec/unit/zammad_api/collection_spec.rb | 155 ++++++++++++++++++++ spec/unit/zammad_api/resource_proxy_spec.rb | 56 +++++++ spec/unit/zammad_api/resources/base_spec.rb | 27 ++++ spec/unit/zammad_api/test_spec.rb | 22 +++ 14 files changed, 425 insertions(+), 13 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d91a2f9..7a4bf58 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -822,6 +822,17 @@ asked for, with `gem install zammad_api --pre` or `gem 'zammad_api', '~> 2.0.0.a transport's own rule, so a write is not repeated and a `Retry-After` longer than `timeout` ends the attempts. `ZammadAPI::Test.new(retries: 0)` raises for the first failure, as before. +- A resource can declare that its index endpoint does not page, with `paginated false`, + and is then read in one request. A walk asks for the page after a full one, and an + endpoint that serves every record in one response and reads no `page` — + `api/v1/object_manager_attributes` is one — answers that with the same list. The guard + against an endpoint that ignores `page` raised `PaginationError` for it, so a resource + declared for such an endpoint could not be read at all: `to_a` raised with every record + in hand, and a `find_by` that missed raised instead of answering `nil`, which broke + `find_by(...) || create(...)`. Nothing in the responses tells such an endpoint from one + that serves only its first page, so it is declared rather than inferred, and the error + for an index that repeats its first page now says what to declare. `page` refuses a + resource declared this way. Whether its index sorts is still what `sortable` says. ### Changed diff --git a/README.md b/README.md index 10296b9..8335cbe 100644 --- a/README.md +++ b/README.md @@ -299,6 +299,7 @@ Say what else is true of the endpoint, where it differs from the defaults: | `search_filters :role_ids` | none | What that search narrows by besides the term, `condition:` and `ids:`. `search` refuses any other keyword. | | `max_per_page 100` | `1000` | The largest page the index endpoint serves. | | `sortable false` | `true` | The index endpoint is always served in the same order, so `order` refuses it. | +| `paginated false` | `true` | The index endpoint serves every record in one response and reads no `page`. It is read in one request, and `page` refuses it. | | `belongs_to :role, class_name: 'Role'` | — | A foreign key, read as a record through `record.related.role`. | | `has_many :members, class_name: 'User', path: ->(id) { "…/#{id}" }` | — | A list served whole by an endpoint of its own. | @@ -306,6 +307,28 @@ Say what else is true of the endpoint, where it differs from the defaults: full name, `'Acme::Role'`. A subclass of a modelled resource works too, and inherits what its parent declares: `class MyTicket < ZammadAPI::Resources::Ticket`. +Most of Zammad's index endpoints page, and a collection walks them a page at a time. One +that does not — `api/v1/object_manager_attributes` serves every attribute in one response, +whatever it is asked — answers the request for a second page with the first again, which +a walk reports as `ZammadAPI::PaginationError` rather than read as the end. Declare such a +resource `paginated false`: + +```ruby +class ObjectAttribute < ZammadAPI::Resources::Base + path 'api/v1/object_manager_attributes' + paginated false + sortable false +end + +client.resource(ObjectAttribute).find_by(name: 'priority_id') # one request +``` + +Declare it only where the endpoint does serve every record. One that ignores `page` and +caps what it serves would be read as far as its cap, with nothing to say that there is +more. Whether the endpoint sorts is a declaration of its own: this one reads no parameter +at all, so it says `sortable false` as well. A search always pages, whatever the index +beside it does. + Use raw requests for an endpoint that is not shaped like that — an action, a report, a setting. diff --git a/lib/zammad_api/collection.rb b/lib/zammad_api/collection.rb index 262b531..caff818 100644 --- a/lib/zammad_api/collection.rb +++ b/lib/zammad_api/collection.rb @@ -15,6 +15,10 @@ module ZammadAPI # +Enumerable+ stop the walk as soon as they have enough, so neither has to # download everything. # + # An index that serves every record in one response and reads no +page+ is + # read in one request instead, where its resource says so: see + # {Resources::Base.paginated}. + # # @example Iterate every ticket # client.tickets.all.each { |ticket| puts ticket.title } # @@ -57,7 +61,10 @@ class Collection # +per_page+ once one has come back with nothing on it, which a read # sized by {#first} may and a batch size a caller chose may not: see # {#widened} - def initialize(transport:, resource_class:, path:, operation:, max_per_page:, sortable:, unsortable_hint:, query: {}, per_page: nil, page: nil, search: false, widens: false) + # @param paginated [Boolean] whether this endpoint reads +page+ and + # +per_page+. One that does not serves every record in one response, + # and is read in one request: see {#read_whole} + def initialize(transport:, resource_class:, path:, operation:, max_per_page:, sortable:, unsortable_hint:, query: {}, per_page: nil, page: nil, search: false, widens: false, paginated: true) @transport = transport @resource_class = resource_class @path = path @@ -84,6 +91,7 @@ def initialize(transport:, resource_class:, path:, operation:, max_per_page:, so @page = page @search = search @widens = widens + @paginated = paginated end # Yields every record, fetching further pages as needed. @@ -115,6 +123,9 @@ def find_each(batch_size: nil, &block) # so +of+ is what sizes it. For groups of a size the API knows nothing # about, slice the records instead: +find_each.each_slice(12)+. # + # An index that is not paginated has one response for every record, so + # there a batch is a slice of it, of the same size at most. + # # @param of [Integer, nil] records fetched per request # @yieldparam records [Array] # @return [Enumerator] when no block is given @@ -122,7 +133,7 @@ def in_batches(of: nil, &block) return to_enum(:in_batches, of: of) if !block return with(per_page: page_size!(of, 'of')).in_batches(&block) if of - walk(&block) + @paginated ? walk(&block) : read_whole(&block) self end @@ -143,9 +154,11 @@ def in_batches(of: nil, &block) # @param per_page [Integer, nil] records on the page, as many as the endpoint # serves by default # @return [Collection] - # @raise [ArgumentError] for a page size the endpoint does not serve + # @raise [ArgumentError] for a page size the endpoint does not serve, or + # an endpoint that does not page at all def page(number, per_page: nil) raise ArgumentError, 'page needs to be a positive integer' if !number.is_a?(Integer) || !number.positive? + raise ArgumentError, "#{@path} serves every record in one response and reads no page parameter, so page(#{number}) would hold all of them, whatever the number. Read them with each, or in groups with each_slice." if !@paginated return with(page: number) if per_page.nil? size = positive_integer!(per_page, 'per_page') @@ -362,7 +375,7 @@ def count(*args, &block) def empty? = first.nil? def inspect - "#<#{self.class.name} #{@resource_class.name} path=#{@path.inspect} per_page=#{@per_page}#{" page=#{@page}" if @page}>" + "#<#{self.class.name} #{@resource_class.name} path=#{@path.inspect} per_page=#{@per_page}#{" page=#{@page}" if @page}#{' paginated=false' if !@paginated}>" end private @@ -387,8 +400,11 @@ def each_distinct # endpoint serves - {#clamp_per_page} would reduce it to the same size the # collection already has. A zero or negative count is left to # Enumerable#first, which has its own answers for both. + # + # And not where the endpoint does not page: it serves every record + # whatever it is asked for, so there is no request to size. def own_request_for_first?(count) - return false if @page + return false if @page || !@paginated count.is_a?(Integer) && count.positive? && count <= @max_per_page end @@ -472,6 +488,34 @@ def page_size!(value, name) size end + # The one read of an index that does not page: every record it serves, + # from one request that names no page. + # + # Walked like the others, such an index never got past its first page. + # A walk learns the page size from the first page and asks for the next + # while pages come back that full, so a whole list was always followed + # by a request for page two - and an endpoint that reads no +page+ + # answers that with the same list. The repeated-page guard is there for + # exactly that answer, so `to_a` raised PaginationError with every + # record in hand, and a `find_by` that found nothing on the first page + # raised it instead of answering nil. + # + # Nothing in the two responses tells such an endpoint from one that + # ignores +page+ and serves the first hundred of a thousand records. + # Reading that one in a single request would return a truncated list and + # call it whole, which is what the guard exists to refuse. So this is + # not inferred from a page that repeats: the resource says it, with + # {Resources::Base.paginated}, and the guard stays as it is for every + # resource that does not. + # + # The batches are slices of the one response, so that `in_batches(of: + # 50)` hands a block fifty records at most here as everywhere else. + def read_whole(&block) + records, = fetch(1, @per_page) + + records.each_slice(@per_page, &block) + end + def walk page = @page || 1 previous = nil @@ -522,7 +566,7 @@ def walk # are what a search serves for two pages of hits whose records are # gone, with more beyond them - see #hits_past? - and there is nothing # on either for the block to be handed twice. - raise PaginationError.build(operation: @operation, page: page, resource_class: @resource_class) if received.positive? && digest == previous + raise PaginationError.build(operation: @operation, page: page, resource_class: @resource_class, index: !@search) if received.positive? && digest == previous yield records if received.positive? @@ -663,7 +707,8 @@ def with(page: @page, per_page: @per_page, query: @query, widens: false) per_page: per_page, page: page, search: @search, - widens: widens + widens: widens, + paginated: @paginated ) end @@ -738,7 +783,12 @@ def fetch(page, per_page) # It costs Zammad nothing it was not doing. model_search_render asks the # search for the total on every request and leaves it out of the answer # unless the parameter is there. + # + # An endpoint that does not page is sent neither parameter. It would + # drop both, and a request that names a page reads as one of several. def page_query(page, per_page) + return @query if !@paginated + query = @query.merge(page: page, per_page: per_page) @search && @page.nil? ? query.merge(with_total_count: true) : query diff --git a/lib/zammad_api/errors.rb b/lib/zammad_api/errors.rb index c5bd351..6ea7ce0 100644 --- a/lib/zammad_api/errors.rb +++ b/lib/zammad_api/errors.rb @@ -51,12 +51,25 @@ def self.build(operation:, expected:, actual:, resource_class: nil) # Raised when the server answers a page request with the page before it, # which means it is ignoring +page+ and a collection walk would never end. class PaginationError < Error + # What to do about an index that repeats its first page, which is what + # one that serves every record in a single response does. Said as a + # condition, because the same two pages come from an endpoint that + # serves only the first of many and ignores +page+, and that one is not + # to be read as whole. + UNPAGINATED_ADVICE = 'If this endpoint serves every record in one response, declare `paginated false` on the resource, ' \ + 'and it is read in one request.' + # @param operation [String] # @param page [Integer] the page that repeated its predecessor # @param resource_class [Class, nil] + # @param index [Boolean] whether an index endpoint was being walked, + # which is the kind a resource may declare as not paginated. A search + # always pages. # @return [PaginationError] - def self.build(operation:, page:, resource_class: nil) - new("Can't #{subject_for(operation, resource_class)}: page #{page} repeated page #{page - 1}, so the endpoint is ignoring the page parameter") + def self.build(operation:, page:, resource_class: nil, index: false) + message = "Can't #{subject_for(operation, resource_class)}: page #{page} repeated page #{page - 1}, so the endpoint is ignoring the page parameter" + + new(index && page == 2 ? "#{message}. #{UNPAGINATED_ADVICE}" : message) end end diff --git a/lib/zammad_api/resource_proxy.rb b/lib/zammad_api/resource_proxy.rb index a830b1c..141e73d 100644 --- a/lib/zammad_api/resource_proxy.rb +++ b/lib/zammad_api/resource_proxy.rb @@ -487,6 +487,8 @@ def search(term, **filters) query: DeepCopy.frozen_copy({ query: term }.merge(search_filters(filters))), max_per_page: SEARCH_MAX_PER_PAGE, sortable: true, + # Every search endpoint pages, whatever the index beside it does. + paginated: true, search: true ) end @@ -495,7 +497,7 @@ def inspect = "#<#{self.class.name} #{resource_class.name}>" private - def collection(path, operation, query: {}, max_per_page: resource_class.page_limit, sortable: resource_class.sortable?, search: false) + def collection(path, operation, query: {}, max_per_page: resource_class.page_limit, sortable: resource_class.sortable?, paginated: resource_class.paginated?, search: false) Collection.new( transport: @transport, resource_class: resource_class, @@ -505,6 +507,7 @@ def collection(path, operation, query: {}, max_per_page: resource_class.page_lim sortable: sortable, unsortable_hint: resource_class.searchable? ? SEARCHABLE_UNSORTABLE_HINT : UNSORTABLE_HINT, search: search, + paginated: paginated, query: { expand: true }.merge(query) ) end diff --git a/lib/zammad_api/resources/base.rb b/lib/zammad_api/resources/base.rb index c4fc271..a06f5be 100644 --- a/lib/zammad_api/resources/base.rb +++ b/lib/zammad_api/resources/base.rb @@ -127,6 +127,46 @@ def sortable(value) @sortable = value end + # Declares whether this resource's index endpoint pages. + # + # ApplicationController#model_index_render reads +page+ and + # +per_page+, and every resource this gem models is served by it. + # That is the default, so a resource says nothing. Not every index + # is: ObjectManagerAttributesController#index renders + # `ObjectManager::Attribute.list_full`, every attribute in one + # response, and reads no parameter at all. + # + # Such an index could not be read. A {Collection} asks for the page + # after a full one, was answered with the same list again, and + # raised {PaginationError} for it - correctly, as far as it could + # tell, because an endpoint that ignores +page+ and serves only the + # first of many pages looks the same. A resource that declares + # +paginated false+ says which of the two it is: its index is read + # in one request, and {Collection#page} refuses it. + # + # Declare it only for an endpoint that does serve every record. One + # that caps what it serves and ignores +page+ would be read as far + # as its cap and no further, with nothing to say so. + # + # A search is not affected. Every search endpoint pages. + # + # Whether the index sorts is not affected either: that is + # {.sortable}, a declaration of its own. An endpoint that reads no + # parameter at all, as the one below, says both. + # + # @example + # class ObjectAttribute < ZammadAPI::Resources::Base + # path 'api/v1/object_manager_attributes' + # paginated false + # sortable false + # end + # + # @param value [Boolean] + # @return [void] + def paginated(value) + @paginated = value + end + # @return [String] the API path of this resource def resource_path declaration(:path) || raise(Error, "#{name} does not declare an API path") @@ -150,6 +190,10 @@ def page_limit = declaration(:max_per_page) { DEFAULT_MAX_PER_PAGE } # +sort_by+ and +order_by+ def sortable? = declaration(:sortable) { true } + # @return [Boolean] whether this resource's index endpoint reads + # +page+ and +per_page+ + def paginated? = declaration(:paginated) { true } + # The API path of one record of this kind. # # The id is escaped rather than interpolated, so that one taken from a diff --git a/sig/zammad_api/collection.rbs b/sig/zammad_api/collection.rbs index 7909465..7830bbe 100644 --- a/sig/zammad_api/collection.rbs +++ b/sig/zammad_api/collection.rbs @@ -21,6 +21,7 @@ module ZammadAPI @page: Integer? @search: bool @widens: bool + @paginated: bool def initialize: ( transport: Transport, @@ -34,7 +35,8 @@ module ZammadAPI ?per_page: Integer?, ?page: Integer?, ?search: bool, - ?widens: bool + ?widens: bool, + ?paginated: bool ) -> void def each: () { (R) -> void } -> Collection[R] @@ -69,6 +71,7 @@ module ZammadAPI def positive_integer!: (untyped, String) -> Integer def page_size!: (untyped, String) -> Integer def walk: () { (Array[R]) -> void } -> void + def read_whole: () { (Array[R]) -> void } -> void def page_after: (Integer page, Integer per_page, Integer received, Integer? total) -> [ Integer, Integer ] def widened: (Integer covered, Integer? total) -> [ Integer, Integer ] def each_distinct: () { (Resources::Base) -> void } -> void diff --git a/sig/zammad_api/errors.rbs b/sig/zammad_api/errors.rbs index 2b255eb..9760b35 100644 --- a/sig/zammad_api/errors.rbs +++ b/sig/zammad_api/errors.rbs @@ -23,7 +23,9 @@ module ZammadAPI end class PaginationError < Error - def self.build: (operation: String, page: Integer, ?resource_class: Class?) -> PaginationError + UNPAGINATED_ADVICE: String + + def self.build: (operation: String, page: Integer, ?resource_class: Class?, ?index: bool) -> PaginationError end class ResponseError < Error diff --git a/sig/zammad_api/resource_proxy.rbs b/sig/zammad_api/resource_proxy.rbs index d166f80..208dd3c 100644 --- a/sig/zammad_api/resource_proxy.rbs +++ b/sig/zammad_api/resource_proxy.rbs @@ -46,7 +46,7 @@ module ZammadAPI private - def collection: (String, String, ?query: Hash[Symbol, untyped], ?max_per_page: Integer, ?sortable: bool, ?search: bool) -> Collection[R] + def collection: (String, String, ?query: Hash[Symbol, untyped], ?max_per_page: Integer, ?sortable: bool, ?paginated: bool, ?search: bool) -> Collection[R] def search_filters: (Hash[untyped, untyped] filters) -> Hash[Symbol, untyped] def search_filter_keys: () -> Array[Symbol] def unknown_search_filter_message: (Array[Symbol] unknown) -> String diff --git a/sig/zammad_api/resources/base.rbs b/sig/zammad_api/resources/base.rbs index 1e7bf7b..877689a 100644 --- a/sig/zammad_api/resources/base.rbs +++ b/sig/zammad_api/resources/base.rbs @@ -36,17 +36,20 @@ module ZammadAPI self.@max_per_page: Integer? self.@search_filters: Array[Symbol]? self.@sortable: bool? + self.@paginated: bool? def self.path: (String) -> void def self.searchable: (bool) -> void def self.max_per_page: (Integer) -> void def self.search_filters: (*Symbol | String names) -> void def self.sortable: (bool) -> void + def self.paginated: (bool) -> void def self.resource_path: () -> String def self.searchable?: () -> bool def self.search_filter_names: () -> Array[Symbol] def self.page_limit: () -> Integer def self.sortable?: () -> bool + def self.paginated?: () -> bool def self.member_path: ((Integer | String) id) -> String def self.fetch_one: (Transport transport, (Integer | String) id) -> Base def self.from_response: (Transport, Hash[untyped, untyped] attributes) -> Base diff --git a/spec/unit/zammad_api/collection_spec.rb b/spec/unit/zammad_api/collection_spec.rb index 9124d10..f491e21 100644 --- a/spec/unit/zammad_api/collection_spec.rb +++ b/spec/unit/zammad_api/collection_spec.rb @@ -951,6 +951,154 @@ def sorted_request(sort_by, order_by) end end + # ObjectManagerAttributesController#index renders every attribute in one + # response and reads no parameter. Walked like a paged index, it was asked + # for page two, answered with the same list, and the guard against an + # endpoint that ignores `page` raised with every record already in hand. + describe 'an index that serves every record in one response' do + subject(:collection) { client.resource(resource).all } + + let(:resource) do + Class.new(ZammadAPI::Resources::Base) do + def self.name = 'ObjectAttribute' + + path 'api/v1/object_manager_attributes' + paginated false + end + end + let(:url) { "#{ClientHelper::BASE_URL}api/v1/object_manager_attributes" } + let(:records) { [{ id: 1, name: 'c' }, { id: 2, name: 'a' }, { id: 3, name: 'b' }] } + + # The same list whatever it is asked, which is what such an endpoint does. + before { stub_request(:get, url).with(query: hash_including({})).to_return(json_response(records)) } + + it 'reads every record' do + expect(collection.map(&:id)).to eq([1, 2, 3]) + end + + it 'spends one request on it' do + collection.to_a + expect(a_request(:get, url).with(query: hash_including({}))).to have_been_made.once + end + + it 'names no page in that request' do + collection.to_a + expect(a_request(:get, url).with(query: { 'expand' => 'true' })).to have_been_made.once + end + + context 'without the declaration' do + let(:resource) do + Class.new(ZammadAPI::Resources::Base) do + def self.name = 'ObjectAttribute' + + path 'api/v1/object_manager_attributes' + end + end + + it 'raises PaginationError, as for any endpoint that repeats a page' do + expect { collection.to_a }.to raise_error(ZammadAPI::PaginationError, /page 2 repeated page 1/) + end + + it 'says what to declare where the endpoint does serve every record' do + expect { collection.to_a }.to raise_error(ZammadAPI::PaginationError, /declare `paginated false` on the resource/) + end + end + + it 'hands the list over as one batch' do + expect(collection.in_batches.map { |batch| batch.map(&:id) }).to eq([[1, 2, 3]]) + end + + it 'slices the list where a batch size is asked for' do + expect(collection.in_batches(of: 2).map { |batch| batch.map(&:id) }).to eq([[1, 2], [3]]) + end + + it 'still spends one request where a batch size is asked for' do + collection.find_each(batch_size: 1).to_a + expect(a_request(:get, url).with(query: { 'expand' => 'true' })).to have_been_made.once + end + + it 'yields no batch for a list with nothing on it' do + stub_request(:get, url).with(query: hash_including({})).to_return(json_response([])) + + expect(collection.in_batches.to_a).to eq([]) + end + + it 'reads the first record off the one response' do + expect(collection.first.id).to eq(1) + expect(a_request(:get, url).with(query: { 'expand' => 'true' })).to have_been_made.once + end + + it 'reads the first few' do + expect(collection.first(2).map(&:id)).to eq([1, 2]) + end + + it 'counts the records' do + expect(collection.count).to eq(3) + end + + it 'says whether there are any' do + expect(collection).not_to be_empty + end + + it 'finds a record by what it carries' do + expect(collection.detect { it.name == 'b' }.id).to eq(3) + end + + # Every number would name the same records. + it 'refuses a page' do + expect { collection.page(2) }.to raise_error(ArgumentError, /serves every record in one response and reads no page parameter/) + end + + it 'still refuses a page that is not a number first' do + expect { collection.page(0) }.to raise_error(ArgumentError, /positive integer/) + end + + # Whether an index sorts is a declaration of its own, and sorts unless + # the resource says otherwise, as it does for an index that pages. + it 'sends a sort, and still no page' do + collection.order(:name).to_a + + expect(a_request(:get, url).with(query: { 'expand' => 'true', 'sort_by' => 'name', 'order_by' => 'asc' })).to have_been_made.once + end + + context 'when the resource says the endpoint does not sort either' do + let(:resource) do + Class.new(ZammadAPI::Resources::Base) do + def self.name = 'ObjectAttribute' + + path 'api/v1/object_manager_attributes' + paginated false + sortable false + end + end + + it 'refuses a sort, which such an endpoint drops' do + expect { collection.order(:name) }.to raise_error(ArgumentError, /ignores sort_by/) + end + end + + it 'says so in inspect' do + expect(collection.inspect).to end_with('paginated=false>') + end + end + + describe ZammadAPI::PaginationError do + def message(**) = described_class.build(operation: 'get .all of object', **).message + + it 'says what to declare for an index that repeats its first page' do + expect(message(page: 2, index: true)).to include('declare `paginated false` on the resource') + end + + # An endpoint that served two different pages reads `page`. + it 'does not say so for a page further on' do + expect(message(page: 3, index: true)).not_to include('paginated false') + end + + it 'does not say so for a search, which always pages' do + expect(message(page: 2)).not_to include('paginated false') + end + end + # A walk stops on what the endpoint served, and the size it serves is # learned from the first page rather than taken from `max_per_page`. Where # the server's cap is lower than the request - a cap the gem's declaration @@ -1010,6 +1158,13 @@ def hits(range) = range.map { { id: it } } expect { search.to_a }.to raise_error(ZammadAPI::PaginationError, /ignoring the page parameter/) end + # `paginated false` is a declaration about an index. Every search pages. + it 'does not suggest declaring the resource as not paginated' do + stub_request(:get, search_url).with(query: hash_including({})).to_return(json_response(hits(1..3))) + + expect { search.to_a }.to raise_error(ZammadAPI::PaginationError) { |error| expect(error.message).not_to include('paginated false') } + end + it 'still reads only the one page a search was limited to' do stub_search_page(2, hits(1..3)) diff --git a/spec/unit/zammad_api/resource_proxy_spec.rb b/spec/unit/zammad_api/resource_proxy_spec.rb index b824bce..c3300ec 100644 --- a/spec/unit/zammad_api/resource_proxy_spec.rb +++ b/spec/unit/zammad_api/resource_proxy_spec.rb @@ -442,6 +442,62 @@ def stub_page(number, records) end end + # An index that serves its whole list and reads no page was walked into the + # guard against an endpoint that ignores `page`, so a lookup that missed on + # the first page raised instead of answering nil. + describe 'a resource whose index does not page' do + subject(:proxy) { client.resource(resource) } + + let(:resource) do + Class.new(ZammadAPI::Resources::Base) do + def self.name = 'ObjectAttribute' + + path 'api/v1/object_manager_attributes' + paginated false + end + end + let(:url) { "#{ClientHelper::BASE_URL}api/v1/object_manager_attributes" } + + before do + stub_request(:get, url).with(query: hash_including({})).to_return(json_response([{ id: 1, name: 'a' }, { id: 2, name: 'b' }])) + end + + it 'finds a record by an attribute' do + expect(proxy.find_by(name: 'b').id).to eq(2) + end + + it 'answers nil for a lookup that matches nothing' do + expect(proxy.find_by(name: 'missing')).to be_nil + end + + it 'spends one request on a miss' do + proxy.find_by(name: 'missing') + expect(a_request(:get, url).with(query: { 'expand' => 'true' })).to have_been_made.once + end + + it 'lets a miss go on to create the record' do + created = stub_request(:post, url).with(query: hash_including({})).to_return(json_response({ id: 3, name: 'missing' }, status: 201)) + + expect((proxy.find_by(name: 'missing') || proxy.create(name: 'missing')).id).to eq(3) + expect(created).to have_been_requested + end + + it 'reads every record straight off the proxy' do + expect(proxy.map(&:name)).to eq(%w[a b]) + end + + # The declaration is about the index. A search endpoint always pages. + it 'still pages a search' do + resource.searchable true + search = stub_request(:get, "#{url}/search") + .with(query: hash_including('page' => '1', 'per_page' => described_class::SEARCH_MAX_PER_PAGE.to_s)) + .to_return(json_response({ records: [], total_count: 0 })) + + proxy.search('a').to_a + expect(search).to have_been_requested + end + end + describe '#exists?' do it 'is true when the record is there' do stub_request(:get, "#{url}/1").with(query: hash_including({})).to_return(json_response({ id: 1 })) diff --git a/spec/unit/zammad_api/resources/base_spec.rb b/spec/unit/zammad_api/resources/base_spec.rb index 5ebd858..2de2afe 100644 --- a/spec/unit/zammad_api/resources/base_spec.rb +++ b/spec/unit/zammad_api/resources/base_spec.rb @@ -1001,6 +1001,12 @@ def self.name expect(subclass.sortable?).to be(false) end + it 'inherits whether the index endpoint pages' do + unpaged = Class.new(described_class) { paginated false } + + expect(Class.new(unpaged).paginated?).to be(false) + end + it 'inherits the associations, as it always did' do expect(subclass.associations.keys).to eq(ZammadAPI::Resources::Ticket.associations.keys) end @@ -1043,6 +1049,27 @@ def self.name expect(Class.new(described_class).sortable?).to be(true) end + it 'defaults to an index endpoint that pages, as the generic ones do' do + expect(Class.new(described_class).paginated?).to be(true) + end + + it 'records a declaration that the index endpoint does not page' do + expect(Class.new(described_class) { paginated false }.paginated?).to be(false) + end + + # Two declarations, and neither reads the other. + it 'leaves whether the index endpoint sorts to its own declaration' do + expect(Class.new(described_class) { paginated false }.sortable?).to be(true) + end + + it 'leaves whether the index endpoint pages to its own declaration' do + expect(Class.new(described_class) { sortable false }.paginated?).to be(true) + end + + it 'pages every resource this gem models' do + expect(ZammadAPI::Client::RESOURCES.values).to all(be_paginated) + end + it 'records a declared page limit' do expect(Class.new(described_class) { max_per_page 25 }.page_limit).to eq(25) end diff --git a/spec/unit/zammad_api/test_spec.rb b/spec/unit/zammad_api/test_spec.rb index 1a63c3b..9f020c3 100644 --- a/spec/unit/zammad_api/test_spec.rb +++ b/spec/unit/zammad_api/test_spec.rb @@ -812,6 +812,28 @@ def find = client.groups.find(1) end end + describe 'a list endpoint whose resource says it does not page' do + let(:resource) do + Class.new(ZammadAPI::Resources::Base) do + def self.name = 'ObjectAttribute' + + path 'api/v1/object_manager_attributes' + paginated false + end + end + + before { zammad.stub(:get, 'api/v1/object_manager_attributes', body: [{ id: 1, name: 'a' }]) } + + it 'is read from the one stub' do + expect(client.resource(resource).map(&:name)).to eq(['a']) + end + + it 'is recorded as the one request it is, naming no page' do + client.resource(resource).to_a + expect(zammad.requests.map(&:query)).to eq([{ 'expand' => 'true' }]) + end + end + describe 'a list endpoint stubbed once' do subject(:zammad) { described_class.new } From b6a68f79829e7afc48da008ae26997130ef38773 Mon Sep 17 00:00:00 2001 From: Mantas Date: Thu, 19 Nov 2026 00:38:23 +0200 Subject: [PATCH 11/11] refactor!: remove the names 1.x had for readers and add_article 2.0 kept the singular resource readers and `Ticket#article` as aliases that warned in Ruby's `deprecated` category and were to go in 3.0. 2.0 is a breaking release already, so they go now and it ships without names it would only take away again. `client.ticket` and the other six singular readers raise UnknownResourceError, which lists the plural names, and so does `client.resource(:ticket)`. `DEPRECATED_RESOURCES` and `Client.warn_deprecated_resource` are gone with them. `Ticket#article` is gone, which leaves `article` an attribute reader like any other: `ticket.article(body: '...')` raises NoMethodError on a ticket that has no article staged, and sends nothing. The README and the changelog say the old names raise. The migration guide said most calling code needs no edits, and says now that it needs the one rename. --- CHANGELOG.md | 15 ++-- README.md | 28 +++---- lib/zammad_api/client.rb | 70 +----------------- lib/zammad_api/resources/ticket.rb | 21 ------ sig/zammad_api/client.rbs | 12 --- sig/zammad_api/resources/resources.rbs | 1 - spec/unit/zammad_api/client_spec.rb | 73 +++---------------- spec/unit/zammad_api/resources/ticket_spec.rb | 55 ++++---------- 8 files changed, 49 insertions(+), 226 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7a4bf58..6bc8db6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -107,11 +107,9 @@ asked for, with `gem install zammad_api --pre` or `gem 'zammad_api', '~> 2.0.0.a `client.ticket_priorities` and `client.ticket_states`. A resource is `Enumerable` over every record of its kind, so `client.ticket.each` and `client.ticket.first(5)` read as if they acted on one ticket; the singular dates from 1.x, when a resource was only a - dispatcher for `find` and `create`. The singular names still work, as deprecated aliases - that warn in Ruby's `deprecated` category — silent unless the application asks for - deprecation warnings, with `ruby -W:deprecated` or `Warning[:deprecated] = true` — and - will be removed in 3.0. `client.resource(:ticket)` is answered the same way, and - `client.resource_names` lists the plural names. + dispatcher for `find` and `create`. The singular names are gone: `client.ticket` raises + `UnknownResourceError`, which lists the plural names, and so does + `client.resource(:ticket)`. `client.resource_names` lists the plural names. - The resource readers a client has are a fixed list. 1.x resolved `client.` to `ZammadAPI::Resources::` through `const_get`, so a subclass of `Base` defined in application code could be reached that way. `client.role` now raises @@ -174,10 +172,9 @@ asked for, with `gem install zammad_api --pre` or `gem 'zammad_api', '~> 2.0.0.a credentials an override replaces, so switching schemes through either still works, and an environment that itself sets two schemes is refused until an argument says which is meant. - `ticket.article(…)` is `ticket.add_article(…)`. A noun that sends a `POST` sat one letter - away from `ticket.articles`, which only reads. `article` still works, as a deprecated - alias that warns in Ruby's `deprecated` category the way the singular resource readers do, - and will be removed in 3.0. It requires its attributes, as it did in 1.x, so a bare - `ticket.article` raises `ArgumentError` rather than sending an article with no body. + away from `ticket.articles`, which only reads. The old method is gone, which leaves + `article` an attribute reader like any other: it raises `NoMethodError` on a ticket that + has no article staged, and sends nothing. ### Added diff --git a/README.md b/README.md index 8335cbe..0f84e37 100644 --- a/README.md +++ b/README.md @@ -223,8 +223,8 @@ inherits. The names are plural because what each one hands back stands for every record of its kind: `client.tickets.each` walks them all, and `client.tickets.find(1)` picks one out. The -singular names from 1.x — `client.ticket` and the rest — still work as deprecated aliases; -see [Migrating from 1.x](#the-client). +singular names from 1.x — `client.ticket` and the rest — are gone and raise +`UnknownResourceError`; see [Migrating from 1.x](#the-client). Anything not in that list is reachable by [declaring a resource](#resources-this-gem-does-not-model) for it, or with [raw requests](#raw-requests). @@ -1394,8 +1394,9 @@ test against a specific Zammad ref. ## Migrating from 1.x Version 2.0 fixes long-standing behaviour that could not change without breaking -compatibility. Most calling code needs no edits, and almost everything that does raises -at the call site. Start with the handful of changes that do not. +compatibility. Most calling code needs one rename and no more — the resource readers are +plural, so `client.ticket` is `client.tickets` — and almost everything else that needs an +edit raises at the call site. Start with the handful of changes that do not. If this is not the time to move, [1.x stays available](#staying-on-1x). @@ -1423,11 +1424,12 @@ If this is not the time to move, [1.x stays available](#staying-on-1x). `ZammadAPI::ValidationError` as `save` used to. `update` and `update!` are the same pair. - **`collection.each`** walks every page, where 1.x read one and stopped: - `client.ticket.all.each { ... }`, as 1.x spelled it, touched the first 100 tickets. It - still runs in 2.0, through the deprecated singular reader (`client.tickets` is the new - name), and now touches every ticket the client can read, at a request per page. A loop written to handle the first - page, or one that writes to each record it is handed, does that to all of them now. - Limit it explicitly with `first(n)` or `page(1, per_page: n)`. + `client.ticket.all.each { ... }`, as 1.x spelled it, touched the first 100 tickets. That + line raises in 2.0, because the reader is `client.tickets` now, and renaming it is all it + takes to run again — after which it touches every ticket the client can read, at a request + per page. A loop written to handle the first page, or one that writes to each record it is + handed, does that to all of them now. Limit it explicitly with `first(n)` or + `page(1, per_page: n)`. - **`rescue Faraday::ConnectionFailed`** (and any other Faraday exception) no longer matches. Transport failures are wrapped, so rescue `ZammadAPI::ConnectionError`, @@ -1440,7 +1442,7 @@ If this is not the time to move, [1.x stays available](#staying-on-1x). | `Client.new(config_hash)` | `Client.new(**config_hash)` | Options are keyword arguments now, so a Hash has to be splatted | | an unknown option was ignored | raises `ArgumentError: unknown keyword` | A typo'd option used to be dropped without a word | | `logger: true` | `logger: Logger.new($stderr)` | The flag became an object, so you choose the device and level. Anything that answers `debug` is accepted; `true` raises `ConfigurationError` | -| `client.ticket`, `client.user`, … | `client.tickets`, `client.users`, … | A resource is `Enumerable` over every record now, so `client.ticket.each` read as if it acted on one ticket. The singular names still work and warn in Ruby's `deprecated` category; run with `RUBYOPT=-W:deprecated` to find them. They go in 3.0 | +| `client.ticket`, `client.user`, … | `client.tickets`, `client.users`, … | A resource is `Enumerable` over every record now, so `client.ticket.each` read as if it acted on one ticket. The singular names raise `UnknownResourceError`, which lists the plural ones, and so does `client.resource(:ticket)` | | `client.on_behalf_of = 'login'` | `client.on_behalf_of('login')` → new client | The setter mutated the client and leaked across threads | | `client.perform_on_behalf_of('x') { }` | `client.on_behalf_of('x') { \|scoped\| ... }` | The old block form left the header set if the block raised | | `ZammadAPI::Resources::Role < Base` reached by `client.role` | `client.resource(Role)`, for a `Role < ZammadAPI::Resources::Base` of your own | The named readers are a fixed list, and a class is handed over rather than looked up by name. [Raw requests](#raw-requests) reach whatever is not a resource | @@ -1473,7 +1475,7 @@ If this is not the time to move, [1.x stays available](#staying-on-1x). | `record.unknown_attribute` → `nil` | raises `NoMethodError`; use `record[:x]`, `fetch(:x, nil)` or `key?(:x)` | A typo read as `nil` and flowed on into whatever was written with it. Zammad also serves a reduced object where the user may not see the whole record, and that is worth being told about | | `client.x.new(id: 5)` | `client.x.find(5)` | The constructor was the one door that did not refuse a staged id — and the only one whose value reached Zammad, since a new record is sent in full | | `client.users.find(ticket.customer_id)` | `ticket.related.customer` | Following a foreign key needed the client threaded through | -| `ticket.article(body: '…')` | `ticket.add_article(body: '…')` | A noun that sends a `POST`, one letter away from `ticket.articles`, which only reads. `article` still works and warns in Ruby's `deprecated` category; it goes in 3.0 | +| `ticket.article(body: '…')` | `ticket.add_article(body: '…')` | A noun that sends a `POST`, one letter away from `ticket.articles`, which only reads. The method is gone: `article` is an attribute reader like any other, and raises `NoMethodError` on a ticket that has no article staged | ### Errors @@ -1514,8 +1516,8 @@ a `POST`, `PUT` or `DELETE` is never retried. Both are options — see `find`, `all`, `create` and `new` on a resource, `record.destroy`, attribute readers and writers, `ticket.articles` and `attachment.download`. The resources themselves are reached -by their plural names now — `client.tickets` — and adding an article is -`ticket.add_article`; the old names still answer, with a deprecation warning. +by their plural names — `client.tickets` — and adding an article is `ticket.add_article`; +those two are renames, and the old names raise. `record.save`, `record.changes` and `record.attributes` still exist and still mean what they meant; the tables above only change how they behave at the edges. diff --git a/lib/zammad_api/client.rb b/lib/zammad_api/client.rb index c3059c6..2f80e11 100644 --- a/lib/zammad_api/client.rb +++ b/lib/zammad_api/client.rb @@ -43,18 +43,6 @@ class Client users: Resources::User }.freeze - # The names the readers had in 1.x, mapped to the ones they have now. - # Each still works, as a deprecated alias - see {#resource}. - DEPRECATED_RESOURCES = { - group: :groups, - organization: :organizations, - ticket: :tickets, - ticket_article: :ticket_articles, - ticket_priority: :ticket_priorities, - ticket_state: :ticket_states, - user: :users - }.freeze - # Methods Ruby calls implicitly for type coercion. They must keep raising # NoMethodError so that this object behaves normally in core operations. CONVERSION_METHODS = %i[to_ary to_a to_hash to_str to_io to_proc coerce].freeze @@ -81,51 +69,6 @@ class Client define_method(name) { @resources.fetch(resource_class) } end - # @!method group - # @deprecated Use {#groups}. - # @return [ResourceProxy] - # @!method organization - # @deprecated Use {#organizations}. - # @return [ResourceProxy] - # @!method ticket - # @deprecated Use {#tickets}. - # @return [ResourceProxy] - # @!method ticket_article - # @deprecated Use {#ticket_articles}. - # @return [ResourceProxy] - # @!method ticket_priority - # @deprecated Use {#ticket_priorities}. - # @return [ResourceProxy] - # @!method ticket_state - # @deprecated Use {#ticket_states}. - # @return [ResourceProxy] - # @!method user - # @deprecated Use {#users}. - # @return [ResourceProxy] - DEPRECATED_RESOURCES.each do |old_name, name| - define_method(old_name) do - Client.warn_deprecated_resource(old_name, name) - @resources.fetch(RESOURCES.fetch(name)) - end - end - - # Says that a reader was called by the name it had in 1.x. - # - # In Ruby's own +deprecated+ category, so it is silent unless the - # application asks for deprecation warnings - +ruby -W:deprecated+, or - # +Warning[:deprecated] = true+, which is what a test suite turns on - - # and a script that has not been migrated yet does not print a line per - # request in production. +uplevel+ names the line that made the call, - # past the two frames of this class in between. - # - # @api private - # @param old_name [Symbol] - # @param name [Symbol] - # @return [void] - def self.warn_deprecated_resource(old_name, name) - warn("ZammadAPI::Client##{old_name} is deprecated and will be removed in 3.0: use ##{name} instead", uplevel: 2, category: :deprecated) - end - # Environment variables {.from_env} reads, mapped to the options they set. ENV_OPTIONS = { 'ZAMMAD_URL' => :url, @@ -205,9 +148,6 @@ def initialize(**options) # The proxy for a resource, by name or by class. # - # A name from 1.x - +:ticket+ for +:tickets+ - is still answered, with - # a deprecation warning. - # # A class is the way to the parts of the API this gem does not model. # {Resources::Base} is built to be subclassed - a path, and whatever the # endpoint needs said about it - and a proxy for such a class gives its @@ -234,15 +174,9 @@ def initialize(**options) def resource(name) return proxy_for(name) if name.is_a?(Class) - key = name.to_sym - - if !RESOURCES.key?(key) - current = DEPRECATED_RESOURCES.fetch(key) { raise UnknownResourceError, unknown_resource_message(name) } - Client.warn_deprecated_resource(key, current) - key = current - end + resource_class = RESOURCES.fetch(name.to_sym) { raise UnknownResourceError, unknown_resource_message(name) } - @resources.fetch(RESOURCES.fetch(key)) + @resources.fetch(resource_class) end # @return [Array] every resource name this client supports diff --git a/lib/zammad_api/resources/ticket.rb b/lib/zammad_api/resources/ticket.rb index 7f1c1f5..cf2385e 100644 --- a/lib/zammad_api/resources/ticket.rb +++ b/lib/zammad_api/resources/ticket.rb @@ -80,27 +80,6 @@ def add_article(attributes = {}) record.save! record end - - # Adds an article to this ticket, under the name the method had in 1.x. - # - # Warns in Ruby's +deprecated+ category, the way the singular readers - # on {Client} do: silent unless the application asks for deprecation - # warnings. - # - # The attributes are required, as they were in 1.x. With a default, - # a bare +ticket.article+ - which reads like the attribute a ticket is - # created with, `ticket.article = {body: 'reply'}` - sent a POST - # naming nothing but the ticket, which Zammad refused for want of a - # body. 1.x raised ArgumentError for it without a request, and so does - # this. - # - # @deprecated Use {#add_article}. - # @param attributes [Hash] article attributes - # @return [TicketArticle] the created article - def article(attributes) - warn("#{Ticket.name}#article is deprecated and will be removed in 3.0: use #add_article instead", uplevel: 1, category: :deprecated) - add_article(attributes) - end end end end diff --git a/sig/zammad_api/client.rbs b/sig/zammad_api/client.rbs index ce64ff2..0ac96c6 100644 --- a/sig/zammad_api/client.rbs +++ b/sig/zammad_api/client.rbs @@ -1,7 +1,6 @@ module ZammadAPI class Client RESOURCES: Hash[Symbol, untyped] - DEPRECATED_RESOURCES: Hash[Symbol, Symbol] CONVERSION_METHODS: Array[Symbol] ENV_OPTIONS: Hash[String, Symbol] @@ -11,7 +10,6 @@ module ZammadAPI @resources: Hash[untyped, ResourceProxy[untyped]] def self.from_env: (**untyped overrides) -> Client - def self.warn_deprecated_resource: (Symbol old_name, Symbol name) -> void def self.build: (Config config, untyped transport) -> Client def initialize: (**untyped options) -> void @@ -24,16 +22,6 @@ module ZammadAPI def ticket_states: () -> ResourceProxy[Resources::TicketState] def users: () -> ResourceProxy[Resources::User] - # The names these readers had in 1.x. Each warns in Ruby's `deprecated` - # category and answers what its plural answers. - %a{deprecated: use groups} def group: () -> ResourceProxy[Resources::Group] - %a{deprecated: use organizations} def organization: () -> ResourceProxy[Resources::Organization] - %a{deprecated: use tickets} def ticket: () -> ResourceProxy[Resources::Ticket] - %a{deprecated: use ticket_articles} def ticket_article: () -> ResourceProxy[Resources::TicketArticle] - %a{deprecated: use ticket_priorities} def ticket_priority: () -> ResourceProxy[Resources::TicketPriority] - %a{deprecated: use ticket_states} def ticket_state: () -> ResourceProxy[Resources::TicketState] - %a{deprecated: use users} def user: () -> ResourceProxy[Resources::User] - # A class cannot carry its own type into the answer - RBS has no way to # say "a proxy for whichever class this is" - so a proxy for a resource of # your own is untyped until you say what it is: diff --git a/sig/zammad_api/resources/resources.rbs b/sig/zammad_api/resources/resources.rbs index c4e5b10..8b96876 100644 --- a/sig/zammad_api/resources/resources.rbs +++ b/sig/zammad_api/resources/resources.rbs @@ -152,7 +152,6 @@ module ZammadAPI def articles: () -> Array[TicketArticle] def add_article: (?Hash[untyped, untyped] attributes) -> TicketArticle - %a{deprecated: use add_article} def article: (Hash[untyped, untyped] attributes) -> TicketArticle end class TicketArticle < Base diff --git a/spec/unit/zammad_api/client_spec.rb b/spec/unit/zammad_api/client_spec.rb index 60b158c..6c8c488 100644 --- a/spec/unit/zammad_api/client_spec.rb +++ b/spec/unit/zammad_api/client_spec.rb @@ -230,52 +230,17 @@ # A proxy is Enumerable over every record of its kind, so the readers are # plural. The singular names are what they were called in 1.x, when a proxy - # was only a dispatcher for find and create. + # was only a dispatcher for find and create, and they are gone. describe 'the singular names the readers had in 1.x' do - around do |example| - enabled = Warning[:deprecated] - Warning[:deprecated] = true - example.run - ensure - Warning[:deprecated] = enabled - end - - ZammadAPI::Client::DEPRECATED_RESOURCES.each do |old_name, name| - it "still answers ##{old_name} with what ##{name} answers" do - client = unit_client - proxy = nil - - expect { proxy = client.public_send(old_name) }.to output.to_stderr - expect(proxy).to be(client.public_send(name)) + %i[group organization ticket ticket_article ticket_priority ticket_state user].each do |old_name| + it "does not answer ##{old_name}" do + expect { unit_client.public_send(old_name) } + .to raise_error(ZammadAPI::UnknownResourceError, /Unknown resource #{old_name}, available resources are: groups, /) end end - it 'covers every reader' do - expect(ZammadAPI::Client::DEPRECATED_RESOURCES.values).to eq(ZammadAPI::Client::RESOURCES.keys) - end - - it 'warns, naming the replacement' do - expect { unit_client.ticket } - .to output(/ZammadAPI::Client#ticket is deprecated and will be removed in 3\.0: use #tickets instead/).to_stderr - end - - it 'names the line that made the call, not one inside the gem' do - expect { unit_client.ticket }.to output(/#{Regexp.escape(__FILE__)}:#{__LINE__}: warning: /).to_stderr - end - - it 'does not warn for the plural name' do - expect { unit_client.tickets }.not_to output.to_stderr - end - - # Ruby's own category for this, so an application decides whether to hear - # it: a script that has not been migrated does not print a line per call. - it 'says nothing unless deprecation warnings are on' do - Warning[:deprecated] = false - expect { unit_client.ticket }.not_to output.to_stderr - end - - it 'is not listed among the resource names' do - expect(unit_client.resource_names).not_to include(:ticket) + it 'does not claim to respond to one' do + expect(unit_client).not_to respond_to(:ticket) end end @@ -388,27 +353,9 @@ end end - context 'with a name from 1.x' do - around do |example| - enabled = Warning[:deprecated] - Warning[:deprecated] = true - example.run - ensure - Warning[:deprecated] = enabled - end - - it 'still answers, with the proxy the plural answers with' do - client = unit_client - proxy = nil - - expect { proxy = client.resource(:ticket) }.to output.to_stderr - expect(proxy).to be(client.tickets) - end - - it 'warns, naming the line that made the call' do - expect { unit_client.resource('ticket') } - .to output(/#{Regexp.escape(__FILE__)}:#{__LINE__ - 1}: warning: ZammadAPI::Client#ticket is deprecated/).to_stderr - end + it 'raises for a singular name from 1.x' do + expect { unit_client.resource(:ticket) } + .to raise_error(ZammadAPI::UnknownResourceError, /Unknown resource ticket, available resources are: groups, /) end end diff --git a/spec/unit/zammad_api/resources/ticket_spec.rb b/spec/unit/zammad_api/resources/ticket_spec.rb index ea42c82..8c743f7 100644 --- a/spec/unit/zammad_api/resources/ticket_spec.rb +++ b/spec/unit/zammad_api/resources/ticket_spec.rb @@ -162,55 +162,32 @@ def posted_ticket_ids end end - # The name the method had in 1.x: a noun that sends a POST, one letter away - # from the reader beside it. + # The name add_article had in 1.x: a noun that sends a POST, one letter away + # from the reader beside it. It is gone, which leaves `article` what it is + # everywhere else on a record - an attribute. describe '#article' do - around do |example| - enabled = Warning[:deprecated] - Warning[:deprecated] = true - example.run - ensure - Warning[:deprecated] = enabled + it 'is not a method of a ticket' do + expect(described_class.method_defined?(:article)).to be(false) end - before do - stub_request(:post, article_url).with(query: hash_including({})) - .to_return(json_response({ id: 9, body: 'hello', ticket_id: 42 }, status: 201)) - end - - it 'still adds the article' do - added = nil - - expect { added = ticket.article(body: 'hello') }.to output.to_stderr - expect(added.id).to eq(9) - end - - it 'warns, naming the replacement' do - expect { ticket.article(body: 'hello') } - .to output(/ZammadAPI::Resources::Ticket#article is deprecated and will be removed in 3\.0: use #add_article instead/).to_stderr + it 'raises NoMethodError for the call 1.x made' do + expect { ticket.article(body: 'hello') }.to raise_error(NoMethodError) end - it 'names the line that made the call' do - expect { ticket.article(body: 'hello') }.to output(/#{Regexp.escape(__FILE__)}:#{__LINE__}: warning: /).to_stderr - end - - it 'says nothing unless deprecation warnings are on' do - Warning[:deprecated] = false - expect { ticket.article(body: 'hello') }.not_to output.to_stderr - end + it 'sends nothing for the call 1.x made' do + begin + ticket.article(body: 'hello') + rescue NoMethodError + nil + end - it 'does not warn for add_article' do - expect { ticket.add_article(body: 'hello') }.not_to output.to_stderr + expect(a_request(:post, article_url).with(query: hash_including({}))).not_to have_been_made end - # It reads like the attribute a ticket is created with, and with a - # default it sent a POST naming nothing but the ticket. 1.x required the - # attributes. - it 'requires the attributes, as 1.x did, and sends nothing without them' do + it 'reads the article staged for the next save' do ticket.article = { body: 'reply' } - expect { ticket.article }.to raise_error(ArgumentError, /wrong number of arguments/) - expect(a_request(:post, article_url).with(query: hash_including({}))).not_to have_been_made + expect(ticket.article).to eq(body: 'reply') end end end