obrimbaseapi/essential/visible/service/helper/retriever/retriever.go

/*
|--------------------------------------------------------------------------
| Retriever
|--------------------------------------------------------------------------
|
| Name:
|   - Retriever
|
| Purpose:
|   - Retrieve data from supported resource providers through a unified
|     retrieval interface.
|
| Guidelines:
|   - Validate retrieval type before processing.
|   - Validate configuration according to retrieval type.
|   - Route retrieval through type-based dispatching.
|   - Maintain provider registries per retrieval type.
|   - Hide provider-specific implementation details from consumers.
|
| Examples:
|   - ObrimRetriever("json", config)
|   - ObrimRetrieverJsonRegister("metadata", provider)
|
|--------------------------------------------------------------------------
*/

/*
|--------------------------------------------------------------------------
| Credit
|--------------------------------------------------------------------------
|
| Contributor:
|   - Rajon Ahmed
|   - Scionite
|
|--------------------------------------------------------------------------
*/

package retriever

import (
	"strings"
	"sync"

	"go/module/name/essential/external/service/helper/log"
	"go/module/name/essential/external/service/helper/status"
)

// JSON Provider Purpose: Retrieve a complete resource payload.
type ObrimRetrieverJsonProvider interface {
	Retrieve() (any, error)
}

// JSON Registry Purpose: Store registered JSON providers.
var ObrimRetrieverJsonRegistry = struct {
	sync.RWMutex
	Providers map[string]ObrimRetrieverJsonProvider
}{
	Providers: map[string]ObrimRetrieverJsonProvider{},
}

// DB Registry Purpose: Store registered database providers.
var ObrimRetrieverDbRegistry = struct {
	sync.RWMutex
	Providers map[string]any
}{
	Providers: map[string]any{},
}

// Function Name: ObrimRetriever
// Function Purpose: Retrieve data using a unified retrieval interface.
func ObrimRetriever(retrievalType string, config map[string]any) map[string]any {
	status.ObrimStatus("INFO", "Processing retrieval request.")
	log.ObrimLog("INIT", "Retriever execution started.")

	if response := obrimRetrieverValidateType(retrievalType); response != nil {
		return response
	}

	if response := obrimRetrieverValidateConfig(retrievalType, config); response != nil {
		return response
	}

	switch retrievalType {
	case "json":
		return obrimRetrieverJson(config)

	case "db":
		return obrimRetrieverDb(config)

	default:
		return obrimRetrieverBuildResponse(
			false,
			"FAILED_UNSUPPORTED_TYPE",
			nil,
		)
	}
}

// Function Name: ObrimRetrieverJsonRegister
// Function Purpose: Register a JSON provider against a resource identifier.
func ObrimRetrieverJsonRegister(resource string, provider any) {
	jsonProvider, ok := provider.(ObrimRetrieverJsonProvider)
	if !ok {
		return
	}

	ObrimRetrieverJsonRegistry.Lock()
	defer ObrimRetrieverJsonRegistry.Unlock()

	ObrimRetrieverJsonRegistry.Providers[resource] = jsonProvider
}

// Function Name: ObrimRetrieverDbRegister
// Function Purpose: Register a database provider against a resource identifier.
func ObrimRetrieverDbRegister(resource string, provider any) {
	ObrimRetrieverDbRegistry.Lock()
	defer ObrimRetrieverDbRegistry.Unlock()

	ObrimRetrieverDbRegistry.Providers[resource] = provider
}

// Function Name: obrimRetrieverValidateType
// Function Purpose: Validate the requested retrieval type.
func obrimRetrieverValidateType(retrievalType string) map[string]any {
	switch retrievalType {
	case "json", "db":
		return nil
	default:
		return obrimRetrieverBuildResponse(
			false,
			"FAILED_UNSUPPORTED_TYPE",
			nil,
		)
	}
}

// Function Name: obrimRetrieverValidateConfig
// Function Purpose: Validate configuration according to retrieval type requirements.
func obrimRetrieverValidateConfig(
	retrievalType string,
	config map[string]any,
) map[string]any {
	if config == nil {
		return obrimRetrieverBuildResponse(
			false,
			"FAILED_MISSING_CONFIGURATION",
			nil,
		)
	}

	switch retrievalType {
	case "json":
		return obrimRetrieverJsonValidate(config)

	case "db":
		return obrimRetrieverDbValidate(config)

	default:
		return obrimRetrieverBuildResponse(
			false,
			"FAILED_UNSUPPORTED_TYPE",
			nil,
		)
	}
}

// Function Name: obrimRetrieverResolveProvider
// Function Purpose: Resolve a provider using a registered resource identifier.
func obrimRetrieverResolveProvider(resource string) (any, bool) {
	ObrimRetrieverJsonRegistry.RLock()
	defer ObrimRetrieverJsonRegistry.RUnlock()

	provider, exists := ObrimRetrieverJsonRegistry.Providers[resource]

	return provider, exists
}

// Function Name: obrimRetrieverBuildResponse
// Function Purpose: Build standardized utility responses.
func obrimRetrieverBuildResponse(
	statusValue bool,
	code string,
	payload any,
) map[string]any {
	return map[string]any{
		"status":  statusValue,
		"code":    code,
		"payload": payload,
	}
}

// Function Name: obrimRetrieverJson
// Function Purpose: Process JSON retrieval requests.
func obrimRetrieverJson(config map[string]any) map[string]any {
	resource := config["resource"].(string)

	provider, exists := obrimRetrieverResolveProvider(resource)
	if !exists {
		return obrimRetrieverBuildResponse(
			false,
			"FAILED_RESOURCE_NOT_FOUND",
			nil,
		)
	}

	jsonProvider := provider.(ObrimRetrieverJsonProvider)

	if _, exists := config["path"]; exists {
		return obrimRetrieverJsonPath(jsonProvider, config)
	}

	if _, exists := config["fields"]; exists {
		return obrimRetrieverJsonFields(jsonProvider, config)
	}

	return obrimRetrieverJsonResource(jsonProvider)
}

// Function Name: obrimRetrieverJsonResource
// Function Purpose: Retrieve a complete JSON resource payload.
func obrimRetrieverJsonResource(
	provider ObrimRetrieverJsonProvider,
) map[string]any {
	data, err := provider.Retrieve()
	if err != nil {
		return obrimRetrieverBuildResponse(
			false,
			"FAILED_RESOURCE_NOT_FOUND",
			nil,
		)
	}

	return obrimRetrieverBuildResponse(
		true,
		"SUCCESS_RESOURCE",
		map[string]any{
			"data": data,
		},
	)
}

// Function Name: obrimRetrieverJsonPath
// Function Purpose: Retrieve a value using a dot-notation path.
func obrimRetrieverJsonPath(
	provider ObrimRetrieverJsonProvider,
	config map[string]any,
) map[string]any {
	data, err := provider.Retrieve()
	if err != nil {
		return obrimRetrieverBuildResponse(
			false,
			"FAILED_RESOURCE_NOT_FOUND",
			nil,
		)
	}

	path := config["path"].(string)

	value, found := obrimRetrieverJsonResolvePath(data, path)
	if !found {
		return obrimRetrieverBuildResponse(
			false,
			"FAILED_PATH_NOT_FOUND",
			nil,
		)
	}

	return obrimRetrieverBuildResponse(
		true,
		"SUCCESS_PATH",
		map[string]any{
			"data": value,
		},
	)
}

// Function Name: obrimRetrieverJsonFields
// Function Purpose: Retrieve multiple values using field path selection.
func obrimRetrieverJsonFields(
	provider ObrimRetrieverJsonProvider,
	config map[string]any,
) map[string]any {
	data, err := provider.Retrieve()
	if err != nil {
		return obrimRetrieverBuildResponse(
			false,
			"FAILED_RESOURCE_NOT_FOUND",
			nil,
		)
	}

	fields, ok := config["fields"].([]string)
	if !ok {
		interfaceFields, ok := config["fields"].([]any)
		if !ok {
			return obrimRetrieverBuildResponse(
				false,
				"FAILED_INVALID_CONFIGURATION",
				nil,
			)
		}

		fields = make([]string, 0, len(interfaceFields))

		for _, field := range interfaceFields {
			fieldString, ok := field.(string)
			if !ok {
				return obrimRetrieverBuildResponse(
					false,
					"FAILED_INVALID_CONFIGURATION",
					nil,
				)
			}

			fields = append(fields, fieldString)
		}
	}

	result := map[string]any{}

	for _, field := range fields {
		value, found := obrimRetrieverJsonResolvePath(data, field)
		if !found {
			return obrimRetrieverBuildResponse(
				false,
				"FAILED_FIELD_NOT_FOUND",
				nil,
			)
		}

		result[field] = value
	}

	return obrimRetrieverBuildResponse(
		true,
		"SUCCESS_FIELDS",
		map[string]any{
			"data": result,
		},
	)
}

// Function Name: obrimRetrieverJsonValidate
// Function Purpose: Validate JSON retrieval configuration.
func obrimRetrieverJsonValidate(config map[string]any) map[string]any {
	resource, exists := config["resource"]
	if !exists {
		return obrimRetrieverBuildResponse(
			false,
			"FAILED_MISSING_CONFIGURATION",
			nil,
		)
	}

	resourceString, ok := resource.(string)
	if !ok || strings.TrimSpace(resourceString) == "" {
		return obrimRetrieverBuildResponse(
			false,
			"FAILED_INVALID_CONFIGURATION",
			nil,
		)
	}

	_, hasPath := config["path"]
	_, hasFields := config["fields"]

	if hasPath && hasFields {
		return obrimRetrieverBuildResponse(
			false,
			"FAILED_INVALID_CONFIGURATION",
			nil,
		)
	}

	return nil
}

// Function Name: obrimRetrieverDb
// Function Purpose: Process database retrieval requests.
func obrimRetrieverDb(config map[string]any) map[string]any {
	return obrimRetrieverBuildResponse(
		false,
		"FAILED_NOT_IMPLEMENTED",
		nil,
	)
}

// Function Name: obrimRetrieverDbValidate
// Function Purpose: Validate database retrieval configuration.
func obrimRetrieverDbValidate(config map[string]any) map[string]any {
	return nil
}

// Function Name: obrimRetrieverJsonResolvePath
// Function Purpose: Resolve a dot-notation path from a resource payload.
func obrimRetrieverJsonResolvePath(
	data any,
	path string,
) (any, bool) {
	if strings.TrimSpace(path) == "" {
		return data, true
	}

	current := data

	for _, segment := range strings.Split(path, ".") {
		object, ok := current.(map[string]any)
		if !ok {
			return nil, false
		}

		value, exists := object[segment]
		if !exists {
			return nil, false
		}

		current = value
	}

	return current, true
}