Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

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

Aperta
  • Qualcosa non va?
#163 2 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 2 giorni

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
25/100
Tipo di issue
Funzionalità
Chiarezza
Da chiarire
Stato di attività
Attiva
Stack tecnologico
rust
Ambito
cryptography

Direzione di ricerca

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.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

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
Lingua principale
Rust
Stelle
25
Fork
18
Merge medio
14g 10h
PR unite (30g)
5

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di bcgit/bc-rust

Tutte le issue di bcgit/bc-rust

Issue simili

Altre issue su Rust

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.