RFC: Error Handling Safe/Must [Accepted]

[42atomys]

Introduction

This RFC addresses the need for improved error handling mechanisms in Go templates within the go-sprout/sprout project. The goal is to ensure that template functions can operate without causing panics, with an emphasis on providing both safe and must operational modes.

---

Important

Actual implementation selected are available here https://github.com/orgs/go-sprout/discussions/32#discussioncomment-10520650

---

Motivation

Currently, unexpected errors in functions within templates can lead to panics, disrupting the rendering process and potentially causing system instability. By providing more robust error handling capabilities, developers can choose between failing silently and returning default values, or explicitly handling errors, depending on their specific needs and the application context.

Proposal

We propose two distinct operational modes for functions used in templates:

• Safe Mode: Functions return a default value upon encountering an error, allowing the template rendering to proceed uninterrupted. This mode is intended for scenarios where continuity is crucial, even at the cost of losing some data fidelity.
• Must Mode: Functions return both a value and an error. In cases of errors, they are managed using the default error handler provided by Go's template package, enhancing error visibility and manageability.

To implement these modes, the following solutions are proposed:

1. Error Handler Integration: Introduce an ErrHandler that can be attached to the functionHandler. This would allow developers to use a default handler without configuration or to customize their own error handling to achieve greater autonomy and control.

// ErrorHandler defines an interface for handling errors.
// It offers methods to handle raw errors and string messages as errors,
// with support for custom handler options.
// Returns:
// - error: The processed error (when is safe mode, it may be nil).
// - bool: A boolean indicating if an error was present (usefull for safe mode).
type ErrorHandler interface {

	// Handle processes an error according to implemented strategies and options.
	// It returns the error and a boolean indicating if the error was present. This
	// double return value is useful for checking if an error occurred without
	// taking care of error handling.
	Handle(err error, opts ...RuntimeOption) (error, bool)

	// HandleMessage processes a string message as an error, applying the same
	// strategies and options as Handle if wanted.
	HandleMessage(msg string, opts ...RuntimeOption) (error, bool)
}

2. Function Naming Conventions: Utilize the loader mechanism to register functions like safeToInt and mustToInt from a single function definition in the library (in this example toInt), written in the "Must" style (e.g., func(...any)(any, error)). Also, provide a default mode to reduce the need for specifying "safe" or "must" each time, such as defaulting to "must" mode where calling toInt in template would execute mustToInt.

This is an arbitrary example of how to set the default mode, the implementation will be

// sprout.SetTheDefaultModeTo(sprout.MustMode)
{{ toInt "asd" }} // This will execute mustToInt and return an error
{{ mustToInt "asd" }} // This will execute mustToInt and return an error
{{ safeToInt "asd" }} // This will execute safeToInt and return a default value (0)

// sprout.SetTheDefaultModeTo(sprout.SafeMode)
{{ toInt "asd" }} // This will execute safeToInt and return a default value (0)
{{ safeToInt "asd" }} // This will execute safeToInt and return a default value (0)
{{ mustToInt "asd" }} // This will execute mustToInt and return an error 

3. Code Generation: Use Go's go generate tool to define functions on the Sprout side, automatically generating them within the Sprout library and making them available for use at build time. This approach, however, limits external functions from utilizing the "safe/must" error management btw.

//go:generate go run github.com/go-sprout/sproutgen -mode=safe|must -func=toInt

// From the initial definition:
func (fh *FunctionHandler) toInt(...any)(any, error) {
  // Implementation
}

// This will generate the following functions:
func (fh *FunctionHandler) SafeToInt(...any)(any)
func (fh *FunctionHandler) MustToInt(...any)(any, error)

Benefits

• Flexibility: Developers can choose the error handling strategy that best suits their application's needs.
• Reliability: Enhances the stability of template rendering by reducing the likelihood of panics.
• Visibility: Improves error management and diagnostics, facilitating easier debugging and maintenance.

Drawbacks

• Complexity: Increases the complexity of the function loader and the template setup.
• Maintenance Overhead: Code generation and custom error handlers require additional maintenance and oversight.

Open Questions

• Default Behavior: What should the default behavior be for error handling if not explicitly specified by the developer? Must for me
• Performance Impact: What are the performance implications of these error handling mechanisms on template rendering?
• Customization Limits: How much customization should be allowed without introducing excessive complexity?

Conclusion

Your insights and comments are crucial for refining and improving the proposed feature, ensuring it meets the needs and expectations of a broad range of developers. Please share your thoughts on the proposed functionalities, any concerns you might have, and any additional features you believe should be considered. This collaborative approach is essential for us to achieve a robust and versatile implementation. We look forward to your contributions and are excited to see how together we can enhance the capabilities of sprout.

[maitredede]

Hello,

Some thoughts :

• Data validation is the biggest part of applications to ensure processing goes fine. A template rendering engine should not validate data, only process it.
• In a final document, missing data due to invalid convertion for template engine can lead to business impacts (ex: a reminder email missing the part that your house will be seized because you didn't pay your 200$ bill, missing the "200$" part because "200 is a string and not a float32")
• Developpers are lazy (so am I) : they don't fix errors until they must or if they don't see them. That is why I hate when code automagically handles errors by itself by not knowing there was an error, when using minimum code.

So, my answers :

• Default behavior should be "must": with minimal code, the errors can be caught early. It feels more safe for a developper to know that there is an error to fix, than "it does not work" (missing data because of "safe" default mode). It should be the developper resonsibility to know that he can activate a "safe" default mode, and know that rendered data can be missing.
• Performance impact : for most usages (small datasets), performance losses are negligible. It may be two if calls. For example :

func toInt(value any) (int,error) {
    if(defaultMode == must) {
        return  mustToInt(value)
    }
    return safeToInt(value)
}

func mustToInt(value any) (int, error) {
    intVal,err := safeToInt(value);
    if err != nil{
        panic(err)
    }
    return intVal, nil
}

func safeToInt(value any) (int,error) {
    // conversion...
    if err == nil {
        return intVal, nil
    } 
    return 0, err
}

• Customization limit : the limit is when maintaining the library becomes impossible because of current architecture. There should be a point where a library is considered "mature", and should not add more functionnalities without redesigning entire library (and breaking changes). For example, adding the safe/must for functions with retro-compatible behaviors (how does sprig work with failing conversions ?) is ok. Function registries are also a good idea to reduce code size, and also to allow customization (we could rewrite standard functions, to extend conversion behavior, or be more fault tolerent). But adding too much customization may fall out of the scope of the original library. For example, a template rendering library should not do http requests to download data, it is not the goal of the library.

[ccoVeille]

My reply won't be as detailed as yours, but I agree with you.

The templating system should not do magical things.

I don't think it's the role of the template to do things such as safeInt, or mustInt

I would expect to be able to use something like that

{ whatever(17) | fallback "error"} 

[42atomys]

In my initial research, I tried to implement something like:

{{ safe(functionFail) }}
// or
{{ functionFail | fallback }}

However, due to how the Go template engine is designed, we cannot do that without reworking the template engine itself. This is because when a function returns an error, the template automatically stops processing the rest of the line or template.

I agree that MUST should be the default. As a developer, I want to know when I've made a mistake before a user tells me, "This doesn't work."

Maintaining a registry (for myself and future developers) with safeToInt, mustToInt, and toInt functions feels cumbersome. So, as a first step, I used go generate to automatically generate safe and must versions of a function using AST, avoiding runtime costs. However, the trade-off between load size and performance gain is negligible (~50ns/op).

---

At this point, I think the "best" compromise is to use the same system as Function Notices. At runtime, we check if a function starts with safe, and in that case—and only in that case—create a wrapper (for those curious, here is the implementation for notices) to:

1. Log the error but continue rendering.
2. Silence all errors.
3. Let user decide between 1 or 2 with configuration.

Let me know what you think about this approach.

[42atomys]

UPDATE: Solution have a dedicated page on documentation:
https://docs.atom.codes/sprout/~/changes/1eETtqCYtVeEPVLnbGs0/features/safe-functions