nexus

type CancelOperationOptions struct {
	// Header contains the request header fields either received by the server or to be sent by the client.
	//
	// Header will always be non empty in server methods and can be optionally set in the client API.
	Header Header
}

type Client struct {
	// contains filtered or unexported fields
}

type ClientOptions struct {
	// Base URL of the service.
	ServiceBaseURL string
	// A function for making HTTP requests.
	// Defaults to [http.DefaultClient.Do].
	HTTPCaller func(*http.Request) (*http.Response, error)
	// A [Serializer] to customize client serialization behavior.
	// By default the client handles, JSONables, byte slices, and nil.
	Serializer Serializer
}

type ClientStartOperationResult[T any] struct {
	// Set when start completes synchronously and successfully.
	//
	// If T is a [LazyValue], ensure that your consume it or read the underlying content in its entirety and close it to
	// free up the underlying connection.
	Successful T
	// Set when the handler indicates that it started an asynchronous operation.
	// The attached handle can be used to perform actions such as cancel the operation or get its result.
	Pending *OperationHandle[T]
}

type CompletionHandler interface {
	CompleteOperation(context.Context, *CompletionRequest) error
}

type CompletionHandlerOptions struct {
	// Handler for completion requests.
	Handler CompletionHandler
	// A stuctured logging handler.
	// Defaults to slog.Default().
	Logger *slog.Logger
	// A [Serializer] to customize handler serialization behavior.
	// By default the handler handles, JSONables, byte slices, and nil.
	Serializer Serializer
}

type CompletionRequest struct {
	// The original HTTP request.
	HTTPRequest *http.Request
	// State of the operation.
	State OperationState
	// Parsed from request and set if State is failed or canceled.
	Failure *Failure
	// Extracted from request and set if State is succeeded.
	Result *LazyValue
}

type Content struct {
	// Header that should include information on how to deserialize this content.
	// Headers constructed by the framework always have lower case keys.
	// User provided keys are considered case-insensitive by the framework.
	Header Header
	// Data contains request or response data. May be nil for empty data.
	Data []byte
}

type ExecuteOperationOptions struct {
	// Callback URL to provide to the handle for receiving async operation completions. Optional.
	// Even though Client.ExecuteOperation waits for operation completion, some applications may want to set this
	// callback as a fallback mechanism.
	CallbackURL string
	// Optional header fields set by a client that are required to be attached to the callback request when an
	// asynchronous operation completes.
	CallbackHeader Header
	// Request ID that may be used by the server handler to dedupe this start request.
	// By default a v4 UUID will be generated by the client.
	RequestID string
	// Header to attach to start and get-result requests. Optional.
	//
	// Header keys with the "content-" prefix are reserved for [Serializer] headers and should not be set in the
	// client API; they are not be avaliable to server [Handler] and [Operation] implementations.
	Header Header
	// Duration to wait for operation completion.
	//
	// ⚠ NOTE: unlike GetOperationResultOptions.Wait, zero and negative values are considered effectively infinite.
	Wait time.Duration
}

type Failure struct {
	// A simple text message.
	Message string `json:"message"`
	// A key-value mapping for additional context. Useful for decoding the 'details' field, if needed.
	Metadata map[string]string `json:"metadata,omitempty"`
	// Additional JSON serializable structured data.
	Details json.RawMessage `json:"details,omitempty"`
}

type GetOperationInfoOptions struct {
	// Header contains the request header fields either received by the server or to be sent by the client.
	//
	// Header will always be non empty in server methods and can be optionally set in the client API.
	Header Header
}

type GetOperationResultOptions struct {
	// Header contains the request header fields either received by the server or to be sent by the client.
	//
	// Header will always be non empty in server methods and can be optionally set in the client API.
	Header Header
	// If non-zero, reflects the duration the caller has indicated that it wants to wait for operation completion,
	// turning the request into a long poll.
	Wait time.Duration
}

type Handler interface {
	// StartOperation handles requests for starting an operation. Return [HandlerStartOperationResultSync] to
	// respond successfully - inline, or [HandlerStartOperationResultAsync] to indicate that an asynchronous
	// operation was started. Return an [UnsuccessfulOperationError] to indicate that an operation completed as
	// failed or canceled.
	StartOperation(ctx context.Context, operation string, input *LazyValue, options StartOperationOptions) (HandlerStartOperationResult[any], error)
	// GetOperationResult handles requests to get the result of an asynchronous operation. Return non error result
	// to respond successfully - inline, or error with [ErrOperationStillRunning] to indicate that an asynchronous
	// operation is still running. Return an [UnsuccessfulOperationError] to indicate that an operation completed as
	// failed or canceled.
	//
	// When [GetOperationResultOptions.Wait] is greater than zero, this request should be treated as a long poll.
	// Long poll requests have a server side timeout, configurable via [HandlerOptions.GetResultTimeout], and exposed
	// via context deadline. The context deadline is decoupled from the application level Wait duration.
	//
	// It is the implementor's responsiblity to respect the client's wait duration and return in a timely fashion.
	// Consider using a derived context that enforces the wait timeout when implementing this method and return
	// [ErrOperationStillRunning] when that context expires as shown in the example.
	GetOperationResult(ctx context.Context, operation, operationID string, options GetOperationResultOptions) (any, error)
	// GetOperationInfo handles requests to get information about an asynchronous operation.
	GetOperationInfo(ctx context.Context, operation, operationID string, options GetOperationInfoOptions) (*OperationInfo, error)
	// CancelOperation handles requests to cancel an asynchronous operation.
	// Cancelation in Nexus is:
	//  1. asynchronous - returning from this method only ensures that cancelation is delivered, it may later be
	//  ignored by the underlying operation implemention.
	//  2. idempotent - implementors should ignore duplicate cancelations for the same operation.
	CancelOperation(ctx context.Context, operation, operationID string, options CancelOperationOptions) error
	// contains filtered or unexported methods
}

type HandlerError struct {
	// Defaults to HandlerErrorTypeInternal
	Type HandlerErrorType
	// Failure to report back in the response. Optional.
	Failure *Failure
}

type HandlerErrorType string

type HandlerOptions struct {
	// Handler for handling service requests.
	Handler Handler
	// A stuctured logger.
	// Defaults to slog.Default().
	Logger *slog.Logger
	// Max duration to allow waiting for a single get result request.
	// Enforced if provided for requests with the wait query parameter set.
	//
	// Defaults to one minute.
	GetResultTimeout time.Duration
	// A [Serializer] to customize handler serialization behavior.
	// By default the handler handles, JSONables, byte slices, and nil.
	Serializer Serializer
}

type HandlerStartOperationResult[T any] interface {
	// contains filtered or unexported methods
}

type HandlerStartOperationResultAsync struct {
	OperationID string
}

type HandlerStartOperationResultSync[T any] struct {
	Value T
}

type Header map[string]string

type LazyValue struct {
	Reader *Reader
	// contains filtered or unexported fields
}

type NoValue *struct{}

type Operation[I, O any] interface {
	RegisterableOperation
	OperationReference[I, O]

	// Start handles requests for starting an operation. Return [HandlerStartOperationResultSync] to respond
	// successfully - inline, or [HandlerStartOperationResultAsync] to indicate that an asynchronous operation was
	// started. Return an [UnsuccessfulOperationError] to indicate that an operation completed as failed or
	// canceled.
	Start(context.Context, I, StartOperationOptions) (HandlerStartOperationResult[O], error)
	// GetResult handles requests to get the result of an asynchronous operation. Return non error result to respond
	// successfully - inline, or error with [ErrOperationStillRunning] to indicate that an asynchronous operation is
	// still running. Return an [UnsuccessfulOperationError] to indicate that an operation completed as failed or
	// canceled.
	//
	// When [GetOperationResultOptions.Wait] is greater than zero, this request should be treated as a long poll.
	// Long poll requests have a server side timeout, configurable via [HandlerOptions.GetResultTimeout], and exposed
	// via context deadline. The context deadline is decoupled from the application level Wait duration.
	//
	// It is the implementor's responsiblity to respect the client's wait duration and return in a timely fashion.
	// Consider using a derived context that enforces the wait timeout when implementing this method and return
	// [ErrOperationStillRunning] when that context expires as shown in the [Handler] example.
	GetResult(context.Context, string, GetOperationResultOptions) (O, error)
	// GetInfo handles requests to get information about an asynchronous operation.
	GetInfo(context.Context, string, GetOperationInfoOptions) (*OperationInfo, error)
	// Cancel handles requests to cancel an asynchronous operation.
	// Cancelation in Nexus is:
	//  1. asynchronous - returning from this method only ensures that cancelation is delivered, it may later be
	//  ignored by the underlying operation implemention.
	//  2. idempotent - implementors should ignore duplicate cancelations for the same operation.
	Cancel(context.Context, string, CancelOperationOptions) error
}

type OperationCompletion interface {
	// contains filtered or unexported methods
}

type OperationCompletionSuccesfulOptions struct {
	// Optional serializer for the result. Defaults to the SDK's default Serializer, which handles JSONables, byte
	// slices and nils.
	Serializer Serializer
}

type OperationCompletionSuccessful struct {
	// Header to send in the completion request.
	Header http.Header
	// Body to send in the completion HTTP request.
	// If it implements `io.Closer` it will automatically be closed by the client.
	Body io.Reader
}

type OperationCompletionUnsuccessful struct {
	// Header to send in the completion request.
	Header http.Header
	// State of the operation, should be failed or canceled.
	State OperationState
	// Failure object to send with the completion.
	Failure *Failure
}

type OperationHandle[T any] struct {
	// Name of the Operation this handle represents.
	Operation string
	// Handler generated ID for this handle's operation.
	ID string
	// contains filtered or unexported fields
}

type OperationInfo struct {
	// ID of the operation.
	ID string `json:"id"`
	// State of the operation.
	State OperationState `json:"state"`
}

type OperationReference[I, O any] interface {
	Name() string
	// contains filtered or unexported methods
}

type OperationRegistry struct {
	// contains filtered or unexported fields
}

type OperationState string

type Reader struct {
	// ReaderCloser contains request or response data. May be nil for empty data.
	io.ReadCloser
	// Header that should include information on how to deserialize this content.
	// Headers constructed by the framework always have lower case keys.
	// User provided keys are considered case-insensitive by the framework.
	Header Header
}

type RegisterableOperation interface {
	// Name of the operation. Used for invocation and registration.
	Name() string
	// contains filtered or unexported methods
}

type Serializer interface {
	// Serialize encodes a value into a [Content].
	Serialize(any) (*Content, error)
	// Deserialize decodes a [Content] into a given reference.
	Deserialize(*Content, any) error
}

type StartOperationOptions struct {
	// Header contains the request header fields either received by the server or to be sent by the client.
	//
	// Header will always be non empty in server methods and can be optionally set in the client API.
	//
	// Header keys with the "content-" prefix are reserved for [Serializer] headers and should not be set in the
	// client API; they are not be avaliable to server [Handler] and [Operation] implementations.
	Header Header
	// Callbacks are used to deliver completion of async operations.
	// This value may optionally be set by the client and should be called by a handler upon completion if the started operation is async.
	//
	// Implement a [CompletionHandler] and expose it as an HTTP handler to handle async completions.
	CallbackURL string
	// Optional header fields set by a client that are required to be attached to the callback request when an
	// asynchronous operation completes.
	CallbackHeader Header
	// Request ID that may be used by the server handler to dedupe a start request.
	// By default a v4 UUID will be generated by the client.
	RequestID string
}

type UnexpectedResponseError struct {
	// Error message.
	Message string
	// The HTTP response. The response body will have already been read into memory and does not need to be closed.
	Response *http.Response
	// Optional failure that may have been emedded in the HTTP response body.
	Failure *Failure
}

type UnimplementedHandler struct{}

type UnimplementedOperation[I, O any] struct{}

type UnsuccessfulOperationError struct {
	State   OperationState
	Failure Failure
}