engrrajonahmed/obrimbaseapi
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

upd: helper utilities updated

Browse Source
This commit is contained in:
Rajon Ahmed 2026-06-17 21:35:35 +08:00
parent 43aa75db55
commit 8ee00518d3
Signed by: engrrajonahmed
GPG Key ID: 19C3D328D8C8F65F
8 changed files with 78 additions and 92 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

84
README.md
View File

@ -2,9 +2,9 @@
## Description ## 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: The framework supports:
@ -19,29 +19,29 @@ The framework supports:
The architecture is organized into four primary layers: The architecture is organized into four primary layers:
- **Data** — Framework and application resources. - **Data** — Framework and software resources.
- **Essential** — Reusable framework capabilities and infrastructure. - **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. - **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 ## 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 ### Objectives
- Establish clear separation of concerns. - Establish clear separation of concerns.
- Standardize API request and response processing. - 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. - Provide reusable infrastructure and utility capabilities.
- Centralize policy enforcement and access control. - Centralize policy enforcement and access control.
- Simplify application development through a structured architecture. - Simplify software development through a structured architecture.
- Improve maintainability and scalability. - Improve maintainability and scalability.
- Enable controlled application extensibility. - Enable controlled software extensibility.
- Protect internal framework implementation details. - Protect internal framework implementation details.
- Encourage consistent API design and execution patterns. - Encourage consistent API design and execution patterns.
@ -53,15 +53,15 @@ Each architectural layer is responsible for a specific concern and communicates
#### Ownership Separation #### 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 #### 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 #### 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 #### Encapsulation
@ -89,20 +89,20 @@ source
└── run └── 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 ### 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 ```text
source/data source/data
├── framework ├── framework
│ ├── metadata │ ├── metadata
│ └── glossary │ └── glossary
└── application └── software
├── metadata ├── metadata
└── glossary └── glossary
``` ```
@ -111,8 +111,8 @@ source/data
- Store framework metadata and configuration resources. - Store framework metadata and configuration resources.
- Store framework glossary and terminology resources. - Store framework glossary and terminology resources.
- Store application metadata and configuration resources. - Store software metadata and configuration resources.
- Store application glossary and terminology resources. - Store software glossary and terminology resources.
- Provide centralized resource ownership boundaries. - Provide centralized resource ownership boundaries.
#### Ownership #### Ownership
@ -120,7 +120,7 @@ source/data
| Area | Owner | | Area | Owner |
|--------|--------| |--------|--------|
| data/framework | Framework | | data/framework | Framework |
| data/application | Application | | data/software | Software |
--- ---
@ -161,7 +161,7 @@ exchange
### Essential Hidden ### 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 ```text
hidden hidden
@ -218,7 +218,7 @@ Responsible for maintenance and cleanup operations.
### Essential Visible ### Essential Visible
Contains reusable framework capabilities available to applications. Contains reusable framework capabilities available to softwares.
```text ```text
visible visible
@ -260,7 +260,7 @@ codec
### Operational Layer ### 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 ```text
source/operational source/operational
@ -269,13 +269,13 @@ source/operational
└── service └── service
``` ```
This is the primary application development area. This is the primary software development area.
--- ---
### Operational Exchange ### Operational Exchange
Provides the application API interaction model. Provides the software API interaction model.
```text ```text
exchange exchange
@ -287,17 +287,17 @@ exchange
#### Responsibilities #### Responsibilities
- Application request routing. - Software request routing.
- Application request processing. - Software request processing.
- Application response generation. - Software response generation.
- Imperative execution. - Imperative execution.
- Application-level API orchestration. - Software-level API orchestration.
--- ---
### Operational Pipeline ### Operational Pipeline
Contains application-defined policy execution capabilities. Contains software-defined policy execution capabilities.
```text ```text
pipeline pipeline
@ -331,13 +331,13 @@ Examples:
- Request validation. - Request validation.
- Request throttling. - Request throttling.
- Policy definition. - Policy definition.
- Application-specific execution controls. - Software-specific execution controls.
--- ---
### Operational Service ### Operational Service
Contains application-specific business capabilities. Contains software-specific business capabilities.
```text ```text
service service
@ -371,7 +371,7 @@ service
#### Responsibilities #### Responsibilities
- Implement business rules. - Implement business rules.
- Manage application workflows. - Manage software workflows.
- Execute domain-specific operations. - Execute domain-specific operations.
- Consume reusable framework capabilities. - Consume reusable framework capabilities.
@ -471,7 +471,7 @@ Responsibilities:
### Runtime Main ### Runtime Main
Application bootstrap and startup. Software bootstrap and startup.
```text ```text
main main
@ -481,7 +481,7 @@ main
#### Responsibilities #### Responsibilities
- Framework initialization. - Framework initialization.
- Application initialization. - Software initialization.
- Runtime startup. - Runtime startup.
- Lifecycle coordination. - Lifecycle coordination.
- API server bootstrap. - API server bootstrap.
@ -506,14 +506,14 @@ Access Pipeline
Policy Enforcement Policy Enforcement
│ │
▼ ▼
Application Exchange Software Exchange
│ │
▼ ▼
Application Policies Software Policies
(Validation / Rate Limiting) (Validation / Rate Limiting)
│ │
▼ ▼
Application Service Software Service
│ │
▼ ▼
Framework Services Framework Services
@ -532,29 +532,29 @@ Response
| Layer | Owner | Responsibility | | Layer | Owner | Responsibility |
|---------|---------|---------| |---------|---------|---------|
| data/framework | Framework | Framework resources | | data/framework | Framework | Framework resources |
| data/application | Application | Application resources | | data/software | Software | Software resources |
| essential | Framework | Reusable framework capabilities | | essential | Framework | Reusable framework capabilities |
| operational | Application | Business capabilities and policies | | operational | Software | Business capabilities and policies |
| run | Framework | Runtime execution and enforcement | | run | Framework | Runtime execution and enforcement |
--- ---
### Extension Surface ### 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 ```text
source/data/application source/data/software
source/operational source/operational
``` ```
Applications should consume reusable framework capabilities from: Softwares should consume reusable framework capabilities from:
```text ```text
source/essential/visible source/essential/visible
``` ```
Applications should not directly depend on: Softwares should not directly depend on:
```text ```text
source/essential/hidden source/essential/hidden

6
essential/visible/service/helper/cipher/cipher.go
View File

@ -54,8 +54,6 @@ import (
"path/filepath" "path/filepath"
"go/module/essential/visible/service/helper/log" "go/module/essential/visible/service/helper/log"
"go/module/essential/visible/service/helper/retriever"
"go/module/essential/visible/service/helper/status"
) )
const ( const (
@ -74,8 +72,6 @@ type obrimCipherResponse struct {
// ObrimCipher executes encryption and decryption workflows. // ObrimCipher executes encryption and decryption workflows.
func ObrimCipher(operationType string, config map[string]any) map[string]any { func ObrimCipher(operationType string, config map[string]any) map[string]any {
_, _ = retriever.ObrimRetriever, status.ObrimStatus
log.ObrimLog("INIT", "Cipher operation initialized.") log.ObrimLog("INIT", "Cipher operation initialized.")
if err := obrimCipherValidateType(operationType); err != nil { 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) keyValue := config["key"].(string)
if err := obrimCipherValidateKey(keyValue); err != nil { if err := obrimCipherValidateKey([]byte(keyValue)); err != nil {
return obrimCipherBuildResponse(false, "FAILED_INVALID_KEY", nil) return obrimCipherBuildResponse(false, "FAILED_INVALID_KEY", nil)
} }

9
essential/visible/service/helper/hash/hash.go
View File

@ -45,7 +45,6 @@ import (
"strings" "strings"
"go/module/essential/visible/service/helper/log" "go/module/essential/visible/service/helper/log"
"go/module/essential/visible/service/helper/retriever"
"go/module/essential/visible/service/helper/status" "go/module/essential/visible/service/helper/status"
) )
@ -57,14 +56,6 @@ func ObrimHash(
status.ObrimStatus("INFO", "Hash utility execution started.") status.ObrimStatus("INFO", "Hash utility execution started.")
log.ObrimLog("INIT", "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) { if !obrimHashValidateType(hashType) {
status.ObrimStatus("ERROR", "Invalid hash type.") status.ObrimStatus("ERROR", "Invalid hash type.")
log.ObrimLog("ERROR", "Invalid hash type.") log.ObrimLog("ERROR", "Invalid hash type.")

56
essential/visible/service/helper/log/log.go
View File

@ -14,7 +14,7 @@
| - Use for framework and software logging. | - Use for framework and software logging.
| - Writes append-only UTF-8 log entries. | - Writes append-only UTF-8 log entries.
| - Preserves existing log content. | - 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. | - Does not implement rotation, retention, archival, or compression.
| |
| Example: | Example:
@ -51,7 +51,7 @@ import (
// ObrimLog writes a structured log entry. // ObrimLog writes a structured log entry.
func ObrimLog(label string, message string) { func ObrimLog(label string, message string) {
applicationName := obrimLogApplicationResolve() softwareName := obrimLogSoftwareResolve()
timestamp := obrimLogTimestampGenerate() timestamp := obrimLogTimestampGenerate()
@ -61,11 +61,11 @@ func ObrimLog(label string, message string) {
message, message,
) )
logDirectory := obrimLogDirectoryResolve(applicationName) logDirectory := obrimLogDirectoryResolve(softwareName)
logFile := obrimLogFileResolve( logFile := obrimLogFileResolve(
logDirectory, logDirectory,
applicationName, softwareName,
) )
if !obrimLogFileEnsure(logDirectory, logFile) { if !obrimLogFileEnsure(logDirectory, logFile) {
@ -94,47 +94,47 @@ func obrimLogEntryBuild(
) )
} }
// obrimLogApplicationResolve resolves the application name. // obrimLogSoftwareResolve resolves the software name.
func obrimLogApplicationResolve() string { func obrimLogSoftwareResolve() string {
value := retriever.ObrimRetriever( value := retriever.ObrimRetriever(
"json", "json",
map[string]any{ map[string]any{
"resource": "application/metadata", "resource": "software/metadata",
"path": "application.lower", "path": "software.lower",
}, },
) )
name := strings.TrimSpace(fmt.Sprintf("%v", value)) name := strings.TrimSpace(fmt.Sprintf("%v", value))
if name == "" { if name == "" {
return "application" return "software"
} }
return name return name
} }
// obrimLogDirectoryResolve resolves platform-specific log directory paths. // obrimLogDirectoryResolve resolves platform-specific log directory paths.
func obrimLogDirectoryResolve(applicationName string) string { func obrimLogDirectoryResolve(softwareName string) string {
switch runtime.GOOS { switch runtime.GOOS {
case "windows": case "windows":
return obrimLogDirectoryResolveWindows(applicationName) return obrimLogDirectoryResolveWindows(softwareName)
case "darwin": case "darwin":
return obrimLogDirectoryResolveMacOS(applicationName) return obrimLogDirectoryResolveMacOS(softwareName)
default: default:
return obrimLogDirectoryResolveLinux(applicationName) return obrimLogDirectoryResolveLinux(softwareName)
} }
} }
// obrimLogDirectoryResolveLinux resolves Linux log directory paths. // obrimLogDirectoryResolveLinux resolves Linux log directory paths.
func obrimLogDirectoryResolveLinux(applicationName string) string { func obrimLogDirectoryResolveLinux(softwareName string) string {
xdgStateHome := strings.TrimSpace(os.Getenv("XDG_STATE_HOME")) xdgStateHome := strings.TrimSpace(os.Getenv("XDG_STATE_HOME"))
if xdgStateHome != "" { if xdgStateHome != "" {
return filepath.Join( return filepath.Join(
xdgStateHome, xdgStateHome,
"."+applicationName, "."+softwareName,
"logs", "logs",
) )
} }
@ -144,7 +144,7 @@ func obrimLogDirectoryResolveLinux(applicationName string) string {
if errorValue != nil { if errorValue != nil {
return filepath.Join( return filepath.Join(
".", ".",
"."+applicationName, "."+softwareName,
"logs", "logs",
) )
} }
@ -153,40 +153,40 @@ func obrimLogDirectoryResolveLinux(applicationName string) string {
homeDirectory, homeDirectory,
".local", ".local",
"state", "state",
"."+applicationName, "."+softwareName,
"logs", "logs",
) )
} }
// obrimLogDirectoryResolveWindows resolves Windows log directory paths. // obrimLogDirectoryResolveWindows resolves Windows log directory paths.
func obrimLogDirectoryResolveWindows(applicationName string) string { func obrimLogDirectoryResolveWindows(softwareName string) string {
localApplicationData := strings.TrimSpace( localSoftwareData := strings.TrimSpace(
os.Getenv("LOCALAPPDATA"), os.Getenv("LOCALAPPDATA"),
) )
if localApplicationData == "" { if localSoftwareData == "" {
homeDirectory, errorValue := os.UserHomeDir() homeDirectory, errorValue := os.UserHomeDir()
if errorValue == nil { if errorValue == nil {
localApplicationData = homeDirectory localSoftwareData = homeDirectory
} }
} }
return filepath.Join( return filepath.Join(
localApplicationData, localSoftwareData,
applicationName, softwareName,
"Logs", "Logs",
) )
} }
// obrimLogDirectoryResolveMacOS resolves macOS log directory paths. // obrimLogDirectoryResolveMacOS resolves macOS log directory paths.
func obrimLogDirectoryResolveMacOS(applicationName string) string { func obrimLogDirectoryResolveMacOS(softwareName string) string {
homeDirectory, errorValue := os.UserHomeDir() homeDirectory, errorValue := os.UserHomeDir()
if errorValue != nil { if errorValue != nil {
return filepath.Join( return filepath.Join(
".", ".",
"."+applicationName, "."+softwareName,
) )
} }
@ -194,18 +194,18 @@ func obrimLogDirectoryResolveMacOS(applicationName string) string {
homeDirectory, homeDirectory,
"Library", "Library",
"Logs", "Logs",
"."+applicationName, "."+softwareName,
) )
} }
// obrimLogFileResolve resolves platform-specific log file paths. // obrimLogFileResolve resolves platform-specific log file paths.
func obrimLogFileResolve( func obrimLogFileResolve(
logDirectory string, logDirectory string,
applicationName string, softwareName string,
) string { ) string {
return filepath.Join( return filepath.Join(
logDirectory, logDirectory,
applicationName+".log", softwareName+".log",
) )
} }

7
essential/visible/service/helper/retriever/retriever.go
View File

@ -20,7 +20,7 @@
| - ObrimRetriever("json", map[string]any{"resource": "metadata"}) | - ObrimRetriever("json", map[string]any{"resource": "metadata"})
| - ObrimRetriever("json", map[string]any{ | - ObrimRetriever("json", map[string]any{
| "resource": "metadata", | "resource": "metadata",
| "path": "application.name", | "path": "software.name",
| }) | })
| |
|-------------------------------------------------------------------------- |--------------------------------------------------------------------------
@ -43,9 +43,6 @@ package retriever
import ( import (
"fmt" "fmt"
"strings" "strings"
"go/module/essential/visible/service/helper/log"
"go/module/essential/visible/service/helper/status"
) )
// ObrimRetrieverResponse represents the standardized utility response. // ObrimRetrieverResponse represents the standardized utility response.
@ -63,8 +60,6 @@ var ObrimRetrieverDbProviderRegistry = map[string]any{}
// ObrimRetriever retrieves data using a unified retrieval interface. // ObrimRetriever retrieves data using a unified retrieval interface.
func ObrimRetriever(retrievalType string, config map[string]any) map[string]any { 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) { if !obrimRetrieverValidateType(retrievalType) {
return obrimRetrieverBuildResponse(false, "FAILED_UNSUPPORTED_TYPE", nil) return obrimRetrieverBuildResponse(false, "FAILED_UNSUPPORTED_TYPE", nil)

4
essential/visible/service/helper/status/status.go
View File

@ -9,7 +9,7 @@
| Purpose: | Purpose:
| - Provide a framework-level CLI status utility that standardizes | - Provide a framework-level CLI status utility that standardizes
| terminal message presentation using semantic labels and visual | 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: | Guideline:
| - Use semantic labels to classify terminal messages. | - Use semantic labels to classify terminal messages.
@ -18,7 +18,7 @@
| - Intended for framework and software level terminal messaging. | - Intended for framework and software level terminal messaging.
| |
| Example: | Example:
| - ObrimStatus("INFO", "Application started.") | - ObrimStatus("INFO", "Software started.")
| - ObrimStatus("SUCCESS", "Operation completed.") | - ObrimStatus("SUCCESS", "Operation completed.")
| - ObrimStatus("WARNING", "Configuration missing.") | - ObrimStatus("WARNING", "Configuration missing.")
| - ObrimStatus("ERROR", "Operation failed.") | - ObrimStatus("ERROR", "Operation failed.")

2
go.mod
View File

@ -1,3 +1,5 @@
module go/module module go/module
go 1.26.4 go 1.26.4
require github.com/sqids/sqids-go v0.4.1

2
go.sum Normal file
View File

@ -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=