Class SessionEventArgs

Holds info related to a single proxy session (single request/response exchange). Under HTTP/2 and HTTP/3, many sessions share one client connection (one stream each); ending a session ends that request/response exchange, not necessarily the connection.

Inheritance

object

EventArgs

ProxyEventArgsBase

SessionEventArgsBase

SessionEventArgs

Implements

IDisposable

Inherited Members

SessionEventArgsBase.BufferPool

SessionEventArgsBase.ClientConnectionId

SessionEventArgsBase.ServerConnectionId

SessionEventArgsBase.Timing

SessionEventArgsBase.UpstreamConnectionTiming

SessionEventArgsBase.UserData

SessionEventArgsBase.ConnectTimeout

SessionEventArgsBase.EnableWinAuth

SessionEventArgsBase.IsHttps

SessionEventArgsBase.ClientLocalEndPoint

SessionEventArgsBase.ClientRemoteEndPoint

SessionEventArgsBase.ClientEndPoint

SessionEventArgsBase.ServerRemoteEndPoint

SessionEventArgsBase.ServerIpAddress

SessionEventArgsBase.HttpClient

SessionEventArgsBase.WebSession

SessionEventArgsBase.CustomUpStreamProxy

SessionEventArgsBase.CustomUpStreamProxyUsed

SessionEventArgsBase.ProxyEndPoint

SessionEventArgsBase.LocalEndPoint

SessionEventArgsBase.IsTransparent

SessionEventArgsBase.IsSocks

SessionEventArgsBase.Exception

SessionEventArgsBase.Logger

SessionEventArgsBase.Dispose()

SessionEventArgsBase.OnException(Exception)

SessionEventArgsBase.DataSent

SessionEventArgsBase.DataReceived

SessionEventArgsBase.TerminateSession()

ProxyEventArgsBase.ClientUserData

EventArgs.Empty

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Titanium.Web.Proxy.EventArguments

Assembly: Titanium.Web.Proxy.dll

Syntax

public class SessionEventArgs : SessionEventArgsBase, IDisposable

Properties

IdleReadTimeout

Per-session override for IdleReadTimeoutSeconds. null uses the server default; Zero or negative disables.

Declaration

public TimeSpan? IdleReadTimeout { get; set; }

Property Value

Type	Description
TimeSpan?

IdleWriteTimeout

Per-session override for IdleWriteTimeoutSeconds. null uses the server default; Zero or negative disables.

Declaration

public TimeSpan? IdleWriteTimeout { get; set; }

Property Value

Type	Description
TimeSpan?

IsPromise

Is this session a HTTP/2 promise?

Declaration

public bool IsPromise { get; }

Property Value

Type	Description
bool

MaxBufferedBodyBytes

Per-session override for MaxBufferedBodyBytes. null uses the server default. Set in BeforeRequest to increase the limit for large uploads/downloads without relaxing the global limit for all requests.

Declaration

public int? MaxBufferedBodyBytes { get; set; }

Property Value

Type	Description
int?

MaxWebSocketFramePayloadBytes

Per-session override for MaxWebSocketFramePayloadBytes. null uses the server default. Set in BeforeRequest before the WebSocket upgrade completes.

Declaration

public int? MaxWebSocketFramePayloadBytes { get; set; }

Property Value

Type	Description
int?

NetworkFailureRetryAttempts

Per-session override for NetworkFailureRetryAttempts. null uses the server default. Set to 0 in BeforeRequest for non-idempotent methods (POST, PATCH) to prevent unsafe retries.

Declaration

public int? NetworkFailureRetryAttempts { get; set; }

Property Value

Type	Description
int?

OriginHttpVersionPolicy

Per-session override for OriginHttpVersionPolicy. null uses the server default (PreserveClientVersion unless the server property was changed). Set in BeforeRequest.

Declaration

public OriginHttpVersionPolicy? OriginHttpVersionPolicy { get; set; }

Property Value

Type	Description
OriginHttpVersionPolicy?

ReRequest

Should we send the request again ?

Declaration

public bool ReRequest { get; set; }

Property Value

Type	Description
bool

RequestTimeout

Per-session override for RequestTimeoutSeconds. null uses the server default; Zero or negative disables.

Declaration

public TimeSpan? RequestTimeout { get; set; }

Property Value

Type	Description
TimeSpan?

ResponseHeaderTimeout

Per-session override for ResponseHeaderTimeoutSeconds. null uses the server default; Zero or negative disables.

Declaration

public TimeSpan? ResponseHeaderTimeout { get; set; }

Property Value

Type	Description
TimeSpan?

UpstreamHttpProtocol

Per-request outbound protocol version policy. Overrides the connection-level UpstreamHttpProtocol value set during BeforeSslAuthenticate / BeforeQuicAuthenticate for this single request stream only. null uses the connection-level policy (or Auto if none was set). Evaluated in BeforeRequest; changes after that have no effect.

On an H3 inbound connection (one client QUIC connection serving many concurrent streams), each stream resolves its outbound protocol independently after BeforeRequest fires, making per-stream protocol overrides possible even though the inbound leg is already QUIC.

Declaration

public UpstreamHttpProtocol? UpstreamHttpProtocol { get; set; }

Property Value

Type	Description
UpstreamHttpProtocol?

WebSocketClientWriter

Inject frames toward the local client (server→client direction, unmasked). Available only while an intercepted WebSocket relay is active.

Declaration

public WebSocketFrameWriter? WebSocketClientWriter { get; }

Property Value

Type	Description
WebSocketFrameWriter

WebSocketDecoder

Declaration

[Obsolete("Use [WebSocketDecoderReceive] instead")]
public WebSocketDecoder WebSocketDecoder { get; }

Property Value

Type	Description
WebSocketDecoder

WebSocketDecoderReceive

Declaration

public WebSocketDecoder WebSocketDecoderReceive { get; }

Property Value

Type	Description
WebSocketDecoder

WebSocketDecoderSend

Declaration

public WebSocketDecoder WebSocketDecoderSend { get; }

Property Value

Type	Description
WebSocketDecoder

WebSocketServerWriter

Inject frames toward the remote server (client→server direction, masked). Available only while an intercepted WebSocket relay is active.

Declaration

public WebSocketFrameWriter? WebSocketServerWriter { get; }

Property Value

Type	Description
WebSocketFrameWriter

Methods

Dispose(bool)

Declaration

protected override void Dispose(bool disposing)

Parameters

Type	Name	Description
bool	disposing

Overrides

SessionEventArgsBase.Dispose(bool)

DrainClientBodyAsync(CancellationToken)

Drains (reads and discards) any unread client request body from the underlying stream or connection so the client's keep-alive / multiplexed connection can be reused. This reads the bytes off the wire without buffering them in memory. It is a no-op if the body was already received or the request has no body.

Declaration

public Task DrainClientBodyAsync(CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
CancellationToken	cancellationToken

Returns

Type	Description
Task

Remarks

Useful when short-circuiting a request (e.g. Respond(Response, bool), RespondStreaming(Response, Func<Stream, CancellationToken, Task>, bool), or blocking) while the client is uploading a body: draining leaves the client connection in a reusable state. Note the proxy already drains the client body automatically on the normal synthetic-response path, so this is only needed for advanced/manual control. Warning: for an endless chunked request (one that never sends its terminating zero chunk) this will block until the passed cancellationToken is cancelled or the connection closes.

DrainServerBodyAsync(CancellationToken)

Drains (reads and discards) any unread server response body from the underlying client/server stream or connection so it can be reused. This reads the bytes off the wire without buffering them in memory. It is a no-op if the body was already received or the response has no body.

Declaration

public Task DrainServerBodyAsync(CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
CancellationToken	cancellationToken

Returns

Type	Description
Task

Remarks

Warning: for an endless chunked response (one that never sends its terminating zero chunk) this will block until the passed cancellationToken is cancelled or the connection closes. In that case prefer closing the connection (e.g. TerminateServerConnection()) instead.

GenericResponse(byte[], HttpStatusCode, IDictionary<string, HttpHeader>, bool)

Before request is made to server respond with the specified byte[], the specified status to client. And then ignore the request.

Declaration

public void GenericResponse(byte[] result, HttpStatusCode status, IDictionary<string, HttpHeader> headers, bool closeServerConnection = false)

Parameters

Type	Name	Description
byte[]	result	The bytes to sent.
HttpStatusCode	status	The HTTP status code.
IDictionary<string, HttpHeader>	headers	The HTTP headers.
bool	closeServerConnection	Close the server connection used by request if any?

GenericResponse(byte[], HttpStatusCode, IEnumerable<HttpHeader>?, bool)

Before request is made to server respond with the specified byte[], the specified status to client. And then ignore the request.

Declaration

public void GenericResponse(byte[] result, HttpStatusCode status, IEnumerable<HttpHeader>? headers, bool closeServerConnection = false)

Parameters

Type	Name	Description
byte[]	result	The bytes to sent.
HttpStatusCode	status	The HTTP status code.
IEnumerable<HttpHeader>	headers	The HTTP headers.
bool	closeServerConnection	Close the server connection used by request if any?

GenericResponse(string, HttpStatusCode, IDictionary<string, HttpHeader>?, bool)

Before request is made to server  respond with the specified HTML string and the specified status to client. And then ignore the request.

Declaration

public void GenericResponse(string html, HttpStatusCode status, IDictionary<string, HttpHeader>? headers, bool closeServerConnection = false)

Parameters

Type	Name	Description
string	html	The html content.
HttpStatusCode	status	The HTTP status code.
IDictionary<string, HttpHeader>	headers	The HTTP headers.
bool	closeServerConnection	Close the server connection used by request if any?

GenericResponse(string, HttpStatusCode, IEnumerable<HttpHeader>?, bool)

Before request is made to server  respond with the specified HTML string and the specified status to client. And then ignore the request.

Declaration

public void GenericResponse(string html, HttpStatusCode status, IEnumerable<HttpHeader>? headers = null, bool closeServerConnection = false)

Parameters

Type	Name	Description
string	html	The html content.
HttpStatusCode	status	The HTTP status code.
IEnumerable<HttpHeader>	headers	The HTTP headers.
bool	closeServerConnection	Close the server connection used by request if any?

GetRequestBody(CancellationToken)

Gets the request body as bytes.

Declaration

public Task<byte[]> GetRequestBody(CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
CancellationToken	cancellationToken	Optional cancellation token for this async task.

Returns

Type	Description
Task<byte[]>	The body as bytes.

GetRequestBodyAsString(CancellationToken)

Gets the request body as string.

Declaration

public Task<string> GetRequestBodyAsString(CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
CancellationToken	cancellationToken	Optional cancellation token for this async task.

Returns

Type	Description
Task<string>	The body as string.

GetResponseBody(CancellationToken)

Gets the response body as bytes.

Declaration

public Task<byte[]> GetResponseBody(CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
CancellationToken	cancellationToken	Optional cancellation token for this async task.

Returns

Type	Description
Task<byte[]>	The resulting bytes.

GetResponseBodyAsString(CancellationToken)

Gets the response body as string.

Declaration

public Task<string> GetResponseBodyAsString(CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
CancellationToken	cancellationToken	Optional cancellation token for this async task.

Returns

Type	Description
Task<string>	The string body.

Ok(byte[], IDictionary<string, HttpHeader>?, bool)

Before request is made to server respond with the specified byte[] to client and ignore the request.

Declaration

public void Ok(byte[] result, IDictionary<string, HttpHeader>? headers, bool closeServerConnection = false)

Parameters

Type	Name	Description
byte[]	result	The html content bytes.
IDictionary<string, HttpHeader>	headers	The HTTP headers.
bool	closeServerConnection	Close the server connection used by request if any?

Ok(byte[], IEnumerable<HttpHeader>?, bool)

Before request is made to server respond with the specified byte[] to client and ignore the request.

Declaration

public void Ok(byte[] result, IEnumerable<HttpHeader>? headers = null, bool closeServerConnection = false)

Parameters

Type	Name	Description
byte[]	result	The html content bytes.
IEnumerable<HttpHeader>	headers	The HTTP headers.
bool	closeServerConnection	Close the server connection used by request if any?

Ok(string, IDictionary<string, HttpHeader>?, bool)

Before request is made to server respond with the specified HTML string to client and ignore the request.

Declaration

public void Ok(string html, IDictionary<string, HttpHeader>? headers, bool closeServerConnection = false)

Parameters

Type	Name	Description
string	html	HTML content to sent.
IDictionary<string, HttpHeader>	headers	HTTP response headers.
bool	closeServerConnection	Close the server connection used by request if any?

Ok(string, IEnumerable<HttpHeader>?, bool)

Before request is made to server respond with the specified HTML string to client and ignore the request.

Declaration

public void Ok(string html, IEnumerable<HttpHeader>? headers = null, bool closeServerConnection = false)

Parameters

Type	Name	Description
string	html	HTML content to sent.
IEnumerable<HttpHeader>	headers	HTTP response headers.
bool	closeServerConnection	Close the server connection used by request if any?

Redirect(string, bool)

Redirect to provided URL.

Declaration

public void Redirect(string url, bool closeServerConnection = false)

Parameters

Type	Name	Description
string	url	The URL to redirect.
bool	closeServerConnection	Close the server connection used by request if any?

Respond(Response, bool)

Respond with given response object to client.

Declaration

public void Respond(Response response, bool closeServerConnection = false)

Parameters

Type	Name	Description
Response	response	The response object.
bool	closeServerConnection	Close the server connection used by request if any?

Remarks

If the server response was already received, the original server body (if any) is drained (syphoned) so the server connection stays reusable. To avoid reading a large or endless server body, pass closeServerConnection = true (or call TerminateServerConnection()), which closes the connection instead of draining. Note that an HTTP/1.1 connection cannot be both reused and have its body skipped.

RespondStreaming(Response, Func<Stream, CancellationToken, Task>, bool)

Respond to the client with a streamed body produced on the fly, without buffering the whole body in memory. Use this to serve large or endless bodies (e.g. a multi-gigabyte file or a synthetic server-sent-events stream) from scratch.

Declaration

public void RespondStreaming(Response response, Func<Stream, CancellationToken, Task> writeBody, bool closeServerConnection = false)

Parameters

Type	Name	Description
Response	response	The response object (status and headers).
Func<Stream, CancellationToken, Task>	writeBody	Delegate that writes the body to the provided stream.
bool	closeServerConnection	Close the server connection used by request if any?

Remarks

Framing is chosen from the response headers: if a Content-Length is set on response the body is written raw (the delegate must write exactly that many bytes); otherwise HTTP/1.1 uses chunked transfer-encoding and HTTP/2/HTTP/3 emit DATA / stream frames. The delegate receives a write-only stream; only a single buffer is in flight at a time, so memory stays bounded regardless of the total size. See Respond(Response, bool) for the server body syphon-vs-close trade-off controlled by closeServerConnection.

SetRequestBody(byte[])

Sets the request body.

Declaration

public void SetRequestBody(byte[] body)

Parameters

Type	Name	Description
byte[]	body	The request body bytes.

SetRequestBodyString(string)

Sets the body with the specified string.

Declaration

public void SetRequestBodyString(string body)

Parameters

Type	Name	Description
string	body	The request body string to set.

SetResponseBody(byte[])

Set the response body bytes.

Declaration

public void SetResponseBody(byte[] body)

Parameters

Type	Name	Description
byte[]	body	The body bytes to set.

SetResponseBodyString(string)

Replace the response body with the specified string.

Declaration

public void SetResponseBodyString(string body)

Parameters

Type	Name	Description
string	body	The body string to set.

TerminateServerConnection()

Terminate the connection to server at the end of this HTTP request/response session.

Declaration

public void TerminateServerConnection()

Events

BeforeWebSocketFrame

Fired for each WebSocket frame after upgrade when at least one handler is subscribed. Handlers may Forward, Drop, or Replace the frame, optionally with a Delay. Observational DataSent / DataReceived still fire for bytes actually written to the peer.

Declaration

public event AsyncEventHandler<WebSocketFrameInterceptEventArgs>? BeforeWebSocketFrame

Event Type

Type	Description
AsyncEventHandler<WebSocketFrameInterceptEventArgs>

MultipartRequestPartSent

Occurs when multipart request part sent.

Declaration

public event EventHandler<MultipartRequestPartSentEventArgs>? MultipartRequestPartSent

Event Type

Type	Description
EventHandler<MultipartRequestPartSentEventArgs>

Implements

IDisposable