/*
|
* Copyright (C) 2017 Twitter, Inc.
|
*
|
* Licensed under the Apache License, Version 2.0 (the "License");
|
* you may not use this file except in compliance with the License.
|
* You may obtain a copy of the License at
|
*
|
* http://www.apache.org/licenses/LICENSE-2.0
|
*
|
* Unless required by applicable law or agreed to in writing, software
|
* distributed under the License is distributed on an "AS IS" BASIS,
|
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
* See the License for the specific language governing permissions and
|
* limitations under the License.
|
*
|
*/
|
|
@class TWTRAuthConfig;
|
@class TWTRGuestSession;
|
@class TWTRSession;
|
@protocol TWTRAuthSession;
|
@protocol TWTRAPIServiceConfig;
|
@protocol TWTRErrorLogger;
|
|
NS_ASSUME_NONNULL_BEGIN
|
|
#pragma mark - TWTRSessionRefreshingStore Protocol
|
|
/**
|
* Completion block called when a session refresh succeeds or fails.
|
*
|
* @param refreshedSession The refreshed session
|
* @param error Error that will be non nil if the refresh request failed
|
*/
|
typedef void (^TWTRSessionStoreRefreshCompletion)(id _Nullable refreshedSession, NSError *_Nullable error);
|
|
/**
|
* Protocol for session stores that can refresh expired sessions.
|
*/
|
@protocol TWTRSessionRefreshingStore <NSObject>
|
|
/**
|
* Refresh an expired session.
|
*
|
* @param sessionClass The class of the session
|
* @param sessionID ID of the session wherever applicable e.g. `userID` if it's a user session.
|
* @param completion The completion block to call when the refresh request succeeds or fails.
|
*/
|
- (void)refreshSessionClass:(Class)sessionClass sessionID:(nullable NSString *)sessionID completion:(TWTRSessionStoreRefreshCompletion)completion;
|
|
/**
|
* Determines whether the given session has expired.
|
*
|
* @param session The session to check for expiration
|
* @param response API request response to check for expiration
|
*
|
* @return Whether the session has expired.
|
*/
|
- (BOOL)isExpiredSession:(id)session response:(NSHTTPURLResponse *)response;
|
|
/**
|
* Determines whether the given session has expired based on a given error.
|
*
|
* @param session The session to check for expiration
|
* @param error API request error to check for expiration
|
*
|
* @return Whether the session has expired.
|
*/
|
- (BOOL)isExpiredSession:(id)session error:(NSError *)error;
|
|
@end
|
|
#pragma mark - TWTRUserSessionStore Protocol
|
|
/**
|
* Completion block called when a user session saved to the session store or fails.
|
*
|
* @param session The saved session
|
* @param error Error that will be non nil if the save request fails.
|
*/
|
typedef void (^TWTRSessionStoreSaveCompletion)(id<TWTRAuthSession> _Nullable session, NSError *_Nullable error);
|
|
/**
|
* Completion block called when fetching all stored user sessions completes or fails.
|
*
|
* @param sessions All stored user sessions or empty array if there are no user sessions found.
|
*/
|
typedef void (^TWTRSessionStoreBatchFetchCompletion)(NSArray *sessions);
|
|
/**
|
* Completion block to call when the session is deleted or fails.
|
*
|
* @param session The deleted session or nil if none was found for the user.
|
*/
|
typedef void (^TWTRSessionStoreDeleteCompletion)(id<TWTRAuthSession> _Nullable session);
|
|
/**
|
* Protocol for session store that manages user sessions.
|
*/
|
@protocol TWTRUserSessionStore <NSObject>
|
|
/**
|
* Saves the existing session to the store after validations.
|
*
|
* @param session The user session to save
|
* @param completion Completion block to call when the save request succeeds or fails
|
*/
|
- (void)saveSession:(id<TWTRAuthSession>)session completion:(TWTRSessionStoreSaveCompletion)completion;
|
|
/**
|
* Fetches the user session for for the given auth tokens and saves it to the store after validations.
|
*
|
* @param authToken The existing authToken to use for authentication.
|
* @param authTokenSecret The existing authTokenSecret to use for authentication.
|
* @param completion Completion block to call when the save request succeeds or fails
|
*/
|
- (void)saveSessionWithAuthToken:(NSString *)authToken authTokenSecret:(NSString *)authTokenSecret completion:(TWTRSessionStoreSaveCompletion)completion;
|
|
/**
|
* Checks to see if the user is logged in and has a saved session.
|
*
|
* @param userID The user ID to fetch session for.
|
*/
|
- (nullable id<TWTRAuthSession>)sessionForUserID:(NSString *)userID;
|
|
/**
|
* Retrieve all logged in user sessions in ascending order of last saved date
|
*
|
* @note This is a blocking call.
|
*/
|
- (NSArray *)existingUserSessions;
|
|
/**
|
* Returns YES if there are existing user sessions.
|
*
|
* @note This is a blocking call.
|
*/
|
- (BOOL)hasLoggedInUsers;
|
|
/**
|
* Retrieves the last logged in user session.
|
*
|
* @return The last logged in user session.
|
*/
|
- (nullable id<TWTRAuthSession>)session;
|
|
/**
|
* Deletes the local Twitter user session from this app. This will not remove the system Twitter account nor make a network request to invalidate the session.
|
*
|
* @param userID ID of the user to log out
|
*/
|
- (void)logOutUserID:(NSString *)userID;
|
|
@end
|
|
#pragma mark - TWTRGuestSessionStore Protocol
|
|
/**
|
* Completion block called when retrieving a guest session succeeds or fails.
|
*
|
* @param guestSession The retrieved guest session
|
* @param error Error that will be non nil if the save request fails.
|
*/
|
typedef void (^TWTRSessionGuestLogInCompletion)(TWTRGuestSession *_Nullable guestSession, NSError *_Nullable error);
|
|
/**
|
* Protocol for session stores that can manage guest sessions.
|
*/
|
@protocol TWTRGuestSessionStore <NSObject>
|
|
/**
|
* Log in as a guest user and return the guest session. This can be used when the user is not a Twitter user.
|
*
|
* @param completion Completion block to call when the authentication succeeds or fails.
|
*
|
* @warning This method assumes your application, as indicated by the `consumerKey` and `consumerSecret` in the `authConfig`, has been whitelisted for guest authentication.
|
*/
|
- (void)fetchGuestSessionWithCompletion:(TWTRSessionGuestLogInCompletion)completion;
|
|
@end
|
|
#pragma mark - Composite TWTRSessionStore Protocol
|
|
/**
|
* Convenience composite protocol of a store that handles user, guest, and refreshable sessions.
|
*/
|
@protocol TWTRSessionStore <TWTRUserSessionStore, TWTRGuestSessionStore, TWTRSessionRefreshingStore>
|
|
/**
|
* Returns the store's auth config.
|
*/
|
@property (nonatomic, readonly) TWTRAuthConfig *authConfig;
|
|
@end
|
|
#pragma mark - Concrete Session Store Class
|
|
/**
|
* Concrete implementation of <TWTRSessionStore>. This session store supports fetching and storage of
|
* user and guest sessions. In addition, the session store also supports refreshing of such sessions when they expire.
|
*
|
* @warning Instances of the session manager at the same path are not synchronized. The session store
|
* will simply choose the latest version in the case of conflicts.
|
*/
|
@interface TWTRSessionStore : NSObject <TWTRSessionStore>
|
|
- (instancetype)init NS_UNAVAILABLE;
|
|
/**
|
* Provides a mechanism for reloading the session store. This method will force the session store
|
* to find any sessions that may have been saved by another session store or application that is
|
* using the same keychain access groups.
|
*
|
* Most applications will not need to call this method. You may need to call this method if you are
|
* using multiple stores within your application and you need to synchronize when one writes to the
|
* store. The more likely case for needing to call this method is if you are sharing credentials
|
* between applications. In this situation you will want to call this method when the application
|
* comes back to the foreground.
|
*
|
* This method does not need to be called when the store is created because this process happens
|
* by default at time of instantiation.
|
*
|
* You should avoid calling this method if you do not have a specific reason to do so, like the reasons
|
* mentioned above as this method does cause disk I/O and multiple calls can cause performance problems.
|
*/
|
- (void)reloadSessionStore;
|
|
/**
|
* Sets a local string which can be used to verify the auth token using
|
* isValidOauthToken:
|
*/
|
- (void)saveOauthToken:(NSString *)token;
|
|
/**
|
* If saveOauthToken is called then this will compare the set to the token passed by the token parameter.
|
* This is used to verify the token generated from the oauth/request_token request after a URL has been passed
|
* back from web authenticatoin.
|
*
|
* Returns YES is the token string matches the internal OAuth token.
|
*/
|
- (BOOL)isValidOauthToken:(NSString *)token;
|
@end
|
|
NS_ASSUME_NONNULL_END
|
