From 8ee00518d3b7b0730bac2ebd67a19d462ab83ac3 Mon Sep 17 00:00:00 2001 From: Rajon Ahmed Date: Wed, 17 Jun 2026 21:35:35 +0800 Subject: [PATCH] upd: helper utilities updated --- README.md | 84 +++++++++---------- .../visible/service/helper/cipher/cipher.go | 6 +- essential/visible/service/helper/hash/hash.go | 9 -- essential/visible/service/helper/log/log.go | 56 ++++++------- .../service/helper/retriever/retriever.go | 7 +- .../visible/service/helper/status/status.go | 4 +- go.mod | 2 + go.sum | 2 + 8 files changed, 78 insertions(+), 92 deletions(-) create mode 100644 go.sum diff --git a/README.md b/README.md index b92e1d1..92de6ea 100644 --- a/README.md +++ b/README.md @@ -2,9 +2,9 @@ ## Description -API Framework is a layered API application framework designed to provide a structured foundation for building maintainable, scalable, and extensible web services. +API Framework is a layered API software framework designed to provide a structured foundation for building maintainable, scalable, and extensible web services. -The framework separates framework capabilities, application capabilities, resource management, request processing, policy enforcement, and runtime execution into clearly defined architectural layers. It provides standardized request handling, response generation, execution pipelines, reusable utility services, and runtime orchestration while maintaining strict ownership boundaries between framework and application components. +The framework separates framework capabilities, software capabilities, resource management, request processing, policy enforcement, and runtime execution into clearly defined architectural layers. It provides standardized request handling, response generation, execution pipelines, reusable utility services, and runtime orchestration while maintaining strict ownership boundaries between framework and software components. The framework supports: @@ -19,29 +19,29 @@ The framework supports: The architecture is organized into four primary layers: -- **Data** — Framework and application resources. +- **Data** — Framework and software resources. - **Essential** — Reusable framework capabilities and infrastructure. -- **Operational** — Application-specific business capabilities and policies. +- **Operational** — Software-specific business capabilities and policies. - **Run** — Runtime initialization, execution, and request processing. -This separation enables developers to focus on application behavior while relying on a consistent framework foundation for API processing, security, policy enforcement, utility services, and runtime coordination. +This separation enables developers to focus on software behavior while relying on a consistent framework foundation for API processing, security, policy enforcement, utility services, and runtime coordination. --- ## Purpose -API Framework exists to provide a consistent, maintainable, and extensible architecture for building API-driven applications while establishing clear boundaries between framework responsibilities and application responsibilities. +API Framework exists to provide a consistent, maintainable, and extensible architecture for building API-driven softwares while establishing clear boundaries between framework responsibilities and software responsibilities. ### Objectives - Establish clear separation of concerns. - Standardize API request and response processing. -- Distinguish framework-owned and application-owned resources. +- Distinguish framework-owned and software-owned resources. - Provide reusable infrastructure and utility capabilities. - Centralize policy enforcement and access control. -- Simplify application development through a structured architecture. +- Simplify software development through a structured architecture. - Improve maintainability and scalability. -- Enable controlled application extensibility. +- Enable controlled software extensibility. - Protect internal framework implementation details. - Encourage consistent API design and execution patterns. @@ -53,15 +53,15 @@ Each architectural layer is responsible for a specific concern and communicates #### Ownership Separation -Framework-owned capabilities remain separate from application-owned capabilities to prevent implementation leakage and architectural drift. +Framework-owned capabilities remain separate from software-owned capabilities to prevent implementation leakage and architectural drift. #### Extensibility -Applications extend the framework through approved extension surfaces without modifying framework internals. +Softwares extend the framework through approved extension surfaces without modifying framework internals. #### Reusability -Common functionality is implemented once and reused throughout both framework and application layers. +Common functionality is implemented once and reused throughout both framework and software layers. #### Encapsulation @@ -89,20 +89,20 @@ source └── run ``` -The architecture is organized into four primary layers that collectively provide resource management, reusable framework capabilities, application capabilities, policy enforcement, and runtime execution. +The architecture is organized into four primary layers that collectively provide resource management, reusable framework capabilities, software capabilities, policy enforcement, and runtime execution. --- ### Data Layer -The Data Layer stores all framework-owned and application-owned resources. +The Data Layer stores all framework-owned and software-owned resources. ```text source/data ├── framework │ ├── metadata │ └── glossary -└── application +└── software ├── metadata └── glossary ``` @@ -111,8 +111,8 @@ source/data - Store framework metadata and configuration resources. - Store framework glossary and terminology resources. -- Store application metadata and configuration resources. -- Store application glossary and terminology resources. +- Store software metadata and configuration resources. +- Store software glossary and terminology resources. - Provide centralized resource ownership boundaries. #### Ownership @@ -120,7 +120,7 @@ source/data | Area | Owner | |--------|--------| | data/framework | Framework | -| data/application | Application | +| data/software | Software | --- @@ -161,7 +161,7 @@ exchange ### Essential Hidden -Contains internal framework capabilities that are not intended for application consumption. +Contains internal framework capabilities that are not intended for software consumption. ```text hidden @@ -218,7 +218,7 @@ Responsible for maintenance and cleanup operations. ### Essential Visible -Contains reusable framework capabilities available to applications. +Contains reusable framework capabilities available to softwares. ```text visible @@ -260,7 +260,7 @@ codec ### Operational Layer -The Operational Layer contains all application-specific behavior, business capabilities, and policy definitions. +The Operational Layer contains all software-specific behavior, business capabilities, and policy definitions. ```text source/operational @@ -269,13 +269,13 @@ source/operational └── service ``` -This is the primary application development area. +This is the primary software development area. --- ### Operational Exchange -Provides the application API interaction model. +Provides the software API interaction model. ```text exchange @@ -287,17 +287,17 @@ exchange #### Responsibilities -- Application request routing. -- Application request processing. -- Application response generation. +- Software request routing. +- Software request processing. +- Software response generation. - Imperative execution. -- Application-level API orchestration. +- Software-level API orchestration. --- ### Operational Pipeline -Contains application-defined policy execution capabilities. +Contains software-defined policy execution capabilities. ```text pipeline @@ -331,13 +331,13 @@ Examples: - Request validation. - Request throttling. - Policy definition. -- Application-specific execution controls. +- Software-specific execution controls. --- ### Operational Service -Contains application-specific business capabilities. +Contains software-specific business capabilities. ```text service @@ -371,7 +371,7 @@ service #### Responsibilities - Implement business rules. -- Manage application workflows. +- Manage software workflows. - Execute domain-specific operations. - Consume reusable framework capabilities. @@ -471,7 +471,7 @@ Responsibilities: ### Runtime Main -Application bootstrap and startup. +Software bootstrap and startup. ```text main @@ -481,7 +481,7 @@ main #### Responsibilities - Framework initialization. -- Application initialization. +- Software initialization. - Runtime startup. - Lifecycle coordination. - API server bootstrap. @@ -506,14 +506,14 @@ Access Pipeline Policy Enforcement │ ▼ -Application Exchange +Software Exchange │ ▼ -Application Policies +Software Policies (Validation / Rate Limiting) │ ▼ -Application Service +Software Service │ ▼ Framework Services @@ -532,29 +532,29 @@ Response | Layer | Owner | Responsibility | |---------|---------|---------| | data/framework | Framework | Framework resources | -| data/application | Application | Application resources | +| data/software | Software | Software resources | | essential | Framework | Reusable framework capabilities | -| operational | Application | Business capabilities and policies | +| operational | Software | Business capabilities and policies | | run | Framework | Runtime execution and enforcement | --- ### Extension Surface -Applications are expected to extend the framework through the following locations: +Softwares are expected to extend the framework through the following locations: ```text -source/data/application +source/data/software source/operational ``` -Applications should consume reusable framework capabilities from: +Softwares should consume reusable framework capabilities from: ```text source/essential/visible ``` -Applications should not directly depend on: +Softwares should not directly depend on: ```text source/essential/hidden diff --git a/essential/visible/service/helper/cipher/cipher.go b/essential/visible/service/helper/cipher/cipher.go index 5a0da83..6eefb35 100644 --- a/essential/visible/service/helper/cipher/cipher.go +++ b/essential/visible/service/helper/cipher/cipher.go @@ -54,8 +54,6 @@ import ( "path/filepath" "go/module/essential/visible/service/helper/log" - "go/module/essential/visible/service/helper/retriever" - "go/module/essential/visible/service/helper/status" ) const ( @@ -74,8 +72,6 @@ type obrimCipherResponse struct { // ObrimCipher executes encryption and decryption workflows. func ObrimCipher(operationType string, config map[string]any) map[string]any { - _, _ = retriever.ObrimRetriever, status.ObrimStatus - log.ObrimLog("INIT", "Cipher operation initialized.") if err := obrimCipherValidateType(operationType); err != nil { @@ -88,7 +84,7 @@ func ObrimCipher(operationType string, config map[string]any) map[string]any { keyValue := config["key"].(string) - if err := obrimCipherValidateKey(keyValue); err != nil { + if err := obrimCipherValidateKey([]byte(keyValue)); err != nil { return obrimCipherBuildResponse(false, "FAILED_INVALID_KEY", nil) } diff --git a/essential/visible/service/helper/hash/hash.go b/essential/visible/service/helper/hash/hash.go index 647f370..b2cbc2b 100644 --- a/essential/visible/service/helper/hash/hash.go +++ b/essential/visible/service/helper/hash/hash.go @@ -45,7 +45,6 @@ import ( "strings" "go/module/essential/visible/service/helper/log" - "go/module/essential/visible/service/helper/retriever" "go/module/essential/visible/service/helper/status" ) @@ -57,14 +56,6 @@ func ObrimHash( status.ObrimStatus("INFO", "Hash utility execution started.") log.ObrimLog("INIT", "Hash utility execution started.") - _, _ = retriever.ObrimRetriever( - "json", - map[string]any{ - "resource": "framework/metadata", - "path": "name", - }, - ) - if !obrimHashValidateType(hashType) { status.ObrimStatus("ERROR", "Invalid hash type.") log.ObrimLog("ERROR", "Invalid hash type.") diff --git a/essential/visible/service/helper/log/log.go b/essential/visible/service/helper/log/log.go index 2935454..cfd35a4 100644 --- a/essential/visible/service/helper/log/log.go +++ b/essential/visible/service/helper/log/log.go @@ -14,7 +14,7 @@ | - Use for framework and software logging. | - Writes append-only UTF-8 log entries. | - Preserves existing log content. -| - Uses application metadata to determine storage location. +| - Uses software metadata to determine storage location. | - Does not implement rotation, retention, archival, or compression. | | Example: @@ -51,7 +51,7 @@ import ( // ObrimLog writes a structured log entry. func ObrimLog(label string, message string) { - applicationName := obrimLogApplicationResolve() + softwareName := obrimLogSoftwareResolve() timestamp := obrimLogTimestampGenerate() @@ -61,11 +61,11 @@ func ObrimLog(label string, message string) { message, ) - logDirectory := obrimLogDirectoryResolve(applicationName) + logDirectory := obrimLogDirectoryResolve(softwareName) logFile := obrimLogFileResolve( logDirectory, - applicationName, + softwareName, ) if !obrimLogFileEnsure(logDirectory, logFile) { @@ -94,47 +94,47 @@ func obrimLogEntryBuild( ) } -// obrimLogApplicationResolve resolves the application name. -func obrimLogApplicationResolve() string { +// obrimLogSoftwareResolve resolves the software name. +func obrimLogSoftwareResolve() string { value := retriever.ObrimRetriever( "json", map[string]any{ - "resource": "application/metadata", - "path": "application.lower", + "resource": "software/metadata", + "path": "software.lower", }, ) name := strings.TrimSpace(fmt.Sprintf("%v", value)) if name == "" { - return "application" + return "software" } return name } // obrimLogDirectoryResolve resolves platform-specific log directory paths. -func obrimLogDirectoryResolve(applicationName string) string { +func obrimLogDirectoryResolve(softwareName string) string { switch runtime.GOOS { case "windows": - return obrimLogDirectoryResolveWindows(applicationName) + return obrimLogDirectoryResolveWindows(softwareName) case "darwin": - return obrimLogDirectoryResolveMacOS(applicationName) + return obrimLogDirectoryResolveMacOS(softwareName) default: - return obrimLogDirectoryResolveLinux(applicationName) + return obrimLogDirectoryResolveLinux(softwareName) } } // obrimLogDirectoryResolveLinux resolves Linux log directory paths. -func obrimLogDirectoryResolveLinux(applicationName string) string { +func obrimLogDirectoryResolveLinux(softwareName string) string { xdgStateHome := strings.TrimSpace(os.Getenv("XDG_STATE_HOME")) if xdgStateHome != "" { return filepath.Join( xdgStateHome, - "."+applicationName, + "."+softwareName, "logs", ) } @@ -144,7 +144,7 @@ func obrimLogDirectoryResolveLinux(applicationName string) string { if errorValue != nil { return filepath.Join( ".", - "."+applicationName, + "."+softwareName, "logs", ) } @@ -153,40 +153,40 @@ func obrimLogDirectoryResolveLinux(applicationName string) string { homeDirectory, ".local", "state", - "."+applicationName, + "."+softwareName, "logs", ) } // obrimLogDirectoryResolveWindows resolves Windows log directory paths. -func obrimLogDirectoryResolveWindows(applicationName string) string { - localApplicationData := strings.TrimSpace( +func obrimLogDirectoryResolveWindows(softwareName string) string { + localSoftwareData := strings.TrimSpace( os.Getenv("LOCALAPPDATA"), ) - if localApplicationData == "" { + if localSoftwareData == "" { homeDirectory, errorValue := os.UserHomeDir() if errorValue == nil { - localApplicationData = homeDirectory + localSoftwareData = homeDirectory } } return filepath.Join( - localApplicationData, - applicationName, + localSoftwareData, + softwareName, "Logs", ) } // obrimLogDirectoryResolveMacOS resolves macOS log directory paths. -func obrimLogDirectoryResolveMacOS(applicationName string) string { +func obrimLogDirectoryResolveMacOS(softwareName string) string { homeDirectory, errorValue := os.UserHomeDir() if errorValue != nil { return filepath.Join( ".", - "."+applicationName, + "."+softwareName, ) } @@ -194,18 +194,18 @@ func obrimLogDirectoryResolveMacOS(applicationName string) string { homeDirectory, "Library", "Logs", - "."+applicationName, + "."+softwareName, ) } // obrimLogFileResolve resolves platform-specific log file paths. func obrimLogFileResolve( logDirectory string, - applicationName string, + softwareName string, ) string { return filepath.Join( logDirectory, - applicationName+".log", + softwareName+".log", ) } diff --git a/essential/visible/service/helper/retriever/retriever.go b/essential/visible/service/helper/retriever/retriever.go index 13e0ab0..102bab9 100644 --- a/essential/visible/service/helper/retriever/retriever.go +++ b/essential/visible/service/helper/retriever/retriever.go @@ -20,7 +20,7 @@ | - ObrimRetriever("json", map[string]any{"resource": "metadata"}) | - ObrimRetriever("json", map[string]any{ | "resource": "metadata", -| "path": "application.name", +| "path": "software.name", | }) | |-------------------------------------------------------------------------- @@ -43,9 +43,6 @@ package retriever import ( "fmt" "strings" - - "go/module/essential/visible/service/helper/log" - "go/module/essential/visible/service/helper/status" ) // ObrimRetrieverResponse represents the standardized utility response. @@ -63,8 +60,6 @@ var ObrimRetrieverDbProviderRegistry = map[string]any{} // ObrimRetriever retrieves data using a unified retrieval interface. func ObrimRetriever(retrievalType string, config map[string]any) map[string]any { - status.ObrimStatus("INFO", "Retriever started.") - log.ObrimLog("INIT", "Retriever execution started.") if !obrimRetrieverValidateType(retrievalType) { return obrimRetrieverBuildResponse(false, "FAILED_UNSUPPORTED_TYPE", nil) diff --git a/essential/visible/service/helper/status/status.go b/essential/visible/service/helper/status/status.go index a9b3bf4..0439283 100644 --- a/essential/visible/service/helper/status/status.go +++ b/essential/visible/service/helper/status/status.go @@ -9,7 +9,7 @@ | Purpose: | - Provide a framework-level CLI status utility that standardizes | terminal message presentation using semantic labels and visual -| indicators to ensure consistent output across all applications. +| indicators to ensure consistent output across all softwares. | | Guideline: | - Use semantic labels to classify terminal messages. @@ -18,7 +18,7 @@ | - Intended for framework and software level terminal messaging. | | Example: -| - ObrimStatus("INFO", "Application started.") +| - ObrimStatus("INFO", "Software started.") | - ObrimStatus("SUCCESS", "Operation completed.") | - ObrimStatus("WARNING", "Configuration missing.") | - ObrimStatus("ERROR", "Operation failed.") diff --git a/go.mod b/go.mod index 75e7cc0..d13e469 100644 --- a/go.mod +++ b/go.mod @@ -1,3 +1,5 @@ module go/module go 1.26.4 + +require github.com/sqids/sqids-go v0.4.1 diff --git a/go.sum b/go.sum new file mode 100644 index 0000000..a02109b --- /dev/null +++ b/go.sum @@ -0,0 +1,2 @@ +github.com/sqids/sqids-go v0.4.1 h1:eQKYzmAZbLlRwHeHYPF35QhgxwZHLnlmVj9AkIj/rrw= +github.com/sqids/sqids-go v0.4.1/go.mod h1:EMwHuPQgSNFS0A49jESTfIQS+066XQTVhukrzEPScl8=