Skip to content

feat(exception)!: keep error details and contain request failures - #126

Merged
gilbertotcc merged 9 commits into
mainfrom
feat/error-handling
Nov 3, 2026
Merged

gilbertotcc merged 9 commits into
mainfrom
feat/error-handling

Conversation

@gilbertotcc

@gilbertotcc gilbertotcc commented Nov 3, 2026 •

Copy link
Copy Markdown
Owner

Makes failed calls easier to diagnose, accepts power labels in any case, and stops null arguments and request-building failures from surfacing as stray exceptions.

Changes

Error details. LifxErrorException now keeps the status code, the raw error body and the X-RateLimit-* data (new LifxRateLimit record). A malformed rate-limit header gives a null component and never fails. The exception message now includes the status code; the raw body stays out of it. There is still no retry on 429: callers can use reset() on the rate limit, after checking for null.

Deserialization. Power labels match case-insensitively.

Null and request failures. *Input constructors and LightsState reject null values when built, and LifxClientImpl rejects a null input, instead of an NPE from an operation's log line. If call.request() throws, the caller now gets a Failure whose message reads Call <unknown request> failed with cause ....

Decisions

  • Light keeps native types, so a null primitive still fails the whole response, and seconds_since_seen is an int, so a fractional value is truncated. Tests pin both.
  • An undocumented status or power label still fails the whole response. Enums hold only documented values, so there is no UNKNOWN constant.
  • Null arguments throw NullPointerException rather than returning Failure, since they are programmer errors. The README and LifxResult Javadoc are amended accordingly.

Breaking changes

  • The LifxErrorException constructor takes the status code, error model, raw body and rate limit, and its message format changed.
  • Null inputs and input components throw NullPointerException.
  • SetLightsStatesInput copies its list and rejects null elements.

Testing

./gradlew check passes (166 JUnit tests, 25 Spock specs), and markdownlint-cli2 is clean. New tests cover the error details end to end over WireMock for every operation, null components of every input, null input on every client method, and call.request() throwing.

integrationTest was not run, because it switches a real light.

🤖 Generated with Claude Code

gilbertotcc and others added 2 commits November 3, 2026 23:25
Power labels match case-insensitively. All Light primitives are boxed and
nullable, so one null no longer fails listLights for every light, and
seconds_since_seen keeps its fraction. Undocumented status and power values
still fail the response: enums hold only documented values.

BREAKING CHANGE: Light accessors return Boolean, Double or Integer and may
return null; missing fields are null instead of 0 or false.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
LifxErrorException keeps the status code, raw body and X-RateLimit-* data
(LifxRateLimit), and its message includes the status code. Retry on 429 is
still out of scope.

*Input constructors and LightsState reject null values when built, and
LifxClientImpl rejects a null input, instead of an NPE from a log line.
A failing call.request() now yields a Failure, with no URL in the message.

BREAKING CHANGE: the LifxErrorException constructor takes the status code,
error model, raw body and rate limit. Null inputs and input components throw
NullPointerException. SetLightsStatesInput copies its list. The exception
message format changed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@coderabbitai

coderabbitai Bot commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor

Review in Change Stack →

Walkthrough

This PR adds null checks to operation inputs, expands HTTP error details with status, raw body, and rate-limit data, and updates model deserialization to support nullable fields and case-insensitive power labels.

Changes: Input Validation

Layer / File(s) Summary
Input construction and validation
src/main/java/com/github/gilbertotcc/lifx/operations/*Input.java, src/main/java/com/github/gilbertotcc/lifx/models/LightsState.java, src/test/java/com/github/gilbertotcc/lifx/operations/OperationInputsTest.java, .claude/rules/operations.md, .claude/skills/lifx-operation/*
Operation inputs and LightsState reject null required components. SetLightsStatesInput copies its list and rejects null elements. Tests cover these behaviors, and operation guidance describes them.
Client null-input checks
src/main/java/com/github/gilbertotcc/lifx/impl/LifxClientImpl.java, src/main/java/com/github/gilbertotcc/lifx/LifxResult.java, src/test/java/com/github/gilbertotcc/lifx/impl/LifxClientImplTest.java, .claude/rules/operations.md, .claude/skills/lifx-operation/SKILL.md
All nine client operation methods reject a null input before delegation. Tests verify the exception message "input". LifxResult documentation distinguishes call failures from null-argument exceptions.

HTTP Error Data

Layer / File(s) Summary
Error response and rate-limit data
src/main/java/com/github/gilbertotcc/lifx/exception/LifxErrorException.java, src/main/java/com/github/gilbertotcc/lifx/exception/LifxRateLimit.java, src/test/java/com/github/gilbertotcc/lifx/impl/CallExecutorTest.java, src/test/java/com/github/gilbertotcc/lifx/operations/OperationFailuresTest.java
LifxErrorException retains the HTTP status, raw response body, parsed error model, and rate-limit data. LifxRateLimit parses header values independently. Tests cover error response data and malformed or absent rate-limit headers.
Call failure formatting
src/main/java/com/github/gilbertotcc/lifx/exception/LifxCallException.java, src/main/java/com/github/gilbertotcc/lifx/impl/CallExecutor.java, src/test/java/com/github/gilbertotcc/lifx/impl/CallExecutorTest.java
When request construction fails, LifxCallException.with omits the method and URL and retains the cause message. CallExecutor logs only the error message. Tests cover request-construction failures.
Error and exception documentation
README.md, AGENTS.md
The documentation describes error data exposed by LifxErrorException, null-argument exceptions, and the absence of retries for 429 responses.

Model Deserialization

Layer / File(s) Summary
Nullable light model fields
src/main/java/com/github/gilbertotcc/lifx/models/Light.java, src/test/java/com/github/gilbertotcc/lifx/models/LightTest.java, src/test/java/com/github/gilbertotcc/lifx/util/json/JacksonUtilsTest.java
Light, Color, and Capabilities components use nullable boxed types. Tests cover null brightness, fractional secondsSinceSeen, and null Kelvin values when the field is explicit or missing.
Power and status deserialization
src/main/java/com/github/gilbertotcc/lifx/models/Power.java, src/main/java/com/github/gilbertotcc/lifx/util/json/PowerDeserializer.java, src/test/java/com/github/gilbertotcc/lifx/models/PowerTest.java, src/test/java/com/github/gilbertotcc/lifx/models/LightTest.java, src/test/java/com/github/gilbertotcc/lifx/models/ResultsDtoTest.java
Power.byLabel matches case-insensitively. Tests cover mixed-case power labels and rejection of an unknown result status.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Bug fix

Sequence Diagram(s)

sequenceDiagram
  participant CallExecutor
  participant LifxErrorException
  participant LifxRateLimit
  CallExecutor->>LifxErrorException: Create exception from HTTP response
  LifxErrorException->>LifxRateLimit: Parse rate-limit response headers
  LifxRateLimit-->>LifxErrorException: Return parsed rate-limit data
  LifxErrorException-->>CallExecutor: Return exception with response data
Loading

Possibly related PRs

  • gilbertotcc/lifx-client#123: PR #123 moved PowerDeserializer and established the JSON utility structure used by the power-label lookup changes.
  • gilbertotcc/lifx-client#122: PR #122 introduced the LifxResult contract and client delegation extended here with null-input checks and additional error data.

Suggested labels: java

Merge Risk: Low · up to 48750

Document the rate-limit null checks and make the live integration tests tolerate nullable light fields. These are bounded issues, but both should be addressed before relying on the guidance or the integration suite.

Pre-merge checks: Passed 5
Check name Status Explanation
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage Passed Docstring coverage is 80.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentati…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Title check Passed The title clearly identifies the main changes: retaining error details and containing request failures. It is concise and specific, although it does not mention the additional nullable-field and input…
Full details: Docstring Coverage

Explanation

Docstring coverage is 80.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 5 functions across 27 files. (5 skipped: 5 unsupported.)

Full details: Title check

Explanation

The title clearly identifies the main changes: retaining error details and containing request failures. It is concise and specific, although it does not mention the additional nullable-field and input-validation changes.

Finishing Touches
Generate docstrings
  • Commit to this branch
  • Create a new PR
Generate unit tests (beta)
  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Tip

🎯 Customize your risk assessments

Guide how CodeRabbit assesses merge risk and security architecture risk. Highlight sensitive changes and explain your security boundaries using Merge Risk Instructions and Security Risk Instructions in your review settings. Security architecture risk assessments require the Advanced plan or above.

✅ Automatic approvals, with your rules

Let CodeRabbit approve pull requests once required threads are resolved, pre-merge checks pass, and your risk limits are met. Enable Automatic approvals in review settings, with overrides for teams or file paths.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share
Recent review info
Run configuration
  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 48a51570-fa56-44f6-bdf6-799f7779ef9f
Commits

Reviewing files that changed from the base of the PR and between 06663f3 and 4875027.

Files selected for processing: 32
  • .claude/rules/operations.md
  • .claude/skills/lifx-operation/SKILL.md
  • .claude/skills/lifx-operation/testing.md
  • AGENTS.md
  • README.md
  • src/main/java/com/github/gilbertotcc/lifx/LifxResult.java
  • src/main/java/com/github/gilbertotcc/lifx/exception/LifxCallException.java
  • src/main/java/com/github/gilbertotcc/lifx/exception/LifxErrorException.java
  • src/main/java/com/github/gilbertotcc/lifx/exception/LifxRateLimit.java
  • src/main/java/com/github/gilbertotcc/lifx/impl/CallExecutor.java
  • src/main/java/com/github/gilbertotcc/lifx/impl/LifxClientImpl.java
  • src/main/java/com/github/gilbertotcc/lifx/models/Light.java
  • src/main/java/com/github/gilbertotcc/lifx/models/LightsState.java
  • src/main/java/com/github/gilbertotcc/lifx/models/Power.java
  • src/main/java/com/github/gilbertotcc/lifx/operations/DoBreatheEffectInput.java
  • src/main/java/com/github/gilbertotcc/lifx/operations/DoPulseEffectInput.java
  • src/main/java/com/github/gilbertotcc/lifx/operations/ListLightsInput.java
  • src/main/java/com/github/gilbertotcc/lifx/operations/SetLightsStateDeltaInput.java
  • src/main/java/com/github/gilbertotcc/lifx/operations/SetLightsStateInput.java
  • src/main/java/com/github/gilbertotcc/lifx/operations/SetLightsStatesInput.java
  • src/main/java/com/github/gilbertotcc/lifx/operations/ToggleLightsPowerInput.java
  • src/main/java/com/github/gilbertotcc/lifx/operations/TransitToNextStateInput.java
  • src/main/java/com/github/gilbertotcc/lifx/operations/ValidateColorInput.java
  • src/main/java/com/github/gilbertotcc/lifx/util/json/PowerDeserializer.java
  • src/test/java/com/github/gilbertotcc/lifx/impl/CallExecutorTest.java
  • src/test/java/com/github/gilbertotcc/lifx/impl/LifxClientImplTest.java
  • src/test/java/com/github/gilbertotcc/lifx/models/LightTest.java
  • src/test/java/com/github/gilbertotcc/lifx/models/PowerTest.java
  • src/test/java/com/github/gilbertotcc/lifx/models/ResultsDtoTest.java
  • src/test/java/com/github/gilbertotcc/lifx/operations/OperationFailuresTest.java
  • src/test/java/com/github/gilbertotcc/lifx/operations/OperationInputsTest.java
  • src/test/java/com/github/gilbertotcc/lifx/util/json/JacksonUtilsTest.java

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@github-actions

github-actions Bot commented Nov 3, 2026 •

Copy link
Copy Markdown

Code coverage

Overall Project 98.59% 🍏
Files changed 100% 🍏

File Coverage
PowerDeserializer.java 100% 🍏
LightsState.java 100% 🍏
Power.java 100% 🍏
LifxCallException.java 100% 🍏
LifxErrorException.java 100% 🍏
LifxRateLimit.java 100% 🍏
CallExecutor.java 100% 🍏
LifxClientImpl.java 100% 🍏
DoPulseEffectInput.java 100% 🍏
SetLightsStateDeltaInput.java 100% 🍏
DoBreatheEffectInput.java 100% 🍏
ToggleLightsPowerInput.java 100% 🍏
TransitToNextStateInput.java 100% 🍏
SetLightsStatesInput.java 100% 🍏
ListLightsInput.java 100% 🍏
ValidateColorInput.java 100% 🍏
SetLightsStateInput.java 100% 🍏
LifxResult.java 100% 🍏

@coderabbitai coderabbitai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • Fix comments: Fix CodeRabbit comments on this PR

Comment thread README.md Resolved
gilbertotcc and others added 2 commits November 3, 2026 23:39
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
gilbertotcc and others added 4 commits November 4, 2026 00:13
By owner decision, Light goes back to primitive fields. A null primitive fails the response again, and seconds_since_seen is truncated to an int. Tests pin both behaviors.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… note

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@gilbertotcc gilbertotcc changed the title feat(exception)!: keep error details, tolerate null light fields, contain request failures feat(exception)!: keep error details and contain request failures Nov 3, 2026
@gilbertotcc
gilbertotcc merged commit a1245db into main Nov 3, 2026
9 checks passed
@gilbertotcc
gilbertotcc deleted the feat/error-handling branch November 3, 2026 23:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant