upd: helper utilities updated
This commit is contained in:
parent
43aa75db55
commit
8ee00518d3
GPG Key ID:
19C3D328D8C8F65F
84
README.md
84
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
|
||||
|
||||
@ -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)
|
||||
}
|
||||
|
||||
|
||||
@ -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.")
|
||||
|
||||
@ -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",
|
||||
)
|
||||
}
|
||||
|
||||
|
||||
@ -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)
|
||||
|
||||
@ -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.")
|
||||
|
||||
2
go.mod
2
go.mod
@ -1,3 +1,5 @@
|
||||
module go/module
|
||||
|
||||
go 1.26.4
|
||||
|
||||
require github.com/sqids/sqids-go v0.4.1
|
||||
|
||||
Loading…
Reference in New Issue
Block a user