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/.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/CHANGELOG.md b/CHANGELOG.md index 422138f..6bc8db6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,875 @@ +# 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 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 + `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. 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 + +- `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. +- 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. +- 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. +- 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. +- 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. +- 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 + +- `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/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/README.md b/README.md index 211469b..0f84e37 100644 --- a/README.md +++ b/README.md @@ -1,390 +1,1528 @@ -# 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: + +```sh +gem install zammad_api --pre +``` + +`'~> 2.0'` does not match an alpha, and `gem install zammad_api` without `--pre` installs +1.x. + +### Staying on 1.x - $ bundle +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. -Or install it yourself as: +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: - $ gem install zammad_api +```ruby +gem 'zammad_api', '~> 1.4' +``` -## Available objects +Or: -* user -* organization -* group -* ticket -* ticket_article -* ticket_state -* ticket_priority +```sh +gem install zammad_api -v '~> 1.4' +``` -## Usage +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`. -### Create instance +## Creating a client -#### Username/email and password +### 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. -Individual resources can be created, modified, saved, and destroyed. +### From the environment -### Create object +`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: -With new and save: ```ruby -group = client.group.new( - name: 'Support', - note: 'Some note', -); +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 — 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). + +### 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: + +| 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. | +| `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. | + +`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`. + +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. + +## 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: + +```ruby +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 -group1 = groups[0] -group1.note = 'Some note' -group1.save +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. -groups.each {|group| - p "group: #{group.name}" -} +A ticket's articles are also reachable without `related`, and `add_article` writes one: + +```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 -groups.page(1,3) {|group| - p "group: #{group.name}" +[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 +``` - group.note = 'Some new note, inclued in page 1 with 3 per page' - group.save -} +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. -groups.page(2,3) {|group| - p "group: #{group.name}" +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. - group.note = 'Some new note, inclued in page 2 with 3 per page' - group.save -} +`to_json` renders the attributes, so a record can be cached, queued or logged as it stands, +and nests inside a structure being generated: + +```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 + +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 + +client.groups.destroy(42) # delete by id, without fetching first +``` -groups.page(1,3) {|group| - p "group: #{group.name}" +## Collections - group.note = 'Some new note, inclued in page 1 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. -groups.page(2,3) {|group| - p "group: #{group.name}" +A resource proxy is itself `Enumerable` over `all`, so `.all` is optional: - group.note = 'Some new note, inclued in page 2 with 3 per page' - group.save -} +```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.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) +``` + +### 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. + +Narrow by a value with [`find_by`](#fetch) for one record, or `search` for many: + +```ruby +client.users.find_by(email: 'someone@example.com') +client.tickets.search('state.name:open').first(10) +``` + +`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.on_behalf_of = 'some_login' +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]}}) ``` -All following actions with the client will be performed on behalf of the user with the `login` "some_login". +A `condition` may nest groups of conditions, the form Zammad calls expert mode: -To reset this back to regular requests just set `nil`: +```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.on_behalf_of = nil +client.ticket_states.find_by(name: 'open') +client.ticket_priorities.select { it.active } ``` -It's possible to perform only a block of actions on behalf of another user via: +### Search ```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.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. + +### Explicit pages + +```ruby +tickets = client.tickets.all -# further actions are performed regularly. +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: + +```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 +``` + +`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 +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 +``` -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' -# ... +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 ``` -List all new or open tickets: +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 -tickets = client.ticket.search(query: 'state.name:new OR state.name:open') +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. + +## Acting on behalf of another user -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' +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. -tickets.each {|ticket| - p "ticket: #{ticket.number} - #{ticket.title}" -} +```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 ) +``` + +## Logging -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 +```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' + +RSpec.describe TicketCloser do + let(:zammad) { ZammadAPI::Test.new } + + 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 +``` + +`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 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 +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 -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 -} +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: -p "article: #{article.from} - #{article.subject}" +```ruby +zammad.stub(:get, 'api/v1/groups', body: [{id: 1, name: 'Users'}, {id: 2, name: 'Sales'}]) + +client.groups.all.map(&:name) # => ["Users", "Sales"] ``` -## Testing +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: -### Setup an (empty Zammad) test env +```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 ``` -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 + +Name a `page` to say what each one holds, and the stub is served exactly as written: + +```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}) +``` + +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. + +```ruby +zammad.stub(:get, 'api/v1/users/search', body: {records: [{id: 1}, {id: 2}], total_count: 2}) ``` -### Execute client tests +### Scopes that overlap -Run tests via `rake spec`. (Remember to export the vars above if you are running this in another shell.) +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: -## Publishing +```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}]) -1. Update version in [version.rb](lib/zammad_api/version.rb). -2. Add release to [CHANGELOG.md](CHANGELOG.md) -3. Commit. -4. Test build. +client.tickets.search('urgent').count # => 42, however often it is asked ``` -> rake build -zammad_api 1.0.7 built to pkg/zammad_api-1.0.7.gem. + +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 ``` -5. Release + +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 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). + +### 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. 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`, + `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 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 | + +### 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. The method is gone: `article` is an attribute reader like any other, and raises `NoMethodError` on a ticket that has no article staged | + +### 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 — `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. + +## 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/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/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/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/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/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/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." 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..2f80e11 100644 --- a/lib/zammad_api/client.rb +++ b/lib/zammad_api/client.rb @@ -1,65 +1,446 @@ -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= + # 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 - def initialize(config) - @config = config - @logger = ZammadAPI::Log.new(@config) - @transport = ZammadAPI::Transport.new(@config, @logger) - check_config + # @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 + # 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 + 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 - 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" - end - ZammadAPI::Dispatcher.new(@transport, class_object) + # 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 + + # The proxy for a resource, by name or by class. + # + # 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) + + resource_class = RESOURCES.fetch(name.to_sym) { raise UnknownResourceError, unknown_resource_message(name) } + + @resources.fetch(resource_class) + 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 + + # 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 + + # 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 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]) + def raw(method, path, query: nil, body: nil, headers: nil) + relative = Transport.relative_path(path) - # check for token auth - return if @config[:http_token] && !@config[:http_token].empty? - return if @config[:oauth2_token] && !@config[:oauth2_token].empty? + @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 - if !@config[:user] || @config[:user].empty? - raise ConfigurationError, 'missing user in config' - end + def unknown_resource_message(name) = "Unknown resource #{name}, available resources are: #{RESOURCES.keys.join(', ')}" - return if @config[:password] && !@config[:password].empty? + # 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) - raise ConfigurationError, 'missing password in config' + @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 - def modulize(string) - string.gsub(/__(.?)/) { "::#{$1.upcase}" } - .gsub(%r{/(.?)}) { "::#{$1.upcase}" } - .gsub(/(?:_+|-+)([a-z])/) { $1.upcase } - .gsub(/(\A|\s)([a-z])/) { $1 + $2.upcase } + # 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..caff818 --- /dev/null +++ b/lib/zammad_api/collection.rb @@ -0,0 +1,863 @@ +# 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. + # + # 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 } + # + # @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} + # @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 + @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 + @paginated = paginated + 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)+. + # + # 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 + 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 + + @paginated ? walk(&block) : read_whole(&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, 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') + 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}#{' paginated=false' if !@paginated}>" + 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. + # + # 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 || !@paginated + + 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 + + # 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 + 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, index: !@search) 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, + paginated: @paginated + ) + 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. + # + # 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 + 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..b038c40 --- /dev/null +++ b/lib/zammad_api/deep_copy.rb @@ -0,0 +1,113 @@ +# frozen_string_literal: true + +require_relative 'duplicate_keys' + +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 + # @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 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}. + # + # @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..6ea7ce0 100644 --- a/lib/zammad_api/errors.rb +++ b/lib/zammad_api/errors.rb @@ -1,62 +1,214 @@ -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 + # 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, 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 + + # 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 + + # 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? - def initialize(operation:, response:, resource_class: 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 - def body_error - return nil if body.to_s.strip.empty? + # Any 5xx response. + class ServerError < ResponseError; end - parsed = JSON.parse(body) - parsed.is_a?(Hash) ? parsed['error'] : nil - rescue JSON::ParserError - nil + # 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 + + # 422 - Zammad rejected the submitted attributes. + class ValidationError < ClientError; end + + # 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..141e73d --- /dev/null +++ b/lib/zammad_api/resource_proxy.rb @@ -0,0 +1,614 @@ +# 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, + # Every search endpoint pages, whatever the index beside it does. + paginated: 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?, paginated: resource_class.paginated?, 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, + paginated: paginated, + 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..a06f5be 100644 --- a/lib/zammad_api/resources/base.rb +++ b/lib/zammad_api/resources/base.rb @@ -1,140 +1,1052 @@ -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 '../duplicate_keys' +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 + + # 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 + + # 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 + + # 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") + 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 } - if attributes.nil? - attributes = {} + # @return [Boolean] whether this resource's index endpoint reads + # +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 + # 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 + + # 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 - @attributes = attributes - symbolize_keys_deep!(@attributes) end - def method_missing(method, *args) - return @attributes[method] if !method.to_s.end_with?('=') + # 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' - method = method.to_s[0, method.length - 1].to_sym - @changes[method] = [@attributes[method], args[0]] - @attributes[method] = args[0] - nil + # @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 + # 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 new_record? - @new_instance + # 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 changed? - !@changes.to_h.empty? + # @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 + + # @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 - def destroy - response = @transport.delete(url: "#{@url}/#{@attributes[:id]}") - return true if response.status == 200 + # 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. + # @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)) - raise ResponseError.from(response, operation: 'destroy object', resource_class: self.class) + # 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. + staged.each { |key, value| refuse_unwritable!(key, value) } + staged.each { |key, value| write_attribute(key, 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 + # 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}>" - 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..cf2385e 100644 --- a/lib/zammad_api/resources/ticket.rb +++ b/lib/zammad_api/resources/ticket.rb @@ -1,25 +1,85 @@ -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 - def article(data) - data[:ticket_id] = @attributes[:id] - item = ZammadAPI::Resources::TicketArticle.new(@transport, data) - item.save - item + 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' + + 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. 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! + record + 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/test.rb b/lib/zammad_api/test.rb new file mode 100644 index 0000000..92ef189 --- /dev/null +++ b/lib/zammad_api/test.rb @@ -0,0 +1,577 @@ +# 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 + # + # @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. + # + # 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. + # + # 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 + # @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. + # + # 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, 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) + # 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) + request = Request.new(verb: method, path: relative, query: params, body: snapshot(body), headers: fields, on_behalf_of: on_behalf_of) + + response = attempt(request) + config.retries.times do + break if !::ZammadAPI::Transport.retried?(config, method, response) + + response = attempt(request) + end + return response if response.success? + + raise ResponseError.build(response, operation: operation, resource_class: resource_class) + end + + 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 + # 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/lib/zammad_api/transport.rb b/lib/zammad_api/transport.rb index 5ade333..6a32554 100644 --- a/lib/zammad_api/transport.rb +++ b/lib/zammad_api/transport.rb @@ -1,63 +1,1211 @@ +# 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 - @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 + + # 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 - %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 + # 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. + # + # 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 [Integer, String, Symbol, nil] + # @return [String] + # @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) + + 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. + # + # {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 + + 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 + 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 + + # 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 + # 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 + + # 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 + @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 + + # 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 + + # +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) - with_params = !param[:params].nil? - if with_params - @logger.debug "Params: #{param[:params].inspect}" + @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, 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) + 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 + + # 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 - yield(req) if block_given? + 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 + + 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) - @logger.debug "Response: #{response.body}" - response + 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'] + + "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=#{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 + + 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 Transport.redact(body) if !body.is_a?(String) + + decoded = JSON.parse(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 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/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 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/sig/vendor/faraday.rbs b/sig/vendor/faraday.rbs new file mode 100644 index 0000000..a811cfb --- /dev/null +++ b/sig/vendor/faraday.rbs @@ -0,0 +1,73 @@ +# 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 + + # 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/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..0ac96c6 --- /dev/null +++ b/sig/zammad_api/client.rbs @@ -0,0 +1,54 @@ +module ZammadAPI + class Client + RESOURCES: Hash[Symbol, untyped] + 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.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] + + # 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..7830bbe --- /dev/null +++ b/sig/zammad_api/collection.rbs @@ -0,0 +1,86 @@ +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 + @paginated: 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, + ?paginated: 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 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 + 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..b5c7325 --- /dev/null +++ b/sig/zammad_api/deep_copy.rbs @@ -0,0 +1,8 @@ +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 +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..9760b35 --- /dev/null +++ b/sig/zammad_api/errors.rbs @@ -0,0 +1,76 @@ +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 + UNPAGINATED_ADVICE: String + + def self.build: (operation: String, page: Integer, ?resource_class: Class?, ?index: bool) -> 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..208dd3c --- /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, ?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 + 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..877689a --- /dev/null +++ b/sig/zammad_api/resources/base.rbs @@ -0,0 +1,104 @@ +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? + 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 + 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..8b96876 --- /dev/null +++ b/sig/zammad_api/resources/resources.rbs @@ -0,0 +1,209 @@ +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 + 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..9215855 --- /dev/null +++ b/sig/zammad_api/test.rbs @@ -0,0 +1,85 @@ +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 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] + 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..0da883f --- /dev/null +++ b/sig/zammad_api/transport.rbs @@ -0,0 +1,94 @@ +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] + RECORD_ID_TYPES: Array[Class] + 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.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 + 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.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 + 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 + 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 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 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/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/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 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..28f2aea --- /dev/null +++ b/spec/unit/zammad_api/attribute_access_spec.rb @@ -0,0 +1,418 @@ +# 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 + + # 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 + 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..6c8c488 --- /dev/null +++ b/spec/unit/zammad_api/client_spec.rb @@ -0,0 +1,1088 @@ +# 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, and they are gone. + describe 'the singular names the readers had in 1.x' do + %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 'does not claim to respond to one' do + expect(unit_client).not_to respond_to(: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 + + 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 + + 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..f491e21 --- /dev/null +++ b/spec/unit/zammad_api/collection_spec.rb @@ -0,0 +1,1461 @@ +# 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 + + # 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 + # 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 + + # `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)) + + 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..c3300ec --- /dev/null +++ b/spec/unit/zammad_api/resource_proxy_spec.rb @@ -0,0 +1,1145 @@ +# 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 + + # 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 + 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 + + # 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 })) + + 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..2de2afe --- /dev/null +++ b/spec/unit/zammad_api/resources/base_spec.rb @@ -0,0 +1,1613 @@ +# 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 + + # 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 + + 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 + + # 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 + 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 + + # 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 + 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 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 + + 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 '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 + + 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..8c743f7 --- /dev/null +++ b/spec/unit/zammad_api/resources/ticket_spec.rb @@ -0,0 +1,193 @@ +# 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 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 + it 'is not a method of a ticket' do + expect(described_class.method_defined?(:article)).to be(false) + end + + it 'raises NoMethodError for the call 1.x made' do + expect { ticket.article(body: 'hello') }.to raise_error(NoMethodError) + end + + it 'sends nothing for the call 1.x made' do + begin + ticket.article(body: 'hello') + rescue NoMethodError + nil + end + + expect(a_request(:post, article_url).with(query: hash_including({}))).not_to have_been_made + end + + it 'reads the article staged for the next save' do + ticket.article = { body: 'reply' } + + expect(ticket.article).to eq(body: 'reply') + 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/test_spec.rb b/spec/unit/zammad_api/test_spec.rb new file mode 100644 index 0000000..9f020c3 --- /dev/null +++ b/spec/unit/zammad_api/test_spec.rb @@ -0,0 +1,1048 @@ +# 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. + # 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 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 } + + 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 diff --git a/spec/unit/zammad_api/transport_spec.rb b/spec/unit/zammad_api/transport_spec.rb new file mode 100644 index 0000000..8a66a29 --- /dev/null +++ b/spec/unit/zammad_api/transport_spec.rb @@ -0,0 +1,1729 @@ +# 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 + + # 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]' }) + 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') + 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 + + 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 + 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