mist

func (*Context) BindJSON ¶

func (c *Context) BindJSON(val any) error

BindJSON deserializes the JSON-encoded request body into the provided value. It is often used in the context of HTTP handlers to parse incoming JSON data into a Go data structure.

Parameters:

• 'val' is a pointer to any Go data structure into which the JSON body of the request will be decoded. This argument must be a non-nil pointer that points to an allocatable or allocated value so that the JSON package can populate the fields of the structure. It must not be nil, as passing nil does not provide a storage location for the decoded data.

The function execution involves the following steps:

1. It checks if 'val' is nil. If it is, no storage is allocated for the JSON data to be decoded into, so it returns an error using 'errs.ErrInputNil()', indicating that the input value cannot be nil.
2. It checks if 'c.Request.Body' is nil. If the body is nil, there is no data to decode, and it returns an error using 'errs.ErrBodyNil()', signaling that there is no request body to parse.
3. It creates a new JSON decoder for the request body and performs the decoding operation using 'decoder.Decode(val)'. If the JSON data in the request body is not well-formed or does not match the expected structure of 'val', json.Decoder will return a relevant error to inform the call site about the issue.

Return Value: - If the decoding is successful, it returns 'nil', indicating that the JSON data has been successfully bound to 'val'. - If an error occurs during decoding, it returns the error, indicating an issue with input validation or the decoding process.

Usage:

• This method is useful when you want to automatically handle the parsing of JSON data into a Go data structure from an HTTP request. It abstracts away the low-level streaming and decoding of JSON.

Example: - To bind the JSON body of an HTTP request to a struct:

type UserInput struct {
   Name  string `json:"name"`
   Email string `json:"email"`
}

var userInput
if err := c.BindJSON(&userInput); err != nil {
   // handle the error (e.g., send an HTTP 400 Bad Request response)
}

Note:

• The 'BindJSON' method should be called before accessing the request body by any other means, as the body is an io.ReadCloser and can generally only be read once. Reading the body elsewhere before calling 'BindJSON' will likely result in an EOF error.

func (*Context) BindJSONOpt ¶

func (c *Context) BindJSONOpt(val any, useNumber bool, disableUnknown bool) error

BindJSONOpt deserializes the JSON-encoded request body into the provided value with options to use JSON numbers and disallow unknown fields. This function extends the BindJSON method by providing additional decoding options that can be enabled as needed.

Parameters:

• 'val' is a pointer to any Go data structure into which the JSON body of the request will be decoded. It must be a non-nil pointer, so it can be populated with decoded data. Passing a nil pointer will result in an error since there would be no allocated structure to decode the data into.
• 'useNumber' is a boolean option that, when set to true, tells the decoder to decode numbers into an interface{} as a json.Number instead of as a float64. This is useful when precision for large integers is necessary or when the numeric values need to be unmarshalled into a specific typed variable later.
• 'disableUnknown' is a boolean option that, when set to true, causes the decoder to return an error if it encounters any unknown fields in the JSON data that do not match any fields in the target Go data structure. This can be useful for strict input validation.

The function performs the following steps:

1. It verifies that 'val' is not nil. If it is nil, it returns an error signaling that a valid pointer is required.
2. It checks if 'c.Request.Body' is nil, which would indicate that there is no data to decode, and returns an error if this is the case.
3. It initializes a JSON decoder for the request body. The decoder then checks the 'useNumber' and 'disableUnknown' options to configure its behavior accordingly: a. If 'useNumber' is true, it configures the decoder to treat numbers as json.Number types instead of defaulting them to float64. b. If 'disableUnknown' is true, it configures the decoder to reject unknown fields.
4. It attempts to decode the JSON request body into 'val'. If the decoding is unsuccessful (for example, due to JSON syntax errors, mismatch between the JSON data and 'val' structure, etc.), it returns the error resulting from the decoder.

Return Value: - Returns 'nil' if the JSON request body has been successfully decoded into 'val'. - Returns an error if 'val' is nil, if there is no request body, or if the JSON decoding process encounters an error.

Usage: - This method is useful for controlling the JSON decoding process in HTTP handlers where there may be a need for more strict or lenient JSON parsing.

Example: - To bind a JSON body to a struct with strict type preservation and unknown field rejection:

type UserInput struct {
   Name string `json:"name"`
   Age  json.Number `json:"age"`
}

var userInput
err := c.BindJSONOpt(&userInput, true, true)
if err != nil {
   // handle the error (e.g., send an HTTP 400 Bad Request response)
}

Note:

• Similar to BindJSON, BindJSONOpt should be called before any other form of accessing the request body is performed, as it is an io.ReadCloser that allows for a single read operation. This means that calling BindJSONOpt after the body has been read will likely result in an EOF error.

func (*Context) FormValue ¶

func (c *Context) FormValue(key string) StringValue

FormValue extracts a value from the form data in an HTTP request based on the given key. It parses the URL-encoded form data (both in the URL query string and the request body) and retrieves the value associated with the provided key.

Parameters: - 'key' is a string representing the name of the form value to be retrieved from the HTTP request.

The function performs the following actions:

1. It calls 'c.Request.ParseForm()' to parse the request body as a URL-encoded form. This is necessary to populate 'c.Request.Form' with the form data. This method also parses the query parameters from the URL, merging them into the form values. If parsing fails (for example, if the body can't be read, is too large, or if the content type is not application/x-www-form-urlencoded), an error is returned.
2. If 'ParseForm()' returns an error, the function creates a 'StringValue' instance with an empty string for 'val' and the parsing error for 'err'. It then returns this 'StringValue' containing the error information.
3. If 'ParseForm()' succeeds, 'c.Request.FormValue(key)' is used to retrieve the first value for the specified key from the merged form data. A 'StringValue' instance is then returned with the retrieved value and 'nil' for the error.

Return Value:

• A 'StringValue' instance is always returned. This struct contains two fields: a. 'val' which is the string value retrieved from the form data. b. 'err' which captures any error that may have occurred during the parsing of the form data.

Usage: - This method is intended to be used in HTTP handlers when you need to access form values sent in an HTTP request.

Example: - To retrieve a form value named "email" from an HTTP request:

email := c.FormValue("email")
if email.err != nil {
   // handle the error (e.g., send an HTTP 400 Bad Request response)
}
// Use email.val as the required string value for "email".

Note:

• The 'FormValue' method does not handle multiple values for the same key. It only retrieves the first such value.
• Calling 'FormValue' multiple times on the same request is safe as it does not reparse the form data. The form data is parsed only once, and subsequent calls will retrieve values from the already parsed form.
• The 'ParseForm' method can only parse the request body if the method is "POST" or "PUT" and the content type is "application/x-www-form-urlencoded". For other HTTP methods or content types, the body will not be parsed, but URL query parameters will still be available.

Considerations: - Ensure that the 'ParseForm' method is not called before any other method that might consume the request body, as the request body is typically read-only once.

func (*Context) PathValue ¶

func (c *Context) PathValue(key string) StringValue

PathValue retrieves a value from the path parameters of an HTTP request based on the given key. The path parameters are typically extracted from the URL path, where they are defined by the routing patterns used in the application.

Parameters: - 'key': A string representing the name of the path parameter to be retrieved.

The function performs the following actions:

1. It checks if the map 'c.PathParams' contains the key provided in the method parameter. 'c.PathParams' is expected to be populated with key-value pairs where keys correspond to path parameter names defined in the URL pattern, and values are the respective parameters extracted from the actual request URL.
2. If the key is present in 'c.PathParams', it retrieves the corresponding value, wraps it in a 'StringValue' struct by setting the 'val' field to the retrieved value and 'err' field to nil, and then returns it.
3. If the key is not found, it means the requested path parameter is not present in the request URL. In this case, the method returns a 'StringValue' struct with 'val' set to an empty string and 'err' set to an error instance that typically indicates the absence of the key.

Return Value:

• A 'StringValue' struct that contains the value associated with the provided key ('val') and an error field ('err'). If the key is not present, the 'err' field contains an appropriate error while 'val' is an empty string.

Usage: - This method is useful in web server routing where URL paths may contain parameters that need to be extracted and used within the application logic.

Example: - Assuming a URL pattern like "/users/:id" where :id is a path parameter:

userID := c.PathValue("id")
if userID.err != nil {
   // handle the error (e.g., send an HTTP 404 Not Found response)
}
// Use userID.val as the required user ID string value.

Note:

• The method assumes that 'c.PathParams' has already been populated with the correct path parameters before calling 'PathValue'. In a typical web server implementation, this population is done during the routing process, before the request handler is invoked.
• The 'PathParams' may hold multiple path parameters depending on the URL pattern; 'PathValue' method is responsible for extracting a single parameter by key.
• If the same key would be present multiple times in 'c.PathParams', this method would return the first instance of the value associated with the key.

Considerations:

• When working with frameworks or routers that facilitate path parameter extraction, ensure the router is correctly configured to parse and store the path parameters before calling this method.

func (*Context) QueryValue ¶

func (c *Context) QueryValue(key string) StringValue

QueryValue retrieves the first value associated with the specified key from the URL query parameters of an HTTP request.

Parameters: - 'key' is the string that specifies the key in the query parameter that we want to retrieve the value for.

This function operates as follows:

1. Checks if 'c.queryValues' is already populated. If it is not, it initializes it with the parsed query parameters obtained by calling 'c.Request.URL.Query()'. This method parses the raw query from the URL and returns a map of the query parameters.
2. It looks for the given 'key' in 'c.queryValues' to see if it exists. The values are stored in a slice of strings because URL query parameters can have multiple values.
3. If the key does not exist in the map, it implies that the parameter was not supplied in the query string. In this case, the function returns a 'StringValue' struct with an empty string for the 'val' field and an 'ErrKeyNil' error for the 'err' field.
4. If the key is present, the function returns a 'StringValue' struct with the first value associated with the key and 'nil' for the 'err' field.

Return Value:

• A 'StringValue' struct is always returned. It contains: a. 'val', the value associated with the provided key from the query parameters. b. 'err', an error if the key is not found in the query parameters.

Usage: - The method is ideal when you need to obtain individual query parameters from an HTTP request without parsing the entire URL query string manually.

Example: - To retrieve a query parameter named "page" from an HTTP request:

page := c.QueryValue("page")
if page.err != nil {
   // handle the error (e.g., the "page" query parameter was not provided)
}
// Use page.val to work with the value of "page".

Note:

• This function only retrieves the first value for the specified key even if there are multiple values for that key.
• 'c.queryValues' is cached after its first use, which improves performance when accessing multiple query parameters since it avoids reparsing the query string of the URL.
• It is important to correctly handle the error scenario since a missing key in the query parameters can affect application logic.

Considerations: - While handling query data, consider the URL's sensitivity and the possibility of multiple values. Always validate and clean data from URL queries to ensure security.

func (*Context) Render ¶

func (c *Context) Render(templateName string, data any) error

Render processes a template and populates it with dynamic data provided by the 'data' parameter. The method first attempts to render the specified template by calling the rendering engine bound to the context.

Parameters:

• 'templateName' is the name of the template that should be rendered. It is expected that this template has been defined and is recognizable by the template engine.
• 'data' is an interface{} type, which means it can accept any value that conforms to Go's empty interface. This is the dynamic content that will be injected into the template during rendering.

The rendered template output is captured and assigned to 'c.RespData'. This output will typically be HTML or another text format suitable for the client's response.

If the rendering operation is successful, the response status code is set to HTTP 200 (OK) indicating the request has been successfully processed and the client can expect valid content.

If an error occurs during the rendering operation (such as if the template is not found, or if there is a problem with the template's syntax), the response status code is set to HTTP 500 (Internal Server Error), and the error is returned to the caller. This error should be handled appropriately by the caller, possibly by logging it or presenting a user-friendly error message to the end-user.

Return Value: Returns 'nil' if rendering succeeds without any error, otherwise an error object describing the rendering failure is returned.

func (*Context) RespJSON ¶

func (c *Context) RespJSON(status int, val any) error

RespJSON sends a JSON-formatted response to the client with a specified HTTP status code. It converts the provided value to JSON, sets the response headers, and writes the JSON data to the response.

Parameters:

• 'status' is an integer that represents the HTTP status code to send with the response. Standard HTTP status codes should be used (e.g., 200 for OK, 400 for Bad Request, 404 for Not Found, etc.).
• 'val' is an interface{} (any type) that holds the data to be serialized into JSON. This can be any Go data structure such as structs, slices, maps, etc. The value provided must be a valid input for the json.Marshal function, which means it should be able to be encoded into JSON. Non-exported struct fields will be omitted by the marshaller.

This function performs several actions:

1. It uses the 'json.Marshal' function to serialize the 'val' parameter into a JSON-formatted byte slice 'data'. If marshaling fails, it returns the resultant error without writing anything to the response.
2. Assuming marshaling is successful, it sets the "Content-Type" header of the response to "application/json" to inform the client that the server is returning JSON-formatted data.
3. It sets the "Content-Length" header to the length of the serialized JSON data, which helps the client understand how much data is being transmitted.
4. It writes the HTTP status code to the response using WriteHeader(status). This must be done before writing the response body.
5. Lastly, it assigns the JSON data to 'c.RespData' and the status code to 'c.RespStatusCode' for later use or inspection.

Return Value: - If the JSON serialization and writing to the response are successful, it returns 'nil', indicating that the operation completed without error. - If an error occurs during JSON serialization, the error is returned, and no further action is taken.

Usage: - This method is designed to be used in HTTP handler functions where a JSON response is needed. It abstracts away the common tasks of JSON serialization, header setting, and response writing.

Example: - To send an object with an OK (200) status code:

data := map[string]string{"status": "success"}
err := c.RespJSON(http.StatusOK, data)
if err != nil {
   log.Printf("Error sending JSON response: %v", err)
   // handle the error, like sending a 500 Internal Server Error status code
}

Note:

• It is important to note that once the 'WriteHeader' method is called, it's not possible to change the response status code or write any new headers. Also, care must be taken to ensure that 'RespJSON' is not called after the response body has started to be written by other means, as this would result in an HTTP protocol error.

func (*Context) RespJSONOK ¶

func (c *Context) RespJSONOK(val any) error

RespJSONOK sends a JSON response with an HTTP status code 200 (OK) to the client. This is a convenience method that wraps around the more general 'RespJSON' method, abstracting the common case of responding with an OK status.

Parameters:

• 'val' is the data of any type that will be serialized into JSON format. The 'val' can be any Go data structure, including structs, maps, slices, and primitive types. It is important that the 'val' can be marshaled into JSON; otherwise, the serialization will fail.

Internally, 'RespJSONOK' calls the 'RespJSON' method on the same context instance 'c', passing in 'http.StatusOK' as the status code and 'val' as the value to be serialized.

The 'RespJSON' method handles the serialization of 'val' to JSON, sets the "Content-Type" response header to "application/json", and writes the JSON-encoded data to the response along with the provided HTTP status code.

Return Value: - If the serialization into JSON is successful and the response is written to the client, it returns 'nil' indicating no error occurred. - In case of an error during JSON marshaling or writing to the response, it returns an error detailing the issue encountered.

Usage:

• This method is typically used within an HTTP handler function when the server needs to send a JSON response back to the client with a 200 OK status code. This is usually the case when a request has been processed successfully, and server needs to inform the client of the success, often with accompanying data.

Example: - To send a simple success message in JSON format:

type response struct {
   Message string `json:"message"`
}

resp := response{Message: "Data processed successfully"}
err := c.RespJSONOK(resp)
if err != nil {
   // handle error
}

Note: - This method should be called after all response headers and status codes are set, and before any calls to write body content directly, as it will write data to the body and set headers.

func (*Context) SetCookie ¶

func (c *Context) SetCookie(ck *http.Cookie)

SetCookie adds a Set-Cookie header to the response of the current HTTP context. This method is used to send cookies from the server to the client's web browser.

Parameters: - 'ck' is a pointer to an 'http.Cookie' object which represents the cookie you want to set. This object includes various fields that define the properties of a cookie, such as Name, Value, Path, Domain, Expires, and so on.

This function does not return any value or error, as it directly manipulates the HTTP headers of the response. It's essential to call SetCookie before writing any response body to the client because HTTP headers cannot be modified after the body starts to be written.

'http.SetCookie' is a standard library function that ensures the correct formatting of the Set-Cookie header. When calling this method, 'c.ResponseWriter' is used to gain access to the response writer associated with the current HTTP request handled by the context 'c'.

Usage:

• This method is typically called within an HTTP handler function where you have an instance of the Context 'c' available. It is part of managing session data, sending tracking cookies, or setting any other kind of cookie data required by the application.

Example: - To set a session cookie with a session identifier:

sessionCookie := &http.Cookie{
   Name:    "session_id",
   Value:   "abc123",
   Expires: time.Now().Add(24 * time.Hour),
   Path:    "/",
}
c.SetCookie(sessionCookie)

Note: - If you need to set multiple cookies, you would call this method multiple times, passing in each cookie as a separate 'http.Cookie' object.

func (*FileDownloader) Handle ¶

func (f *FileDownloader) Handle() HandleFunc

Handle creates and returns a HandleFunc designed for serving files for download. This HTTP handler ensures that the files served for download are securely retrieved from a specified server directory and delivered to the client correctly. The handler takes care to resolve the file path, validate the request, and to set proper HTTP headers to facilitate the file download on the client side.

The HandleFunc performs the following steps:

1. Extracts the 'file' query parameter from the request's URL. This parameter contains the relative path to the file that the client wants to download.
2. If the 'file' query parameter is missing or another error occurs while retrieving it, the handler responds with an HTTP 400 Bad Request status and a message indicating that the destination file could not be found.
3. Cleans up the requested file path using filepath.Clean to prevent any directory traversal attempts and ensure the path is in its simplest form.
4. Joins the cleaned file path with the FileDownloader's Dir to form an absolute path to the file within the server's file system.
5. Converts the resulting path to an absolute path and checks if the resolved file path actually exists within the designated download directory. This acts as a security measure to prevent clients from accessing files outside the allowed directory.
6. If the resolved file path is outside the designated download directory, the handler responds with an HTTP 400 Bad Request status and a message indicating an access path error.
7. The file name is extracted from the resolved path to be used in the Content-Disposition header, which advises the client's browser that a file is expected to be downloaded and saved locally.
8. Various HTTP response headers are set to inform the client about the file transfer details: - Content-Disposition: Advises the client on how to handle the file data. - Content-Description: Description of the content. - Content-Type: Specifies that the content is a stream of binary data (i.e., a file). - Content-Transfer-Encoding: Notates that the content transfer will be in binary mode. - Expires: Indicates that the content should not be cached for later use. - Cache-Control and Pragma: Directives to control browser caching.
9. The http.ServeFile function is called to serve the file contained in the resolved path to the client. This function takes care of streaming the file data to the client. The function also automatically determines the Content-Type header, although it is overridden here to "application/octet-stream" to trigger the browser's download dialog.

The handler secured by the FileDownloader ensures that only files from a specified directory can be accessed and downloaded by the client. Proper error handling is implemented to return meaningful HTTP status codes and messages to the client in case of an error, such as path resolution issues or illegal file access attempts.

func (*FileUploader) Handle ¶

func (f *FileUploader) Handle() HandleFunc

Handle returns a HandleFunc specifically prepared to process file upload requests based on the configuration of the FileUploader struct. This HandleFunc can be used as an HTTP handler that intercepts file upload HTTP requests, processes them, and provides an appropriate response to the client based on the outcome of the operation.

The returned HandleFunc performs the following steps:

1. It attempts to retrieve the file data from the request's form field as specified by the FileUploader's FileField.
2. If it encounters an error during file retrieval, it sets the HTTP response status code to Internal Server Error (500), and it sends back an error message to the client, indicating that the upload failed, along with the error details.
3. Upon successful retrieval of the file, the function then calls the FileUploader's DstPathFunc with the metadata of the uploaded file (fileHeader) to determine the destination path where the file should be saved.
4. The function checks for errors from the DstPathFunc call; if there's an error, it responds with an Internal Server Error status and an error message as in step 2.
5. Next, it attempts to open (or create if not existing) the destination file for writing. It ensures that the permissions for the new file allow read and write operations for the user, group, and others (permission mode 0666).
6. If it cannot open the destination file, it responds with an Internal Server Error status and an error message.
7. If the destination file is opened successfully, it then copies the content of the uploaded file to the destination file using an io.CopyBuffer operation. This function performs the copy operation and allows the reuse of an existing slice (buffer) to reduce memory allocation, which is set to nil to use a pre-allocated buffer of a default size.
8. Any error encountered during the copy process results in an Internal Server Error status and an error message.
9. If the file is uploaded and saved successfully, the function sets the HTTP response status to OK (200) and sends a success message to the client.

It's important that the file handles for both the uploaded file and the destination file are closed properly to release the resources. The defer keyword is used right after each file is opened to ensure that the file handles are closed when the function returns.

Usage of the Handle method would typically involve adding the returned HandleFunc as an HTTP handler in a web server's routing configuration. This would route certain POST requests expected to contain file uploads through this handler to process the file saving task accordingly.

func (*GoTemplateEngine) LoadFromFS ¶

func (g *GoTemplateEngine) LoadFromFS(fs fs.FS, patterns ...string) error

LoadFromFS is a method on the GoTemplateEngine struct that loads and parses templates from a file system abstraction (fs.FS) using specified glob patterns. It updates the GoTemplateEngine's T field with the resulting template set. This allows the loading of templates from various sources that implement the fs.FS interface, such as in-memory file systems, making the method flexible and adaptable to different run-time environments.

Parameters:

• fs.FS: The fs.FS interface instance represents an abstract file system to load templates from. It provides a way to abstract the file system operations through methods like Open, making it possible to work with different file systems (e.g., an actual OS file system, in-memory file systems, embedded file systems).
• patterns ...string: This variadic parameter takes multiple string arguments, each representing a glob pattern used to match files within the provided file system (fs). These patterns tell the method which files to consider when loading and parsing the templates.

Returns:

• error: If there is an issue parsing the templates using the provided file system and patterns, the method will return an error. This error could be a result of file I/O operations issues, files not matching any patterns, permission issues, or problems within the template files such as syntax errors. In the case of an error, the GoTemplateEngine's T field will not be updated with any new templates.

Internally, the method uses the template.ParseFS function from Go's template package. This function is designed to work with the fs.FS interface to read and parse templates. The method parses all the files that match the provided patterns into a template set, which is then stored in the T field of the current GoTemplateEngine instance.

As with other template loading methods, proper error handling is crucial to ensure the application can handle cases where templates could not be loaded. If no errors are returned, the engine can proceed to render these templates through its Render method, as they are immediately available for use.

func (*GoTemplateEngine) LoadFromFiles ¶

func (g *GoTemplateEngine) LoadFromFiles(filenames ...string) error

LoadFromFiles is a method on the GoTemplateEngine struct that parses template files specified by the filenames and updates the GoTemplateEngine's T field with the parsed template set. This method allows for explicit control over which template files are loaded and is commonly used for initializing the engine with a known set of templates or updating the templates at runtime.

Parameters:

• filenames ...string: A variadic parameter that accepts an arbitrary number of strings, each representing the path to a template file that should be included in the parsing process. This allows for a flexible number of files to be loaded at once without needing to specify them in a slice.

Returns:

• error: If the method encounters any issues while trying to read or parse the provided template files, it will return an error. Potential issues include file I/O errors, file not found errors, permission denials, or problems within the template files themselves, such as syntax errors. If an error is returned, the T field remains unchanged, and the new templates are not loaded.

The method makes use of the template.ParseFiles function provided by Go's template package. The ParseFiles function takes the provided file paths, reads the contents, and attempts to parse them into templates within a template set. These templates are then stored in the T field of the GoTemplateEngine.

Error handling after calling this method is essential to ensure the application's stability, as templates are fundamental for generating output based on them. On successful execution, the templates become immediately available for rendering through the engine's Render method.

func (*GoTemplateEngine) LoadFromGlob ¶

func (g *GoTemplateEngine) LoadFromGlob(pattern string) error

LoadFromGlob is a method of GoTemplateEngine that loads and parses template files based on a specified pattern (glob). After execution, the GoTemplateEngine's T field is updated to contain the new parsed templates. This method is typically used during initialization or when the templates need to be refreshed.

Parameter:

• pattern string: The pattern parameter is a string that specifies the glob pattern used to identify the template files that should be parsed and added to the template set. A glob pattern may include wildcards (e.g., "*.tmpl" for all files with the .tmpl extension in the current directory, or "templates/*.html" for all .html files within a 'templates' directory).

Returns:

• error: This function will return an error if the parsing operation fails. The error might be caused by an inability to read files due to incorrect permissions, non-existent files, or syntax errors within the template files themselves. If an error is returned, the T field of the GoTemplateEngine struct is not updated with any new templates.

The method works by invoking template.ParseGlob from Go's template package with the provided pattern string. This function reads and parses all the template files that match the pattern into a new template set. The parsed templates are then assigned to the T field of the GoTemplateEngine instance.

When calling this method, it's important to handle any errors returned to ensure the application is aware if the templates failed to load. A successful execution means that the T field is now ready to execute the loaded templates with the Render method.

func (*GoTemplateEngine) Render ¶

func (g *GoTemplateEngine) Render(ctx context.Context, templateName string, data any) ([]byte, error)

Render is the method that implements the rendering functionality for the GoTemplateEngine. It satisfies the TemplateEngine interface's Render method, allowing the GoTemplateEngine to be used wherever a TemplateEngine is required. This method executes the named template using the provided data and generates a rendered output as a slice of bytes.

Parameters:

• ctx context.Context: This parameter provides context for the render operation. It can carry deadlines, cancellations signals, and other request-scoped values across API boundaries and between processes. In this method, ctx is not directly used but could be utilized by extending the method further to support context-aware operations in the render process, such as logging, tracing, timeout, or cancellation.
• templateName string: The name of the template to be executed. This must correspond to the name given to one of the parsed templates contained within the *template.Template associated with the GoTemplateEngine.
• data any: The data to be applied to the template during rendering. This could be any type of value that the underlying templates are expected to work with, typically a struct, map, or a primitive type that the template fields can reference.

Returns:

• []byte: A byte slice containing the rendered output from the executed template. If rendering is successful without any errors, the content of the slice represents the completed output, ready to be used as needed (e.g., sent as an HTTP response).
• error: An error that may have been encountered during the template execution. If such an error occurs, it's usually related to issues like an undefined template name, missing data for placeholders in the template, or execution errors within the template. If the error is non-nil, the byte slice returned will be nil, and the error should be handled appropriately.

The Render method works by creating a new bytes.Buffer to act as an in-memory writer where the rendered output is temporarily stored. The ExecuteTemplate method of the *template.Template is then called with this buffer, the name of the template, and the data to be used for rendering. If the template execution is successful, the content of the buffer is returned as a byte slice. In case of an error, the error returned from ExecuteTemplate is passed through to the caller.

func (*HTTPServer) CONNECT ¶ added in v0.0.10

func (s *HTTPServer) CONNECT(path string, handleFunc HandleFunc)

CONNECT registers a new route with an associated handler function for handling HTTP CONNECT requests. The HTTP CONNECT method is utilized primarily for establishing a tunnel to a server identified by a given URI.

Parameters:

• path string: The endpoint or route pattern where the server will listen for incoming CONNECT requests. This may include parameter placeholders that can be used to extract values from the URL during request handling.
• handleFunc: A callback function that is invoked in response to a CONNECT request to the given path. This function has access to the request and response through a *Context, providing the necessary tools to implement the tunneling behavior or other custom logic expected on a CONNECT request.

Example usage:

s.Connect("/proxy", func(ctx *Context) {
    // Logic to establish a proxy connection.
})

Note: The use of `http.MethodConnect` ensures that only HTTP CONNECT requests are matched to this handler, facilitating the appropriate processing logic for these specialized request types, which are different from the standard GET, POST, PUT, etc., methods.

func (*HTTPServer) DELETE ¶ added in v0.0.10

func (s *HTTPServer) DELETE(path string, handleFunc HandleFunc)

DELETE registers a new route with an associated handler function for HTTP DELETE requests. This method is used to remove a resource identified by a URI.

Parameters:

• path string: The URL pattern that the server will listen on for incoming DELETE requests. This parameter defines the endpoint at which the handler will be called when a DELETE request matches the path.
• handleFunc: A function that is called when a DELETE request is made to the registered path. This function should contain the logic to handle the deletion of a resource, and it is provided with a *Context object to interact with the request and response data.

Example usage:

s.Delete("/users/{id}", func(ctx *Context) {
    // Handler logic to delete a user resource with the given ID.
})

Note: Using `http.MethodDelete` in the call to registerRoute confines this handler to respond solely to DELETE requests, providing a way to define how the server handles deletions.

func (*HTTPServer) GET ¶ added in v0.0.10

func (s *HTTPServer) GET(path string, handleFunc HandleFunc)

GET registers a new route and its associated handler function for HTTP GET requests. This method is a shortcut for registering routes that should only respond to GET HTTP method, typically used for retrieving resources.

Parameters:

• path string: The URL pattern to match against incoming requests. The route pattern can contain parameters that will be parsed from the URL and made available to the handler function during request handling.
• handleFunc: The function to be called when a request matching the path is received. The handler function is defined to take a *Context as its only parameter, through which it can access the request data and send a response back.

Example usage:

s.Get("/home", func(ctx *Context) {
    // Handler logic for the `/home` path when an HTTP GET request is received
})

Note: The method internally calls registerRoute to add the route to the server's routing table with the method specified as `http.MethodGet`, which ensures that only GET requests are handled by the provided handler.

func (*HTTPServer) Group ¶ added in v0.0.14

func (r *HTTPServer) Group(prefix string, ms ...Middleware) *routerGroup

Group creates and returns a new routerGroup attached to the router it is called on. The method ensures the provided prefix conforms to format requirements by checking if it starts and does not end with a forward slash, unless it is the root group ("/"). This method panics if the prefix is invalid to prevent router misconfiguration.

Parameters:

• prefix: The path prefix for the new group of routes. It should start with a forward slash and, except for the root group, not end with a forward slash.
• ms: Zero or more Middleware functions that will be applied to every route within the created routerGroup.

Returns: *routerGroup: A pointer to the newly created routerGroup with the given prefix and middlewares.

Panics: This method will panic if 'prefix' does not start with a '/' or if 'prefix' ends with a '/' (except when 'prefix' is exactly "/").

Usage: r := &router{} // Assume router is already initialized group := r.Group("/api", loggingMiddleware, authMiddleware)

func (*HTTPServer) HEAD ¶ added in v0.0.10

func (s *HTTPServer) HEAD(path string, handleFunc HandleFunc)

HEAD registers a new route and its associated handler function for HTTP HEAD requests. This method is used to handle requests where the client is interested only in the response headers, and not the actual body of the response, which is typical behavior of a HEAD request in HTTP.

Parameters:

• path string: The path pattern to which the route will respond. When a HEAD request to this pattern is received, the registered handler function will be executed.
• handleFunc: The handler function that will be associated with the provided path pattern. This function will be called with a *Context parameter that contains information about the request and mechanisms to construct a response.

Example usage:

s.Head("/resource", func(ctx *Context) {
    // Handler logic to return response headers for the '/resource' path
    // without returning the actual body.
})

Note: The method utilizes the registerRoute internal function to add the route to the server's routing table specifically for the HEAD HTTP method, which ensures that only HEAD requests will trigger the execution of the provided handler function.

func (*HTTPServer) OPTIONS ¶ added in v0.0.10

func (s *HTTPServer) OPTIONS(path string, handleFunc HandleFunc)

OPTIONS registers a new route with an associated handler function for HTTP OPTIONS requests. The HTTP OPTIONS method is used to describe the communication options for the target resource.

Parameters:

• path string: The URL pattern that the server will match against incoming OPTIONS requests. Defining the endpoint allows clients to find out which methods and operations are supported at a given URL or server.
• handleFunc: The function to be executed when an OPTIONS request is received. It typically provides information about the HTTP methods that are available for a particular URL endpoint. The handleFunc is supplied with a *Context object to facilitate interaction with the HTTP request and response.

Example usage:

s.Options("/articles/{id}", func(ctx *Context) {
    // Handler logic to indicate supported methods like GET, POST, PUT on the article resource.
})

Note: This registration only affects OPTIONS requests due to the use of `http.MethodOptions`. It is standard practice to implement this method on a server to inform clients about the methods and content types that the server is capable of handling, thereby aiding the client's decision-making regarding further actions.

func (*HTTPServer) PATCH ¶ added in v0.0.10

func (s *HTTPServer) PATCH(path string, handleFunc HandleFunc)

PATCH registers a new route with an associated handler function for HTTP PATCH requests. This method is generally used for making partial updates to an existing resource.

Parameters:

• path string: The pattern of the URL that the server will match against incoming PATCH requests. The path can include variables that will be extracted from the URL and passed to the handler.
• handleFunc: The function to execute when the server receives a PATCH request at the specified path. This function is provided with a *Context object, enabling access to request information and response functionalities.

Example usage:

s.Patch("/profile/{id}", func(ctx *Context) {
    // Handler logic to apply partial updates to a profile based on the ID in the URL.
})

Note: Registering the route with the `http.MethodPatch` constant ensures that only PATCH requests are handled by the provided function. The PATCH method is typically used to apply a partial update to a resource, and this function is where you would define how the server handles such requests.

func (*HTTPServer) POST ¶ added in v0.0.10

func (s *HTTPServer) POST(path string, handleFunc HandleFunc)

POST registers a new route and its associated handler function for handling HTTP POST requests. This method is used for routes that should accept data sent to the server, usually for the purpose of creating or updating resources.

Parameters:

• path string: The URL pattern to match against incoming POST requests. It defines the endpoint at which the handler function will be called for incoming POST requests.
• handleFunc: The function to be executed when a POST request is made to the specified path. It receives a *Context object that contains the request information and provides the means to write a response back to the client.

Example usage:

s.Post("/submit", func(ctx *Context) {
    // Handler logic for processing the POST request to the `/submit` path.
})

Note: The method delegates to registerRoute, internally setting the HTTP method to `http.MethodPost`. This ensures that the registered handler is invoked only for POST requests matching the specified path.

func (*HTTPServer) PUT ¶ added in v0.0.10

func (s *HTTPServer) PUT(path string, handleFunc HandleFunc)

PUT registers a new route and its associated handler function for handling HTTP PUT requests. This method is typically used to update an existing resource or create a new resource at a specific URL.

Parameters:

• path string: The URL pattern to which the server should listen for PUT requests. This pattern may include placeholders for dynamic segments of the URL, which can be used to pass variables to the handler function.
• handleFunc: A callback function that will be invoked when a PUT request is made to the specified path. The function takes a *Context parameter that provides access to the request data and response writer.

Example usage:

s.Put("/items/{id}", func(ctx *Context) {
    // Handler logic for updating an item with a particular ID using a PUT request.
})

Note: By calling registerRoute and specifying `http.MethodPut`, this method ensures that the handler is specifically associated with PUT requests. If a PUT request is made on the matched path, the corresponding handler function will be executed.

func (*HTTPServer) ServeHTTP ¶

func (s *HTTPServer) ServeHTTP(writer http.ResponseWriter, request *http.Request)

ServeHTTP is the core method for handling incoming HTTP requests in the HTTPServer. This method fulfills the http.Handler interface, making an HTTPServer instance compatible with Go's built-in HTTP server machinery. ServeHTTP is responsible for creating the context for the request, applying middleware, and calling the final request handler. After the request is processed, it ensures that any buffered response (if applicable) is flushed to the client.

Parameters: - writer: An http.ResponseWriter that is used to write the HTTP response to be sent to the client. - request: An *http.Request that represents the client's HTTP request being handled.

The ServeHTTP function operates in the following manner:

1. It begins by creating a new Context instance, which is a custom type holding the HTTP request and response writer, along with other request-specific information like the templating engine.
2. It retrieves the root handler from the server's configuration 's.server', which represents the starting point for the request handling pipeline.
3. Iteratively wraps the root handler with the server's configured middleware in reverse order. Middleware is essentially a chain of functions that can execute before and/or after the main request handler to perform tasks such as logging, authentication, etc.
4. Introduces a final middleware that calls the next handler in the chain and then flushes any buffered response using 's.flashResp'. This ensures that even if a response is buffered (for performance reasons or to allow for manipulations), it gets sent out after the request is processed.
5. Calls the fully wrapped root handler, beginning the execution of the middleware chain and ultimately invoking the appropriate request handler.

func (*HTTPServer) Start ¶

func (s *HTTPServer) Start(addr string) error

Start initiates the HTTP server listening on the specified address. It sets up a TCP network listener on the given address and then starts the HTTP server to accept and handle incoming requests using this listener. If there is a problem creating the network listener or starting the server, it returns an error.

Parameters:

• addr: A string specifying the TCP address for the server to listen on. This typically includes a hostname or IP followed by a colon and the port number (e.g., "localhost:8080" or ":80"). If only the port number is specified with a leading colon, the server will listen on all available IP addresses on the given port.

The Start function operates in the following manner:

1. Calls net.Listen with "tcp" as the network type and the provided address. This attempts to create a listener that can accept incoming TCP connections on the specified address.
2. If net.Listen returns an error, it is immediately returned to the caller, indicating that the listener could not be created (possibly due to an invalid address, inability to bind to the port, etc.).
3. If the listener is successfully created, the function then calls http.Serve with the listener and the server itself as arguments. This starts the HTTP server, which begins listening for and handling requests. The server will use the ServeHTTP method of the HTTPServer to process each request.
4. If http.Serve encounters an error, it will also be returned to the caller. This can happen if there's an unexpected issue while the server is running, such as a failure to accept a connection.

The Start method is a blocking call. Once called, it will continue to run, serving incoming HTTP requests until an error is encountered or the server is manually stopped.

func (*HTTPServer) TRACE ¶ added in v0.0.10

func (s *HTTPServer) TRACE(path string, handleFunc HandleFunc)

TRACE registers a new route with an associated handler function for HTTP TRACE requests. The HTTP TRACE method is used to echo back the received request so that a client can see what (if any) changes or additions have been made by intermediate servers.

Parameters:

• path string: The endpoint on the server that will respond to the TRACE requests. This defines the path pattern that must be matched for the handler function to be invoked.
• handleFunc: A function that handles the TRACE request. It should process the request and typically returns the same request message in the response body. This function has a *Context object allowing access to the request details and the ability to write the response.

Example usage:

s.Trace("/echo", func(ctx *Context) {
    // Handler logic that echoes the incoming request back to the client.
})

Note: Registering this route specifically listens for HTTP TRACE requests by using `http.MethodTrace`. This is helpful for debugging purposes where the client needs to understand what headers and body are being received by the server after any possible alterations by intermediate devices.

func (*HTTPServer) Use ¶

func (s *HTTPServer) Use(mils ...Middleware)

Use attaches the provided middlewares to the existing set of middlewares in the HTTPServer instance. If no middleware has been set yet, it initializes the middleware list with the provided ones. If there are already middlewares present in the server, it appends the new ones to the end of the middleware chain.

Middlewares are executed in the order they are added to the server, meaning that the order of middlewares can affect the request/response processing. They are commonly used to handle tasks such as request logging, authentication, input validation, error handling, etc.

Usage example:

server := &HTTPServer{}
server.Use(loggingMiddleware)
server.Use(authenticationMiddleware)

Parameters: - mils ...Middleware : One or multiple Middleware functions to add to the server's middleware chain.

Note: This method appends provided middlewares variably, allowing for zero or more middlewares to be added at once. If called with no arguments, it will simply do nothing to the current middleware chain.

func (*HTTPServer) UseForAll ¶ added in v0.0.5

func (s *HTTPServer) UseForAll(path string, mdls ...Middleware)

UseForAll associates the provided middlewares with all HTTP methods for the specified path. This method configures the HTTP server to apply the given middlewares to every request method (GET, POST, OPTIONS, etc.) for the specified route path. This is useful when you want consistent middleware execution for a path, irrespective of the HTTP method used in the request.

Parameters: - path: The URL pattern to match against incoming request URLs. - mdls: A variadic list of middlewares to be applied to all requests for the route.

Usage:

• server.UseForAll("/api/resource", loggerMiddleware, authMiddleware) This example would apply the logger and auth middlewares to all request methods for path "/api/resource".

func (*HTTPServer) UseRoute ¶

func (s *HTTPServer) UseRoute(method string, path string, mils ...Middleware)

UseRoute associates a new route with the specified HTTP method and path to the server's routing system. Additionally, it allows for the chaining of middleware functions that can intercept and modify the request or response, or perform specific actions like logging, authentication, etc., before the request reaches the final handler function.

Parameters:

• method string: The HTTP method (e.g., GET, POST, PUT, DELETE) for which the route is to be registered.
• path string: The path pattern to be matched against the URL of incoming requests.
• mils ...Middleware: A variadic parameter that allows passing an arbitrary number of middleware functions. These functions are executed in the order they are provided, prior to the final handler.

Usage: When registering a route, you can specify the HTTP method and path, followed by the series of middleware you wish to apply. If no final handler is provided at the time of route registration, one must be attached later for the route to be functional.

Example usage:

s.UseRoute("GET", "/articles", AuthMiddleware, LogMiddleware)

Here, `AuthMiddleware` would be used to authenticate the request, and `LogMiddleware` would log the request details. A route handler would need to be added subsequently to handle the GET requests for `/articles` path.

Note: This method is used for initial route setup and must be combined with a handler registration to create a complete, functional route. If a handler is not attached later, the route will not have any effect.

func (*StaticResourceHandler) Handle ¶

func (s *StaticResourceHandler) Handle(ctx *Context)

Handle takes a Context pointer and serves static files based on the request's path. It attempts to retrieve and serve the requested file, handling various error scenarios gracefully. It sets appropriate HTTP response status codes and headers, leveraging an LRU cache for performance optimization when possible.

The method logic is as follows:

1. It extracts the requested 'file' from the context's PathValue.
2. If there's an error in retrieving the file (e.g., malformed request path), it sends a 400 Bad Request status and a "Request path error" message.
3. If the file can be retrieved, it constructs a full file path using the provided directory path and the file's name.
4. The file extension is extracted to determine the correct content type from the handler's extension to MIME type mapping (extContentTypeMap).
5. If the file's data is found in the cache, it uses this data to set the response headers and body, sending a 200 OK status code.
6. If not cached, it reads the file from disk using os.ReadFile.
7. If there's an error reading the file (e.g., file not found, permissions issue), it sets a 500 Internal Server Error status code and a "Server error" message.
8. It checks if the file size is within the allowed maximum size (s.maxSize). If it is, the function adds the file's data to the cache.
9. Lastly, it sets the correct "Content-Type" and "Content-Length" headers and sends the file data with a 200 OK status.

Parameters:

• ctx *Context: A pointer to the Context object which contains information about the HTTP request and utilities for writing a response.

Note: This method should be used to handle routes that match static file requests. It automatically uses caching to improve performance, but it also ensures that the file size does not exceed a configured threshold before caching the data.

Example Usage: Assuming 'handler' is an instance of StaticResourceHandler with a configured directory and cache, the Handle method would be attached to a web server route like so:

http.Handle("/static/", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    ctx := NewContext(r, w)
    handler.Handle(ctx)
}))

This specifies that all requests to '/static/' should be handled by the Handle method of 'handler', which will serve the files as static resources.

func (*StringValue) AsFloat64 ¶

func (s *StringValue) AsFloat64() (float64, error)

AsFloat64 converts the string value encapsulated within the StringValue struct to a float64 type. This operation is essential in situations where the string value is expected to contain a floating-point number that will be used in complex calculations or any context where precise decimal values are necessary, such as financial computations or scientific measurements.

The method follows a clear two-step conversion process:

1. It first checks for the presence of an error in the 'err' field of the StringValue struct. If an error is already associated with the value, the method precludes any conversion attempt and immediately returns a zero value (0.0) and the stored error, preserving the integrity of the error handling flow.

2. If no error is found (i.e., 'err' is nil), the method utilizes the strconv.ParseFloat function to attempt the conversion of the string value to a float64. The function parameter '64' specifies that the conversion should result in a floating-point number that adheres to a 64-bit IEEE 754 representation. This conversion is capable of handling both integer values and floating-point strings, including those with scientific notation.

   If the conversion is conducted successfully, the parsed float64 value is returned alongside a nil error to indicate a successful operation. However, if strconv.ParseFloat encounters any issues—such as if the string contains characters inappropriate for a numeric value, or if the number is outside the range representable by a float64—the method will instead yield a zero value (0.0) with the corresponding error.

Parameters: - None. The method operates solely on the fields contained within the invoked StringValue struct instance.

Return Values: - A float64 value representing the successfully converted string or 0.0 in the event of an error. - An error object that either carries an existing error from 'err' or a newly encountered error in conversion.

Usage:

• Users of this method should handle the returned error prior to using the numeric result to ensure that no conversion error has taken place and the result is indeed a valid and accurate floating-point number.

Example: - If a 'StringValue' instance named 'priceString' comes from a reliable function that parses a price value:

priceString := parsePriceValueFromInput()
price, err := priceString.AsFloat64()
if err != nil {
    // Error handling logic such as logging the error or prompting the user to provide a valid numeric value.
} else {
    // The price variable is now appropriately typed as a float64 and ready for financial calculations.
}

Considerations:

• The float64 type follows IEEE 754 standards and is the set choice for all floating-point operations within Go, offering a double-precision floating-point format which is fairly suited for a wide range of numerical tasks.
• Ensure that the source string is supposed to represent a floating-point value and that it is formatted correctly. Proper validation or sanitization might be essential if the input is obtained from external or untrusted sources.

func (*StringValue) AsInt64 ¶

func (s *StringValue) AsInt64() (int64, error)

AsInt64 attempts to convert the value held in the StringValue struct to an int64 type. This method is particularly useful when the string value is expected to hold a numeric value that needs to be used in a context where integer types are required (e.g., calculations, database operations, etc.).

This method performs a two-step process:

1. It checks if the err field of the StringValue receiver is not nil, which implies that an error occurred in acquiring or processing the original string value. If an error is present, the method immediately returns 0 and the error, propagating the original error without attempting to convert the value.
2. If there is no error associated with the string value (i.e., err is nil), the method attempts to parse the string as an int64 base 10 number with the strconv.ParseInt function. If the parsing succeeds, it returns the resulting int64 value and a nil error. If parsing fails, it returns 0 and the parsing error that occurred.

Parameters: - None. The method operates on the StringValue structs internal state.

Return Value:

• The first return value is the int64 result of the parsing operation. It is set to 0 if there is an error.
• The second return value is the error encountered during the conversion process. It will contain any error that may have previously been present in the StringValue struct or any error that occurs during the parsing with strconv.ParseInt.

Usage:

• It is essential to always handle the error return value to ensure that the int64 conversion was successful. Do not use the numeric value if the error is non-nil, as it would be incorrect or undefined.

Example:

• Suppose we have a StringValue struct that is created as the result of another function that reads a stringifies integer from user input or external data source:

  value := otherFunctionThatReturnsStringValue() number, err := value.AsInt64() if err != nil { // handle the error (e.g., log the error or inform the user of a bad input) } else { // use the number for further processing }

Considerations:

• This method allows for a clean and efficient interpretation of string data when an integer is expected. Doing so can simplify error handling by centralizing the conversion logic and error checking.
• The strconv.ParseInt function is configured to interpret the string as a base 10 integer within the int64 range. This corresponds to the range of -9223372036854775808 to 9223372036854775807.
• Make sure that the source string is appropriately validated or sanitized if coming from an untrusted source before attempting the conversion to mitigate any risks such as injection attacks or data corruption.

func (*StringValue) AsUint64 ¶

func (s *StringValue) AsUint64() (uint64, error)

AsUint64 attempts to convert the string value within the StringValue struct to an uint64 type. This method is crucial when the string is expected to represent an unsigned numeric value that must be processed in environments or calculations that specifically require unsigned integers.

The method involves the following steps:

1. First, it verifies whether the 'err' field in the StringValue struct is not nil, indicating an error was encountered during the prior retrieval or conversion of the string value. Should an error be present, the method exits early, returning 0 for the numeric value and passing the error forward.
2. If the 'err' field is nil, signaling no previous error, the method proceeds to parse the string value to an uint64 using the strconv.ParseUint function. This function is instructed to interpret the string value as a base 10 number. The second argument (10) specifies the number base (decimal in this case), and the third argument (64) specifies that the conversion should fit into a 64-bit unsigned integer format.
3. If the conversion is successful, the method outputs the parsed uint64 value and a nil error. If the conversion fails (e.g., if the string contains non-numeric characters or represents a number outside the uint64 range), it instead returns 0 and the error produced by strconv.ParseUint.

Parameters: - There are no parameters taken by this method, as it operates on the 'StringValue' struct instance it is called upon.

Return Value: - An uint64 type value representing the converted string if successful. - An error indicating the conversion failed or an error was present already in the StringValue struct's 'err' field.

Usage:

• The caller should always evaluate the error returned by this function before utilizing the numeric value, to ensure the conversion occurred correctly and the result is valid and reliable for further use.

Example: - Imagine a situation where the 'StringValue' instance 'numericString' was created by parsing a user-provided configuration value:

numericString := GetStringFromConfig("max_users")
maxValue, err := numericString.AsUint64()
if err != nil {
    // Handle the error appropriately (e.g., fallback to default value, logging, or user notification)
} else {
    // The maxValue is now safe to use for setting the maximum users allowed
}

Considerations:

• This method assists in preventing the proliferation of error handling logic scattered throughout codebases by encapsulating both the value and potential errors within a single, self-contained struct.
• The uint64 data type can represent integers from 0 to 18,446,744,073,709,551,615. Ensure the source string is meant to fit within this range.
• Additional validation might be required for the initial string value if it comes from external or user inputs to prevent errors during conversion.