Interface IPushSettings

All Known Implementing Classes:
PushNotificationsProps
public interface IPushSettings
Configuration contract for the push notification service.

This interface defines every configurable setting the push subsystem exposes, as a set of getXxx() accessors together with the string property keys and the MIN/DEFAULT/MAX bounds each accessor enforces. It is implemented by com.iizix.prop.push.PushNotificationsProps, a PropCnr whose property container is defined in com/iizix/schema/base-properties.xml so that its values stream over standard IIZI transports (Send/ReadTransaction over WebSockets). When such a container is communicating, a modification to any one property is transferred automatically to the other connected parties as a delta — only the change is sent, not the whole container. This is how a push-setting change on one server propagates across the interconnected star of iiziServers.

Design contract for implementers. Every accessor MUST clamp the stored value into its documented range using the pattern

    return Math.min(XXX_MAX, Math.max(XXX_MIN, getInt(KEY, XXX_DEFAULT)));
so that a value edited out of range (whether by an administrator, a transport error, or a hand-edited file) can never take the subsystem outside its safe envelope. The bounds are part of the contract, not advice: an accessor that returned an unclamped value would be a defect. The ServerAdmin application presents these settings as editable within the documented ranges, and takes the range documentation for each accessor directly from the JavaDoc on that accessor here.

Keys and bounds. Each setting declares four constants: the string key used in the property container (XXX), and the XXX_MIN, XXX_DEFAULT and XXX_MAX bounds. Keys are the wire identity of the property and MUST NOT change once shipped — a renamed key is an incompatible change to any persisted or in-flight container.

Enum settings. An enum-valued setting is stored as an int, the constant's ordinal(), using setInt(KEY, value.ordinal()). It is read back with a bounds guard so a corrupt or out-of-range index can never throw on a configuration read:

    int index = getInt(KEY, SomeEnum.DEFAULT.ordinal());
    SomeEnum[] values = SomeEnum.values();
    if (index < 0 || index >= values.length)
      return SomeEnum.DEFAULT;   // out of range -> default, never throw
    return values[index];
Because the stored value is an ordinal, the order of an enum's constants is part of the persisted and wire contract: new constants MUST be appended at the end, never inserted or reordered, or an existing stored value will silently change meaning. Each such enum carries a persistence note to that effect.

Author:
IIZI

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    DEFAULT_DELIVERY_MODE
    Property key for the server-default DeliveryMode, stored as its ordinal().
    static final String
    DEFAULT_RESIDENCY_POLICY
    Property key for the server-default ResidencyPolicy, stored as its ordinal().
    static final String
    DEFAULT_TTL
    Property key for the default notification time-to-live, in milliseconds.
    static final String
    MAX_PARALLEL
    Property key for the maximum number of concurrently in-flight push sends.
    static final int
    PARALLEL_DEFAULT
    Default value for getMaxParallelPush() when unset: 1000.
    static final int
    PARALLEL_MAX
    Maximum permitted value for getMaxParallelPush(): 100000.
    static final int
    PARALLEL_MIN
    Minimum permitted value for getMaxParallelPush(): 100.
    static final String
    PUSH_ROOF
    Property key for this server's outbound push throughput roof, in sends per second.
    static final int
    PUSH_ROOF_DEFAULT
    Default push throughput roof when unset: 500 sends/second.
    static final int
    PUSH_ROOF_MAX
    Maximum permitted push throughput roof: 50000 sends/second.
    static final int
    PUSH_ROOF_MIN
    Minimum permitted push throughput roof: 10 sends/second.
    static final String
    SPOOL_DIRECTORY
    Property key for the spool directory path.
    static final long
    TTL_DEFAULT
    Default TTL when unset: 2073600000L ms (24 days, the shipped designer default).
    static final long
    TTL_MAX
    Maximum permitted default TTL: 2419200000L ms (28 days, the RFC 8030 maximum).
    static final long
    TTL_MIN
    Minimum permitted default TTL: 60000L ms (one minute).

  • Method Summary

    Modifier and Type
    Method
    Description
    DeliveryMode
    getDefaultDeliveryMode()
    Gets the server-default delivery mode applied to a send that does not name its own.
    ResidencyPolicy
    getDefaultResidencyPolicy()
    Gets the server-default residency policy applied to a send that does not name its own.
    long
    getDefaultTTL()
    Gets the default time-to-live applied to a notification that does not carry its own TTL, in milliseconds.
    int
    getMaxParallelPush()
    Gets the hard ceiling on the number of push notifications that may be "floating through the channels" at any single moment.
    int
    getPushRoof()
    Gets this server's outbound push throughput roof, in sends per second.
    String
    getSpoolDirectory()
    Gets the directory in which the write-ahead spool holds notifications that could not be delivered immediately — because no recipient was reachable, or because a target region's server was down.

  • Field Details

  • Method Details

    • getMaxParallelPush

      int getMaxParallelPush()
      Gets the hard ceiling on the number of push notifications that may be "floating through the channels" at any single moment.

      This is enforced by the engine as an admission gate: a send acquires one permit before it is dispatched to a transport and releases it on completion (delivered, failed, or spooled). When all permits are held, further sends queue rather than launch, so the outbound concurrency never exceeds this value regardless of how many sends are requested. It bounds the virtual-thread executor, which is otherwise unbounded by construction.

      The value is clamped into the range [100, 100000]; the default is 1000. A larger value increases throughput at the cost of memory and downstream (FCM/VAPID) rate-limit pressure; a smaller value is gentler on the network but slows bulk delivery.

      Returns:
      The maximum number of concurrent in-flight push sends, in [100, 100000].

    • getDefaultTTL

      long getDefaultTTL()
      Gets the default time-to-live applied to a notification that does not carry its own TTL, in milliseconds.

      The stored and configured unit is milliseconds throughout the IIZI push classes and the designer; the conversion to the seconds required by the RFC 8030 TTL header (or the FCM equivalent) happens only at the transport boundary, nowhere else. A spooled message checks its remaining TTL before replay so an expired message is dropped rather than resent.

      The value is clamped into [60000L, 2419200000L] ms; the default is 2073600000L ms.

      Returns:
      The default notification TTL in milliseconds, in [60000L, 2419200000L].

    • getPushRoof

      int getPushRoof()
      Gets this server's outbound push throughput roof, in sends per second.

      This is the push capacity roof, deliberately separate from the session capacity roof that governs how many live WebSocket sessions a server may hold. A server full of sessions may still have push headroom, and a server used heavily for push may hold few sessions; the two resources are independent and are routed against independently. The router will not dispatch a slice to a server over this roof; it spreads to a sibling in the same region or spools briefly, so delivery latency stays bounded. A DeliveryUrgency.FAST send may be permitted to burst past this soft roof; a DeliveryUrgency.DONT_CARE send respects it strictly.

      The value is clamped into [10, 50000]; the default is 500.

      Returns:
      The outbound push throughput roof in sends/second, in [10, 50000].

    • getDefaultResidencyPolicy

      ResidencyPolicy getDefaultResidencyPolicy()
      Gets the server-default residency policy applied to a send that does not name its own.

      Governs only the handling of subscriptions whose region cannot be resolved; a subscription with a known region is always routed to its home region regardless of this setting (that is the residency invariant, not a policy).

      Stored as an ordinal per the enum-storage idiom in the type documentation; an out-of-range stored index resolves to ResidencyPolicy.DEFAULT (ResidencyPolicy.MUST) rather than throwing, because failing closed on unresolved residency is never a compliance violation whereas failing open can be.

      Returns:
      The default ResidencyPolicy; never null.

    • getDefaultDeliveryMode

      DeliveryMode getDefaultDeliveryMode()
      Gets the server-default delivery mode applied to a send that does not name its own.

      Stored as an ordinal per the enum-storage idiom in the type documentation; an out-of-range stored index resolves to DeliveryMode.DEFAULT (DeliveryMode.PREFER_IN_SESSION), which uses the fastest and cheapest tier whenever the recipient is live and falls back to a device push otherwise.

      Returns:
      The default DeliveryMode; never null.

    • getSpoolDirectory

      String getSpoolDirectory()
      Gets the directory in which the write-ahead spool holds notifications that could not be delivered immediately — because no recipient was reachable, or because a target region's server was down.

      The spool provides two durability guarantees with one mechanism: a sudden server shutdown does not lose an accepted-but-unsent notification, and a transient regional outage does not drop notifications destined for that region. On restart, or when a region returns, the spool replays whatever remains, dropping any entry whose TTL has since elapsed. An empty configured value selects a server-determined default location.

      Returns:
      The spool directory path, or an empty string to use the server default; never null.