themwi-smsc: doc/Arch-design comparison

comparison doc/Arch-design @ 1:c4f8a32af088

doc/Arch-design: continuing

author	Mychaela Falconia <falcon@freecalypso.org>
date	Wed, 20 Dec 2023 09:27:05 +0000
parents	9e364c18e0e8
children	b203ebebe9b3

comparison

equal deleted inserted replaced

-:9e364c18e0e8
+:c4f8a32af088
 possible to avoid looking at users' private message content when it is not
 necessary to do so for technical troubleshooting reasons.  Toward this
 objective, themwi-smsc-dump must make it easy to look at only technically
 necessary information, without throwing unnecessary private info into the
 operator's eyeballs.
+2.3. themwi-smsc-core daemon operation
+The core daemon (long-lived process) of ThemWi-SMSC is named themwi-smsc-core.
+Aside from themwi-smsc-dump read-only tool, themwi-smsc-core will be the only
+software component that accesses pms.bin directly - all other components of
+ThemWi-SMSC will connect to a UNIX domain local socket provided by
+themwi-smsc-core.  In more detail, the core daemon will perform the following
+functions:
+* Read the potentially-active (not marked as historical-only) tail portion of
+PMS on startup, catch all still-active SMs and hold them in RAM-based data
+structures;
+* Listen on a UNIX domain local socket of type SOCK_SEQPACKET, meaning
+connection- and message-oriented;
+* Accept message submission (or entry) commands from other ThemWi-SMSC
+components connecting to this socket;
+* Allow those socket-connecting SMSC components to register themselves as
+performing special roles (GSM network interface, IMSI resolver, uplink and
+downlink SMPP connection handlers), and send notification packets to those
+role-handlers when an active SM needs that type of processing;
+* When these just-described role-handlers respond with success or failure of
+message handling, discharge the SM into historical state (either delivered or
+failed), or in one special case (successful completion of MSISDN-to-IMSI
+lookup) promote the SM from need-IMSI-lookup state into GSM-MT-delivery state.
+The key feature of themwi-smsc-core daemon is that it can stay up and running
+even when all other ThemWi-SMSC daemon processes are shut down.  It won't be
+particularly useful in this state, and won't be able to bring any outstanding
+active SMs any closer toward delivery, but the key point is that dependency
+graph arrows between sw components point in only one direction.
+2.4. Message entry paths
+Every new SM enters the SMSC by way of one of our sw components making a local
+socket connection to themwi-smsc-core and sending it a "submit new message"
+command packet.  The following ThemWi-SMSC sw components will be able to enter
+new SMs in this manner:
+* A special command line utility named themwi-smsc-submit will perform just
+this function and nothing else;
+* GSM network interface daemon themwi-smsc-gsmif will submit SMs received from
+GSM subscribers as MO messages;
+* Upstream SMPP link handler themwi-smsc-uplink will submit SMs received from
+the upstream connection, i.e., from the outside world;
+* Downstream SMPP link handlers will submit SMs received from downstream peers.
+Most of the common processing functions, such routing and validation steps,
+will be performed by themwi-smsc-core.  Once all admission-time checks pass,
+the new SM will be written into PMS, and if the destination is anything other
+than write-into-PMS-only, the new active SM will also be added to the core
+daemon's in-RAM data structures.  Further delivery steps will happen if and when
+the appropriate role-handler connects to themwi-smsc-core and accepts messages
+for processing.
+2.4.1. Routing of Short Messages
+For every incoming SM, themwi-smsc-core will apply routing based on the
+destination address in addr_to_orig member of the submitted struct sm_record.
+Referring to the general principles of section 1.1, this step is very specific
+to the numbering plan (NANP) for which ThemWi-SMSC is designed.  The following
+routing rules will be applied:
+* If the destination number is international (TON=1) and the country code is
+anything other than +1, the destination is set to SME_CLASS_UPSTREAM.
+* If the destination number is NANP, entered in international TON=1 format or
+in one of local-culture formats (10-digit NPANXXXXXX or 11-digit 1NPANXXXXXX,
+TON=0), NANP validation rules are applied and outright-invalid numbers are
+rejected.  The validated NANP number is looked up in themwi-nanp database of
+locally owned phone numbers; if the number is locally owned, the destination
+is either SME_CLASS_LOCAL or SME_CLASS_GSM, depending on how the number is
+assigned, or the message may be rejected if the locally-owned number is of a
+type that cannot receive SMS.  If there is no hit in the database of locally
+owned numbers, another number database gets a lookup, the one for numbers of
+downstream peers - a hit in that database will set the destination to
+SME_CLASS_DOWNSTREAM.  Finally, if the NANP destination number doesn't hit
+anywhere, the destination is SME_CLASS_UPSTREAM.
+* If the destination number is a USA SMS short code of form NXXXX or NXXXXX,
+the destination is SME_CLASS_UPSTREAM.
+* In the case of locally originated SMs only (coming from GSM MO or from
+themwi-smsc-submit command line utility), special 4-digit numbers may be
+defined in the number database of themwi-nanp that are meaningful only
+locally.  If one of those numbers matches, the destination is SME_CLASS_LOCAL
+or SME_CLASS_GSM according to the exact number type.
+* If none of the above conditions match, the message is rejected as unroutable.
+What is the difference between SME_CLASS_LOCAL and SME_CLASS_GSM destinations?
+Answer: SME_CLASS_LOCAL means that writing the SM into PMS constitutes final
+delivery, and nothing more needs to be done.  OTOH, destination of SME_CLASS_GSM
+means that an MSISDN-to-IMSI lookup needs to be performed, followed by GSM MT
+delivery.
+There is one additional routing mode that is available only via
+themwi-smsc-submit, or perhaps future specialized network sw components that
+incorporate the same function: if a locally generated MT message needs to be
+sent to a local GSM MS addressed by IMSI, with no destination phone number
+existing at all, themwi-smsc-submit can instruct themwi-smsc-core to skip the
+routing step, with the destination preset to SME_CLASS_GSM and dest_imsi
+prefilled.
+2.4.2. Permission to send to the uplink
+To be described.
+2.4.3. PID and DCS constraints
+To be described.
+2.4.4. Validity period and expiry time
+To be described.
+3. SMS communication via direct shell access
+To be filled.
+4. Interface to local Osmocom GSM network
+GSUP and separate MSISDN-to-IMSI lookup, to be described.
+5. SMPP connection handlers and outside-world SM exchange
+To be filled.

FreeCalypso > hg > themwi-smsc

comparison doc/Arch-design @ 1:c4f8a32af088