QuartzUITypedEndpoint: declaration reference

#pragma once

#include "CoreMinimal.h"
#include "StructUtils/InstancedStruct.h"
#include "UObject/Object.h"
#include "QuartzUICoreContract.h"

#include "QuartzUITypedEndpoint.generated.h"

class UQuartzUIEndpointRequest;
class UQuartzUIView;
class UQuartzUIWidget;
class UQuartzUIBridge;
struct FQuartzUIContractMessageDeclaration;
struct FQuartzUIEndpointResult;

/** Typed one-shot capability passed to a Blueprint/C++ asynchronous request handler. */
UCLASS(BlueprintType)
class QUARTZUIRUNTIME_API UQuartzUITypedEndpointRequest final : public UObject
{
	GENERATED_BODY()

public:
	UFUNCTION(BlueprintPure, Category = "QuartzUI|Project Endpoint")
	FName GetEndpointName() const { return EndpointName; }

	UFUNCTION(BlueprintPure, Category = "QuartzUI|Project Endpoint")
	bool IsPending() const;

	UFUNCTION(BlueprintPure, Category = "QuartzUI|Project Endpoint")
	UScriptStruct* GetExpectedResultType() const { return ExpectedResultType; }

	/** Completes once with the exact result USTRUCT declared by the app contract. */
	UFUNCTION(BlueprintCallable, Category = "QuartzUI|Project Endpoint")
	bool CompleteSuccess(const FInstancedStruct& Result);

	/** Convenience available only when the declared result is QuartzUIEmpty. */
	UFUNCTION(BlueprintCallable, Category = "QuartzUI|Project Endpoint")
	bool CompleteEmptySuccess();

	/** Rejects once with a project-owned lowercase dotted code and bounded message. */
	UFUNCTION(BlueprintCallable, Category = "QuartzUI|Project Endpoint")
	bool CompleteFailure(FName ErrorCode, const FText& ErrorMessage);

private:
	void Initialize(
		class UQuartzUITypedEndpoint* InEndpoint,
		UQuartzUIEndpointRequest* InRawRequest,
		FName InEndpointName,
		UScriptStruct* InExpectedResultType);
	void Finish();

	UPROPERTY(Transient)
	TWeakObjectPtr<class UQuartzUITypedEndpoint> Endpoint;

	UPROPERTY(Transient)
	TObjectPtr<UQuartzUIEndpointRequest> RawRequest;

	UPROPERTY(Transient)
	FName EndpointName;

	UPROPERTY(Transient)
	TObjectPtr<UScriptStruct> ExpectedResultType;

	friend class UQuartzUITypedEndpoint;
};

/**
 * Blueprintable, explicitly constructed endpoint bound to one logical player view.
 * The class default names one declaration; no arbitrary UObject members are scanned.
 */
UCLASS(Abstract, BlueprintType, Blueprintable, EditInlineNew)
class QUARTZUIRUNTIME_API UQuartzUITypedEndpoint : public UObject
{
	GENERATED_BODY()

public:
	static constexpr float DefaultRequestTimeoutSeconds = 5.0f;

	UFUNCTION(BlueprintPure, Category = "QuartzUI|Project Endpoint")
	FName GetEndpointName() const { return EndpointName; }

	UFUNCTION(BlueprintPure, Category = "QuartzUI|Project Endpoint")
	EQuartzUIContractMessageKind GetEndpointKind() const { return EndpointKind; }

	UFUNCTION(BlueprintPure, Category = "QuartzUI|Project Endpoint")
	UScriptStruct* GetPayloadType() const { return PayloadType; }

	UFUNCTION(BlueprintPure, Category = "QuartzUI|Project Endpoint")
	UScriptStruct* GetResultType() const { return ResultType; }

	UFUNCTION(BlueprintPure, Category = "QuartzUI|Project Endpoint")
	UQuartzUIView* GetBoundView() const { return BoundView.Get(); }

	/** Called for a declared one-way action after strict payload decoding. */
	UFUNCTION(BlueprintNativeEvent, Category = "QuartzUI|Project Endpoint")
	void HandleAction(const FInstancedStruct& Payload);
	virtual void HandleAction_Implementation(const FInstancedStruct& Payload);

	/** Called for a declared request; complete Request exactly once, now or later. */
	UFUNCTION(BlueprintNativeEvent, Category = "QuartzUI|Project Endpoint")
	void HandleRequest(const FInstancedStruct& Payload, UQuartzUITypedEndpointRequest* Request);
	virtual void HandleRequest_Implementation(
		const FInstancedStruct& Payload,
		UQuartzUITypedEndpointRequest* Request);

	/** Exact declaration is initialized before this explicit attach callback. */
	UFUNCTION(BlueprintNativeEvent, Category = "QuartzUI|Project Endpoint")
	void EndpointBound(UQuartzUIView* View);
	virtual void EndpointBound_Implementation(UQuartzUIView* View);

	/** Finalize project subscriptions here; pending completions are already cancelled. */
	UFUNCTION(BlueprintNativeEvent, Category = "QuartzUI|Project Endpoint")
	void EndpointUnbound();
	virtual void EndpointUnbound_Implementation();

protected:
	/** Must match one Action or Request declaration on the owning app asset. */
	UPROPERTY(EditDefaultsOnly, BlueprintReadOnly, Category = "QuartzUI|Project Endpoint")
	FName EndpointName;

	/** Uses the bridge's existing bounded asynchronous request timer. */
	UPROPERTY(EditDefaultsOnly, BlueprintReadOnly, Category = "QuartzUI|Project Endpoint",
		meta = (ClampMin = "0.05", ClampMax = "30.0"))
	float RequestTimeoutSeconds = DefaultRequestTimeoutSeconds;

private:
	bool BindToView(
		UQuartzUIView* View,
		const FQuartzUIContractMessageDeclaration& Declaration,
		bool bAllowReservedCoreName);
	void UnbindFromView(UQuartzUIView* View);
	bool RegisterWithBridge(UQuartzUIBridge* Bridge);
	void UnregisterFromBridge(UQuartzUIBridge* Bridge);
	FQuartzUIEndpointResult DispatchAction(const FString& PayloadJson);
	void DispatchRequest(const FString& PayloadJson, UQuartzUIEndpointRequest* Request);
	void NotifyCompletion(UQuartzUITypedEndpointRequest* Request);
	void PruneCompletedRequests();

	UPROPERTY(Transient)
	TWeakObjectPtr<UQuartzUIView> BoundView;

	UPROPERTY(Transient)
	EQuartzUIContractMessageKind EndpointKind = EQuartzUIContractMessageKind::Action;

	UPROPERTY(Transient)
	TObjectPtr<UScriptStruct> PayloadType;

	UPROPERTY(Transient)
	TObjectPtr<UScriptStruct> ResultType;

	UPROPERTY(Transient)
	bool bUsesReservedCoreRegistration = false;

	UPROPERTY(Transient)
	TArray<TObjectPtr<UQuartzUITypedEndpointRequest>> PendingRequests;

	friend class UQuartzUIView;
	friend class UQuartzUITypedEndpointRequest;
	friend class FQuartzUITypedEndpointTestAccess;
};