Error Handling

// Most SDK calls report failure as data rather than throwing, by returning a
// `Result<T>` that is either a `Success` or a `Failure`.
final result = await feed.getOrCreate();

switch (result) {
  case Success(data: final feedData):
    print('Loaded ${feedData.fid}');
  case Failure(error: final StreamFeedsException error):
    print('Could not load the feed: ${error.message}');
  case Failure(error: final error):
    print('Could not load the feed: $error');
}

final result = await feed.getOrCreate();

// Throws the failure's exception
final feedData = result.getOrThrow();

// Or returns null instead
final maybeFeedData = result.getOrNull();

// And the booleans, when all you need is whether it worked
if (result.isFailure) return;

// `StreamFeedsException` aliases the base type, so one `on` clause catches
// all four subclasses.
try {
  final feedData = (await feed.getOrCreate()).getOrThrow();
} on StreamFeedsException catch (e) {
  print('${e.runtimeType}: ${e.message}');
}

final result = await feed.getOrCreate();
if (result case Failure(error: final error)) {
  switch (error) {
    case StreamApiException(:final statusCode, :final code):
      // The server refused the request. `statusCode` and `code` say why.
      print('API error $statusCode ($code)');
    case StreamNetworkException(isCancelled: true):
      // Usually the app navigating away, something to ignore rather than surface.
      break;
    case StreamNetworkException(isTimeout: final timedOut):
      print(timedOut ? 'Timed out' : 'The request did not reach the server');
    case StreamAuthenticationException():
      // The token was rejected. Sign the user out, or issue a fresh token.
      print('Authentication failed: ${error.message}');
    case StreamClientException():
      // A failure inside the SDK. Worth reporting to a crash tracker rather
      // than showing in UI.
      print('Client error: ${error.message}');
  }
}

final result = await feed.getOrCreate();

// What the SDK itself treats as worth retrying: a network failure the caller
// did not cancel, and a server error. A rate limit is not retried here,
// because a fixed wait is not the wait a rate limit asks for.
return switch (result) {
  Success() => false,
  Failure(:final error) => switch (error) {
    StreamNetworkException(isCancelled: true) => false,
    StreamNetworkException() => true,
    StreamApiException(:final statusCode) => statusCode < 100 || statusCode >= 500,
    _ => false,
  },
};

// `connect` is one of the calls that throws rather than returning a Result.
// The connection attempt's own failure arrives as a StreamFeedsException,
// with the cause travelling on it.
try {
  await client.connect();
} on StreamFeedsException catch (e) {
  print('Connection failed: ${e.message} (${e.cause})');
}

// Calling connect again while a connection is established or in progress, or
// after `dispose`, is a programming error rather than a runtime failure: it
// throws a StateError. Guard on the connection's state instead of catching it.

// The connection's state, for a banner while it is down. A disconnection
// carries its source, and a server-initiated one carries the failure behind
// it.
client.connectionState.listen((state) {
  switch (state) {
    case Connected():
      print('Connected');
    case Connecting() || Authenticating():
      print('Connecting...');
    case Disconnected(:final source):
      // `closeReason` reads the source in words, `cause` is the failure behind it
      // when there was one.
      print('Disconnected: ${source.closeReason}');
      print('Cause: ${source.cause}');
      print('Will reconnect: ${state.isAutomaticReconnectionEnabled}');
    case Initialized() || Disconnecting():
      break;
  }
});