class XBlockUserStateClient(object):
    """
    First stab at an interface for accessing XBlock User State. This will have
    use StudentModule as a backing store in the default case.
    
    Scope/Goals:
    1. Mediate access to all student-specific state stored by XBlocks.
        a. This includes "preferences" and "user_info" (i.e. UserScope.ONE)
        b. This includes XBlock Asides.
        c. This may later include user_state_summary (i.e. UserScope.ALL).
           - Though I'm fuzzy on where we're going in general with this and how
             it relates to content.
        d. This may include group state in the future.
        e. This may include other key types + UserScope.ONE (e.g. Definition)
           - I think this implies a per-user partition scheme and not a 
             user+course partition scheme.
    2. Assume network service semantics.
        At some point, this will probably be calling out to an external service.
        Even if it doesn't, we want to be able to implement circuit breakers, so
        that a failure in StudentModule doesn't bring down the whole site.
        This also implies that the client is running as a user, and whatever is
        backing it is smart enough to do authorization checks.
    3. This does not yet cover export-related functionality.

    Open Questions:
    1. Is it sufficient to just send the block_key in and extract course + 
       version info from it?
    2. Do we want to use the username as the identifier? Privacy implications?
       Ease of debugging?
    3. Would a get_many_by_type() be useful?
    """

    class ServiceUnavailableError(Exception):
        pass

    class PermissionDeniedError(Exception):
        pass

    # 001
    def get(user_id, block_key, scope=Scope.user_state):
        pass

    # 001
    def set(user_id, block_key, state, scope=Scope.user_state):
        pass

    # 002
    def get_many(user_id, block_keys, scope=Scope.user_state):
        """Returns dict of block_id -> state."""
        pass

    # 002
    def set_many(user_id, block_keys_to_state, scope=Scope.user_state):
        pass

    # 003
    def get_history(user_id, block_key, scope=Scope.user_state):
        """We don't guarantee that history for many blocks will be fast."""
        pass

    # 004, 006
    def iter_all_for_block(block_key, scope=Scope.user_state, batch_size=None):
        """
        You get no ordering guarantees. Fetching will happen in batch_size
        increments. If you're using this method, you should be running in an
        async task.
        """
        pass

    # 005 if you want to push it...?
    def iter_all_for_course(course_key, block_type=None, scope=Scope.user_state, batch_size=None):
        """
        You get no ordering guarantees. Fetching will happen in batch_size
        increments. If you're using this method, you should be running in an
        async task.
        """
        pass

CREATE TABLE IF NOT EXISTS xblock_user_state (
    user varchar,     -- varchar so that we can support anonymous IDs if desired
    course_key varchar,
    block_type varchar, 
    usage_key varchar,
    created timestamp,  -- append only, each update is a new record
    state binary,
    PRIMARY KEY ((user, course_key), block_type, usage_key, created)
)

CREATE TABLE IF NOT EXISTS xblock_state (
  -- Not a 1:1 mapping with real users, as it might store anonymized user IDs,
  -- groups, as well as special values like "none".
  --
  -- Examples: "none", "u.301291", "au.31904f9de10"
  user text,
 
  -- Anything where we want to hold all the state in the same place. Note that
  -- this may mean denormalization (so storing definitions in multiple places).
  -- A course "publishing" might mean we write out a new partition where the
  -- grouping is the versioned course_id, and write all content/settings scopes
  -- there.
  --
  -- Examples: {course_id}, {course_id@version}, {library_id}
  grouping text,

  -- A way to namespace different entities that may want to store different info
  -- for the same (user, grouping). 
  -- 
  -- For example, we might have many kinds of things that want to create field
  -- overrides (due date extensions, adaptive courseware, etc.) These would all
  -- be placed together in the (user, grouping) partition, where grouping is an
  -- unversioned course_id.
  -- 
  -- Examples: "lms", "idde", "ccx"
  app text, 


  -- There are two ways we can go with this. Either use this to represent scope
  -- in the BlockScope sense ("usage", "def", "type", "all"), or use this to
  -- represent the named scopes people are more familiar with (content, settings
  -- user_state, preferences, user_info, user_state_summary). I actually prefer
  -- the latter, because it lets us eventually model FieldOverrides in this
  -- table as well. So you could have "settings" var with a user association 
  -- to override a due date, instead of that being "user_state" because it has
  -- the user association.
  --
  -- Examples: "content", "settings", "user_state", "preferences", "user_info"
  --           "user_state_summary" (though possibly abbreviated forms)
  b_scope text,


  -- Type of XBlock. This is here mostly for sorting reasons, so we can
  -- efficiently query for "all A/B tests", "all videos", etc.
  -- Is this redundant given that string representation of keys already
  -- sort by type? Might not be if we're mixing old and new style IDs.
  -- And anyway, the point of opaque keys is that they should remain opaque.
  --
  -- Examples: "video", "html", "problem"
  b_type text,


  -- Usage key, definition key, etc. Unversioned.
  b_key text,


  -- Timestamp, provided by client. Should exactly match the entry going into
  -- the state_hs map.
  modified timestamp,
 
  -- Typically a UTF-8 encoded JSON string, but XBlocks are free to store
  -- arbitrary binary data here. If we need to find out when this was written,
  -- we can call WRITETIME on this column.
  state binary


  -- A map of timestamps to states. When we update a row, we set both the state
  -- column and add the same entry into this map. This preserves history. Also,
  -- because a map is a CRDT, we shouldn't lose data in the case of a split.
  state_hs = map<timestamp, binary>
  
  PRIMARY KEY (
    -- Parititon by user and grouping
    (user, grouping),


    -- Cluster within a partition so we can scan by app, scope, and type.
    app, b_scope, b_type, b_key
)


-- Side note: re-examine user_state_summary use cases to see if counter +
-- ability to scan across users for user_state scope might be sufficient.
CREATE TABLE IF NOT EXISTS xblock_state_summary (
    grouping text,
    b_scope text
    b_key text,
    app text,
    user text,
    hash text, -- bigint? (xxhash)
    modified timestamp,
    state binary,
    PRIMARY KEY (
        (grouping, b_scope, b_key), app, user
    )
)