From c987e8b4887a6c22a5c66695a48d788960083b38 Mon Sep 17 00:00:00 2001 From: Salvatore Giordano Date: Tue, 22 Jun 2021 14:20:43 +0200 Subject: [PATCH] add comments --- .../stream_chat/lib/src/client/client.dart | 26 +++++++++---------- .../lib/src/client/retry_policy.dart | 6 +++++ .../lib/src/core/api/channel_api.dart | 4 +-- .../lib/src/core/api/device_api.dart | 4 +-- .../lib/src/core/api/general_api.dart | 4 +-- .../lib/src/core/api/guest_api.dart | 6 ++--- .../lib/src/core/api/message_api.dart | 4 +-- .../lib/src/core/api/moderation_api.dart | 4 +-- .../lib/src/core/api/responses.dart | 10 +++---- .../lib/src/core/api/stream_chat_api.dart | 24 ++++++++--------- .../lib/src/core/api/user_api.dart | 4 +-- .../src/core/http/connection_id_manager.dart | 12 ++++----- .../http/interceptor/auth_interceptor.dart | 10 +++---- .../connection_id_interceptor.dart | 3 +-- .../http/interceptor/logging_interceptor.dart | 21 +++++---------- .../src/core/http/stream_chat_dio_error.dart | 4 +-- .../stream_chat/lib/src/core/http/token.dart | 19 +++++++------- .../lib/src/core/http/token_manager.dart | 15 ++++++----- 18 files changed, 89 insertions(+), 91 deletions(-) diff --git a/packages/stream_chat/lib/src/client/client.dart b/packages/stream_chat/lib/src/client/client.dart index 3cc3ad0d..b579f030 100644 --- a/packages/stream_chat/lib/src/client/client.dart +++ b/packages/stream_chat/lib/src/client/client.dart @@ -6,33 +6,31 @@ import 'package:dio/dio.dart'; import 'package:logging/logging.dart'; import 'package:rxdart/rxdart.dart'; import 'package:stream_chat/src/client/channel.dart'; -import 'package:stream_chat/src/core/util/utils.dart'; -import 'package:stream_chat/src/core/error/error.dart'; -import 'package:stream_chat/src/location.dart'; -import 'package:stream_chat/src/ws/connection_status.dart'; +import 'package:stream_chat/src/client/retry_policy.dart'; import 'package:stream_chat/src/core/api/attachment_file_uploader.dart'; import 'package:stream_chat/src/core/api/requests.dart'; import 'package:stream_chat/src/core/api/responses.dart'; -import 'package:stream_chat/src/client/retry_policy.dart'; -import 'package:stream_chat/src/ws/websocket.dart'; import 'package:stream_chat/src/core/api/stream_chat_api.dart'; +import 'package:stream_chat/src/core/error/error.dart'; import 'package:stream_chat/src/core/http/connection_id_manager.dart'; import 'package:stream_chat/src/core/http/stream_http_client.dart'; import 'package:stream_chat/src/core/http/token.dart'; import 'package:stream_chat/src/core/http/token_manager.dart'; -import 'package:stream_chat/src/db/chat_persistence_client.dart'; -import 'package:stream_chat/src/event_type.dart'; import 'package:stream_chat/src/core/models/attachment_file.dart'; import 'package:stream_chat/src/core/models/channel_model.dart'; import 'package:stream_chat/src/core/models/channel_state.dart'; import 'package:stream_chat/src/core/models/event.dart'; +import 'package:stream_chat/src/core/models/filter.dart'; +import 'package:stream_chat/src/core/models/member.dart'; import 'package:stream_chat/src/core/models/message.dart'; import 'package:stream_chat/src/core/models/own_user.dart'; import 'package:stream_chat/src/core/models/user.dart'; - -import 'package:stream_chat/src/core/models/filter.dart'; - -import 'package:stream_chat/src/core/models/member.dart'; +import 'package:stream_chat/src/core/util/utils.dart'; +import 'package:stream_chat/src/db/chat_persistence_client.dart'; +import 'package:stream_chat/src/event_type.dart'; +import 'package:stream_chat/src/location.dart'; +import 'package:stream_chat/src/ws/connection_status.dart'; +import 'package:stream_chat/src/ws/websocket.dart'; /// Handler function used for logging records. Function requires a single /// [LogRecord] as the only parameter. @@ -137,10 +135,10 @@ class StreamChatClient { late final RetryPolicy _retryPolicy; - // sync state of the channels present inside state, defaults to false + /// sync state of the channels present inside state, defaults to false bool _synced = false; - // the last dateTime at the which all the channels were synced + /// the last dateTime at the which all the channels were synced DateTime? _lastSyncedAt; /// The retry policy options getter diff --git a/packages/stream_chat/lib/src/client/retry_policy.dart b/packages/stream_chat/lib/src/client/retry_policy.dart index fbebc696..5b7812ab 100644 --- a/packages/stream_chat/lib/src/client/retry_policy.dart +++ b/packages/stream_chat/lib/src/client/retry_policy.dart @@ -2,6 +2,12 @@ import 'package:stream_chat/src/client/client.dart'; import 'package:stream_chat/src/core/error/error.dart'; /// The retry options +/// When sending/updating/deleting a message any temporary error will trigger the retry policy +/// The retry policy exposes 2 methods +/// - shouldRetry: returns a boolean if the request should be retried +/// - retryTimeout: How many milliseconds to wait till the next attempt +/// +/// maxRetryAttempts is a hard limit on maximum retry attempts before giving up class RetryPolicy { /// Instantiate a new RetryPolicy RetryPolicy({ diff --git a/packages/stream_chat/lib/src/core/api/channel_api.dart b/packages/stream_chat/lib/src/core/api/channel_api.dart index 9da05df0..7660c125 100644 --- a/packages/stream_chat/lib/src/core/api/channel_api.dart +++ b/packages/stream_chat/lib/src/core/api/channel_api.dart @@ -9,9 +9,9 @@ import 'package:stream_chat/src/core/models/event.dart'; import 'package:stream_chat/src/core/models/filter.dart'; import 'package:stream_chat/src/core/models/message.dart'; -/// +/// Defines the api dedicated to channel operations class ChannelApi { - /// + /// Initialize a new channel api ChannelApi(this._client); final StreamHttpClient _client; diff --git a/packages/stream_chat/lib/src/core/api/device_api.dart b/packages/stream_chat/lib/src/core/api/device_api.dart index 69f509f8..2d2b9d7b 100644 --- a/packages/stream_chat/lib/src/core/api/device_api.dart +++ b/packages/stream_chat/lib/src/core/api/device_api.dart @@ -19,9 +19,9 @@ extension PushProviderX on PushProvider { }[this]!; } -/// +/// Defines the api dedicated to device operations class DeviceApi { - /// + /// Initialize a new device api DeviceApi(this._client); final StreamHttpClient _client; diff --git a/packages/stream_chat/lib/src/core/api/general_api.dart b/packages/stream_chat/lib/src/core/api/general_api.dart index d26ffc7d..8eeeaa5f 100644 --- a/packages/stream_chat/lib/src/core/api/general_api.dart +++ b/packages/stream_chat/lib/src/core/api/general_api.dart @@ -6,9 +6,9 @@ import 'package:stream_chat/src/core/http/stream_http_client.dart'; import 'package:stream_chat/src/core/models/filter.dart'; import 'package:stream_chat/src/core/models/member.dart'; -/// +/// Defines the api dedicated to general operations class GeneralApi { - /// + /// Initialize a new general api GeneralApi(this._client); final StreamHttpClient _client; diff --git a/packages/stream_chat/lib/src/core/api/guest_api.dart b/packages/stream_chat/lib/src/core/api/guest_api.dart index 438a637f..b6727902 100644 --- a/packages/stream_chat/lib/src/core/api/guest_api.dart +++ b/packages/stream_chat/lib/src/core/api/guest_api.dart @@ -2,14 +2,14 @@ import 'package:stream_chat/src/core/api/responses.dart'; import 'package:stream_chat/src/core/http/stream_http_client.dart'; import 'package:stream_chat/src/core/models/user.dart'; -/// +/// Defines the api dedicated to guest users operations class GuestApi { - /// + /// Initialize a new guest api GuestApi(this._client); final StreamHttpClient _client; - /// + /// Returns the information about guest user Future getGuestUser(User user) async { final response = await _client.post( '/guest', diff --git a/packages/stream_chat/lib/src/core/api/message_api.dart b/packages/stream_chat/lib/src/core/api/message_api.dart index 22f7bfef..f50cb4a1 100644 --- a/packages/stream_chat/lib/src/core/api/message_api.dart +++ b/packages/stream_chat/lib/src/core/api/message_api.dart @@ -3,9 +3,9 @@ import 'package:stream_chat/src/core/api/responses.dart'; import 'package:stream_chat/src/core/http/stream_http_client.dart'; import 'package:stream_chat/src/core/models/message.dart'; -/// +/// Defines the api dedicated to messages operations class MessageApi { - /// + /// Initialize a new message api MessageApi(this._client); final StreamHttpClient _client; diff --git a/packages/stream_chat/lib/src/core/api/moderation_api.dart b/packages/stream_chat/lib/src/core/api/moderation_api.dart index 22c58c35..533fbf63 100644 --- a/packages/stream_chat/lib/src/core/api/moderation_api.dart +++ b/packages/stream_chat/lib/src/core/api/moderation_api.dart @@ -1,9 +1,9 @@ import 'package:stream_chat/src/core/api/responses.dart'; import 'package:stream_chat/src/core/http/stream_http_client.dart'; -/// +/// Defines the api dedicated to moderation operations class ModerationApi { - /// + /// Initialize a new moderation api ModerationApi(this._client); final StreamHttpClient _client; diff --git a/packages/stream_chat/lib/src/core/api/responses.dart b/packages/stream_chat/lib/src/core/api/responses.dart index ccf03822..e06a213a 100644 --- a/packages/stream_chat/lib/src/core/api/responses.dart +++ b/packages/stream_chat/lib/src/core/api/responses.dart @@ -1,5 +1,6 @@ import 'package:json_annotation/json_annotation.dart'; import 'package:stream_chat/src/client/client.dart'; +import 'package:stream_chat/src/core/error/error.dart'; import 'package:stream_chat/src/core/models/channel_model.dart'; import 'package:stream_chat/src/core/models/channel_state.dart'; import 'package:stream_chat/src/core/models/device.dart'; @@ -9,7 +10,6 @@ import 'package:stream_chat/src/core/models/message.dart'; import 'package:stream_chat/src/core/models/reaction.dart'; import 'package:stream_chat/src/core/models/read.dart'; import 'package:stream_chat/src/core/models/user.dart'; -import 'package:stream_chat/src/core/error/error.dart'; part 'responses.g.dart'; @@ -20,17 +20,17 @@ class _BaseResponse { /// Model response for [StreamChatNetworkError] data @JsonSerializable() class ErrorResponse extends _BaseResponse { - /// + /// The http error code int? code; - /// + /// The message associated to the error code String? message; - /// + /// The backend error code @JsonKey(name: 'StatusCode') int? statusCode; - /// + /// A detailed message about the error String? moreInfo; /// Create a new instance from a json diff --git a/packages/stream_chat/lib/src/core/api/stream_chat_api.dart b/packages/stream_chat/lib/src/core/api/stream_chat_api.dart index 13342160..bcf041c1 100644 --- a/packages/stream_chat/lib/src/core/api/stream_chat_api.dart +++ b/packages/stream_chat/lib/src/core/api/stream_chat_api.dart @@ -1,21 +1,21 @@ import 'package:logging/logging.dart'; +import 'package:stream_chat/src/core/api/attachment_file_uploader.dart'; import 'package:stream_chat/src/core/api/channel_api.dart'; import 'package:stream_chat/src/core/api/device_api.dart'; import 'package:stream_chat/src/core/api/general_api.dart'; import 'package:stream_chat/src/core/api/guest_api.dart'; import 'package:stream_chat/src/core/api/message_api.dart'; import 'package:stream_chat/src/core/api/moderation_api.dart'; +import 'package:stream_chat/src/core/api/user_api.dart'; import 'package:stream_chat/src/core/http/connection_id_manager.dart'; import 'package:stream_chat/src/core/http/stream_http_client.dart'; -import 'package:stream_chat/src/core/api/user_api.dart'; import 'package:stream_chat/src/core/http/token_manager.dart'; -import 'package:stream_chat/src/core/api/attachment_file_uploader.dart'; export 'device_api.dart' show PushProvider; -/// +/// ApiClient that wraps every other specific api class StreamChatApi { - /// + /// Initialize a new stream chat api StreamChatApi( String apiKey, { StreamHttpClient? client, @@ -38,42 +38,42 @@ class StreamChatApi { UserApi? _user; - /// + /// Api dedicated to users operations UserApi get user => _user ??= UserApi(_client); GuestApi? _guest; - /// + /// Api dedicated to guest operations GuestApi get guest => _guest ??= GuestApi(_client); MessageApi? _message; - /// + /// Api dedicated to message operations MessageApi get message => _message ??= MessageApi(_client); ChannelApi? _channel; - /// + /// Api dedicated to channel operations ChannelApi get channel => _channel ??= ChannelApi(_client); DeviceApi? _device; - /// + /// Api dedicated to device operations DeviceApi get device => _device ??= DeviceApi(_client); ModerationApi? _moderation; - /// + /// Api dedicated to moderation operations ModerationApi get moderation => _moderation ??= ModerationApi(_client); GeneralApi? _general; - /// + /// Api dedicated to general operations GeneralApi get general => _general ??= GeneralApi(_client); AttachmentFileUploader? _fileUploader; - /// + /// Class responsible for uploading images and files to a given channel AttachmentFileUploader get fileUploader => _fileUploader ??= StreamAttachmentFileUploader(_client); } diff --git a/packages/stream_chat/lib/src/core/api/user_api.dart b/packages/stream_chat/lib/src/core/api/user_api.dart index 04c72284..61159731 100644 --- a/packages/stream_chat/lib/src/core/api/user_api.dart +++ b/packages/stream_chat/lib/src/core/api/user_api.dart @@ -6,9 +6,9 @@ import 'package:stream_chat/src/core/http/stream_http_client.dart'; import 'package:stream_chat/src/core/models/filter.dart'; import 'package:stream_chat/src/core/models/user.dart'; -/// +/// Defines the api dedicated to users operations class UserApi { - /// + /// Initialize a new user api UserApi(this._client); final StreamHttpClient _client; diff --git a/packages/stream_chat/lib/src/core/http/connection_id_manager.dart b/packages/stream_chat/lib/src/core/http/connection_id_manager.dart index 55fa1896..59dcb1b6 100644 --- a/packages/stream_chat/lib/src/core/http/connection_id_manager.dart +++ b/packages/stream_chat/lib/src/core/http/connection_id_manager.dart @@ -1,26 +1,26 @@ // ignore_for_file: use_setters_to_change_properties -/// +/// Handles the connection id of the websocket connection class ConnectionIdManager { - /// + /// Initialize a new connection id manager ConnectionIdManager({ String? connectionId, }) : _connectionId = connectionId; String? _connectionId; - /// + /// Get the current connection id String? get connectionId => _connectionId; - /// + /// True if there is a connection id bool get hasConnectionId => _connectionId != null; - /// + /// Set the connection id void setConnectionId(String connectionId) { _connectionId = connectionId; } - /// + /// Clear the connection id void reset() { _connectionId = null; } diff --git a/packages/stream_chat/lib/src/core/http/interceptor/auth_interceptor.dart b/packages/stream_chat/lib/src/core/http/interceptor/auth_interceptor.dart index 3097c2b1..9947eefa 100644 --- a/packages/stream_chat/lib/src/core/http/interceptor/auth_interceptor.dart +++ b/packages/stream_chat/lib/src/core/http/interceptor/auth_interceptor.dart @@ -1,20 +1,20 @@ import 'package:dio/dio.dart'; import 'package:stream_chat/src/core/api/responses.dart'; +import 'package:stream_chat/src/core/error/error.dart'; import 'package:stream_chat/src/core/http/stream_chat_dio_error.dart'; import 'package:stream_chat/src/core/http/stream_http_client.dart'; import 'package:stream_chat/src/core/http/token.dart'; - import 'package:stream_chat/src/core/http/token_manager.dart'; -import 'package:stream_chat/src/core/error/error.dart'; -/// +/// Authentication interceptor that refreshes the token if +/// an auth error is received class AuthInterceptor extends Interceptor { - /// + /// Initialize a new auth interceptor AuthInterceptor(this._client, this._tokenManager); final StreamHttpClient _client; - /// + /// The token manager used in the client final TokenManager _tokenManager; @override diff --git a/packages/stream_chat/lib/src/core/http/interceptor/connection_id_interceptor.dart b/packages/stream_chat/lib/src/core/http/interceptor/connection_id_interceptor.dart index 78a3147f..59e1c4bc 100644 --- a/packages/stream_chat/lib/src/core/http/interceptor/connection_id_interceptor.dart +++ b/packages/stream_chat/lib/src/core/http/interceptor/connection_id_interceptor.dart @@ -1,8 +1,7 @@ import 'package:dio/dio.dart'; - import 'package:stream_chat/src/core/http/connection_id_manager.dart'; -/// +/// Interceptor that injects the connection id in the request params class ConnectionIdInterceptor extends Interceptor { /// ConnectionIdInterceptor(this.connectionIdManager); diff --git a/packages/stream_chat/lib/src/core/http/interceptor/logging_interceptor.dart b/packages/stream_chat/lib/src/core/http/interceptor/logging_interceptor.dart index 1f5687a8..f78b46ea 100644 --- a/packages/stream_chat/lib/src/core/http/interceptor/logging_interceptor.dart +++ b/packages/stream_chat/lib/src/core/http/interceptor/logging_interceptor.dart @@ -5,26 +5,26 @@ import 'dart:math' as math; import 'package:dio/dio.dart'; -/// +/// Step where we're logging enum InterceptStep { - /// + /// Request request, - /// + /// Response response, - /// + /// Error error, } -/// +/// Function used to print the log typedef LogPrint = void Function(InterceptStep step, Object object); void _defaultLogPrint(InterceptStep step, Object object) => print(object); -/// +/// Interceptor dedicated to logging class LoggingInterceptor extends Interceptor { - /// + /// Initialize a new logging interceptor LoggingInterceptor({ this.request = true, this.requestHeader = false, @@ -310,13 +310,6 @@ class LoggingInterceptor extends Interceptor { }); } -/* bool _canFlattenMap(Map map) => - map.values.where((dynamic val) => val is Map || val is List).isEmpty && - map.toString().length < maxWidth; - - bool _canFlattenList(List list) => - list.length < 10 && list.toString().length < maxWidth;*/ - void _printMapAsTable( void Function(Object) logPrint, Map? map, { diff --git a/packages/stream_chat/lib/src/core/http/stream_chat_dio_error.dart b/packages/stream_chat/lib/src/core/http/stream_chat_dio_error.dart index 987c9d67..a8ee0988 100644 --- a/packages/stream_chat/lib/src/core/http/stream_chat_dio_error.dart +++ b/packages/stream_chat/lib/src/core/http/stream_chat_dio_error.dart @@ -1,9 +1,9 @@ import 'package:dio/dio.dart'; import 'package:stream_chat/src/core/error/error.dart'; -/// +/// Error class specific to StreamChat and Dio class StreamChatDioError extends DioError { - /// + /// Initialize a stream chat dio error StreamChatDioError({ required this.error, required RequestOptions requestOptions, diff --git a/packages/stream_chat/lib/src/core/http/token.dart b/packages/stream_chat/lib/src/core/http/token.dart index 26532e80..7d746286 100644 --- a/packages/stream_chat/lib/src/core/http/token.dart +++ b/packages/stream_chat/lib/src/core/http/token.dart @@ -5,21 +5,22 @@ import 'package:jose/jose.dart'; import 'package:stream_chat/src/core/models/user.dart'; import 'package:stream_chat/src/core/util/utils.dart'; -/// +/// A function which can be used to request a Stream Chat API token from your +/// own backend server typedef GuestTokenProvider = Future Function(User user); -/// +/// Authentication type enum AuthType { - /// + /// JWT token jwt, - /// + /// Anonymous user anonymous, } -/// +/// Extension for returning the AuthType as a string extension AuthTypeX on AuthType { - /// + /// Returns the AuthType as a string String get raw => { AuthType.jwt: 'jwt', AuthType.anonymous: 'anonymous', @@ -71,13 +72,13 @@ class Token extends Equatable { return Token.fromRawValue(rawToken); } - /// + /// Authentication type of this token final AuthType authType; - /// + /// String value of the token final String rawValue; - /// + /// User id associated with this token final String userId; @override diff --git a/packages/stream_chat/lib/src/core/http/token_manager.dart b/packages/stream_chat/lib/src/core/http/token_manager.dart index 88e9746d..e5af0ddc 100644 --- a/packages/stream_chat/lib/src/core/http/token_manager.dart +++ b/packages/stream_chat/lib/src/core/http/token_manager.dart @@ -1,12 +1,13 @@ import 'package:stream_chat/src/core/http/token.dart'; /// A function which can be used to request a Stream Chat API token from your -/// own backend server. Function requires a single [userId]. +/// own backend server. +/// Function requires a single [userId]. typedef TokenProvider = Future Function(String userId); -/// +/// Handles common token operations class TokenManager { - /// + /// Initialize a new token manager TokenManager({ String? userId, Token? token, @@ -25,10 +26,10 @@ class TokenManager { /// User id to which this TokenManager is configured to String? get userId => _userId; - /// + /// True if it's a static token bool get isStatic => _type == 'static'; - /// + /// Set a token or a token provider Future setTokenOrProvider( String userId, { Token? token, @@ -58,7 +59,7 @@ class TokenManager { return loadToken(); } - /// + /// Returns the token refreshing the existing one if [refresh] is true Future loadToken({bool refresh = false}) async { assert( _userId != null && _type != null, @@ -71,7 +72,7 @@ class TokenManager { return _token!; } - /// + /// Resets the token manager void reset() { _userId = null; _token = null;