附录 4. Session 与 Flash 的处理详解

    1. 处理请求 1.1 ActFramework 使用 SessionMapper 将请求中的某个特定 Cookie 或者 Header 映射为一个字串 1.2 然后使用 SessionCodec 将字串解析为 H.Session 或者 H.Flash Scope 对象
    2. 处理响应 2.1 ActFramework 使用 SessionCodec 将 H.Session 或者 H.Flash Scope 对象打包进一个字串 2.2 然后使用 SessionMapper 将该字串映射到响应特定 Cookie 或者 Header 上

    SessionMapper 负责将序列化之后的 session/flash 字串映射到响应上, 以及从请求中获取 session/flash 字串. 具体来说 ActFramework 内置两大类型的 SessionMapper:

    1.1 CookieSessionMapper

    1. session cookie 名字为 ${app-short-id}-session; flash cookie 名字为 ${app-short-id}-flash
    2. cookie path: /
    3. cookie domain: 当 localhost 为 host 时, 为空值, 否则为 host 配置
    4. httpOnly: true
    5. secure: http.secure 的配置值
    6. value: 序列化之后的 session 或者 flash 字串
    7. ttl: 配置, 默认为 60 * 30, 即半小时

    1.1 HeaderSessionMapper

    HeaderSessionMapper 将 session 字串写入某个 HTTP 响应头. Session 头的名字为 X-Act-Session, Flash 头的名字为 X-Act-Flash

    注意 如果配置文件中存在 jwt=true 会使用 Authorization 作为 Session 头的名字, 且会设置 session.header.payload.prefix 为 Bearer, 表明 session 字串会存放在 Authorization 头的值中, 且使用 Bearer作为前缀. 这直接按照标准方式提供了 JWT 服务, 且应用无需任何改变.

    2 SessionCodec

    2.1 DefaultSessionCodec

    这是系统默认使用的 . 其编码过程如下:

    1. 如果发现 session/flash 对象没有变化且无内容, 则返回 null
    2. 在 session 对象上设定过期时间 (默认为 30*60 - 半小时, 通过 session.ttl 配置参数调整) - 仅适用于 session
    3. 对于 session/flash 对象上每一个 (key, value) 配对, 将其用 \u0001 拼接, 配对之间使用 \u0000 拼接, 生成 payload 字串
    4. 当配置文件中设置了 session.encrypt 为 true 的情况下, 对 {签名-payload} 做加密处理 - 仅适用于 session
    5. 最后对字串做 url 安全编码生成最终结果

    当收到请求的时候解码过程是上面的逆操作.

    2.2 JsonWebTokenSessionCodec

    1. 如果发现 session 对象没有变化且无内容, 则返回 null
    2. 生成一个空的 JWT 对象
    3. 在 JWT 对象上通过 exp 设定过期时间 (默认为 30*60 - 半小时, 通过 session.ttl 配置参数调整)
    4. 对于 session 对象上每一个 (key, value) 配对, 将其放入 JWT 对象的 payload 中
    5. 将算法名字使用 alg JWT 头部. 默认算法为 SHA256, 可以通过 jwt.algo 配置为其他算法. 目前支持的算法除了 SHA256, 还有 SHA384 和 SHA512
    6. 将 JWT 的头部序列化为 JSON 字串并做 URL 安全编码, payload 部分序列化为 JSON 字串并作 URL 安全编码, 两个部分用 拼接起来
    7. 对上面生成的字串使用算法进行 hash 计算, 并将计算结果使用 . 拼接在最后, 生成 JWT 字串

    当受到请求的时候发现了 JWT 字串, 采用上面的逆操作生成 session 对象.