themwi-smsc: doc/Arch-design annotate

annotate doc/Arch-design @ 6:acc5b1c3e07d default tip

doc/Arch-design: document Osmocom network interface plan

author	Mychaela Falconia <falcon@freecalypso.org>
date	Sat, 23 Dec 2023 08:07:33 +0000
parents	8a7eb3d4570a
children

rev	line source
0 9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	1 Themyscira Wireless SMSC implementation
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	2 Architectural design specification
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	3
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	4 1. Purpose and scope of the software
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	5
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	6 The purpose of the present software project is to facilitate store-and-forward
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	7 SMS exchange among the following parties:
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	8
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	9 * Locally owned mobile telephone numbers (LOMTNs) that belong to Themyscira
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	10 Wireless, with Short Message Service accessed either via the local GSM network
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	11 (Osmocom-based) or via direct command line access to the SMSC;
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	12
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	13 * The outside world: the total set of all SMS-capable E.164 telephone numbers
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	14 in the world, with whom our users must be able to freely exchange SMS just
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	15 like users of any other cellular phone carrier in USA;
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	16
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	17 * USA-specific 5-digit and 6-digit short codes: these services aren't accessible
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	18 from anywhere in the world, only from USA (each country has its own services
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	19 of this type), but because we are located in USA, we must provide the same
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	20 access to public services as any other cellular phone carrier;
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	21
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	22 * Any downstream parties who enter into an interconnection agreement with ThemWi
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	23 for the purpose of sharing our SMS uplink to the outside world.
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	24
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	25 1.1. NANP specifics
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	26
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	27 The design of our SMSC makes the following assumptions that are specific to
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	28 North American Numbering Plan:
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	29
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	30 * All LOMTNs and all downstream peer MTNs are expected to be NANP numbers;
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	31 any/all SMS source or destination numbers in country codes other than +1 are
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	32 treated as belonging in the Outside World, accessible only via the SMPP
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	33 "uplink" connection to our upstream SMS connectivity provider.
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	34
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	35 * The set of SMS destination numbers that can be sent to the upstream includes
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	36 not only non-NANP and not-locally-known NANP E.164 numbers, but also any/all
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	37 SMS short codes in USA-specific NXXXX or NXXXXX format.
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	38
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	39 * In the case of Mobile-Originated SMS from the local GSM network, if the
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	40 user-entered destination number is not explicitly international (TON=1) and
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	41 does not fit the format of a USA SMS short code, other USA-customary dialing
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	42 formats are supported, as in 10-digit NPANXXXXXX or 11-digit 1NPANXXXXXX
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	43 without '+' prefix.
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	44
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	45 themwi-nanp software package is a strict dependency for themwi-smsc: themwi-nanp
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	46 utilities must be used to manage the database of locally owned NANP numbers,
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	47 and the present software uses themwi-nanp libraries to access that database.
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	48
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	49 1.2. Hierarchical arrangement of upstream and downstream peers
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	50
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	51 The telecom landscape in USA is such that anyone can obtain 10-digit telephone
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	52 numbers (TNs) very easily and very cheaply, but making them SMS-capable (able
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	53 to function as Mobile Telephone Numbers or MTNs) is much more difficult.
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	54 Suitably equipped providers such as Bandwidth.com are generally unwilling to
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	55 provide service directly to small customers, and we (Themyscira Wireless team)
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	56 were able to find only one company (Sopranica Telecom) who buys P2P SMS
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	57 interconnection service from Bandwidth and was willing to resell to us.
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	58
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	59 Suppose that many different ultra-small parties wish to set up their own indie
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	60 GSM networks in different parts of USA. Each of these tiny fiefdoms can serve
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	61 as its own administration and get its own TNs from a provider such as BulkVS.
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	62 How would all of these tiny fiefdoms then add SMS capability? The feedback we
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	63 got from Sopranica is that asking them to set up a sub-account on their
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	64 Bandwidth service for each microfiefdom would be too much work - hence San Diego
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	65 2G Association (the primary instance of Themyscira Wireless) will need to serve
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	66 as a third-level reseller, getting Bandwidth SMS interconnection service from
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	67 Sopranica and then further subletting it to other microfiefdoms.
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	68
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	69 Vertical hierarchy support in ThemWi-SMSC is designed to support the just-
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	70 described use case. Each SMSC instance has a set of locally owned mobile TNs
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	71 (LOMTNs, owned by the local fiefdom operating this SMSC instance), a single
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	72 upstream SMPP link pointing up the hierarchy tree (toward the Outside World)
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	73 and any number of downstream SMPP links to downstream peers. The total set of
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	74 phone numbers known to each SMSC instance is its own local set (themwi-nanp
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	75 database of locally owned TNs) plus the set of numbers assigned to downstream
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	76 peers - all other E.164 numbers everywhere in the world (plus all non-E.164 USA
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	77 SMS short codes) belong in the Outside World and are sent to the "uplink"
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	78 connection. Messages are then routed as follows:
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	79
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	80 * Any SM originating from a local GSM subscriber can go to another GSM
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	81 subscriber, to a known downstream peer or to the Outside World.
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	82
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	83 * Any SM that are injected directly into the SMSC from local shell access are
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	84 treated the same way as Mobile-Originated SMS from local GSM users - hence
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	85 this mechanism can be used to send SMS to the local GSM network or to the
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	86 Outside World.
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	87
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	88 * Any SM coming from the uplink connection can be addressing a local GSM
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	89 subscriber or a downstream peer - but either way it must be a number known
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	90 to this SMSC, otherwise something is badly misconfigured somewhere.
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	91
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	92 * Any SM coming from a downlink connection can go to a local GSM subscriber, to
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	93 a different downstream peer or to the Outside World.
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	94
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	95 1.2.1. Direction of SMPP connections
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	96
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	97 Despite the name "Short Message Peer to Peer", SMPP is an asymmetric client-
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	98 server protocol, not symmetric peer-to-peer. Our primary, above-all-else
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	99 requirement when it comes to SMPP is to connect to the "big daddy" SMSC of
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	100 Bandwidth.com, the one that allows us to receive SMS from and send SMS to
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	101 anywhere in the Outside World. BW requires that we connect to their SMSC server
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	102 in the role of an SMPP client and bind as a bidirectional transceiver - both
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	103 message directions then flow over this single long-lived TCP connection from our
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	104 client to their server.
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	105
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	106 This externally imposed requirement dictates the entire architectural design of
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	107 ThemWi-SMSC with respect to SMPP. Each instance of ThemWi-SMSC can have a
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	108 single upstream peer to whom we connect in the role of an SMPP client, and it
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	109 can optionally act as an SMPP server accepting TCP connections from downstream
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	110 peers. The master instance of ThemWi-SMSC at smsc.sandiego2g.org will point
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	111 its "upstream" link at Bandwidth.com SMPP server, using credentials given to us
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	112 by Sopranica, whereas other small fiefdoms who wish to join our service resale
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	113 tree will point the "upstream" link of their ThemWi-SMSC instances to
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	114 smsc.sandiego2g.org, and we (SD2G) will assign them authentication credentials
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	115 and manage their downstream number pools.
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	116
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	117 1.3. Possible use outside of originally intended North American use case
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	118
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	119 If your situation and/or interests do not match the very specific use case for
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	120 which the present software is designed (if you are located outside of North
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	121 America, and/or you have no interest in attaining SMS interconnection with the
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	122 national mobile telephony environment of whichever country you call home), you
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	123 can still play with the present implementation of GSM-oriented SMSC: the uplink
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	124 connection to the Outside World can be omitted, and if you don't have real TNs
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	125 (telephone numbers) in North American Numbering Plan (either because you are
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	126 outside of North America or because you are in NA but not interested in official
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	127 phone network interconnection), you can operate ThemWi-SMSC (plus the attached
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	128 Osmocom GSM network) with fake NANP numbers instead.
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	129
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	130 To be clear, this support for modes of usage outside of the primary design goals
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	131 of ThemWi-SMSC is intended only to facilitate "play" and evaluation (getting a
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	132 feel for what may be the first SMSC implementation connecting to Osmocom CNI
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	133 via GSUP), not for serious long-term usage. If your actual desired use case is
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	134 an isolated GSM network with a totally ad hoc or "free" numbering plan (the
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	135 default which one gets with a "vanilla" installation of Osmocom CNI), or a GSM
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	136 network that is interconnected with the national mobile telephony environment
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	137 of some country other than USA, you need a different SMSC design that is
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	138 tailored for your numbering plan (free-form or non-USA national) that will be
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	139 different from NANP, and for local telecom environment quirks that will almost
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	140 certainly be different from those in USA.
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	141
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	142 If you like the general idea and overall design of ThemWi-SMSC, but require an
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	143 adaptation to a different numbering plan or a different telecom environment
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	144 (isolated or a national interconnect in some other country), you should be able
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	145 to take the present code base and modify just the numbering plan aspects,
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	146 producing a derivative-work SMSC for your different needs.
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	147
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	148 2. ThemWi-SMSC software architecture
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	149
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	150 2.1. Modularity of components
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	151
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	152 A complete deployment of ThemWi-SMSC, as in our own use case at Themyscira
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	153 Wireless, includes a local GSM network (Osmocom-based) and a connection to the
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	154 hierarchical SMPP tree that eventually leads to the Outside World SMS
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	155 connectivity provider at the top. However, our software implementation will be
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	156 modular, divided into separate software components for:
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	157
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	158 * The internal core of the SMSC (one daemon process and some command line
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	159 utilities);
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	160
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	161 * A pair of daemon processes devoted to the task of connecting the SMSC to the
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	162 local Osmocom-based GSM network, to be omitted if you don't have one;
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	163
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	164 * A dedicated daemon process serving the SMPP link to the upstream peer, to be
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	165 omitted if you have no upstream link;
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	166
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	167 * Another dedicated sw component serving downstream peer SMPP connections, one
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	168 process instance per downstream peer, or none if you have no such peers.
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	169
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	170 This modularity allows the software to be used and (hopefully) appreciated
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	171 outside of its primary intended use case. At one extreme, someone could have
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	172 an isolated Osmocom GSM network, modify it slightly to use MSISDNs that look
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	173 like (fake) NANP numbers, hook up ThemWi-SMSC and use this SMSC as a replacement
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	174 for the Osmocom-default one, paving the way for factoring the SMSC function out
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	175 of OsmoMSC. At the other extreme, if someone is located in USA and wishes to
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	176 interconnect to the world of SMS through the chain of 3 resellers (Bandwidth
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	177 followed by Sopranica followed by San Diego 2G Association), they can run an
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	178 instance of ThemWi-SMSC without any GSM network at all. (You will still need
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	179 Osmocom libraries, but no Osmocom processes and no hardware.) In such a
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	180 deployment, all incoming SMS to your number(s) will be written into the
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	181 persistent store which you can read, and you can send outgoing SMS with a
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	182 command line utility.
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	183
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	184 2.2. Persistent message store
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	185
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	186 Every SM that passes through ThemWi-SMSC gets written into an append-only
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	187 persistent message store (PMS). Because this store is append-only, no messages
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	188 are ever deleted - however, each message in PMS can be in one of two states:
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	189 active or historical. An active SM is one for which the SMSC still needs to
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	190 make delivery attempts, either attempts at GSM MT delivery or attempts at
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	191 delivery to the appropriate upstream or downstream SMPP peer. A historical SM
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	192 is one for which no further action will be taken by any component of our SMSC.
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	193 An SM can enter "historical" state in several ways:
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	194
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	195 * For some LOMTNs the act of writing incoming messages into PMS constitutes
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	196 final delivery in itself, and no other delivery actions are needed. In this
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	197 case a newly entered SM is directly written into PMS in the "historical"
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	198 state, without ever going through "active".
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	199
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	200 * For messages that need to be delivered to a GSM MS or to an SMPP peer, once
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	201 that delivery has been made successfully, the message transitions from active
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	202 to historical.
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	203
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	204 * In the case of failed deliveries (permament error, or expiration time reached
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	205 after repeated temporary failures), the failed message also transitions from
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	206 active to historical.
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	207
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	208 The persistent message store is a simple binary file (/var/sms/pms.bin)
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	209 consisting of directly abutted 'struct sm_record' records. Each message record
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	210 is exactly 256 bytes (see struct definition - we were able to fit everything we
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	211 needed under the 256 byte mark, and then padded the struct to perfect round
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	212 size), and this perfect power-of-2 record size makes it very easy to perform
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	213 operations such as binary search via mmap or stripping initial megabytes of
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	214 historical records - see subsequent sections for more detailed description.
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	215
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	216 PMS is append-only as already stated, but already-written records do not become
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	217 fully immutable until they become historical. For as long as a given SM is in
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	218 the active state, themwi-smsc-core daemon can and will update that record in
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	219 pms.bin:
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	220
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	221 * For messages addressed to local GSM subscribers, dest_imsi will be filled
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	222 when the MSISDN-to-IMSI lookup operation on the destination number succeeds;
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	223
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	224 * Upon discharge (successful delivery, permanent error or validity period
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	225 expiration after temporary failures), themwi-smsc-core will transition the
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	226 sm_record into historical state by filling disposition and time_disch struct
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	227 members;
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	228
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	229 * Additional info may be written into dest_extra_info upon discharge, depending
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	230 on the destination type and thus the mode of final delivery.
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	231
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	232 Once an sm_record transitions into historical state, it is then immutable for
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	233 archival purposes; archives of historical messages can be kept for years or even
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	234 decades, depending on local administration policy.
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	235
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	236 2.2.1. Historical megabyte count
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	237
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	238 Given the simple binary structure of the main PMS file, each megabyte (2**20
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	239 bytes) holds exactly 4096 messages. It is envisioned that as a busy SMSC runs
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	240 for a long time, a significant number of historical messages will accumulate,
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	241 and the content of PMS may become many megabytes of historical messages followed
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	242 by some active SMs at the end. When themwi-smsc-core daemon restarts, it has
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	243 to read the entire PMS in order to collect all still-active SMs. Having to
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	244 read through many megabytes of historical SMs to get to active ones at the end
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	245 becomes unacceptable at large archive sizes, hence a mechanism is needed for
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	246 marking where the historical-only portion ends and the possibly-active portion
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	247 begins.
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	248
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	249 There will be an auxiliary file named historical-mb, containing a single ASCII
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	250 line giving the number of historical megabytes in pms.bin. If this file reads
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	251 1, the first 4096 SM records are historical, if the auxiliary file reads 2, the
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	252 first 8192 SM records are historical, and so forth. This auxiliary file will be
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	253 used as follows:
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	254
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	255 * Upon startup, themwi-smsc-core will read this historical-mb file and skip that
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	256 many initial megabytes of pms.bin;
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	257
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	258 * At run time, themwi-smsc-core will track the index of the oldest still-active
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	259 SM in PMS. Whenever this index crosses a megabyte boundary, historical-mb
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	260 will be updated.
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	261
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	262 2.2.2. Offline storage
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	263
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	264 Even with the historical-mb mechanism of the previous section, the fact remains
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	265 that disk space on live servers is not infinite. If the archive of historical
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	266 messages grows so big that it needs to be removed from the SMSC server to free
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	267 up disk space, one can carry out the following procedure:
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	268
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	269 * Temporarily stop themwi-smsc-core daemon at the level of runit or systemctl
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	270 or whatever you are using - this operation will bring down the entire SMSC,
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	271 so do it during a scheduled maintenance window;
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	272
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	273 * Use dd to split pms.bin into historical and active portions:
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	274
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	275 dd if=pms.bin of=pms-hist.bin bs=1048576 count=N
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	276 dd if=pms.bin of=pms-new.bin bs=1048576 skip=N
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	277
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	278 * Move pms-hist.bin to offline storage;
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	279
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	280 * Replace the long file with the shortened one:
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	281
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	282 mv pms-new.bin pms.bin
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	283 echo 0 > historical-mb
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	284
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	285 * Re-enable themwi-smsc-core and restart all other SMSC daemons.
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	286
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	287 2.2.3. themwi-smsc-dump reading tool
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	288
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	289 The program named themwi-smsc-dump will be a standalone command line utility
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	290 (fully static in its operation, not talking to any daemons or services) for
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	291 reading and parsing (decoding) pms.bin. It will open pms.bin with O_RDONLY, do
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	292 a read-only mmap on it, and then access this PMS as a memory-mapped file.
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	293 Several different modes of operation will be provided:
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	294
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	295 * It will be possible to dump and decode the entire PMS, as needed during early
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	296 debugging.
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	297
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	298 * It will be possible to specify a starting date/time at which the dump should
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	299 begin. As records are added in strict forward chronological order, it is
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	300 possible to find a record nearest (by time_entry timestamp) to a given time
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	301 point by binary search, very efficient on a memory-mapped file.
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	302
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	303 * Once the dump has a starting point (beginning of the file or a time point
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	304 found by binary search), the tool can be told to dump till the end, display
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	305 some count of messages, or run until a certain ending date/time is crossed.
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	306
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	307 * The tool can dump all message records in the selected range, or only those
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	308 matching specific filters such as a particular source or destination type, or
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	309 a specific phone number.
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	310
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	311 The complexity described above is needed for the following reasons:
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	312
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	313 * One radical idea is to grant limited access (by way of a very strict wrapper)
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	314 to themwi-smsc-dump to unprivileged users of the network served by the SMSC,
5 8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	315 i.e., to end users. Please see section 3.2 for the details.
0 9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	316
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	317 * By the nature of her job, the administrator of the SMSC (and of the community
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	318 GSM network to which this SMSC belongs) necessarily has access to every
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	319 message that passes through the system, all metadata and actual content.
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	320 While this access is technically necessary, an administrator who is worthy of
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	321 her trusted position must not abuse this trust, and must do everything
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	322 possible to avoid looking at users' private message content when it is not
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	323 necessary to do so for technical troubleshooting reasons. Toward this
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	324 objective, themwi-smsc-dump must make it easy to look at only technically
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	325 necessary information, without throwing unnecessary private info into the
9e364c18e0e8 beginning of architectural design spec Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	326 operator's eyeballs.
1 c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	327
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	328 2.3. themwi-smsc-core daemon operation
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	329
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	330 The core daemon (long-lived process) of ThemWi-SMSC is named themwi-smsc-core.
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	331 Aside from themwi-smsc-dump read-only tool, themwi-smsc-core will be the only
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	332 software component that accesses pms.bin directly - all other components of
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	333 ThemWi-SMSC will connect to a UNIX domain local socket provided by
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	334 themwi-smsc-core. In more detail, the core daemon will perform the following
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	335 functions:
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	336
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	337 * Read the potentially-active (not marked as historical-only) tail portion of
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	338 PMS on startup, catch all still-active SMs and hold them in RAM-based data
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	339 structures;
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	340
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	341 * Listen on a UNIX domain local socket of type SOCK_SEQPACKET, meaning
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	342 connection- and message-oriented;
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	343
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	344 * Accept message submission (or entry) commands from other ThemWi-SMSC
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	345 components connecting to this socket;
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	346
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	347 * Allow those socket-connecting SMSC components to register themselves as
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	348 performing special roles (GSM network interface, IMSI resolver, uplink and
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	349 downlink SMPP connection handlers), and send notification packets to those
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	350 role-handlers when an active SM needs that type of processing;
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	351
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	352 * When these just-described role-handlers respond with success or failure of
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	353 message handling, discharge the SM into historical state (either delivered or
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	354 failed), or in one special case (successful completion of MSISDN-to-IMSI
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	355 lookup) promote the SM from need-IMSI-lookup state into GSM-MT-delivery state.
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	356
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	357 The key feature of themwi-smsc-core daemon is that it can stay up and running
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	358 even when all other ThemWi-SMSC daemon processes are shut down. It won't be
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	359 particularly useful in this state, and won't be able to bring any outstanding
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	360 active SMs any closer toward delivery, but the key point is that dependency
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	361 graph arrows between sw components point in only one direction.
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	362
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	363 2.4. Message entry paths
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	364
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	365 Every new SM enters the SMSC by way of one of our sw components making a local
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	366 socket connection to themwi-smsc-core and sending it a "submit new message"
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	367 command packet. The following ThemWi-SMSC sw components will be able to enter
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	368 new SMs in this manner:
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	369
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	370 * A special command line utility named themwi-smsc-submit will perform just
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	371 this function and nothing else;
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	372
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	373 * GSM network interface daemon themwi-smsc-gsmif will submit SMs received from
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	374 GSM subscribers as MO messages;
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	375
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	376 * Upstream SMPP link handler themwi-smsc-uplink will submit SMs received from
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	377 the upstream connection, i.e., from the outside world;
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	378
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	379 * Downstream SMPP link handlers will submit SMs received from downstream peers.
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	380
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	381 Most of the common processing functions, such routing and validation steps,
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	382 will be performed by themwi-smsc-core. Once all admission-time checks pass,
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	383 the new SM will be written into PMS, and if the destination is anything other
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	384 than write-into-PMS-only, the new active SM will also be added to the core
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	385 daemon's in-RAM data structures. Further delivery steps will happen if and when
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	386 the appropriate role-handler connects to themwi-smsc-core and accepts messages
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	387 for processing.
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	388
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	389 2.4.1. Routing of Short Messages
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	390
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	391 For every incoming SM, themwi-smsc-core will apply routing based on the
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	392 destination address in addr_to_orig member of the submitted struct sm_record.
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	393 Referring to the general principles of section 1.1, this step is very specific
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	394 to the numbering plan (NANP) for which ThemWi-SMSC is designed. The following
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	395 routing rules will be applied:
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	396
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	397 * If the destination number is international (TON=1) and the country code is
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	398 anything other than +1, the destination is set to SME_CLASS_UPSTREAM.
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	399
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	400 * If the destination number is NANP, entered in international TON=1 format or
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	401 in one of local-culture formats (10-digit NPANXXXXXX or 11-digit 1NPANXXXXXX,
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	402 TON=0), NANP validation rules are applied and outright-invalid numbers are
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	403 rejected. The validated NANP number is looked up in themwi-nanp database of
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	404 locally owned phone numbers; if the number is locally owned, the destination
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	405 is either SME_CLASS_LOCAL or SME_CLASS_GSM, depending on how the number is
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	406 assigned, or the message may be rejected if the locally-owned number is of a
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	407 type that cannot receive SMS. If there is no hit in the database of locally
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	408 owned numbers, another number database gets a lookup, the one for numbers of
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	409 downstream peers - a hit in that database will set the destination to
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	410 SME_CLASS_DOWNSTREAM. Finally, if the NANP destination number doesn't hit
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	411 anywhere, the destination is SME_CLASS_UPSTREAM.
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	412
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	413 * If the destination number is a USA SMS short code of form NXXXX or NXXXXX,
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	414 the destination is SME_CLASS_UPSTREAM.
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	415
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	416 * In the case of locally originated SMs only (coming from GSM MO or from
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	417 themwi-smsc-submit command line utility), special 4-digit numbers may be
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	418 defined in the number database of themwi-nanp that are meaningful only
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	419 locally. If one of those numbers matches, the destination is SME_CLASS_LOCAL
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	420 or SME_CLASS_GSM according to the exact number type.
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	421
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	422 * If none of the above conditions match, the message is rejected as unroutable.
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	423
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	424 What is the difference between SME_CLASS_LOCAL and SME_CLASS_GSM destinations?
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	425 Answer: SME_CLASS_LOCAL means that writing the SM into PMS constitutes final
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	426 delivery, and nothing more needs to be done. OTOH, destination of SME_CLASS_GSM
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	427 means that an MSISDN-to-IMSI lookup needs to be performed, followed by GSM MT
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	428 delivery.
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	429
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	430 There is one additional routing mode that is available only via
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	431 themwi-smsc-submit, or perhaps future specialized network sw components that
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	432 incorporate the same function: if a locally generated MT message needs to be
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	433 sent to a local GSM MS addressed by IMSI, with no destination phone number
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	434 existing at all, themwi-smsc-submit can instruct themwi-smsc-core to skip the
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	435 routing step, with the destination preset to SME_CLASS_GSM and dest_imsi
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	436 prefilled.
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	437
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	438 2.4.2. Permission to send to the uplink
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	439
2 b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	440 Not every local phone number served by ThemWi-SMSC is allowed to send SMS to
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	441 our upstream interconnection point with Bandwidth.com SMPP server. As explained
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	442 in section 1.2, our access to Bandwidth P2P SMS interconnection service is
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	443 through a reseller (Sopranica Telecom), and our arrangement is such that we
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	444 have to pay for each individual phone number for which P2P SMS interconnection
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	445 service is provided. The economics of the situation are such that the total
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	446 set of NANP numbers (good for calls) we rent from BulkVS is greater than the
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	447 subset for which we enable outside SMS interconnection service through
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	448 Bandwidth+Sopranica. Therefore, we have a flag in our themwi-nanp database of
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	449 locally owned numbers (NUMBER_FLAG_SMSPROV) which we set only on certain
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	450 numbers, those that are provisioned for outside SMS interconnection and which
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	451 are therefore allowed to send SMS to the outside world. All other locally
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	452 owned phone numbers (those without this flag) can only exchange SMS within our
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	453 fiefdom, including our downstream peers.
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	454
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	455 For each newly submitted SM, themwi-smsc-core will make a routing determination
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	456 per the previous section, and if the destination is SME_CLASS_UPSTREAM, the
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	457 identity of the sender will be checked. The sender will need to be a locally
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	458 owned number with upstream SMS permission bit set, otherwise the message is
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	459 rejected.
1 c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	460
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	461 2.4.3. PID and DCS constraints
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	462
2 b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	463 Special codes in PID and DCS octets can invoke many special functions that go
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	464 far beyond ordinary human-to-human SMS: setting and clearing voice mail waiting
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	465 indication flags, SIM OTA communication, silent SMS etc. While there are
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	466 legitimate use cases for all of these special services, and an SMSC
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	467 implementation should provide a way for duly authorized network components to
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	468 send such special SMS to local GSM subscribers, it would be irresponsible for
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	469 a public MNO to allow any Alice to send such SMS-encoded trojans to any Bob, or
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	470 to accept the same from Big Bad outside world and forward them directly to
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	471 unsuspecting local users.
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	472
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	473 The solution adopted for ThemWi-SMSC is that each sw component that accepts SMs
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	474 from untrusted parties will apply filtering rules to both PID and DCS octets.
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	475 In the case of messages originated from local GSM MS, themwi-smsc-gsmif will be
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	476 responsible for preening PID and DCS, whereas in the case of messages coming
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	477 from the outside world, the responsibility falls on themwi-smsc-uplink instead.
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	478
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	479 The specific masks or ACLs of which PID and DCS codes should be accepted will
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	480 be configurable; the recommended default is to:
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	481
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	482 * allow any PID in 000xxxxx range (0x00 through 0x1F), but no others;
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	483
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	484 * allow DCS 0x00 (GSM7 text) and 0x08 (UCS-2 text), but no others.
1 c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	485
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	486 2.4.4. Validity period and expiry time
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	487
2 b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	488 Given the store-and-forward nature of SMS, the amount of work spent trying to
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	489 deliver a message to a "difficult" destination must be bounded. The standard
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	490 SMS architecture of GSM 03.40 provides the notion of a validity period,
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	491 optionally specified by message senders, as the mechanism for limiting the
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	492 lifetime of a message that cannot be delivered right away.
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	493
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	494 Message validity periods and expiry times will be handled as follows in
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	495 ThemWi-SMSC:
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	496
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	497 * At the socket interface from message-submitting components to
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	498 themwi-smsc-core, the VP will always be communicated in relative form, as a
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	499 count of seconds. Special value 0 means that the source is not setting the
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	500 VP, and a system-wide default needs to be applied.
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	501
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	502 * If themwi-smsc-gsmif receives an absolute-format VP from GSM MS, it will
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	503 convert to relative seconds-from-present before submitting the SM to
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	504 themwi-smsc-core.
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	505
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	506 * themwi-smsc-core will have two configurable settings with regard to message
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	507 longevity: default VP and maximum VP. The default VP setting will be applied
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	508 when no VP is set at the message source: themwi-smsc-submit without explicit
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	509 VP, MO SM from a GSM MS without VP setting, or a message from the outside
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	510 world where SMPP never provides a VP on incoming messages. OTOH, the maximum
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	511 VP setting will serve as a cap in case a user did specify an explicit VP, but
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	512 it is unreasonably long.
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	513
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	514 2.4.5. Duplicate message detection
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	515
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	516 One can easily envision various scenarios in which a duplicate copy is received
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	517 for an earlier message which is still active, i.e., still queued for delivery
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	518 to its destination. Instead of adding such duplicates to the queue, it is
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	519 desirable to be able to detect and suppress them. The details remain to be
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5] Mychaela Falconia <falcon@freecalypso.org> parents: 1 diff changeset	520 worked out.
1 c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	521
3 b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	522 2.5. Local socket interface between SMSC components
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	523
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	524 There will be an ad hoc local UNIX domain socket interface between different
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	525 components of ThemWi-SMSC. themwi-smsc-core will be the single server for this
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	526 local socket i/f, and all other components will connect to it as clients.
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	527 Local socket clients will be able to function in two fundamental ways on this
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	528 internal interface:
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	529
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	530 a) Irrespective of any other function, each local socket client will be able to
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	531 execute "pure client" exchanges with themwi-smsc-core, such as
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	532 SMSC_REQ_SUBMIT and SMSC_REQ_CANCEL.
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	533
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	534 b) Long-lived SMSC components that perform certain specific roles (IMSI lookup
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	535 role, GSM MT delivery role, SMPP peer delivery role for each upstream or
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	536 downstream peer) will register with themwi-smsc-core as role-handlers for
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	537 these specific roles.
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	538
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	539 The architectural model of this internal socket i/f is that of request-response
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	540 exchanges: each message is either a request or a response, with responses
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	541 matched to requests. There are two possible directions for such exchanges:
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	542
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	543 * For "pure client" operations and role-handler (RH) registration exchanges,
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	544 requests flow from the connected client to themwi-smsc-core;
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	545
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	546 * Once an RH has successfully registered and declared itself to be in "service
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	547 up" state, themwi-smsc-core will initiate certain requests toward this RH,
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	548 as detailed in this section.
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	549
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	550 2.5.1. Pure client exchanges
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	551
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	552 All exchanges listed in this section consist of a request issued by the client
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	553 toward themwi-smsc-core and a response message in the reverse direction. These
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	554 commands will be sent by standalone clients like themwi-smsc-submit and also by
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	555 role-handler components: the same process that acts as RH for GSM MT delivery
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	556 will need to submit SMs coming from GSM MO activity, the same process that acts
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	557 as RH for delivery to a given SMPP peer will need to submit SMs coming from
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	558 that peer, etc.
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	559
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	560 2.5.1.1. SMSC_REQ_SUBMIT
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	561
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	562 This command submits or enters or injects a new SM into the SMSC. The client
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	563 will send a struct sm_record, and themwi-smsc-core takes over from there. All
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	564 processing described in section 2.4 happens upon this command; failure at any
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	565 of the steps detailed there will result in an error response to the issuing
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	566 client in this exchange. A successful response indicates that the new SM has
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	567 been written into PMS and accepted by the SMSC.
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	568
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	569 2.5.1.2. SMSC_REQ_CANCEL
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	570
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	571 This command requests that an active (not yet delivered or timed out) SM be
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	572 canceled. The SM to be canceled can be identified by its absolute index
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	573 (0-based absolute position in PMS) or by a tuple of {OA, DA, MR} - the latter
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	574 option is needed for implementation of cancel operation via SMS-COMMAND from
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	575 GSM MO side.
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	576
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	577 2.5.1.3. SMSC_REQ_CHANGE_SRR
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	578
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	579 This command is similar to SMSC_REQ_CANCEL (supports the same ways of
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	580 identifying the target message), but instead of cancelling the message, it
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	581 changes the state of Status Report Requested flag.
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	582
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	583 2.5.2. Role handler registration and service state
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	584
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	585 These exchanges flow in the same direction as those listed in section 2.5.1
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	586 (from the connected client to themwi-smsc-core), but are issued only by specific
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	587 long-lived processes that serve as specific role-handlers.
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	588
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	589 2.5.2.1. SMSC_RH_REGISTER
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	590
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	591 The long-lived connected client process sending this request is asking to
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	592 register for its specific role. The following 3 roles are possible:
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	593
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	594 * ROLE_IMSI_LOOKUP
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	595 * ROLE_GSM_MT_DELIVERY
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	596 * ROLE_PEER_DELIVERY
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	597
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	598 If the role type is ROLE_PEER_DELIVERY, there is an additional argument naming
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	599 the specific peer; non-empty names identify downstream peers and the special
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	600 name "" (null string) identifies the upstream peer. For the other two role
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	601 types, there is no such extra argument: there is only one ROLE_IMSI_LOOKUP and
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	602 only one ROLE_GSM_MT_DELIVERY.
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	603
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	604 Only one client can be registered for each role: one for ROLE_IMSI_LOOKUP, one
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	605 for ROLE_GSM_MT_DELIVERY and one for each peer. Registration attempts for an
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	606 already-claimed role will result in an error response.
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	607
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	608 2.5.2.2. SMSC_RH_SERVICE_STATE
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	609
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	610 The service state of a given RH may be up or down. If the RH process is running
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	611 but unable to perform its job (e.g., the upstream peer connection is down), its
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	612 service state is down; in order for an RH to receive requests for processing
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	613 from themwi-smsc-core, it needs to not only register for its role, but also
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	614 declare itself to be in "service up" state. The present exchange makes the
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	615 declaration of service state being up or down.
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	616
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	617 2.5.3. Exchanges with the IMSI resolver RH
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	618
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	619 SMSC_MT_FIND_IMSI: request direction is from themwi-smsc-core to the registered
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	620 IMSI resolver RH. The request message carries an MSISDN; the matching response
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	621 carries the corresponding IMSI or an error.
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	622
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	623 2.5.4. Exchanges with the GSM MT delivery RH
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	624
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	625 2.5.4.1. SMSC_MT_TRANSFER
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	626
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	627 Request direction is from themwi-smsc-core to the registered GSM MT delivery RH.
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	628 This exchange transfers a given SM (intended for GSM MT delivery) into temporary
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	629 custody of themwi-smsc-gsmif process, which is the RH for this role.
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	630 themwi-smsc-gsmif retains custody of this SM, and themwi-smsc-core regards this
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	631 SM as being in the custody of themwi-smsc-gsmif, until one of the following two
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	632 outcomes:
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	633
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	634 a) The SM is discharged: delivered, canceled or times out as determined by
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	635 themwi-smsc-gsmif, with an attendant SMSC_MT_DISCHARGE exchange;
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	636
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	637 b) The service goes down (socket client disconnects or declares itself down via
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	638 SMSC_RH_SERVICE_STATE). In this case themwi-smsc-core retakes custody of
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	639 all still-active SMs that were previously handed over to themwi-smsc-gsmif
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	640 via SMSC_MT_TRANSFER.
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	641
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	642 2.5.4.2. SMSC_MT_CANCEL
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	643
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	644 Request direction is from themwi-smsc-core to the registered GSM MT delivery RH,
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	645 which is themwi-smsc-gsmif. themwi-smsc-core issues this request toward
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	646 themwi-smsc-gsmif whenever it receives SMSC_REQ_CANCEL for an SM that has been
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	647 handed over to themwi-smsc-gsmif via SMSC_MT_TRANSFER.
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	648
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	649 2.5.4.3. SMSC_MT_DISCHARGE
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	650
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	651 themwi-smsc-gsmif sends this request to themwi-smsc-core to indicate the
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	652 discharge (successful delivery, cancellation or validity period expiry) of an
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	653 SM that has previously been transferred via SMSC_MT_TRANSFER.
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	654
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	655 2.5.5. Exchanges with peer delivery role handlers
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	656
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	657 SMSC_DELIVER_TO_PEER: request direction is from themwi-smsc-core to the
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	658 registered RH for this peer. The request carries an SM (struct sm_record);
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	659 the response carries success or failure.
b084a9542471 doc/Arch-design: planned design of local socket interface Mychaela Falconia <falcon@freecalypso.org> parents: 2 diff changeset	660
4 da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	661 2.6. Queueing architecture of ThemWi-SMSC
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	662
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	663 2.6.1. Queueing in themwi-smsc-core
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	664
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	665 While every SM, active or historical, is stored in PMS, only active ones are
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	666 also held in RAM-based queues by themwi-smsc-core. There are many queues,
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	667 organized by SM destination:
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	668
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	669 2.6.1.1. Queues of SMs waiting to be delivered to SMPP peers
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	670
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	671 There will be a separate queue for each upstream or downstream peer, or more
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	672 precisely, one queue for the single upstream peer and one for each downstream
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	673 peer. Each peer is another SMSC somewhere else in the world, and each queue
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	674 holds messages which need to be transferred to that other SMSC.
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	675
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	676 When the process that serves as the RH for delivery to a given peer is
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	677 connected, the corresponding queue will be drained by themwi-smsc-core
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	678 transferring the SM at the head of the queue to the RH via SMSC_DELIVER_TO_PEER
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	679 request. Only one such request will be outstanding at any given time to a
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	680 single RH; once the RH responds to this SMSC_DELIVER_TO_PEER request, completing
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	681 that elementary exchange, themwi-smsc-core will discharge the SM at the head
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	682 and proceed to the next one in the queue, doing another SMSC_DELIVER_TO_PEER
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	683 exchange on it, and so forth.
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	684
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	685 2.6.1.2. Queues of SMs waiting for MSISDN-to-IMSI resolution
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	686
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	687 There will be a hierarchical structure of queues for this function:
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	688
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	689 * The top-level MSISDN-to-IMSI lookup queue will have one entry for each
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	690 _different_ target MSISDN in need of resolution;
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	691
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	692 * Under each unique target MSISDN entry in the just-described queue, there will
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	693 be a subqueue of individual SMs addressed to that MSISDN.
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	694
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	695 When the IMSI resolver RH is connected, themwi-smsc-core will take the MSISDN
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	696 at the head of the to-be-resolved queue and send it to the RH in a
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	697 SMSC_MT_FIND_IMSI request. When the RH responds, all SMs that are queued under
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	698 that MSISDN get their dest_imsi filled in, and are moved to the next queue
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	699 described in section 2.6.1.4.
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	700
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	701 2.6.1.3. Cache of recently completed MSISDN-to-IMSI lookups
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	702
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	703 To avoid many repeated queries resolving the same MSISDN to IMSI rapidly back
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	704 to back, particularly in the case of additional SMs to the same recipient (e.g.,
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	705 segments of a long message) arriving just after the initial MSISDN-to-IMSI
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	706 lookup completed and removed the target MSISDN from the queue, there will a
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	707 cache of recently resolved MSISDN-to-IMSI mappings. The time duration of how
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	708 long a cached lookup result will be considered valid will be configurable - it
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	709 is a trade-off between efficiency under high message load vs allowing
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	710 administrative changes in the mapping of subscribers (association between phone
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	711 numbers and physically issued SIM cards) and letting them take effect reasonably
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	712 quickly.
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	713
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	714 2.6.1.4. Queues of SMs waiting for final GSM MT delivery
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	715
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	716 There will be two queues for messages in this state:
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	717
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	718 * The first queue holds MT-intended SMs which are still officially in the
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	719 custody of themwi-smsc-core;
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	720
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	721 * The second queue holds MT SMs that have been transferred into the custody of
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	722 themwi-smsc-gsmif via SMSC_MT_TRANSFER exchange, see section 2.5.4.1.
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	723
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	724 themwi-smsc-core will actively manage the first queue, seeking to transfer each
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	725 SM into the custody of themwi-smsc-gsmif and move it to the second queue. Once
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	726 a message has been placed on the second queue, themwi-smsc-core no longer
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	727 actively manages it - the SM is now a responsiblity of themwi-smsc-gsmif.
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	728 In good system operation, they get discharged when themwi-smsc-gsmif performs
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	729 an SMSC_MT_DISCHARGE exchange. However, if themwi-smsc-gsmif goes away, all SMs
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	730 on the second queue will be moved back to the first queue.
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	731
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	732 2.6.2. Queueing in themwi-smsc-gsmif
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	733
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	734 themwi-smsc-gsmif is the sw component responsible for accepting MO SMs from GSM
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	735 subscribers and for delivering MT SMs to them. The former task is very simple
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	736 (each received SMS-SUBMIT from GSM side turns into SMSC_REQ_SUBMIT), but the
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	737 latter function (MT delivery) is where the real work lies. Our design approach
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	738 is that themwi-smsc-core will transfer all destined-for-MT SMs into the custody
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	739 of themwi-smsc-gsmif as quickly as possible (without waiting for each SM to be
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	740 delivered in turn, unlike transfers to peer SMSCs via SMPP), and then
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	741 themwi-smsc-gsmif is responsible for the actual queueing strategy and scheduling
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	742 of GSM MT delivery attempts.
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	743
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	744 The details of queue structure and delivery attempt scheduling strategy in
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	745 themwi-smsc-gsmif remain to be determined; the current plan is to implement
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	746 other parts of ThemWi-SMSC first.
da97e78a5586 doc/Arch-design: document queueing architecture Mychaela Falconia <falcon@freecalypso.org> parents: 3 diff changeset	747
1 c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	748 3. SMS communication via direct shell access
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	749
5 8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	750 In the context of Themyscira Wireless, local users of the SMSC are human
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	751 members of our local community who have mobile telephone numbers (MTNs) on
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	752 Themyscira Wireless network. The conventional way to access Short Message
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	753 Service is via a GSM phone handset with a Themyscira SIM card: send outgoing
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	754 messages as MO and receive incoming ones as MT. However, we (the Presiding
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	755 Sisterhood of Themyscira) think outside the box, and we believe in maximal user
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	756 empowerment - hence we aim to provide a second way for any of our users to
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	757 access SMS at their personal MTN, via a novel ssh-based command line mechanism.
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	758
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	759 The idea is that each individual user should be able to give their ssh public
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	760 key to the administrator of the community network, and then ssh into a special
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	761 restricted service on the SMSC that does not grant any system shell access, but
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	762 allows them to access services under their own phone number. Such an empowered
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	763 end user should be able to submit SMS from their own phone number using the
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	764 power of a full-size computer (as opposed to very painful text entry on the
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	765 numeric keypad of a traditional GSM phone), and to see a full log of all
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	766 messages received by or sent from their own phone number.
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	767
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	768 Aside from allowing outgoing SMS to be composed on a real computer in vi instead
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	769 of phone keypad text entry, ssh-based access to the SMSC works over the Internet
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	770 and is thus available from everywhere in the world, far outside the coverage
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	771 area of the local GSM network. Enabling Themyscira citizens to send SMS from
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	772 their own "home" number and see texts arriving at that same number while far
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	773 away from home GSM service is expected to be a highly empowering feature.
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	774
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	775 3.1. themwi-smsc-submit command line utility
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	776
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	777 This shell utility takes two mandatory command line arguments (source and
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	778 destination phone numbers) and reads SM body text from stdin. The input
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	779 language expected on stdin will be the same as output from sms-encode-text
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	780 utility, described here:
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	781
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	782 https://www.freecalypso.org/hg/sms-coding-utils/file/tip/doc/Tool-workflow
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	783
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	784 themwi-smsc-submit will construct a new SM in the form of struct sm_record and
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	785 inject it into the SMSC with SMSC_REQ_SUBMIT. themwi-smsc-core needs to be
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	786 running, but no other component daemons are needed.
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	787
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	788 This utility is envisioned as having multiple uses:
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	789
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	790 * During SMSC development, it is the easiest way to generate messages.
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	791
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	792 * For end user access to the SMSC (the main topic of this chapter), there will
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	793 a wrapper that allows users to enter arbitrary destination number and message
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	794 body input, but the source phone number will be fixed to that of the
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	795 subscriber.
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	796
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	797 * All "big" MNOs have "special" auto-generated SMS they send out for customer
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	798 notifications and whatnot, with message source address set to some special
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	799 number or even alphanumeric (TON=5), and they can also have special encodings
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	800 performing functions such as SIM OTA programming. themwi-smsc-submit is one
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	801 way to generate such SMs; the other option is to have custom processes for
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	802 other MNO functions connect directly to themwi-smsc-core socket interface,
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	803 but in simpler and more casual environments the command line utility is
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	804 expected to be sufficient.
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	805
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	806 3.2. Unprivileged user access to themwi-smsc-dump
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	807
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	808 The principal operation of themwi-smsc-dump is described in section 2.2.3.
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	809 When accessed directly, without going through restrictive wrappers, this tool
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	810 has the power of reading every message that ever went through the local SMSC,
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	811 going back to the beginning of PMS archive - such unrestricted access should be
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	812 given only to trusted administrators. However, themwi-smsc-dump will also have
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	813 a lot of command line options that restrict what it displays, including an
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	814 option to show only messages whose source or destination matches a certain phone
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	815 number. A restrictive wrapper that invokes themwi-smsc-dump with this specific
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	816 number option, and strictly preens all other options, can be made available to
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	817 unprivileged users who wish to use ssh access to read their SMS.
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	818
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	819 If someone receives SMS at their phone number while away from ThemWi GSM
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	820 coverage, the received SM will remain in the SMSC in the active state -
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	821 themwi-smsc-gsmif will be retrying delivery attempts to the GSM MS. If the
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	822 human owner of that phone number uses ssh access to read their SMS while in
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	823 this state, they will see the received message in the active state; if they get
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	824 back home into coverage zone before the received SM expires, they will also
8a7eb3d4570a doc/Arch-design: document the plan of shell access to SMSC Mychaela Falconia <falcon@freecalypso.org> parents: 4 diff changeset	825 receive the same SM on their GSM phone.
1 c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	826
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	827 4. Interface to local Osmocom GSM network
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	828
6 acc5b1c3e07d doc/Arch-design: document Osmocom network interface plan Mychaela Falconia <falcon@freecalypso.org> parents: 5 diff changeset	829 There will be two long-lived daemon processes in ThemWi-SMSC dedicated to
acc5b1c3e07d doc/Arch-design: document Osmocom network interface plan Mychaela Falconia <falcon@freecalypso.org> parents: 5 diff changeset	830 interfacing with the local Osmocom GSM network:
acc5b1c3e07d doc/Arch-design: document Osmocom network interface plan Mychaela Falconia <falcon@freecalypso.org> parents: 5 diff changeset	831
acc5b1c3e07d doc/Arch-design: document Osmocom network interface plan Mychaela Falconia <falcon@freecalypso.org> parents: 5 diff changeset	832 * themwi-smsc-gsmif will be the main SMSC-to-GSM interface. It will connect to
acc5b1c3e07d doc/Arch-design: document Osmocom network interface plan Mychaela Falconia <falcon@freecalypso.org> parents: 5 diff changeset	833 OsmoHLR via GSUP, and it will appear to the Osmocom network as the SMSC,
acc5b1c3e07d doc/Arch-design: document Osmocom network interface plan Mychaela Falconia <falcon@freecalypso.org> parents: 5 diff changeset	834 hiding the other components of ThemWi-SMSC from Osmocom network perspective.
acc5b1c3e07d doc/Arch-design: document Osmocom network interface plan Mychaela Falconia <falcon@freecalypso.org> parents: 5 diff changeset	835 This process will be responsible for receiving MO SMs from GSM subscribers
acc5b1c3e07d doc/Arch-design: document Osmocom network interface plan Mychaela Falconia <falcon@freecalypso.org> parents: 5 diff changeset	836 and submitting them to themwi-smsc-core, and it will also be responsible for
acc5b1c3e07d doc/Arch-design: document Osmocom network interface plan Mychaela Falconia <falcon@freecalypso.org> parents: 5 diff changeset	837 delivering MT SMs to GSM MS once the destination IMSI is known. It will
acc5b1c3e07d doc/Arch-design: document Osmocom network interface plan Mychaela Falconia <falcon@freecalypso.org> parents: 5 diff changeset	838 register with themwi-smsc-core as the role-handler for ROLE_GSM_MT_DELIVERY.
acc5b1c3e07d doc/Arch-design: document Osmocom network interface plan Mychaela Falconia <falcon@freecalypso.org> parents: 5 diff changeset	839
acc5b1c3e07d doc/Arch-design: document Osmocom network interface plan Mychaela Falconia <falcon@freecalypso.org> parents: 5 diff changeset	840 * themwi-smsc-mtimsi will be a much simpler daemon process whose only job will
acc5b1c3e07d doc/Arch-design: document Osmocom network interface plan Mychaela Falconia <falcon@freecalypso.org> parents: 5 diff changeset	841 be resolving MSISDNs to IMSIs for MT SMs. It will register with
acc5b1c3e07d doc/Arch-design: document Osmocom network interface plan Mychaela Falconia <falcon@freecalypso.org> parents: 5 diff changeset	842 themwi-smsc-core as the role-handler for ROLE_IMSI_LOOKUP.
acc5b1c3e07d doc/Arch-design: document Osmocom network interface plan Mychaela Falconia <falcon@freecalypso.org> parents: 5 diff changeset	843
acc5b1c3e07d doc/Arch-design: document Osmocom network interface plan Mychaela Falconia <falcon@freecalypso.org> parents: 5 diff changeset	844 In the current (end of 2023) state of Osmocom CNI, there is no way to perform
acc5b1c3e07d doc/Arch-design: document Osmocom network interface plan Mychaela Falconia <falcon@freecalypso.org> parents: 5 diff changeset	845 an MSISDN-to-IMSI lookup via GSUP. It is furthermore not obvious how to add
acc5b1c3e07d doc/Arch-design: document Osmocom network interface plan Mychaela Falconia <falcon@freecalypso.org> parents: 5 diff changeset	846 such capability, and it is not certain if anyone in Osmocom community (other
acc5b1c3e07d doc/Arch-design: document Osmocom network interface plan Mychaela Falconia <falcon@freecalypso.org> parents: 5 diff changeset	847 than us) even cares about the problem of interfacing external SMSCs via GSUP
acc5b1c3e07d doc/Arch-design: document Osmocom network interface plan Mychaela Falconia <falcon@freecalypso.org> parents: 5 diff changeset	848 and the associated problem of addressing in the MT direction:
acc5b1c3e07d doc/Arch-design: document Osmocom network interface plan Mychaela Falconia <falcon@freecalypso.org> parents: 5 diff changeset	849
acc5b1c3e07d doc/Arch-design: document Osmocom network interface plan Mychaela Falconia <falcon@freecalypso.org> parents: 5 diff changeset	850 https://osmocom.org/issues/6312
acc5b1c3e07d doc/Arch-design: document Osmocom network interface plan Mychaela Falconia <falcon@freecalypso.org> parents: 5 diff changeset	851
acc5b1c3e07d doc/Arch-design: document Osmocom network interface plan Mychaela Falconia <falcon@freecalypso.org> parents: 5 diff changeset	852 Given this uncertainty and lack of interest from other stakeholders, we shall
acc5b1c3e07d doc/Arch-design: document Osmocom network interface plan Mychaela Falconia <falcon@freecalypso.org> parents: 5 diff changeset	853 use a not-pretty but very workable solution: themwi-smsc-mtimsi will connect to
acc5b1c3e07d doc/Arch-design: document Osmocom network interface plan Mychaela Falconia <falcon@freecalypso.org> parents: 5 diff changeset	854 the CTRL interface of OsmoHLR (as opposed to GSUP) and make queries for
acc5b1c3e07d doc/Arch-design: document Osmocom network interface plan Mychaela Falconia <falcon@freecalypso.org> parents: 5 diff changeset	855 subscriber.by-msisdn-XXXX.imsi - a query-able object that was just recently
acc5b1c3e07d doc/Arch-design: document Osmocom network interface plan Mychaela Falconia <falcon@freecalypso.org> parents: 5 diff changeset	856 added as a band-aid solution for the current problem.
1 c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	857
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	858 5. SMPP connection handlers and outside-world SM exchange
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	859
c4f8a32af088 doc/Arch-design: continuing Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	860 To be filled.

FreeCalypso > hg > themwi-smsc

annotate doc/Arch-design @ 6:acc5b1c3e07d default tip