Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Update all uses of "_out" functions to inform caller of required buffer size when passed buffer is too small

Open
  • Is something wrong?
#163 2 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 2 days

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
25/100
Issue type
Feature
Clarity
Needs clarification
Activity status
Active
Tech stack
rust
Domain
cryptography

Research direction

Start by inventorying every _out and _final function in the repository and reading the existing error and buffer-handling conventions. Use the memory benches and compiled-assembly checks mentioned in the issue to assess returning Self from _final functions. Done means consistent recoverable buffer-too-small behavior, idempotent failures, and updated documentation across all affected APIs.

Written by the indexing model from the issue text.

Description

There is not currently a consistent way for a caller of an "_out" function (any function that writes its output into a caller-passed buffer argument) to determine the required size for the buffer, or to communicate an error back to the caller in a recoverable way.

The initial proposal here is, when the passed buffer is too small, all "_out" functions should return a "buffer too small" error enum, which includes the actual required size for the buffer for a retry of this API to succeed.

Using this pattern:

  1. allows callers mistakenly passing too small of a buffer to be given sufficient information to try again with a correctly-sized one
  2. allows callers wanting to check the size immediately to pass a zero-length buffer to trigger the same behaviour
  3. eliminates the need for an additional "_out_len()" function, taking identical parameters, whose sole purpose is to fulfill point 2

An edge case that needs to be examined is "_final" functions, which consume the called object. In this case, the caller would not be able to either probe the correct length, or retry for a failed attempt, without losing the object. The proposal here is for all final(self, ..) functions to return -> Result<, (SomeError, Self)>; ie return a tuple containing the error code and a clone of self. This would allow for error recovery on _final() APIs more broadly that only the "buffer too small" case, but it would be best to do some testing with the memory benches and/or Claude to check compiled assembly to see whether this would create an additional burden on the stack.

In addition, some functions may currently silently truncate the output when the provided output buffer is too small (e.g., Hash). My current thinking on this is that they should both provide the truncated output AND return an error indicating the output buffer was too small (using the new pattern). In the case that the caller was intending truncation, they can safely ignore the buffer error, and in the case that truncation was unexpected the caller will be made aware of the error. An alternative would be to decide that the truncation is just a bad idea and have Hash always return the full-length output, and the user can truncate afterwards if they so desire.

Note on implementation - ideally, all functions should return as early as possible on buffer-too-small. This avoids doing unnecessary work before returning, and (hopefully) avoids changes to object state that would need to be unwound before returning the error.

Acceptance Criteria:

  • check whether returning self in "_final" functions will consume additional stack memory, or cause any other unforeseen issues (if so, let's discuss here)
  • apply a consistent pattern for all "_out" functions in the repo
  • apply a consistent pattern for all "_final" functions in the repo
  • any buffer-too-small condition (whether as an error or as a zero-length check) is idempotent (ie does not change the object's state)
  • ensure all documentation is updated to reflect this behaviour
Dominant language
Rust
Stars
25
Forks
18
Avg merge
14d 10h
Merged PRs (30d)
5

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from bcgit/bc-rust

All issues in bcgit/bc-rust

Similar issues

More Rust issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.