Class WhoSessions

java.lang.Object
org.jwcarman.who.core.service.WhoSessions

public class WhoSessions extends Object
who's record of browser sessions: one per sign-in, so a person can see where they are signed in and end a session from elsewhere, and an application can end an identity's sessions.

A session is live while it is not ended and was seen within the idle timeout, the same timeout the servlet container or Spring Session uses, so a session the container dropped without saying so stops counting on its own. This service trusts its caller: it ends whatever session it is asked to, and the endpoints decide who may end which.

  • Field Details

    • MAX_USER_AGENT_LENGTH

      public static final int MAX_USER_AGENT_LENGTH
      The longest User-Agent kept.
      See Also:
  • Constructor Details

    • WhoSessions

      public WhoSessions(SessionRecordRepository repository, WhoEventPublisher events, Clock clock, Duration idleTimeout, Duration lastSeenInterval, int purgeBatchSize, boolean autoPurge)
      Creates the service.
      Parameters:
      repository - where sessions are kept
      events - receives SessionEnded and EndedSessionsPurged
      clock - the current time
      idleTimeout - how long a session lasts without a request
      lastSeenInterval - how often a busy session's last-seen time is written
      purgeBatchSize - the most dead sessions one purge deletes
      autoPurge - whether each sign-in purges one batch
  • Method Details

    • idleTimeout

      public Duration idleTimeout()
      Returns how long a session lasts without a request.
      Returns:
      the idle timeout
    • lastSeenInterval

      public Duration lastSeenInterval()
      Returns how often a busy session's last-seen time is written.
      Returns:
      the interval
    • purgeBatchSize

      public int purgeBatchSize()
      Returns the most dead sessions one purge deletes.
      Returns:
      the batch size
    • autoPurge

      public boolean autoPurge()
      Returns whether each sign-in purges one batch of dead sessions.
      Returns:
      whether auto-purge is on
    • start

      public SessionRecord start(UUID identityId, UUID credentialId, SignInMethod method, String userAgent)
      Records a sign-in made now.
      Parameters:
      identityId - the identity that signed in
      credentialId - the credential it signed in with
      method - how it signed in
      userAgent - the browser's User-Agent, or null; longer ones are cut to 512 characters
      Returns:
      the new session
    • start

      public SessionRecord start(UUID identityId, UUID credentialId, SignInMethod method, String userAgent, Instant signedInAt)
      Records a sign-in made at signedInAt, seen now. When auto-purge is on, each call then purges one batch of dead sessions; a purge that fails is logged and does not fail the sign-in.
      Parameters:
      identityId - the identity that signed in
      credentialId - the credential it signed in with
      method - how it signed in
      userAgent - the browser's User-Agent, or null
      signedInAt - when it signed in
      Returns:
      the new session
    • findLive

      public Optional<SessionRecord> findLive(UUID sessionId)
      Finds a session that is still live: not ended, and seen within the idle timeout plus the last-seen interval, since a busy session's last-seen time is written only that often.
      Parameters:
      sessionId - the session's id
      Returns:
      the session, or empty when it is unknown, ended or idle
    • seen

      public void seen(SessionRecord session)
      Records that a session made a request, writing at most once per last-seen interval.
      Parameters:
      session - the session, as found by findLive(UUID)
    • list

      public List<SessionRecord> list(UUID identityId)
      Lists an identity's live sessions, most recently signed in first.
      Parameters:
      identityId - the identity
      Returns:
      the sessions
    • end

      public boolean end(UUID sessionId)
      Ends a live session; its next request is signed out. Publishes SessionEnded with SessionEndReason.REVOKED.
      Parameters:
      sessionId - the session's id
      Returns:
      whether a live session was ended
    • endAll

      public int endAll(UUID identityId)
      Ends every live session of an identity, for instance after it reports a lost device.
      Parameters:
      identityId - the identity
      Returns:
      how many were ended
    • endAllExcept

      public int endAllExcept(UUID identityId, UUID keepSessionId)
      Ends every live session of an identity but one, usually the one asking.
      Parameters:
      identityId - the identity
      keepSessionId - the session to keep
      Returns:
      how many were ended
    • close

      public void close(UUID sessionId)
      Ends a session that signed out or expired. Publishes nothing: sign-out has its own event.
      Parameters:
      sessionId - the session's id
    • purgeEndedSessions

      public int purgeEndedSessions()
      Deletes at most one batch of dead sessions: ended ones, and ones idle past the timeout. Call it again for more; it never tries to delete them all at once.
      Returns:
      how many were deleted
    • deviceLabel

      public static String deviceLabel(String userAgent)
      A short description of a browser, such as "Firefox on macOS", from its User-Agent. It reads only the browser and system families, and says so when it cannot tell.
      Parameters:
      userAgent - the User-Agent, or null
      Returns:
      the label