# HG changeset patch # User Mychaela Falconia # Date 1703237361 0 # Node ID b084a95424713e0703a3c64bcd8925b78f605871 # Parent b203ebebe9b3b2e1c81b1103459b685c5ce6d810 doc/Arch-design: planned design of local socket interface diff -r b203ebebe9b3 -r b084a9542471 doc/Arch-design --- a/doc/Arch-design Fri Dec 22 06:38:16 2023 +0000 +++ b/doc/Arch-design Fri Dec 22 09:29:21 2023 +0000 @@ -527,6 +527,145 @@ desirable to be able to detect and suppress them. The details remain to be worked out. +2.5. Local socket interface between SMSC components + +There will be an ad hoc local UNIX domain socket interface between different +components of ThemWi-SMSC. themwi-smsc-core will be the single server for this +local socket i/f, and all other components will connect to it as clients. +Local socket clients will be able to function in two fundamental ways on this +internal interface: + +a) Irrespective of any other function, each local socket client will be able to + execute "pure client" exchanges with themwi-smsc-core, such as + SMSC_REQ_SUBMIT and SMSC_REQ_CANCEL. + +b) Long-lived SMSC components that perform certain specific roles (IMSI lookup + role, GSM MT delivery role, SMPP peer delivery role for each upstream or + downstream peer) will register with themwi-smsc-core as role-handlers for + these specific roles. + +The architectural model of this internal socket i/f is that of request-response +exchanges: each message is either a request or a response, with responses +matched to requests. There are two possible directions for such exchanges: + +* For "pure client" operations and role-handler (RH) registration exchanges, + requests flow from the connected client to themwi-smsc-core; + +* Once an RH has successfully registered and declared itself to be in "service + up" state, themwi-smsc-core will initiate certain requests toward this RH, + as detailed in this section. + +2.5.1. Pure client exchanges + +All exchanges listed in this section consist of a request issued by the client +toward themwi-smsc-core and a response message in the reverse direction. These +commands will be sent by standalone clients like themwi-smsc-submit and also by +role-handler components: the same process that acts as RH for GSM MT delivery +will need to submit SMs coming from GSM MO activity, the same process that acts +as RH for delivery to a given SMPP peer will need to submit SMs coming from +that peer, etc. + +2.5.1.1. SMSC_REQ_SUBMIT + +This command submits or enters or injects a new SM into the SMSC. The client +will send a struct sm_record, and themwi-smsc-core takes over from there. All +processing described in section 2.4 happens upon this command; failure at any +of the steps detailed there will result in an error response to the issuing +client in this exchange. A successful response indicates that the new SM has +been written into PMS and accepted by the SMSC. + +2.5.1.2. SMSC_REQ_CANCEL + +This command requests that an active (not yet delivered or timed out) SM be +canceled. The SM to be canceled can be identified by its absolute index +(0-based absolute position in PMS) or by a tuple of {OA, DA, MR} - the latter +option is needed for implementation of cancel operation via SMS-COMMAND from +GSM MO side. + +2.5.1.3. SMSC_REQ_CHANGE_SRR + +This command is similar to SMSC_REQ_CANCEL (supports the same ways of +identifying the target message), but instead of cancelling the message, it +changes the state of Status Report Requested flag. + +2.5.2. Role handler registration and service state + +These exchanges flow in the same direction as those listed in section 2.5.1 +(from the connected client to themwi-smsc-core), but are issued only by specific +long-lived processes that serve as specific role-handlers. + +2.5.2.1. SMSC_RH_REGISTER + +The long-lived connected client process sending this request is asking to +register for its specific role. The following 3 roles are possible: + +* ROLE_IMSI_LOOKUP +* ROLE_GSM_MT_DELIVERY +* ROLE_PEER_DELIVERY + +If the role type is ROLE_PEER_DELIVERY, there is an additional argument naming +the specific peer; non-empty names identify downstream peers and the special +name "" (null string) identifies the upstream peer. For the other two role +types, there is no such extra argument: there is only one ROLE_IMSI_LOOKUP and +only one ROLE_GSM_MT_DELIVERY. + +Only one client can be registered for each role: one for ROLE_IMSI_LOOKUP, one +for ROLE_GSM_MT_DELIVERY and one for each peer. Registration attempts for an +already-claimed role will result in an error response. + +2.5.2.2. SMSC_RH_SERVICE_STATE + +The service state of a given RH may be up or down. If the RH process is running +but unable to perform its job (e.g., the upstream peer connection is down), its +service state is down; in order for an RH to receive requests for processing +from themwi-smsc-core, it needs to not only register for its role, but also +declare itself to be in "service up" state. The present exchange makes the +declaration of service state being up or down. + +2.5.3. Exchanges with the IMSI resolver RH + +SMSC_MT_FIND_IMSI: request direction is from themwi-smsc-core to the registered +IMSI resolver RH. The request message carries an MSISDN; the matching response +carries the corresponding IMSI or an error. + +2.5.4. Exchanges with the GSM MT delivery RH + +2.5.4.1. SMSC_MT_TRANSFER + +Request direction is from themwi-smsc-core to the registered GSM MT delivery RH. +This exchange transfers a given SM (intended for GSM MT delivery) into temporary +custody of themwi-smsc-gsmif process, which is the RH for this role. +themwi-smsc-gsmif retains custody of this SM, and themwi-smsc-core regards this +SM as being in the custody of themwi-smsc-gsmif, until one of the following two +outcomes: + +a) The SM is discharged: delivered, canceled or times out as determined by + themwi-smsc-gsmif, with an attendant SMSC_MT_DISCHARGE exchange; + +b) The service goes down (socket client disconnects or declares itself down via + SMSC_RH_SERVICE_STATE). In this case themwi-smsc-core retakes custody of + all still-active SMs that were previously handed over to themwi-smsc-gsmif + via SMSC_MT_TRANSFER. + +2.5.4.2. SMSC_MT_CANCEL + +Request direction is from themwi-smsc-core to the registered GSM MT delivery RH, +which is themwi-smsc-gsmif. themwi-smsc-core issues this request toward +themwi-smsc-gsmif whenever it receives SMSC_REQ_CANCEL for an SM that has been +handed over to themwi-smsc-gsmif via SMSC_MT_TRANSFER. + +2.5.4.3. SMSC_MT_DISCHARGE + +themwi-smsc-gsmif sends this request to themwi-smsc-core to indicate the +discharge (successful delivery, cancellation or validity period expiry) of an +SM that has previously been transferred via SMSC_MT_TRANSFER. + +2.5.5. Exchanges with peer delivery role handlers + +SMSC_DELIVER_TO_PEER: request direction is from themwi-smsc-core to the +registered RH for this peer. The request carries an SM (struct sm_record); +the response carries success or failure. + 3. SMS communication via direct shell access To be filled.