Skip to content

Parse the show_title problem report extension (PP-5235) - #153

Merged
io7m merged 6 commits into
mainfrom
pp5235-problem-report-show-title
Nov 18, 2026
Merged

io7m merged 6 commits into
mainfrom
pp5235-problem-report-show-title

Conversation

@dbernstein

@dbernstein dbernstein commented Sep 28, 2026 •

Copy link
Copy Markdown
Contributor

What's this do?

Teaches LSHTTPProblemReport about the Palace show_title extension member, so that clients can tell when a library's problem detail is meant to be displayed on its own.

  • LSHTTPProblemReport gains a nullable showTitle, plus a shouldShowTitle accessor that returns true when the server sent nothing. Reports that predate the extension therefore behave exactly as they do today.
  • toMap() carries the member only when the server actually sent it, so the attribute set every existing consumer sees (task recorder attributes, error pages) is unchanged for every document that does not use the extension.
  • LSHTTPProblemReportParser reads show_title leniently: anything that is not a real JSON boolean degrades to null rather than failing the parse.

That leniency is the one deliberate design decision here. A caller that loses a problem report loses the server's detail along with it, and on the sign-in path that means a patron blocked by library policy would be told their credentials were invalid instead of being shown their library's message. The flag is allowed to fail; the document is not.

This is a library change only. Nothing renders differently until android-core consumes it.

Why are we doing this? (w/ JIRA link if applicable)

JIRA: PP-5235

The circulation manager can now be configured, per library, to suppress the standard "Blocked by library policy." title on a patron blocking rule message, for libraries whose configured message redirects the patron elsewhere and where that title is unwanted framing. The manager signals it with a show_title: false member on the 403 problem document (circulation#3727, merged):

{
  "type": "http://librarysimplified.org/terms/problem/credentials-blocked-by-policy",
  "title": "Blocked by library policy.",
  "status": 403,
  "detail": "Please sign in at your local library instead.",
  "show_title": false
}

The flag is emitted only when the title should be hidden, so its absence means "render as usual". iOS has already shipped its half (ios-core#1462).

How should this be tested? / Do these changes have associated tests?

Five cases added to LSHTTPProblemReportParserContract (today that contract has exactly one implementation, LSHTTPProblemReportParserTest; the new cases are written there so any future implementation inherits them):

  • testValid / testEmpty extended: no show_title member gives showTitle == null and shouldShowTitle == true (the pre-extension default).
  • testShowTitleFalse: parsed as false; title and detail both still parse, since only the display of the title is suppressed, never the value.
  • testShowTitleTrue: parsed as true, equivalent to omitting the member.
  • testShowTitleNotABoolean: "show_title": "false" (a string) leaves the flag null and the rest of the document intact. This is the case that protects the sign-in path.
  • testToMapShowTitle: the attribute is absent from toMap() without the member, and present with it.

Three new fixtures under org.librarysimplified.http.tests/src/test/resources.

Verified by CI, not locally. These tests were written without ever being compiled: there is no Android SDK on the machine this was authored on, and every module here is an AAR, so compileDebugUnitTestKotlin could not resolve. CI was the first execution of this code.

Run 36464464285 passed. From the uploaded JUnit report, all 9 tests in LSHTTPProblemReportParserTest executed with 0 failures — testShowTitleFalse, testShowTitleTrue, testShowTitleNotABoolean and testToMapShowTitle among them, so the new cases genuinely ran rather than being silently skipped. Full suite: 78 tests, 0 failures, 0 skipped.

I have not seen the red state for these tests (reverting the production change locally only produced the same SDK error, not a compile failure naming the missing members), so treat them as passing-verified but not red-verified.

Dependencies for merging? Releasing to production?

  • Needs a release for android-core to consume (currently 2.7.0-SNAPSHOT), then an android-platform version catalog bump. The android-core side of PP-5235 is blocked on that.
  • Worth a maintainer's eye: adding a parameter to a Kotlin data class primary constructor is binary-incompatible even with a default value, because the 4-arg constructor, copy and copy$default signatures all change. Under strict semver that argues for 3.0.0 rather than 2.7.0. I have left the version alone because everything in the Palace ecosystem is built from source in lockstep, so in practice nothing links against the old signatures — but that is a judgement call I would rather you made than me. Note also that VERSIONING.txt still documents ./gradlew verifySemanticVersioning, and no such task exists in the current build system; org.thepalaceproject.build.checkSemanticVersioning is parsed into PalaceProjectProperties and never consumed. The gate is dormant, so it will not catch this either way.

Have you updated the changelog?

Yes, opening the 2.7.0 release element, following the pattern of 294f6be.

Has the application documentation been updated for these changes?

The new members are documented with KDoc, including why shouldShowTitle should be preferred over reading showTitle directly. No other docs in this repo cover problem reports.

Did someone actually run this code to verify it works?

CI did — run 36464464285, 78 tests, 0 failures, with the four new show_title cases confirmed present in the JUnit report. No human has run it, and no one has exercised it end to end against a manager configured to suppress the title; that happens when android-core consumes this.

🤖 Generated with Claude Code

The Palace circulation manager can mark a problem detail document with
`show_title: false`, meaning its `detail` is written to stand on its own
and clients should not frame it with a title. It is emitted only when the
title should be hidden, so an absent member means "show the title" and
every pre-existing document is unchanged.

LSHTTPProblemReport gains a nullable `showTitle` plus a `shouldShowTitle`
accessor that defaults to true, so reports that predate the extension
display exactly as they do today. `toMap()` carries the member only when
the server sent it, leaving the attribute set every existing consumer
sees untouched.

The parser treats the flag as lenient: anything that is not a JSON
boolean degrades to null rather than failing the document. A caller that
loses a problem report loses the server's `detail` with it, and on the
sign-in path that would tell a patron blocked by library policy that
their credentials were invalid instead of showing their library's
message.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@dbernstein
dbernstein marked this pull request as ready for review September 28, 2026 18:25
Review follow-ups on the show_title extension.

`toMap()` no longer carries the flag. Those attributes reach the task
recorder and are rendered verbatim onto the error page a patron can
open, so gating the entry on the member's presence only hid it for the
documents that do not use the extension. The documents that do are
exactly the ones where a library has asked for less framing around its
message, and answering that request by putting the request itself on
screen works against the reason it exists. Every report now yields the
same four attributes as before, flag or no flag.

`LSHTTPProblemReport` gains an explicit `serialVersionUID`. The class is
Serializable and had no pinned value, so the JVM derived one from the
class structure and this PR's new field silently changed it. Nothing
persists these reports across versions today; pinning keeps that true by
choice rather than by luck, and makes the next field addition free.

The parser now warns when `show_title` is present but not a boolean.
Degrading to "absent" is still right -- the flag must never cost us the
document, and on the sign-in path losing the document means telling a
blocked patron their credentials were invalid -- but doing it in silence
leaves a misconfigured server undiagnosable. An explicit JSON null is
not warned about: that is a server saying nothing, not saying it badly.

Tests: `testToMapShowTitle` asserted the behaviour removed above, so it
becomes `testToMapOmitsShowTitle` and pins an identical attribute set
across the absent, false and true documents. Adds an explicit-null case
with a fixture, a `show_title` serialization round trip, and a UID
assertion that reads ObjectStreamClass rather than the constant, since
the failure worth guarding against is the Kotlin companion declaration
quietly not producing a static field serialization can see.

Also documents that `shouldShowTitle` is independent of whether `title`
is present, since callers must null-check it either way.

PP-5235

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
val title: String?,
val detail: String?,
val type: String?,
val showTitle: Boolean? = null,

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.

Please don't make this nullable. If null has some special meaning that true or false don't cover, then it should be expressed with an enum type or similar.

* exactly the ones where a library has asked for less framing around its message, so
* surfacing it to the patron would work against the reason it exists.
*/

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.

Claude slop comment, I think. Best to just remove this entire comment.

return attributes.toMap()
}

companion object {

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.

This entire companion object can go. We don't use serialVersionUID because we don't actually support persisting objects; the class only implements Serializable due to historical constraints in Android that we've progressively eliminated.


val deserializedProblemReport = objectInputStream.readObject()
/**
* The serial version UID is pinned to an explicit value.

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.

Can be removed.


Assertions.assertEquals(problemReport, deserializedProblemReport)
@Test
fun testProblemReportSerialVersionUID() {

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.

Can be removed.

* callers that lose a problem report lose the server's `detail` along with it, and on
* the sign-in path that means a patron blocked by library policy would be told their
* credentials were invalid instead of being shown their library's message.
*/

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.

It sounds like true means the same thing as null.

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.

(As in "make the default true and then it means the same thing as making the default null)

dbernstein and others added 4 commits November 17, 2026 08:27
…-show-title

# Conflicts:
#	README-CHANGES.xml
Make `showTitle` a non-nullable `Boolean` defaulting to `true`. Absence,
an explicit JSON null, and a non-boolean value all now yield `true`
directly, so `shouldShowTitle` has nothing left to translate and is
removed along with it.

Remove the `serialVersionUID` companion object and the two serialization
tests that went with it, restoring LSHTTPSerializationTest to its
original form.

Trim the commentary in the report class, the parser and the tests.

PP-5235

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Drop the doc comments from the show_title tests and the comment above
the show_title branch in the parser. Neither file documents its other
cases: the parser's four preceding fields carry no comment, and none of
the contract's existing tests carry KDoc. The test names and assertions
already say what is being checked.

PP-5235

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
PP-5235

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@dbernstein
dbernstein requested a review from io7m November 17, 2026 16:51

@io7m io7m 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.

This is fine.

It tags the wrong release in the README-CHANGES.xml file, but I'll fix that when it's merged.

@io7m
io7m merged commit 8e2961d into main Nov 18, 2026
1 check passed
@io7m
io7m deleted the pp5235-problem-report-show-title branch November 18, 2026 10:55
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.

2 participants