Expose ByteString-based text envelope deserialization by Jimbo4350 · Pull Request #1158 · IntersectMBO/cardano-api

Jimbo4350 · 2026-03-26T16:57:54Z

Closes #556

Changelog

- description: |
    Expose deserialiseFromTextEnvelopeJSON and deserialiseFromTextEnvelopeJSONAnyOf
    which accept a raw ByteString, enabling text envelope deserialization without
    file I/O.
# uncomment types applicable to the change:
  type:
   - compatible     # the API has changed but is non-breaking
  # - feature        # introduces a new feature
  # - breaking       # the API has changed in a breaking way
  # - optimisation   # measurable performance improvements
  # - refactoring    # QoL changes
  # - bugfix         # fixes a defect
  # - test           # fixes/modifies tests
  # - maintenance    # not directly related to the code
  # - release        # related to a new release preparation
  # - documentation  # change in code docs, haddocks...
# uncomment at least one main project this PR is associated with
  projects:
   - cardano-api
  # - cardano-api-gen
  # - cardano-rpc
  # - cardano-wasm

Context

Addresses #556 — exposes key/text-envelope reading functions that work from a ByteString rather than requiring file I/O.

Adds two new public functions to Cardano.Api.Serialise.TextEnvelope:

deserialiseFromTextEnvelopeJSON :: HasTextEnvelope a => ByteString -> Either TextEnvelopeError a
deserialiseFromTextEnvelopeJSONAnyOf :: [FromSomeType HasTextEnvelope b] -> ByteString -> Either TextEnvelopeError b

These allow callers to deserialize keys (or any text-enveloped value) directly from a ByteString without going through file I/O. The existing readFileTextEnvelope and readFileTextEnvelopeAnyOf are refactored to use the new functions internally.

How to trust this PR

The new functions are straightforward compositions of existing Aeson.eitherDecodeStrict' and deserialiseFromTextEnvelope/deserialiseFromTextEnvelopeAnyOf.
The refactored readFile* functions are semantically identical — they just delegate to the new helpers.
The build passes with no warnings.

Checklist

Commit sequence broadly makes sense and commits have useful messages
New tests are added if needed and existing tests are updated
Self-reviewed the diff

Add deserialiseFromTextEnvelopeJSON and deserialiseFromTextEnvelopeJSONAnyOf which accept a raw ByteString, enabling text envelope deserialization without file I/O. Refactor readFileTextEnvelope and readFileTextEnvelopeAnyOf to use the new functions.

Copilot

Pull request overview

Exposes ByteString-based helpers for deserialising text envelopes from JSON, and refactors existing file-based readers to delegate to these helpers.

Changes:

Adds deserialiseFromTextEnvelopeJSON and deserialiseFromTextEnvelopeJSONAnyOf (ByteString → Either TextEnvelopeError …).
Refactors readFileTextEnvelope / readFileTextEnvelopeAnyOf to reuse the new helpers.
Re-exports the new functions from Cardano.Api.Serialise.TextEnvelope.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File	Description
cardano-api/src/Cardano/Api/Serialise/TextEnvelope/Internal.hs	Introduces new JSON-from-ByteString deserialisers and updates file readers to call them.
cardano-api/src/Cardano/Api/Serialise/TextEnvelope.hs	Re-exports the new deserialisation helpers from the public API module.

Copilot · 2026-03-26T17:10:05Z

+deserialiseFromTextEnvelopeJSON
+  :: HasTextEnvelope a
+  => ByteString -> Either TextEnvelopeError a
+deserialiseFromTextEnvelopeJSON bs = do
+  te <- first TextEnvelopeAesonDecodeError $ Aeson.eitherDecodeStrict' bs
+  deserialiseFromTextEnvelope te
+
+deserialiseFromTextEnvelopeJSONAnyOf
+  :: [FromSomeType HasTextEnvelope b]
+  -> ByteString
+  -> Either TextEnvelopeError b
+deserialiseFromTextEnvelopeJSONAnyOf types bs = do
+  te <- first TextEnvelopeAesonDecodeError $ Aeson.eitherDecodeStrict' bs
+  deserialiseFromTextEnvelopeAnyOf types te


These are new public(-reexported) API functions but they don’t have Haddock. Please add brief Haddock that explains: the input must be a JSON-encoded text envelope (UTF-8), this performs no file I/O, and the error behavior (TextEnvelopeAesonDecodeError for JSON parse failures vs. downstream deserialiseFromTextEnvelope* errors). This helps API consumers choose between readFile* and deserialiseFromTextEnvelopeJSON* correctly.

Copilot · 2026-03-26T17:10:06Z

+deserialiseFromTextEnvelopeJSON bs = do
+  te <- first TextEnvelopeAesonDecodeError $ Aeson.eitherDecodeStrict' bs
+  deserialiseFromTextEnvelope te


The JSON decode step is duplicated in both functions. Consider factoring out a small helper (e.g., decodeTextEnvelopeJSON :: ByteString -> Either TextEnvelopeError TextEnvelope) and then calling deserialiseFromTextEnvelope* on the result. This reduces duplication and keeps future changes to decoding/error-wrapping consistent.

Copilot · 2026-03-26T17:10:06Z

+deserialiseFromTextEnvelopeJSON
+  :: HasTextEnvelope a
+  => ByteString -> Either TextEnvelopeError a
+deserialiseFromTextEnvelopeJSON bs = do
+  te <- first TextEnvelopeAesonDecodeError $ Aeson.eitherDecodeStrict' bs
+  deserialiseFromTextEnvelope te
+
+deserialiseFromTextEnvelopeJSONAnyOf
+  :: [FromSomeType HasTextEnvelope b]
+  -> ByteString
+  -> Either TextEnvelopeError b
+deserialiseFromTextEnvelopeJSONAnyOf types bs = do
+  te <- first TextEnvelopeAesonDecodeError $ Aeson.eitherDecodeStrict' bs
+  deserialiseFromTextEnvelopeAnyOf types te


The JSON decode step is duplicated in both functions. Consider factoring out a small helper (e.g., decodeTextEnvelopeJSON :: ByteString -> Either TextEnvelopeError TextEnvelope) and then calling deserialiseFromTextEnvelope* on the result. This reduces duplication and keeps future changes to decoding/error-wrapping consistent.

Suggested change

deserialiseFromTextEnvelopeJSON

:: HasTextEnvelope a

=> ByteString -> Either TextEnvelopeError a

deserialiseFromTextEnvelopeJSON bs = do

te <- first TextEnvelopeAesonDecodeError $ Aeson.eitherDecodeStrict' bs

deserialiseFromTextEnvelope te

deserialiseFromTextEnvelopeJSONAnyOf

:: [FromSomeType HasTextEnvelope b]

-> ByteString

-> Either TextEnvelopeError b

deserialiseFromTextEnvelopeJSONAnyOf types bs = do

te <- first TextEnvelopeAesonDecodeError $ Aeson.eitherDecodeStrict' bs

deserialiseFromTextEnvelopeAnyOf types te

decodeTextEnvelopeJSON :: ByteString -> Either TextEnvelopeError TextEnvelope

decodeTextEnvelopeJSON bs =

first TextEnvelopeAesonDecodeError $ Aeson.eitherDecodeStrict' bs

deserialiseFromTextEnvelopeJSON

:: HasTextEnvelope a

=> ByteString -> Either TextEnvelopeError a

deserialiseFromTextEnvelopeJSON bs =

decodeTextEnvelopeJSON bs >>= deserialiseFromTextEnvelope

deserialiseFromTextEnvelopeJSONAnyOf

:: [FromSomeType HasTextEnvelope b]

-> ByteString

-> Either TextEnvelopeError b

deserialiseFromTextEnvelopeJSONAnyOf types bs =

decodeTextEnvelopeJSON bs >>= deserialiseFromTextEnvelopeAnyOf types

Extract shared JSON decoding into decodeTextEnvelopeJSON and add Haddock documentation to the new public functions.

palas

👍

Expose ByteString-based text envelope deserialization

Jimbo4350 marked this pull request as ready for review March 26, 2026 17:03

Jimbo4350 force-pushed the expose-bytestring-key-reading branch from e03455c to 6ebdec2 Compare March 26, 2026 17:03

Copilot AI review requested due to automatic review settings March 26, 2026 17:03

Jimbo4350 requested review from CarlosLopezDeLara, carbolymer, dcoutts, disassembler, erikd, kevinhammond, newhoggy and palas as code owners March 26, 2026 17:03

Copilot AI reviewed Mar 26, 2026

View reviewed changes

Address review feedback: factor out decodeTextEnvelopeJSON, add Haddock

344355c

Extract shared JSON decoding into decodeTextEnvelopeJSON and add Haddock documentation to the new public functions.

carbolymer approved these changes Mar 26, 2026

View reviewed changes

Copilot started reviewing on behalf of Jimbo4350 March 26, 2026 20:56 View session

palas approved these changes Mar 27, 2026

View reviewed changes

Jimbo4350 added this pull request to the merge queue Mar 27, 2026

Merged via the queue into master with commit 846306e Mar 27, 2026
34 checks passed

Jimbo4350 deleted the expose-bytestring-key-reading branch March 27, 2026 11:58

palas pushed a commit that referenced this pull request Mar 27, 2026

Merge pull request #1158 from IntersectMBO/expose-bytestring-key-reading

6b52703

Expose ByteString-based text envelope deserialization

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Expose ByteString-based text envelope deserialization#1158

Expose ByteString-based text envelope deserialization#1158
Jimbo4350 merged 2 commits into
masterfrom
expose-bytestring-key-reading

Jimbo4350 commented Mar 26, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 26, 2026

Uh oh!

Copilot AI Mar 26, 2026

Uh oh!

Copilot AI Mar 26, 2026

Uh oh!

palas left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

Jimbo4350 commented Mar 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changelog

Context

How to trust this PR

Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

palas left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Jimbo4350 commented Mar 26, 2026 •

edited

Loading