Table of Contents

Class FirestoreStalePositionReasonCodes

Namespace
Excalibur.Cdc.Firestore
Assembly
Excalibur.Cdc.Firestore.dll

Provides standardized reason codes for Firestore CDC stale position scenarios.

public static class FirestoreStalePositionReasonCodes
Inheritance
FirestoreStalePositionReasonCodes
Inherited Members

Remarks

These codes categorize why a Firestore CDC position became invalid. Firestore uses gRPC status codes for error reporting. Common stale position scenarios include:

  • Listener stream timeout (gRPC DEADLINE_EXCEEDED)
  • Collection or document not found (gRPC NOT_FOUND)
  • Permission denied (gRPC PERMISSION_DENIED)
  • Database deleted or unavailable (gRPC UNAVAILABLE)

These codes are used in CdcPositionResetEventArgs.ReasonCode to enable consistent logging, alerting, and handling across different stale position scenarios.

Fields

Aborted

The request was aborted.

public const string Aborted = "FIRESTORE_ABORTED"

Field Value

string

Remarks

This occurs when a request is aborted, typically due to a conflict. gRPC status code: ABORTED (10).

Common causes:

  • Conflict with another operation
  • Transaction aborted
  • Optimistic locking failure

Cancelled

The request was cancelled.

public const string Cancelled = "FIRESTORE_CANCELLED"

Field Value

string

Remarks

This occurs when the listener request is cancelled by the client or server. gRPC status code: CANCELLED (1).

Common causes:

  • Client initiated cancellation
  • Server-side cancellation
  • Resource cleanup during shutdown

DeadlineExceeded

The listener stream timed out due to deadline exceeded.

public const string DeadlineExceeded = "FIRESTORE_DEADLINE_EXCEEDED"

Field Value

string

Remarks

Firestore listener connections have timeout limits. If a listener is idle too long or the server takes too long to respond, the stream may time out. gRPC status code: DEADLINE_EXCEEDED (4).

Common causes:

  • Network latency or congestion
  • Server overload
  • Long-running queries timing out

Internal

Internal server error occurred.

public const string Internal = "FIRESTORE_INTERNAL"

Field Value

string

Remarks

This indicates an internal Firestore error. gRPC status code: INTERNAL (13).

NotFound

The collection or document was not found.

public const string NotFound = "FIRESTORE_NOT_FOUND"

Field Value

string

Remarks

This occurs when the watched collection or document no longer exists. gRPC status code: NOT_FOUND (5).

Common causes:

  • Collection deleted
  • Document deleted
  • Invalid collection path

PermissionDenied

Permission was denied to access the collection or document.

public const string PermissionDenied = "FIRESTORE_PERMISSION_DENIED"

Field Value

string

Remarks

This occurs when security rules prevent access to the watched collection. gRPC status code: PERMISSION_DENIED (7).

Common causes:

  • Security rules changed
  • Service account permissions revoked
  • Token expired or invalidated

ResourceExhausted

Resource was exhausted (quota exceeded).

public const string ResourceExhausted = "FIRESTORE_RESOURCE_EXHAUSTED"

Field Value

string

Remarks

This occurs when Firestore quota limits are exceeded. gRPC status code: RESOURCE_EXHAUSTED (8).

Common causes:

  • Too many concurrent listeners
  • Rate limit exceeded
  • Project quota exhausted

Unavailable

The service was unavailable.

public const string Unavailable = "FIRESTORE_UNAVAILABLE"

Field Value

string

Remarks

This occurs when the Firestore service is temporarily unavailable. gRPC status code: UNAVAILABLE (14).

Common causes:

  • Firestore service outage
  • Network connectivity issues
  • Regional availability issues

Unknown

The reason for the stale position could not be determined.

public const string Unknown = "FIRESTORE_UNKNOWN"

Field Value

string

Remarks

This is used when the specific cause cannot be identified from the Firestore error or when an unexpected error occurs during position validation.

Methods

FromErrorMessage(string?)

Determines the reason code from a Firestore error message pattern.

public static string FromErrorMessage(string? errorMessage)

Parameters

errorMessage string

The Firestore error message.

Returns

string

The corresponding reason code.

Remarks

This method provides fallback detection when gRPC status codes are not available by analyzing common error message patterns.

FromGrpcStatusCode(int)

Determines the reason code from a gRPC status code.

public static string FromGrpcStatusCode(int statusCode)

Parameters

statusCode int

The gRPC status code.

Returns

string

The corresponding reason code.

Remarks

gRPC status codes relevant to stale positions:

  • 1 - CANCELLED
  • 4 - DEADLINE_EXCEEDED
  • 5 - NOT_FOUND
  • 7 - PERMISSION_DENIED
  • 8 - RESOURCE_EXHAUSTED
  • 10 - ABORTED
  • 13 - INTERNAL
  • 14 - UNAVAILABLE