kt_errors

type ConversionOption interface {
	// contains filtered or unexported methods
}

type Fault interface {
	error
	fmt.Stringer

	// Returns the type of this error.
	GetKind() FaultKind
	// Returns the message template unresolved (so with possible variable placeholders in it as is)
	GetMessageTemplate() string
	// Returns the message - with resolved variable placeholders from labels.
	GetMessage() string
	// Returns the message template meant for the given audience unresolved (so with possible variable placeholders in it as is).
	// If there is no template for the requested audience, empty string is returned.
	GetMessageTemplateForAudience(forAudience string) string
	// Returns the message meant for the given audience - with resolved variable placeholders from labels.
	// If there is no template for the requested audience, empty string is returned.
	GetMessageForAudience(forAudience string) string
	// Returns map view of message templates by audiences.
	// **Note:** This always makes and returns a copy so use it accordingly!
	GetMessageTemplatesByAudience() map[string]string
	// Tells if this error is suitable to leave the private boundary or not (public = no implementation details leaking for sure).
	IsPublic() bool
	// We extend the error with the possibility of check if error is retryable.
	IsRetryable() bool
	// Returns all associated error codes.
	// **Note:** This always makes and returns a copy so use it accordingly! If possible use `HasErrorCode()` instead.
	GetErrorCodes() []string
	// Tells if this error is carrying ANY of the listed error codes or not.
	HasErrorCode(codes ...string) bool
	// Returns the Cause of this error - which is another (any) error.
	GetCause() error
	// Errors can carry a set of labels. This returns them all.
	// **Note:** This always makes and returns a copy so use it accordingly! If you can use `GetLabel()` method instead.
	GetLabels() map[string]any
	// Returns a specific label if Fault has it - or Nil if does not have it. You can also take and use the returned `found` flag.
	GetLabel(key string) (value any, found bool)
	// Error supports tracking the call chain. You can optionally use this (or not, up to you). But if you do, this method returns the content of this.
	// The `GetSource()` method returns where the error was born - you can set this with the builder `WithSource()` method. Then as the error bubbles
	// up, each hop can use the `AddCallerToCallStack()` method. This is how call stack is building up - what you can retrieve with this method.
	// The last element is the source - returned by `GetSource()`. Then the previous element is who called the source. And so on. The first element
	// is the point who started the whole call chain.
	GetCallStack() []string
	// Tells you where the error is originated from. We do it the easiest way: we can put this into a string :-) That's it.
	// See the error builder `WithSource()` method! If you invoke `GetCallStack()` method, this will be actually the deepest element on the stack.
	GetSource() string

	// You can add a caller to the call stack. You can do this when you capture an error like this because it is returned to you.
	// As you can see, if you want you can pass in multiple string elements. If you do so, they will be automatically concatenated
	// using "." separator. Why is it useful? Because you can do something like this: `AddCallerToCallStack("mypackage", "mymethod")` e.g.
	AddCallerToCallStack(caller ...string)
	// As the error bubbles upwards in higher layers it is often a requirement you want to add a bit more context to it. In classic error handling this
	// often ends in building mapping-functions and you raise a completely new error attaching the original one as Cause or similar tacticts. However
	// this leads to lots of boilerplate code and often results in mistakes especially if you have multiple layers in your code and each one is doing the same.
	//
	// So instead enforcing this strategy `Fault` offers a simpler way. You do not need to create a brand new error just to add your context info but you
	// can simply extend it in place and let the original prublom bubble upwards with all the details it already has! Basically, you simply extend the
	// information with those details you know in the higher level layer only.
	//
	// Using this method you can do this. You can prepend (prefix) to the messageTemplate of the error with a piece of string.
	// It is really a prefix - imagine a simple concatenation! So you need to include separators, white-spaces etc at the end of your prefix str!
	// If you send in empty str nothing will happen.
	AddContextToMessage(msgTemplatePrefix string)
	// Same as `AddContextToMessage()` (read its comment!) but with this one you can extend the audience facing messages with more context. If the audience you
	// refer to with `forAudience` does not exist it will be created. And maybe good to know that the `msgTemplatePrefix` value in this case will be trimmed on
	// the right side (not just whitespaces but also ':' and '-' characters) so no need to worry about strange white spaces.
	// If you send in empty str in any parameters nothing will happen.
	AddContextToAudienceMessage(forAudience string, msgTemplatePrefix string)
	// Please read the comment of `AddContextToMessage()` method! You get a better understanding on the motivation and problem then.
	// With this method - as the error bubbles upwards - highler level layers might want to extend it with their custom error codes. You can do it in one go by
	// adding multiple at once.
	AddErrorCodes(c ...string)
	// Please read the comment of `AddContextToMessage()` method! You get a better understanding on the motivation and problem then.
	// As the error bubbles upwards higher level layers might want to extend it with more labels - especially since we have `AddContextToMessage()` and
	// `AddContextToAudienceMessage()` which can introduce new {var}-s into the messages.
	AddLabel(key string, value any)
	// Please read the comment of `AddContextToMessage()` method! You get a better understanding on the motivation and problem then.
	// As the error bubbles upwards higher level layers might want to extend it with more labels - especially since we have `AddContextToMessage()` and
	// `AddContextToAudienceMessage()` which can introduce new {var}-s into the messages.
	AddLabels(labels map[string]any)

	// Returns the HTTP status code you should use in the response if you fail from this Fault.
	// Note: this is a wrapper around the utility function `GetHttpStatusCodeForFault()` - you can use that if you prefer that form instead.
	// IMPORTANT! In case the `Fault` is not public then it is always 500 INTERNAL ERROR - otherwise it is determined from the attributes and the kind of the
	// Fault.
	GetHttpStatusCode() int
	// Returns the gRPC status code you should use in the response if you fail from this Fault.
	// Note: this is a wrapper around the utility function `GetGrpcStatusCodeForFault()` - you can use that if you prefer that form instead.
	// IMPORTANT! In case the `Fault` is not public then it is always INTERNAL error - otherwise it is determined from the attributes and the kind of the Fault.
	GetGrpcStatusCode() codes.Code

	// Returns the natural (most human readable) JSON form of this Fault - can come handy if you build e.g. HTTP APIs and you need quickly return an error
	// response. Check the available `SerializationOption`s you can use optionally!
	// This method returns a JSON like:
	//
	//    {
	//       "kind": "<the Kind>",
	//       "message": "<the default MessageTemplate or given 'forAudience' template - raw or resolved>",
	//       "isRetryable": true/false,
	//       "errorCodes": ["the", "error", "codes"],
	//       "labels": {
	//           "key1": <value1>,
	//           "key2": <value2>,
	//           ...
	//        }
	//    }
	//
	// As you see really internal details like "cause" or "call stack" etc are absolutely not revealed.
	//
	// IMPORTANT! To prevent accidental data leak this serialization only renders public Faults! If the Fault is non-public you get back empty
	// values only - unless you explicitly use `AllowNonPublicSerialization` option!
	//
	// Parameters:
	// - `forAudience` - if you pass empty string you get back the default MessageTemplate - otherwise the specific audience message comes back
	ToNaturalJSON(forAudience string, options ...SerializationOption) ([]byte, error)

	// Just like `ToNaturalJSON()` this also returns a JSON representation but this one returns the "message" and "messagesByAudience"
	// separately - revealing more internal structure.
	//
	// However really internal details like "cause" or "call stack" etc are absolutely not revealed even in this form.
	//
	// IMPORTANT! To prevent accidental data leak this serialization only renders public Faults! If the Fault is non-public you get back empty
	// values only - unless you explicitly use `AllowNonPublicSerialization` option!
	ToFullJSON(options ...SerializationOption) ([]byte, error)
}

type FaultBuilder struct {
	// contains filtered or unexported fields
}

type FaultKind = string

type SerializationOption int