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

未关闭
  • 哪里不对？
#163 4 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

维护者通常 1 天内回复

还没有人认领这个 Issue。

评估

难度
5/5
预计耗时
一周以上
新手友好度
25/100
Issue 类型
功能
描述清晰度
需要澄清
活跃度
活跃
技术栈
rust
领域
cryptography

调研方向

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.

由索引模型根据 Issue 内容生成。

描述

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
主要语言
Rust
星标
25
派生
18
平均合并
56 分钟
30 天内合并 PR
1

环境准备

从这里开始

  1. 先读完整个 Issue，再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库，在一个分支上完成修改。
  4. 提交 Pull Request，并在描述里引用这个 Issue 编号。

bcgit/bc-rust 的其他 Issue

查看 bcgit/bc-rust 的全部 Issue

相似的 Issue

更多 Rust Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。