Class HubServerProp

java.lang.Object
com.iizix.prop.GProp<GProp<?>[]>
com.iizix.prop.PropCnr
com.iizix.server.hub.HubServerProp
All Implemented Interfaces:
EventListener, IGProp<GProp<?>[]>, IPropCnr, Cloneable
public class HubServerProp extends PropCnr
The hub channel between a member and the principal (HUB-DESIGN.md sections 3.2 to 3.4, built by B-7b): one instance per member connection, the only child of the member's $device container, created by the member client (HubMemberClient) and mirrored on the principal by the property factory, which instantiates it because it is registered in base-properties.xml as hubServer.

Events are remote events, dispatched on getLocalID() (section 3.4): the principal opens every connection with REMOTE_CHALLENGE (ruled LV-12 (a)), the member answers with REMOTE_REGISTER and is admitted or refused (section 2.4). A request carries the request id P_REQUEST and its reply goes back on the same local id carrying the id, with P_OK and the result members or P_REASON, the way the License System replies. Each id has one direction: the principal sends CHALLENGE and 20 to 23, the member sends 1 to 10, 40 to 49 are reserved for D-PUSH-CLUSTER in both; so on each side an incoming event on an id this side sends is a reply and everything else is a request, handed to the HubServerProp.IHubEventHandler the owner set.

Pending requests (section 3.2, the pattern of PushChannelProps): a table keyed by an id from a per-connection counter never reused, each entry with a deadline; a reply with an unknown id is logged at INFO and dropped; at disposal every pending entry is logged at INFO and dropped.

Epoch (sections 3.4, 4.5): every event the principal sends carries P_EPOCH; the member drops, and logs at WARNING, an event whose epoch is lower than the highest it has seen. The principal's epoch is set by B-7c's election; until then it is 0.

Threads. A reply or a request arrives on the connection's thread (the end point's worker on the principal, the client's worker on the member) and a deadline on the timer's: the listener and the handler are called there, at once.

Public properties only (section 3.3): a payload travels as ordinary properties, a credential as a ByteArrayProp; nothing here is serialized by Java.

Author:
Christopher Mindus

  • Field Details

    • ATOM_NAME

      public static final String ATOM_NAME
      The atom name of the channel under the member's $device container: "hub".
      See Also:

    • ATOM

      public static final Atom ATOM
      The atom of the channel under $device.

    • WIRE_VERSION

      public static final int WIRE_VERSION
      The hub wire version this build speaks: 1 (section 2.4, P_WIRE).
      See Also:

    • CHALLENGE_BYTES

      public static final int CHALLENGE_BYTES
      The number of random bytes of a challenge: 32 (section 2.2).
      See Also:

    • REGISTER_DEADLINE_MILLIS

      public static final long REGISTER_DEADLINE_MILLIS
      How long the principal waits for REGISTER after the WebSocket opened, in milliseconds: 10000L (section 13).
      See Also:

    • REQUEST_DEADLINE_MILLIS

      public static final long REQUEST_DEADLINE_MILLIS
      The deadline of an ordinary request, in milliseconds: 10000L (section 13).
      See Also:

    • REMOTE_CHALLENGE

      public static final int REMOTE_CHALLENGE
      Principal to member 0: CHALLENGE, sent when the connection opens, with P_PN: 32 random bytes fresh for this connection (ruled LV-12 (a), section 2.2). Nothing replies; the member's REGISTER answers it.
      See Also:

    • REMOTE_PRINCIPAL

      public static final int REMOTE_PRINCIPAL
      Principal to member 20: PRINCIPAL, the announcement of section 4.4 with P_MEMBER, P_URL and P_EPOCH; answered by ack (B-7c).
      See Also:

    • REMOTE_MEMBERS

      public static final int REMOTE_MEMBERS
      Principal to member 21: MEMBERS, the member list with state and link RTT (P_MEMBERS); nothing replies.
      See Also:

    • REMOTE_INVALIDATE_USER

      public static final int REMOTE_INVALIDATE_USER
      Principal to member 22: INVALIDATE_USER, with uid (B-7d).
      See Also:

    • REMOTE_NOT_PRINCIPAL

      public static final int REMOTE_NOT_PRINCIPAL
      Principal to member 23: NOT_PRINCIPAL, naming the principal it knows; the connection closes (B-7c).
      See Also:

    • REMOTE_REGISTER

      public static final int REMOTE_REGISTER
      Member to principal 1: REGISTER, the member's first and only permitted event after CHALLENGE, with the members of section 2.4; answered with P_OK true, or P_OK false and P_REASON.
      See Also:

    • REMOTE_REPORT

      public static final int REMOTE_REPORT
      Member to principal 2: REPORT, with P_RTT: the member's measure of the link, in milliseconds (section 3.5). The counts per application of R-19 join it when B-6a's counters and B-7d's directory exist. Nothing replies.
      See Also:

    • REMOTE_SESSIONS

      public static final int REMOTE_SESSIONS
      Member to principal 3: SESSIONS (B-7d).
      See Also:

    • REMOTE_CLAIM

      public static final int REMOTE_CLAIM
      Member to principal 4: CLAIM (B-7d).
      See Also:

    • REMOTE_RELEASE

      public static final int REMOTE_RELEASE
      Member to principal 5: RELEASE (B-7d).
      See Also:

    • REMOTE_LOOKUP

      public static final int REMOTE_LOOKUP
      Member to principal 6: LOOKUP (B-8a).
      See Also:

    • REMOTE_TRANSFER

      public static final int REMOTE_TRANSFER
      A to principal to B 7: TRANSFER (B-8a).
      See Also:

    • REMOTE_TRANSFER_DONE

      public static final int REMOTE_TRANSFER_DONE
      B to principal to A 8: TRANSFER_DONE (B-8a).
      See Also:

    • REMOTE_USER_CHANGED

      public static final int REMOTE_USER_CHANGED
      Member to principal 9: USER_CHANGED (B-7d).
      See Also:

    • REMOTE_LOGIN

      public static final int REMOTE_LOGIN
      Member to principal 10: LOGIN (B-9).
      See Also:

    • REMOTE_PUSH_FIRST

      public static final int REMOTE_PUSH_FIRST
      The first and last of the ids reserved for D-PUSH-CLUSTER, in both directions: 40 to 49.
      See Also:

    • REMOTE_PUSH_LAST

      public static final int REMOTE_PUSH_LAST
      The first and last of the ids reserved for D-PUSH-CLUSTER, in both directions: 40 to 49.
      See Also:

    • P_REQUEST

      public static final String P_REQUEST
      The request id member "r": an int from the per-connection counter, on every request and its reply.
      See Also:

    • P_OK

      public static final String P_OK
      The reply's success member "ok": a boolean.
      See Also:

    • P_REASON

      public static final String P_REASON
      The reply's reason member "reason" on a refusal: one of the REASON_ constants.
      See Also:

    • P_EPOCH

      public static final String P_EPOCH
      The epoch member "epoch" on every event the principal sends: a long.
      See Also:

    • P_PN

      public static final String P_PN
      The CHALLENGE member "pn": the 32 random bytes, a ByteArrayProp.
      See Also:

    • P_WIRE

      public static final String P_WIRE
      The REGISTER member "w": the hub wire version, an int.
      See Also:

    • P_MEMBER

      public static final String P_MEMBER
      The REGISTER member "member": the member ID.
      See Also:

    • P_RUN

      public static final String P_RUN
      The REGISTER member "run": the run UUID generated at process start, to tell a restart from a reconnect.
      See Also:

    • P_BUILD

      public static final String P_BUILD
      The REGISTER member "build": SystemConfig.VERSION_BUILD.
      See Also:

    • P_DEF

      public static final String P_DEF
      The REGISTER member "def": the SHA-256 of the member's definition file as read.
      See Also:

    • P_DB

      public static final String P_DB
      The REGISTER member "db": the HUB.CLUSTER UUID, or empty (section 2.3).
      See Also:

    • P_URL

      public static final String P_URL
      The REGISTER and MEMBERS member "url": a member's public base URL.
      See Also:

    • P_APPS

      public static final String P_APPS
      The REGISTER member "apps": the application IDs the member serves, joined with ,.
      See Also:

    • P_CRED

      public static final String P_CRED
      The REGISTER member "cred": the credential, a ByteArrayProp. Until B-9 the interim cluster key's HMAC over the challenge (HubClusterKey, ruled H-8); from B-9 the member's document and its installation key's signature.
      See Also:

    • P_KEYS

      public static final String P_KEYS
      The REGISTER member "keys": the fingerprint of the member's ACTIVE server keys file key, compared by the principal as P_DEF is (ruled RB-6 (a)); empty when the member has none yet.
      See Also:

    • P_STAGED

      public static final String P_STAGED
      The REGISTER member "staged": the fingerprints of the server keys the member holds STAGED by the rotation protocol of RB-6 (locked, not yet used to encrypt), joined with ,; empty until that protocol exists. Reported, never compared.
      See Also:

    • P_RTT

      public static final String P_RTT
      The REPORT and MEMBERS member "rtt": a link round-trip time in milliseconds, a long; -1 when not measured yet.
      See Also:

    • P_RTT_MEMBER

      public static final String P_RTT_MEMBER
      The MEMBERS member "rttm": the round-trip time the member itself measured and reported, in milliseconds, a long; -1 when not reported yet.
      See Also:

    • P_MEMBERS

      public static final String P_MEMBERS
      The MEMBERS member "members": the container of members, one child container per member named by its member ID, each with P_URL, P_STATE, P_RTT and P_RTT_MEMBER.
      See Also:

    • P_STATE

      public static final String P_STATE
      The MEMBERS member "state": a member's state, admitted.
      See Also:

    • P_WARNINGS

      public static final String P_WARNINGS
      The reply members "warnings": what the principal warns about at admission, joined with , (def for a differing definition, keys for differing server keys); absent when nothing.
      See Also:

    • REASON_WIRE

      public static final String REASON_WIRE
      Refused "wire": the wire version differs from the principal's.
      See Also:

    • REASON_AUTH

      public static final String REASON_AUTH
      Refused "auth": the credential does not verify as the answer to this connection's challenge.
      See Also:

    • REASON_LICENCE

      public static final String REASON_LICENCE
      Refused "licence": the member's document names another entitlement than the principal's (from B-9, ruled LV-13 (a)).
      See Also:

    • REASON_UNKNOWN_MEMBER

      public static final String REASON_UNKNOWN_MEMBER
      Refused "unknown-member": the member ID is not in the principal's [members] (ruled H-6).
      See Also:

    • REASON_BUILD

      public static final String REASON_BUILD
      Refused "build": the build differs from the principal's (ruled R-18 (a)); the member runs standalone and retries.
      See Also:

    • REASON_SERVERS

      public static final String REASON_SERVERS
      Refused "servers": admitting the member would exceed the licence's server count (R-6).
      See Also:

    • REASON_TIMEOUT

      public static final String REASON_TIMEOUT
      Refused "timeout": the principal did not answer within the deadline.
      See Also:

    • REASON_INTERNAL

      public static final String REASON_INTERNAL
      Refused "internal": the principal could not process the request.
      See Also:

  • Constructor Details

    • HubServerProp

      public HubServerProp()
      Creates the channel without a name.

    • HubServerProp

      public HubServerProp(Atom atom)
      Creates the channel with a name.
      Parameters:
      atom - The atom name, normally ATOM.

  • Method Details

    • clone

      public HubServerProp clone()
      Clones the channel: the pending table is not cloned.
      Overrides:
      clone in class PropCnr

    • shouldSerializeToXML

      protected boolean shouldSerializeToXML(int programType)
      The channel is never written to XML.
      Overrides:
      shouldSerializeToXML in class GProp<GProp<?>[]>
      Parameters:
      programType - From PropFactory.getProgramType().
      Returns:
      false.

    • of

      public static HubServerProp of(PropCnr device)
      Finds the channel of a member connection.
      Parameters:
      device - The member's $device container, or null.
      Returns:
      The channel, or null when the container holds none: not a member of the hub.

    • setRole

      public void setRole(HubServerProp.Role role, HubServerProp.IHubEventHandler handler)
      Sets the side this instance is on and the handler of the peer's requests.
      Parameters:
      role - The role.
      handler - The handler, or null for none.

    • getRole

      public HubServerProp.Role getRole()
      Gets the role.
      Returns:
      The role, null until set.

    • setTimerEngine

      public void setTimerEngine(ITimerEngine engine)
      Sets the timer engine the deadlines are registered with.
      Parameters:
      engine - The engine, or null for the system's.

    • setEpoch

      public void setEpoch(long epoch)
      Sets the epoch the principal stamps on every event it sends (B-7c's election sets it).
      Parameters:
      epoch - The epoch.

    • getEpoch

      public long getEpoch()
      Gets the epoch the principal stamps on every event it sends.
      Returns:
      The epoch, 0 before an election.

    • getHighestEpoch

      public long getHighestEpoch()
      Gets the highest epoch a member has seen from the principal.
      Returns:
      The epoch, -1 before the first event.

    • isPrincipalToMember

      public static boolean isPrincipalToMember(int localID)
      Tells whether an event id is one the principal sends.
      Parameters:
      localID - The id.
      Returns:
      true for CHALLENGE and 20 to 23.

    • isMemberToPrincipal

      public static boolean isMemberToPrincipal(int localID)
      Tells whether an event id is one the member sends.
      Parameters:
      localID - The id.
      Returns:
      true for 1 to 10.

    • getPendingCount

      public int getPendingCount()
      Gets the number of requests waiting for the peer, for diagnostics and tests.
      Returns:
      The count.

    • request

      public int request(int localID, String operation, PropCnr params, long deadlineMillis, HubServerProp.IReplyListener listener)
      Sends a request to the peer and registers its outcome listener and deadline.
      Parameters:
      localID - The event id.
      operation - The operation, e.g. REGISTER, for the log lines.
      params - The parameters, or null for none but the request id, which is added.
      deadlineMillis - The deadline in milliseconds from now.
      listener - The outcome listener, called once.
      Returns:
      The request id.
      Throws:
      IllegalStateException - If the channel is disposed of.
      NullPointerException - If operation or listener is null.

    • reply

      public boolean reply(int localID, PropCnr request, boolean ok, String reason, PropCnr params)
      Replies to a request of the peer on the same local id, carrying its request id back.
      Parameters:
      localID - The event id of the request.
      request - The request's parameters, whose P_REQUEST is carried back; null or without one, the reply carries none.
      ok - true for success, false for a refusal.
      reason - The reason of a refusal, ignored when ok.
      params - The reply's result members, or null for none: a container is created.
      Returns:
      true when sent, false when the channel is disposed of.

    • send

      public boolean send(int localID, PropCnr params)
      Sends an event to the peer that expects no reply, the principal stamping its epoch on it.
      Parameters:
      localID - The event id.
      params - The parameters, or null for none: a container is created.
      Returns:
      true when sent, false when the channel is disposed of.

    • onRemoteEvent

      public void onRemoteEvent(RemoteEvent event)
      Dispatches an event of the peer: a reply on an id this side sends resolves its pending request; anything else is a request for the handler.
      Specified by:
      onRemoteEvent in interface IGProp<GProp<?>[]>
      Overrides:
      onRemoteEvent in class GProp<GProp<?>[]>
      Parameters:
      event - The remote event.

    • onPropDispose

      protected void onPropDispose()
      Drops every pending request at disposal, logged at INFO.
      Overrides:
      onPropDispose in class PropCnr