001/*
002 * Copyright 2022-2026 Revetware LLC.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package com.soklet;
018
019import org.jspecify.annotations.NonNull;
020
021import java.time.Instant;
022import java.util.Optional;
023
024/**
025 * Represents characteristics of a long-running connection that has been established with a {@link ServerSentEventServer}.
026 * <p>
027 * Instances are exposed via {@link LifecycleObserver}, which enables you to monitor events that occur on the connection over time (established, SSE payload written, terminated, etc.)
028 * <p>
029 * See <a href="https://www.soklet.com/docs/server-sent-events">https://www.soklet.com/docs/server-sent-events</a> for general Server-Sent Event documentation and <a href="https://www.soklet.com/docs/request-lifecycle#server-sent-events">https://www.soklet.com/docs/request-lifecycle#server-sent-events</a> for lifecycle-specific documentation.
030 *
031 * @author <a href="https://www.revetkn.com">Mark Allen</a>
032 */
033public interface ServerSentEventConnection {
034        /**
035         * The request made by the client to the <em>Event Source Method</em> which accepted the SSE handshake and established the connection.
036         *
037         * @return the request made by the client to the <em>Event Source Method</em>
038         */
039        @NonNull
040        Request getRequest();
041
042        /**
043         * Returns the <em>Event Source Method</em> that provided the accepted handshake for this connection.
044         *
045         * @return the <em>Event Source Method</em> that provided the accepted handshake for this connection
046         */
047        @NonNull
048        ResourceMethod getResourceMethod();
049
050        /**
051         * Returns the moment at which this connection was established.
052         *
053         * @return the moment at which this connection was established.
054         */
055        @NonNull
056        Instant getEstablishedAt();
057
058        /**
059         * Returns the connection-specific context as provided by an accepted handshake.
060         * <p>
061         * This will always be the value returned by {@link HandshakeResult.Accepted#getClientContext()}.
062         *
063         * @return the connection-specific context, or {@link Optional#empty()} if none was specified
064         */
065        @NonNull
066        Optional<Object> getClientContext();
067
068        /**
069         * Categorizes why a Server-Sent Event handshake failed.
070         */
071        enum HandshakeFailureReason {
072                /**
073                 * The SSE handshake did not complete in time.
074                 */
075                HANDSHAKE_TIMEOUT,
076                /**
077                 * The SSE handshake completed with a non-accepted result.
078                 */
079                HANDSHAKE_REJECTED,
080                /**
081                 * An unexpected internal error occurred while establishing the SSE connection.
082                 */
083                INTERNAL_ERROR
084        }
085
086        /**
087         * Categorizes why a Server-Sent Event connection terminated.
088         */
089        enum TerminationReason {
090                /**
091                 * Connection was closed due to backpressure (write queue at capacity).
092                 */
093                BACKPRESSURE,
094                /**
095                 * Connection was closed during server shutdown.
096                 */
097                SERVER_STOP,
098                /**
099                 * Connection ended due to an error while processing or writing.
100                 */
101                ERROR,
102                /**
103                 * Connection ended because the remote peer closed the socket.
104                 */
105                REMOTE_CLOSE,
106                /**
107                 * Connection ended for an unspecified reason.
108                 */
109                UNKNOWN
110        }
111}