Document `fetchAuthSession()` behavior including exceptions when offline or expired

[vgribok]

Description

Just did flutter pub upgrade, using amplify_core v.1.0.0-next.2+1.
fetchAuthSession() on Android Pixel 3a emulator with Airplane mode on, with user successfully logged in in a prior app session, followed by app shutdown and restart.
Getting:

I/flutter (10674): Unhandled Amplify error: "POST https://cognito-idp.us-east-2.amazonaws.com/? failed: SocketException: Failed host lookup: 'cognito-idp.us-east-2.amazonaws.com' (OS Error: No address associated with hostname, errno = 7)"

I really think that fetchAuthSession() docs should specify not only what the function does in general, but also what behavior is expected, including exceptions thrown, in different circumstances, like session has expired, like user is not logged in, like the device is offline, etc - all in one place.

Categories

• Analytics
• API (REST)
• API (GraphQL)
• Auth
• Authenticator
• DataStore
• Storage

Steps to Reproduce

1. Use latest release of dev preview libs.
2. Run an auth-enabled app on an Android emulator with Airplane mode on.
3. Observe undocumente

Screenshots

No response

Platforms

• iOS
• Android
• Web
• macOS
• Windows
• Linux

Android Device/Emulator API Level

API 32+

Environment

[✓] Flutter (Channel stable, 3.3.9, on macOS 12.6.2 21G320 darwin-arm, locale en-US)
[✓] Android toolchain - develop for Android devices (Android SDK version 33.0.1)
[✓] Xcode - develop for iOS and macOS (Xcode 14.1)
[✓] Chrome - develop for the web
[✓] Android Studio (version 2021.3)
[✓] VS Code (version 1.74.2)
[✓] Connected device (4 available)
[✓] HTTP Host Availability

Dependencies

dependencies:
- amplify_api 1.0.0-next.2+1 [amplify_api_android amplify_api_ios amplify_core amplify_flutter async aws_common collection connectivity_plus flutter json_annotation meta plugin_platform_interface stream_transform web_socket_channel]
- amplify_auth_cognito 1.0.0-next.2+1 [amplify_auth_cognito_android amplify_auth_cognito_dart amplify_auth_cognito_ios amplify_core amplify_flutter amplify_secure_storage async flutter flutter_web_plugins meta path plugin_platform_interface]
- amplify_authenticator 1.0.0-next.1+3 [amplify_auth_cognito amplify_core amplify_flutter async aws_common collection flutter flutter_localizations intl meta smithy stream_transform]
- amplify_datastore 1.0.0-next.2 [flutter amplify_datastore_plugin_interface amplify_core plugin_platform_interface meta collection async]
- amplify_flutter 1.0.0-next.2 [amplify_core amplify_datastore_plugin_interface amplify_flutter_android amplify_flutter_ios amplify_secure_storage aws_common collection flutter meta plugin_platform_interface]
- amplify_storage_s3 1.0.0-next.2 [amplify_core amplify_db_common amplify_storage_s3_dart aws_common flutter meta path_provider]
- async 2.9.0 [collection meta]
- connectivity_plus 3.0.2 [flutter flutter_web_plugins connectivity_plus_platform_interface js meta nm]
- cupertino_icons 1.0.5
- flutter 0.0.0 [characters collection material_color_utilities meta vector_math sky_engine]
- flutter_form_builder 7.7.0 [flutter intl collection]
- flutter_native_splash 2.2.16 [args flutter flutter_web_plugins js html image meta path universal_io xml yaml]
- flutter_nav2_oop 1.0.0+1 [flutter cupertino_icons flutter_riverpod google_fonts riverpod_restorable]
- flutter_riverpod 2.1.3 [collection flutter meta riverpod state_notifier]
- font_awesome_flutter 10.3.0 [flutter]
- geolocator 9.0.2 [flutter geolocator_platform_interface geolocator_android geolocator_apple geolocator_web geolocator_windows]
- image_picker 0.8.6 [flutter image_picker_android image_picker_for_web image_picker_ios image_picker_platform_interface]
- native_exif 0.4.0 [flutter intl]
- path 1.8.2
- path_provider 2.0.11 [flutter path_provider_android path_provider_ios path_provider_linux path_provider_macos path_provider_platform_interface path_provider_windows]
- riverpod_restorable 2.0.0 [flutter riverpod flutter_riverpod]

transitive dependencies:
- amplify_api_android 1.0.0-next.2 [flutter]
- amplify_api_ios 1.0.0-next.2 [amplify_core flutter]
- amplify_auth_cognito_android 1.0.0-next.2 [flutter]
- amplify_auth_cognito_dart 0.3.1 [amplify_core amplify_secure_storage_dart async aws_common aws_signature_v4 built_collection built_value collection convert crypto fixnum http intl js json_annotation meta oauth2 path smithy smithy_aws stream_transform uuid worker_bee]
- amplify_auth_cognito_ios 1.0.0-next.2 [amplify_core flutter]
- amplify_core 1.0.0-next.2+1 [async aws_common aws_signature_v4 collection intl json_annotation logging meta retry uuid]
- amplify_datastore_plugin_interface 1.0.0-next.2 [amplify_core collection flutter meta]
- amplify_db_common 0.1.2 [amplify_db_common_dart drift flutter path path_provider]
- amplify_db_common_dart 0.1.3 [amplify_core async aws_common drift meta path sqlite3]
- amplify_flutter_android 1.0.0-next.2 [flutter]
- amplify_flutter_ios 1.0.0-next.2 [amplify_core flutter]
- amplify_secure_storage 0.1.4+1 [amplify_secure_storage_dart async file flutter meta path path_provider]
- amplify_secure_storage_dart 0.1.4+1 [async aws_common built_collection built_value ffi file js meta path win32 worker_bee]
- amplify_storage_s3_dart 0.1.4 [amplify_core amplify_db_common_dart async aws_common aws_signature_v4 built_collection built_value drift fixnum meta path smithy smithy_aws]
- archive 3.3.0 [crypto path]
- args 2.3.1
- aws_common 0.3.5+1 [async built_collection built_value collection http2 js json_annotation logging meta mime os_detect path stream_transform uuid]
- aws_signature_v4 0.3.1+1 [async aws_common collection convert crypto json_annotation meta path]
- built_collection 5.1.1
- built_value 8.4.2 [built_collection collection fixnum meta]
- characters 1.2.1
- clock 1.1.1
- collection 1.16.0
- connectivity_plus_platform_interface 1.2.3 [flutter meta plugin_platform_interface]
- convert 3.1.1 [typed_data]
- crclib 3.0.0 [meta tuple]
- cross_file 0.3.3+2 [js meta]
- crypto 3.0.2 [typed_data]
- csslib 0.17.2 [source_span]
- dbus 0.7.8 [args ffi meta xml]
- drift 2.3.0 [async convert collection js meta stream_channel sqlite3]
- ffi 2.0.1
- file 6.1.2 [meta path]
- fixnum 1.0.1
- flutter_localizations 0.0.0 [flutter intl characters clock collection material_color_utilities meta path vector_math]
- flutter_plugin_android_lifecycle 2.0.7 [flutter]
- flutter_web_plugins 0.0.0 [flutter js characters collection material_color_utilities meta vector_math]
- geolocator_android 4.1.4 [flutter geolocator_platform_interface]
- geolocator_apple 2.2.3 [flutter geolocator_platform_interface]
- geolocator_platform_interface 4.0.7 [flutter plugin_platform_interface vector_math meta]
- geolocator_web 2.1.6 [flutter flutter_web_plugins geolocator_platform_interface]
- geolocator_windows 0.1.1 [flutter geolocator_platform_interface]
- google_fonts 3.0.1 [flutter http path_provider crypto]
- html 0.15.1 [csslib source_span]
- http 0.13.5 [async http_parser meta path]
- http2 2.0.1
- http_parser 4.0.2 [collection source_span string_scanner typed_data]
- image 3.3.0 [archive meta xml]
- image_picker_android 0.8.5+4 [flutter flutter_plugin_android_lifecycle image_picker_platform_interface]
- image_picker_for_web 2.1.10 [flutter flutter_web_plugins image_picker_platform_interface]
- image_picker_ios 0.8.6+5 [flutter image_picker_platform_interface]
- image_picker_platform_interface 2.6.2 [cross_file flutter http plugin_platform_interface]
- intl 0.17.0 [clock path]
- js 0.6.4
- json_annotation 4.7.0 [meta]
- logging 1.1.0
- material_color_utilities 0.1.5
- meta 1.8.0
- mime 1.0.3
- nm 0.5.0 [dbus]
- oauth2 2.0.1 [collection crypto http http_parser]
- os_detect 2.0.1
- path_provider_android 2.0.22 [flutter path_provider_platform_interface]
- path_provider_ios 2.0.11 [flutter path_provider_platform_interface]
- path_provider_linux 2.1.7 [ffi flutter path path_provider_platform_interface xdg_directories]
- path_provider_macos 2.0.6 [flutter path_provider_platform_interface]
- path_provider_platform_interface 2.0.5 [flutter platform plugin_platform_interface]
- path_provider_windows 2.1.3 [ffi flutter path path_provider_platform_interface win32]
- petitparser 5.1.0 [meta]
- platform 3.1.0
- plugin_platform_interface 2.1.3 [meta]
- process 4.2.4 [file path platform]
- retry 3.1.0
- riverpod 2.1.3 [collection meta stack_trace state_notifier]
- shelf 1.4.0 [async collection http_parser path stack_trace stream_channel]
- sky_engine 0.0.99
- smithy 0.3.2 [async aws_common built_collection built_value collection convert crypto fixnum http_parser intl json_annotation meta path retry shelf typed_data xml]
- smithy_aws 0.3.2 [aws_common aws_signature_v4 built_collection built_value collection convert crclib crypto intl json_annotation meta path smithy xml]
- source_span 1.9.0 [collection path term_glyph]
- sqlite3 1.9.1 [collection ffi js meta path]
- stack_trace 1.10.0 [path]
- state_notifier 0.7.2+1 [meta]
- stream_channel 2.1.0 [async]
- stream_transform 2.1.0
- string_scanner 1.1.1 [source_span]
- term_glyph 1.2.1
- tuple 2.0.1
- typed_data 1.3.1 [collection]
- universal_io 2.0.4 [collection crypto meta typed_data]
- uuid 3.0.7 [crypto]
- vector_math 2.1.2
- web_socket_channel 2.2.0 [async crypto stream_channel]
- win32 3.1.3 [ffi]
- worker_bee 0.1.3+1 [async aws_common built_collection built_value collection js meta path stack_trace stream_channel stream_transform]
- xdg_directories 0.2.0+2 [meta path process]
- xml 6.1.0 [collection meta petitparser]
- yaml 3.1.1 [collection source_span string_scanner]

Device

Android Pixel 3a emulator

OS

Android API 33

Deployment Method

Amplify CLI

CLI Version

10.6.0

Additional Context

No response

Amplify Config

Instructions unclear. Also, high amount of detail in this submission discourages contributions.

[dnys1]

Thanks for opening an issue, @vgribok.

There are a few points here I want to address:

• Regarding the lack of documentation, you're absolutely correct that the failure states should be better documented. I'll create some tickets to track this.
• Regarding the lengthy, bug report ticket, I will look into how we can simplify that as well.

Now, regarding the actual behavior observed here. If the credentials are expired and need to be refreshed while the client is offline, this is not a use case we've explored deeply yet on the Amplify team (#760), but we do have some meetings scheduled to review this across all our libraries.

I will leave this ticket open to track documentation of fetchAuthSession and will post updates regarding offline behavior here and on #760.

[vgribok]

Many thanks, @dnys1!
To clarify, in this case the session is not yet expired - the device is just offline.

Vlad.

[dnys1]

Ah, understood. I believe then, that the getAWSCredentials flag is the culprit. This is also something we're looking into so that these partial refresh failures can be better handled.

[vgribok]

Thanks.
The credentials are not requested in my flow.

  static Future<AuthSession> _attemptToGetAuthSession() =>
      Amplify.Auth.fetchAuthSession()
          .timeout(const Duration(seconds: 10));

[seanhamstra]

Super similar issue here (same steps and crash) however it throws with the call to:

Amplify.Auth.fetchUserAttributes()

POST https://cognito-idp.us-east-2.amazonaws.com/? failed: SocketException: Failed host lookup: 'cognito-idp.us-east-2.amazonaws.com' (OS Error: No address associated with hostname, errno = 7)

[Jordan-Nelson]

@seanhamstra - Does this happen with a stable internet connection? If yes, can you reproduce this consistently?

If there is no network the expected behavior would be a thrown Exception of type NetworkException. It appears that currently the exception being thrown is a AWSHttpException. Other than the incorrect exception type, this appears to be functioning as expected.

[seanhamstra]

@Jordan-Nelson apologies, you are correct. This is when we are offline. Previously we were only expecting AuthException and thought we handled this case (before 1.0.0). Perhaps it was always throwing this and we missed the test case. Either way, AWSHttpException throws and we now catch any exception. Thanks!

[Jordan-Nelson]

@seanhamstra - it should throw an AuthException. NetworkException (which is what should be thrown) implements AuthException. However, it is throwing the wrong exception (AWSHttpException). We have a fix in progress. In the next release you should be able to just catch AuthException again.