/*
|--------------------------------------------------------------------------
| Metadata
|--------------------------------------------------------------------------
|
| Name:
|   - Handler
|
| Purpose:
|   - Provide a JSON resource provider for the Retriever utility.
|   - Embed, parse, and expose a complete JSON resource payload.
|   - Abstract resource storage details from consumers.
|
| Guideline:
|   - Register the handler through retriever.ObrimRetrieverJsonRegister().
|   - Associate the handler with a unique resource identifier.
|   - Return the complete parsed resource payload only.
|   - Delegate retrieval, traversal, filtering, and selection logic to Retriever.
|   - Do not implement business logic within the handler.
|   - Do not perform querying, transformation, or resource discovery.
|
| Example:
|   - retriever.ObrimRetrieverJsonRegister(
|       "software/metadata",
|       obrimHandlerProvider{},
|     )
|   - response := retriever.ObrimRetriever(
|       "json",
|       map[string]any{
|         "resource": "software/metadata",
|       },
|     )
|
|--------------------------------------------------------------------------
*/

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

package handler

import (
	"embed"
	"encoding/json"
	"errors"

	"go/module/essential/visible/service/helper/retriever"
)

// constant
const (
	// resource
	obrimHandlerResourceIdentifier = "framework/metadata" // change identifier if needed
	obrimHandlerResourceFileName   = "resource"           // change file name if needed
	obrimHandlerResourceFileExt    = ".json"              // do not change

	// success
	ObrimHandlerCodeSuccessResourceAvailable = "SUCCESS_RESOURCE_AVAILABLE"

	// fail
	ObrimHandlerCodeFailedResourceNotFound = "FAILED_RESOURCE_NOT_FOUND"
	ObrimHandlerCodeFailedInvalidResource  = "FAILED_INVALID_RESOURCE"
)

// obrimHandlerEmbeddedResource stores the embedded resource file.
//
//go:embed resource.json
var obrimHandlerEmbeddedResource embed.FS

// obrimHandlerProvider implements the Retriever JSON provider contract.
type obrimHandlerProvider struct{}

// Retrieve loads and returns the complete parsed resource payload.
func (provider obrimHandlerProvider) Retrieve() (any, error) {
	return obrimHandlerFetch()
}

// init registers the handler during package initialization.
func init() {
	obrimHandlerRegister()
}

// obrimHandlerRegister registers the handler with Retriever.
func obrimHandlerRegister() {
	retriever.ObrimRetrieverJsonRegister(
		obrimHandlerResourceIdentifier,
		obrimHandlerProvider{},
	)
}

// obrimHandlerFetch loads, parses, and returns the complete resource payload.
func obrimHandlerFetch() (any, error) {
	resource, err := obrimHandlerLoadResource()
	if err != nil {
		return nil, err
	}

	payload, err := obrimHandlerParseResource(resource)
	if err != nil {
		return nil, err
	}

	return payload, nil
}

// obrimHandlerLoadResource loads the embedded resource.
func obrimHandlerLoadResource() ([]byte, error) {
	resource, err := obrimHandlerEmbeddedResource.ReadFile(
		obrimHandlerResourceFileName + obrimHandlerResourceFileExt,
	)
	if err != nil {
		return nil, errors.New(ObrimHandlerCodeFailedResourceNotFound)
	}

	return resource, nil
}

// obrimHandlerParseResource parses the embedded JSON resource.
func obrimHandlerParseResource(resource []byte) (map[string]any, error) {
	var payload map[string]any

	if err := json.Unmarshal(resource, &payload); err != nil {
		return nil, errors.New(ObrimHandlerCodeFailedInvalidResource)
	}

	return payload, nil
}