Skip to content

Commit 5e1225b

Browse files
author
Mark Pollack
committed
Move the unknown-field policy from the schema records to the mapper
Every schema record carried @JsonIgnoreProperties(ignoreUnknown = true). That made the SDK tolerate fields it does not know, which is deliberate: the specification adds fields between releases and an agent newer than this SDK must keep working. But a class-level annotation wins over any mapper configuration, so a consumer who passed a strict ObjectMapper to JacksonAcpJsonMapper got no strictness at all (#10). Removing the annotations alone would have flipped the default the other way, because the default supplier used a bare new ObjectMapper(), whose Jackson default is to fail on unknown properties. The annotations are gone and the policy lives in the mapper. The default supplier now uses JacksonAcpJsonMapper.defaultObjectMapper(), which disables FAIL_ON_UNKNOWN_PROPERTIES and logs each ignored property at DEBUG so spec drift can be observed without making the wire strict. A consumer who supplies a strict mapper gets strict behaviour; one who supplies a bare ObjectMapper now gets Jackson's default, which the changelog calls out. Unknown fields are not routed into _meta. Reported by @KallivdH.
1 parent 85fb3c5 commit 5e1225b

5 files changed

Lines changed: 136 additions & 126 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
3939
- The agent session now reads `sessionId` from typed `PromptRequest`/`CancelNotification` params as
4040
well as from maps, so in-process transports get the right lock owner in logs and cancel matching.
4141

42+
### Changed
43+
44+
- **Unknown-field policy moved from the schema to the mapper (#10).** Every schema record carried
45+
`@JsonIgnoreProperties(ignoreUnknown = true)`, which made the SDK tolerate fields it does not know
46+
(deliberate: the spec adds fields between releases and a newer agent must keep working) but also
47+
defeated any consumer's strict `ObjectMapper`, since a class-level annotation wins over
48+
`FAIL_ON_UNKNOWN_PROPERTIES`. The annotations are gone. The default mapper,
49+
`JacksonAcpJsonMapper.defaultObjectMapper()`, is lenient and logs each ignored property at DEBUG
50+
so spec drift is observable; a consumer who passes a strict mapper to `JacksonAcpJsonMapper` now
51+
gets strict behaviour. **If you construct `JacksonAcpJsonMapper` with a bare `new ObjectMapper()`,
52+
you now get Jackson's default, which fails on unknown fields**: start from
53+
`defaultObjectMapper()` instead. Unknown fields are not routed into `_meta`, which has its own
54+
spec-defined meaning. Reported by @KallivdH.
55+
4256
### Added
4357

4458
- `AcpSyncClient(AcpAsyncClient)` is public: the supported way to have both APIs over one session.

‎acp-core/src/main/java/com/agentclientprotocol/sdk/json/JacksonAcpJsonMapper.java‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,15 @@
77
import java.io.IOException;
88

99
import com.fasterxml.jackson.databind.JavaType;
10+
import com.fasterxml.jackson.core.JsonParser;
11+
import com.fasterxml.jackson.databind.DeserializationContext;
12+
import com.fasterxml.jackson.databind.DeserializationFeature;
13+
import com.fasterxml.jackson.databind.JsonDeserializer;
1014
import com.fasterxml.jackson.databind.ObjectMapper;
15+
import com.fasterxml.jackson.databind.deser.DeserializationProblemHandler;
16+
import com.fasterxml.jackson.databind.json.JsonMapper;
17+
import org.slf4j.Logger;
18+
import org.slf4j.LoggerFactory;
1119

1220
/**
1321
* Jackson-based implementation of {@link AcpJsonMapper}. Wraps a Jackson
@@ -17,8 +25,52 @@
1725
*/
1826
public final class JacksonAcpJsonMapper implements AcpJsonMapper {
1927

28+
private static final Logger logger = LoggerFactory.getLogger(JacksonAcpJsonMapper.class);
29+
2030
private final ObjectMapper objectMapper;
2131

32+
/**
33+
* The {@link ObjectMapper} the SDK uses by default: <em>lenient</em> about unknown
34+
* properties, because the ACP specification adds fields between releases and an agent
35+
* newer than this SDK must keep working. Each unknown property is logged once per
36+
* occurrence at DEBUG under this class's logger, so spec drift is observable without
37+
* making the wire strict.
38+
*
39+
* <p>
40+
* Strictness is the mapper's decision, not the schema's: the schema records carry no
41+
* {@code @JsonIgnoreProperties}, so a mapper with
42+
* {@link DeserializationFeature#FAIL_ON_UNKNOWN_PROPERTIES} enabled (Jackson's own
43+
* default for a bare {@code new ObjectMapper()}) fails on the first unknown field.
44+
* Consumers who want their own configuration on top of the SDK's defaults should start
45+
* from this method's result.
46+
* </p>
47+
* @return a new, independently configurable lenient mapper
48+
*/
49+
public static ObjectMapper defaultObjectMapper() {
50+
return JsonMapper.builder()
51+
.disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES)
52+
.addHandler(new UnknownPropertyLogger())
53+
.build();
54+
}
55+
56+
/** Skips an unknown property after logging it, so drift is visible at DEBUG. */
57+
static final class UnknownPropertyLogger extends DeserializationProblemHandler {
58+
59+
@Override
60+
public boolean handleUnknownProperty(DeserializationContext ctxt, JsonParser p,
61+
JsonDeserializer<?> deserializer, Object beanOrClass, String propertyName) throws IOException {
62+
if (logger.isDebugEnabled()) {
63+
Object type = beanOrClass instanceof Class<?> c ? c.getSimpleName()
64+
: beanOrClass != null ? beanOrClass.getClass().getSimpleName() : "?";
65+
logger.debug("Ignoring unknown property '{}' on {} (the peer is newer than this SDK, or off-spec)",
66+
propertyName, type);
67+
}
68+
p.skipChildren();
69+
return true;
70+
}
71+
72+
}
73+
2274
/**
2375
* Constructs a new JacksonAcpJsonMapper with the given ObjectMapper.
2476
* @param objectMapper the ObjectMapper to use. Must not be null.

‎acp-core/src/main/java/com/agentclientprotocol/sdk/json/JacksonAcpJsonMapperSupplier.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ public class JacksonAcpJsonMapperSupplier implements AcpJsonMapperSupplier {
1616

1717
@Override
1818
public AcpJsonMapper get() {
19-
return new JacksonAcpJsonMapper(new ObjectMapper());
19+
return new JacksonAcpJsonMapper(JacksonAcpJsonMapper.defaultObjectMapper());
2020
}
2121

2222
}

0 commit comments

Comments
 (0)