Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

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

Abierto
  • ¿Algo no está bien?
#163 2 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 2 días

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
25/100
Tipo de issue
Nueva funcionalidad
Claridad
Necesita aclaración
Estado de actividad
Activo
Stack tecnológico
rust
Área
cryptography

Línea de trabajo

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.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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
Lenguaje dominante
Rust
Estrellas
25
Forks
18
Merge medio
14 d 10 h
PR fusionados (30 d)
5

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de bcgit/bc-rust

Todos los issues de bcgit/bc-rust

Issues similares

Más issues de Rust

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.