Crate codemelted

Expand description

codemelted.rs Crate

LAST UPDATED: 2025-Aug-06

The aim of this project is to deliver a swiss army knife module to aid software engineers in building full stack solutions for their applications. Utilizing the Rust programming language, the module serves as a backbone to engineer solutions for multiple build targets.

The module serves as a consumable crate for software engineers to build their own custom backend / desktop services applications. Secondly built into the module is a Command Line Interface (CLI) to target script based solutions with a powerful CLI that will work the same regardless of the operating system. Lastly parts of the module along with the codemelted.js implementing the codemelted namespace will build a WASM / JS consumable modules to build powerful Single / Progressive Web Applications.

Table of Contents

GETTING STARTED
MODULE INFORMATION

§GETTING STARTED

§Features

The codemelted.rs is a single file implementing the Domain Use Cases domain specific use cases.
These use cases straddle areas of knowledge software engineers should be familiar with regardless of a given programming language, SDK, or chosen framework.
Each of the use cases are implemented as a series of uc_xxx functions reflecting the use case diagram above.
The codemelted.rs is organized by each implemented use case with data definitions first and function implementations after.
Each use case function is fully documented to include example code and mermaid diagrams.
Any use case function that is currently being developed is marked as such.

§Usage

You can access the use case functions via the codemelted::uc_xxx(). The following example demonstrates utilizing the codemelted module.

// Access the module objects of interest. In this case the logger module objects.
use codemelted::{CLogLevel, CLogRecord, CLoggedEventHandler};

// Setup a log handler for post logging.
fn log_handler(data: CLogRecord) {
  // Do something, say post to the cloud about the event
}
codemelted::logger_set_log_handler(Some(log_handler));

// Set the log level
codemelted::logger_set_log_level(CLogLevel::Warning);

// Now later on in your code....
// This will be reported to the console and then to the CLoggedEventHandler.
codemelted::logger_log(CLogLevel::Error, "Oh Know!");

The above is a basic example. All modules are fully documented with examples as you use the codemelted crate.

§Asynchronous Processing Notes

The codemelted crate does not utilize async / await / future syntax.
Code is synchronous in the codemelted module allowing the software engineer to choose an appropriate thread model.
For asynchronous crates utilized by the codemelted module, they are transformed into synchronous APIs via the tokio::Runtime.
For items requiring threading within the codemelted crate, they provide a synchronous API and implement the minimum threading necessary to achieve the module API goal.

§MODULE INFORMATION

The following sub-sections cover various aspects the codemelted.rs module information. It is a single file implementation of the identified use cases.

§Crate Dependencies

The goal of the codemelted.rs is to limit 3rd party items. However, some CodeMelted DEV use cases, thanks to the hard work of the developers who maintain the crates below, would not have been possible.

btleplug: Supports the HW Domain Use Case providing the necessary interface to Bluetooth devices.
chrono: Utilized to support the time formatting utilized in the Logger Domain Use Case.
json: Forms the entire backbone of the Json Domain Use Case. The main json::JsonValue is typed alias as CObject to match other CodeMelted DEV module implementations.
online: Utilized with the Runtime Domain Use Case to determine if an app has access to the Internet or not.
reqwest: Supports the Network Domain Use Case fetch call forming the basis for both the request and response to a server REST API call.
rouille: Supports the network_serve and network_upgrade_web_socket calls of the Network Domain Use Case forming the basis to upgrade a HTTP request wanting to upgrade to a bi-directional web socket. This will create a CWebSocketProtocol that represents a bi-directional server socket. FYI: The following warning occurs with this crate. Will keep an eye out on updates with this crate, see if an assist can be made to the owner, or look for a new crate to utilize with the completed codemelted.rs module design.

warning: the following packages contain code that will be rejected by a future version of Rust: buf_redux v0.8.4, multipart v0.18.0 note: to see what the problems were, use the option --future-incompat-report, or run cargo report future-incompatibilities --id 1
rpassword: Supports the Console Domain Use Case to allow for getting a user’s password from the console without reflecting it to the screen.
rusqlite: Supports the DB Domain Use Case providing the ability to have an embedded sqlite database. The crate takes care of “installing” the items necessary to build the sqlite database file.
simple-mermaid: Supports the crate documentation for the codemelted.rs file to include mermaid models where appropriate to help describe each of the modules.
serialport: Supports the HW Domain Use Case providing the necessary interface to Serial ports.
sysinfo: This provides backbone for the Monitor Domain Use Case objects that support monitoring different aspects of a host operating system..
tokio: Utilized to allow for the consumption of asynchronous crates and turn them into the codemelted crate synchronous design.
url: Supports url validation as part of the JSON Domain Use Case.

§Crate Versioning

The versioning of the codemelted crate will utilize a modified semantic versioning X.Y.Z with the following rules for the numbering scheme.

X: Year of release. Each new year resets the Y.Z values to 1
Y: Breaking change to one of the use case functions or upgrade of dependencies requiring considerations within an app. A change in this value resets .Z to 1.
Z: Bug fix, new use case function implemented, or expansion of a use case function. Continuously updated by adding one with each new release unless reset by X.Y changes.

§License

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

If you find this module useful, any support is greatly appreciated. Thank you! 🙇

Structs§

CBluetoothInfo: Result of the hw_available_bluetooth_devices call identified devices one can open to exchange data via the hw_open_bluetooth_device call.
CComponentMonitor: The result of a monitor_components call providing a view of a system’s internal components and their current health (i.e. temperature in °C) along with their failure points.
CDiskMonitor: The result of the monitor_disk call provide a view of the host operating systems available data disk storage. This is a self contained array of disks and their associated information. Any index call beyond the available disks will panic your application.
CFetchRequest: Object utilized with the network_fetch function to configure the request to be made to a backend server REST API.
CFetchResponse: The response of the network_fetch call holding the result and associated data of the request.
CLogRecord: The record created to represent the logged event.
CNetworkMonitor: The result of the monitor_network call provide a view of the host operating systems available network interfaces. This is a self contained hashtable of network interfaces with statistics related to overall received / transmitted bytes, packets, and encountered errors.
CPerformanceMonitor: Provides a monitoring object to measure the platform’s overall CPU / memory utilization. This is accomplished by calling the monitor_performance function to get a reference of the object. From here you have the ability to sample the data of interest, refresh to get the latest update, and if necessary capture a CCsvFormat of the data.
CProcessMonitor: The result of the monitor_processes call provide a view of the host operating systems currently running processes. It allows for gathering data about the processes (statistics, originating application, etc.) while also providing the ability to know the current run status, the ability to kill, and wait for the process to exit.
CProcessProtocol: Represents a bi-directional process able to allow a Rust application to communicate with a hosted operating system process / command via STDIN / STDOUT / STDERR. This continues until the CProcessProtocol::terminate is called.
CSerialPortProtocol: Created via the hw_open_serial_port function of the module. This implements CProtocolHandler to support a bi-directional communication with an attached device via a serial port.
CTaskResult: The result of a async_task call. This holds an internal thread that will call the CTaskCB to process specified data and return the result. The CTaskResult::has_completed will let you know when the thread has completed so you can then call CTaskResult::value for the processed value.
CTimerResult: The result of a async_timer function call. This holds the internals of the thread running the CTimerCB until the CTimerResult::stop is called.
CWebSocketProtocol: Object created from the network_upgrade_web_socket call when a web socket client request is handled in the network_serve function call of http requests.
CWorkerProtocol: The result of a async_worker call. This holds a dedicated thread that is waiting for data via the CWorkerProtocol::post_message. This will queue of data for processing and the internal thread will process that data in accordance with the CWorkerCB. Any processed data is available via the CProtocolHandler bound trait functions.

Enums§

CDataType: Enumeration to support the json_check_type function for checking if a CObject holds the specified data type.
CDiskType: Identifies the type of src on the disk when attempting to see if it disk_exists or not.
CFetchAction: Supports the CFetchRequest::new object construction in order to set the appropriate action to take with the URL specified.
CFileContents: Supports the disk_read_file and disk_write_file functions for reading / writing file contents from the host operating system disk.
CLogLevel: Represents the log levels for the logging module.
CMathFormula: Collection of mathematical formulas that support the npu_math function. Simply specify the formula, pass the parameters, and get the answer.
CSerialPortData: Provides the CSerialPortProtocol ability to both CSerialPortProtocol::post_message utilizing the CSerialPortData as the data wrapper and as the CSerialPortProtocol::get_message request via the CSerialPortData::get_message_request function to query the port for data.
CWebSocketData: Supports the CWebSocketProtocol::post_message to hold data of an appropriate type along with the CWebSocketProtocol::get_message to get read messages if available.

Traits§

CCsvFormat: Defines a trait to allow a struct to transform its data into a CSV format.
CProtocolHandler: Defines a trait for the “rules” of objects that will setup a protocol that directly exchanges data with an external item, will continuously run until terminated, requires the ability to know it is running and get any errors that have occurred during it run.
CTruthyString: Defines a trait to attach to the CObject providing utility function definitions to make a bool based on a series of strings that can be considered true in nature.

Functions§

async_sleep: Will put a currently running thread (main or background) to sleep for a specified delay in milliseconds.
async_task: Creates a CTaskResult which runs a background thread to eventually retrieve the value of the task. The data in the examples are Option<T> to represent the optional data for the task and optional data returned. The function is templated so you can use any data type.
async_timer: Creates a repeating CTimerCB on the specified interval (in milliseconds). The task is completed when the CTimerResult::stop is called.
async_worker: Creates a CWorkerProtocol object that has a dedicated background thread for processing any data type you specify for the CWorkerCB loop. The task is ran when data is received via the CWorkerProtocol::post_message call. Messages are processed in the order received (First In First Out). The thread is blocked (i.e. no data, not doing anything) until the protocol receives a message. To get process data simply call CWorkerProtocol::get_message.
console_alert: Puts out an alert to STDOUT awaiting for the user to press the ENTER key.
console_choose: Prompts a user via STDIN to choose from a set of choices. The response will be a u32 based on the selection made. Entering invalid data will repeat the menu of choices until a valid selection is made.
console_confirm: Prompts a user via STDIN to confirm a choice. The response will be a true / false based on CObject::is_truthy testing of the response.
console_password: Prompts a user via STDIN to enter their password. The password will not be reflected as they type.
console_prompt: Prompts a user via STDIN to answer a question.
console_write: Will put a string to STDOUT without the new line character.
console_writeln: Will put a string to STDOUT with a new line character.
db_exists: Ensures a database exists as any of the db_query and db_update functions will panic if the specified database does not exist. So this will aid in ensuring expected configurations.
db_manage: Manages the sqlite3 database on disk by creating the initial database if it does not already exist along with execute Data Definition Language SQL statements to manage the database.
db_query: Will query a table specified by the db_path to retrieve the data as a vector of the given type. This represents the Data Query Language (DQL) SELECT statement.
db_update: Provides the ability Data Manipulation Language (DML) statements (i.e. INSERT, DELETE, or UPDATE) with the number of rows updated based on the transaction.
db_version: Determines the setup version of sqlite supported by the module
disk_cp: Will copy a file / directory from one location on the host operating system disk to the other.
disk_exists: Determines if a directory or file exists on the host operating system and will further determine if it is of the expected CDiskType.
disk_ls: Will list the files / directories in a given location on the host operating system.
disk_metadata: Retrieves metadata about the specified directory or stored on the host operating system.
disk_mkdir: Will create a directory and sub-directories in a given location on the host operating system.
disk_mv: Will move a file / directory from one location on the host operating system disk to the other.
disk_read_file: Reads a binary file from the host operating system.
disk_rm: Will remove a file / directory from one location on the host operating system disk to the other.
disk_write_file: Writes a binary file to the host operating system.
hw_available_bluetooth_devices: Scans for available bluetooth devices in the area to allow for later connection via the hw_open_bluetooth_device function.
hw_available_serial_ports: Scans for available serial ports returning a Vector of SerialPortInfo objects that can be utilized with hw_open_serial_port function for a selected port.
hw_open_bluetooth_device: FUTURE IMPLEMENTATION. DON'T USE
hw_open_serial_port: Takes a SerialPortInfo object to create a CSerialPortProtocol to interact with a device attached to the host operating system.
json_as_bool: Will convert the given CObject to its equivalent bool value. This will also be false if not a valid value.
json_as_number: Will convert the given CObject to its equivalent number value. This will be set to None if the conversion fails.
json_as_string: Will convert the given CObject to its equivalent string value. This will be None if the conversion fails.
json_check_type: Will determine if the specified CObject is of the specified CDataType enumeration.
json_create_array: Creates a JSON compliant CObject for working with array JSON data.
json_create_object: Creates a JSON compliant CObject for working with object JSON data.
json_has_key: Will check if a CObject object data JSON type has the specified key property before working with it.
json_parse: Takes a JSON serialized string and parses it to create a CObject. Returns None if the parse fails.
json_stringify: Takes a CObject and converts it the serialized JSON string. See json_parse for examples.
json_valid_url: Validates if a specified data str represents a valid URL. True if it is and false if not.
logger_get_log_handler: Gets the CLoggedEventHandler for the logging module.
logger_get_log_level: Gets the CLogLevel for the logging module.
logger_log: Will log an event via the logger module so long as it meets the currently set CLogLevel. Once logged to STDOUT, if a CLoggedEventHandler, will pass the CLogRecord along for further processing.
logger_set_log_handler: Sets the CLoggedEventHandler for the logging module.
logger_set_log_level: Sets the CLogLevel for the logging module.
monitor_components: Constructs a CComponentMonitor to monitor attached hardware component temperatures in °C.
monitor_disk: Constructs a CDiskMonitor to monitor the attached disk drives to the host operating system.
monitor_network: Constructs a CNetworkMonitor to monitor the network interfaces to the host operating system.
monitor_performance: Constructs a CPerformanceMonitor to monitor the overall CPU / memory utilization.
monitor_processes: Constructs a CProcessMonitor to monitor the the different running processes on the host operating system.
network_fetch: Executes a CFetchRequest to a REST API endpoint resulting in a CFetchResponse from that given server endpoint.
network_serve: Starts a http server listener to service http socket requests via the passed to the function. This function is a light wrapper around the rouille crate building a similar API as other CodeMelted DEV modules for serving HTTP endpoints. This is also a blocking call so once started, it blocks until quit so setup appropriate threading if your app is doing other things besides acting as a REST API endpoint.
network_upgrade_web_socket: Provides the mechanism for upgrading a to a web socket from the network_serve function call. The result will either Websocket with response or an error if the upgrade could not be carried out. The Receiver is held open until the server closes the connection or the connection is lost meaning the client must re-connect.
network_web_rtc: FUTURE IMPLEMENTATION. DON'T CALL.
npu_compute: FUTURE IMPLEMENTATION. DON'T CALL.
npu_math: Function to execute the CMathFormula enumerated formula by specifying enumerated formula and the arguments for the calculated result.
process_exists: Determines if a given executable command exists on the host operating system. Indicated with a true / false return.
process_run: Will execute a command with the host operating system and return its reported output. This is a blocking non-interactive call so no communicating with the process via STDIN.
process_spawn: Creates a bi-directional CProcessProtocol to support communicating with other hosted operating system applications / services via STDIN, STDOUT, and STDERR. You must call CProcessProtocol::terminate to properly cleanup the process.
runtime_cpu_arch: Will identify the current CPU architecture.
runtime_cpu_count: Will identify the number of available CPUs for background thread processing. If it can’t be determined then 1 is returned.
runtime_environment: Provides access to the operating system environment settings. Simply specify the key and get the result. If the key is not found then None is returned.
runtime_home_path: Gets the home path of the logged in user from the host operating system.
runtime_hostname: Retrieves the hostname of the given computer on the network. Will return UNDETERMINED if it cannot be determined.
runtime_kernel_version: Retrieves the kernel version of the host operating system. UNDETERMINED is returned if it could not be determined.
runtime_newline: Retrieves the newline character utilized by the host operating system.
runtime_online: Determines if the host operating system has access to the open Internet.
runtime_os_name: Retrieves the operating system name of the host operating system. UNDETERMINED is returned if it could not be determined.
runtime_os_version: Retrieves the operating system version of the host operating system. UNDETERMINED is returned if it could not be determined.
runtime_path_separator: Gets the path separator slash character based on the host operating system.
runtime_temp_path: Retrieves the temporary path for storing data by the host operating system.
runtime_user: Retrieves the logged in user session for the host operating system. UNDETERMINED is returned if it could not be determined.
storage_clear: Clears the currently held storage in memory and disk.
storage_get: Gets a key from the module storage or None if it don’t exist.
storage_init: Responsible for initializing the storage for the module. This must be called first before the module can be used or a panic will occur. It will read previous storage from disk and bring it into memory for later access.
storage_length: Retrieves the currently held key / value pairs by the module.
storage_remove: Removes a key / value in the module storage.
storage_set: Sets a key / value in the module storage.

Type Aliases§

CLoggedEventHandler: Function type definition for post processing logged events.
CObject: The binding that provides the codemelted module’s “dynamic” data allowing for full support of JSON along with holding general Rust data types that can be returned from different use case functions.
CServerRequest: Wrapper over the rouille::Request struct to prevent name collisions.
CServerResponse: Wrapper over the rouille::Response struct to prevent name collisions.
CTaskCB: The task that runs as part of the CTaskResult internal thread.
CTimerCB: The task that runs within the CTimerResult thread.
CWorkerCB: The task that runs within the CWorkerProtocol thread.