FreeCalypso > hg > themwi-smsc

annotate doc/Arch-design @ 4:da97e78a5586

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/Arch-design: document queueing architecture
author Mychaela Falconia <falcon@freecalypso.org>
date Sat, 23 Dec 2023 00:54:24 +0000
parents b084a9542471
children 8a7eb3d4570a
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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,
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
315 i.e., to end users. The idea is that each individual user should be able to
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
316 give their ssh public key to the administrator of the community network, and
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
317 then ssh into a special restricted service on the SMSC that does not grant
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
318 any system shell access, but allows them to access services under their own
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
319 phone number. Such an empowered end user should be able to submit SMS from
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
320 their own phone number using the power of a full-size computer (as opposed to
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
321 very painful text entry on the numeric keypad of a traditional GSM phone),
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
322 and to see a full log of all messages received by or sent from their own
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
323 phone number.
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
324
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
325 * 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
326 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
327 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
328 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
329 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
330 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
331 necessary to do so for technical troubleshooting reasons. Toward this
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
332 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
333 necessary information, without throwing unnecessary private info into the
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
334 operator's eyeballs.
1
c4f8a32af088 doc/Arch-design: continuing
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
335
c4f8a32af088 doc/Arch-design: continuing
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
336 2.3. themwi-smsc-core daemon operation
c4f8a32af088 doc/Arch-design: continuing
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
337
c4f8a32af088 doc/Arch-design: continuing
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
338 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
339 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
340 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
341 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
342 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
343 functions:
c4f8a32af088 doc/Arch-design: continuing
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
344
c4f8a32af088 doc/Arch-design: continuing
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
345 * 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
346 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
347 structures;
c4f8a32af088 doc/Arch-design: continuing
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
348
c4f8a32af088 doc/Arch-design: continuing
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
349 * 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
350 connection- and message-oriented;
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 * Accept message submission (or entry) commands from other ThemWi-SMSC
c4f8a32af088 doc/Arch-design: continuing
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
353 components connecting to this socket;
c4f8a32af088 doc/Arch-design: continuing
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
354
c4f8a32af088 doc/Arch-design: continuing
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
355 * Allow those socket-connecting SMSC components to register themselves as
c4f8a32af088 doc/Arch-design: continuing
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
356 performing special roles (GSM network interface, IMSI resolver, uplink and
c4f8a32af088 doc/Arch-design: continuing
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
357 downlink SMPP connection handlers), and send notification packets to those
c4f8a32af088 doc/Arch-design: continuing
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
358 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
359
c4f8a32af088 doc/Arch-design: continuing
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
360 * 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
361 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
362 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
363 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
364
c4f8a32af088 doc/Arch-design: continuing
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
365 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
366 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
367 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
368 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
369 graph arrows between sw components point in only one direction.
c4f8a32af088 doc/Arch-design: continuing
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
370
c4f8a32af088 doc/Arch-design: continuing
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
371 2.4. Message entry paths
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 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
374 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
375 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
376 new SMs in this manner:
c4f8a32af088 doc/Arch-design: continuing
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
377
c4f8a32af088 doc/Arch-design: continuing
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
378 * 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
379 this function and nothing else;
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 * 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
382 GSM subscribers as MO messages;
c4f8a32af088 doc/Arch-design: continuing
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
383
c4f8a32af088 doc/Arch-design: continuing
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
384 * 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
385 the upstream connection, i.e., from the outside world;
c4f8a32af088 doc/Arch-design: continuing
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
386
c4f8a32af088 doc/Arch-design: continuing
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
387 * 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
388
c4f8a32af088 doc/Arch-design: continuing
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
389 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
390 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
391 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
392 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
393 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
394 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
395 for processing.
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 2.4.1. Routing of Short Messages
c4f8a32af088 doc/Arch-design: continuing
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
398
c4f8a32af088 doc/Arch-design: continuing
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
399 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
400 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
401 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
402 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
403 routing rules will be applied:
c4f8a32af088 doc/Arch-design: continuing
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
404
c4f8a32af088 doc/Arch-design: continuing
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
405 * 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
406 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
407
c4f8a32af088 doc/Arch-design: continuing
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
408 * 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
409 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
410 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
411 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
412 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
413 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
414 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
415 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
416 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
417 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
418 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
419 anywhere, the destination is SME_CLASS_UPSTREAM.
c4f8a32af088 doc/Arch-design: continuing
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
420
c4f8a32af088 doc/Arch-design: continuing
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
421 * 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
422 the destination is SME_CLASS_UPSTREAM.
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 * 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
425 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
426 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
427 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
428 or SME_CLASS_GSM according to the exact number type.
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 * 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
431
c4f8a32af088 doc/Arch-design: continuing
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
432 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
433 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
434 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
435 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
436 delivery.
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 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
439 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
440 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
441 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
442 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
443 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
444 prefilled.
c4f8a32af088 doc/Arch-design: continuing
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
445
c4f8a32af088 doc/Arch-design: continuing
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
446 2.4.2. Permission to send to the uplink
c4f8a32af088 doc/Arch-design: continuing
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
447
2
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5]
Mychaela Falconia <falcon@freecalypso.org>
parents: 1
diff changeset
448 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
449 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
450 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
451 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
452 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
453 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
454 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
455 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
456 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
457 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
458 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
459 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
460 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
461 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
462
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5]
Mychaela Falconia <falcon@freecalypso.org>
parents: 1
diff changeset
463 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
464 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
465 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
466 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
467 rejected.
1
c4f8a32af088 doc/Arch-design: continuing
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
468
c4f8a32af088 doc/Arch-design: continuing
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
469 2.4.3. PID and DCS constraints
c4f8a32af088 doc/Arch-design: continuing
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
470
2
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5]
Mychaela Falconia <falcon@freecalypso.org>
parents: 1
diff changeset
471 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
472 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
473 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
474 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
475 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
476 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
477 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
478 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
479 unsuspecting local users.
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5]
Mychaela Falconia <falcon@freecalypso.org>
parents: 1
diff changeset
480
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5]
Mychaela Falconia <falcon@freecalypso.org>
parents: 1
diff changeset
481 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
482 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
483 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
484 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
485 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
486
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5]
Mychaela Falconia <falcon@freecalypso.org>
parents: 1
diff changeset
487 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
488 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
489
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5]
Mychaela Falconia <falcon@freecalypso.org>
parents: 1
diff changeset
490 * 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
491
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5]
Mychaela Falconia <falcon@freecalypso.org>
parents: 1
diff changeset
492 * 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
493
c4f8a32af088 doc/Arch-design: continuing
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
494 2.4.4. Validity period and expiry time
c4f8a32af088 doc/Arch-design: continuing
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
495
2
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5]
Mychaela Falconia <falcon@freecalypso.org>
parents: 1
diff changeset
496 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
497 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
498 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
499 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
500 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
501
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5]
Mychaela Falconia <falcon@freecalypso.org>
parents: 1
diff changeset
502 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
503 ThemWi-SMSC:
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5]
Mychaela Falconia <falcon@freecalypso.org>
parents: 1
diff changeset
504
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5]
Mychaela Falconia <falcon@freecalypso.org>
parents: 1
diff changeset
505 * 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
506 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
507 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
508 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
509
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5]
Mychaela Falconia <falcon@freecalypso.org>
parents: 1
diff changeset
510 * 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
511 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
512 themwi-smsc-core.
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 * 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
515 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
516 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
517 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
518 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
519 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
520 it is unreasonably long.
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5]
Mychaela Falconia <falcon@freecalypso.org>
parents: 1
diff changeset
521
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5]
Mychaela Falconia <falcon@freecalypso.org>
parents: 1
diff changeset
522 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
523
b203ebebe9b3 doc/Arch-design: fill out sections 2.4.[2-5]
Mychaela Falconia <falcon@freecalypso.org>
parents: 1
diff changeset
524 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
525 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
526 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
527 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
528 worked out.
1
c4f8a32af088 doc/Arch-design: continuing
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
529
3
b084a9542471 doc/Arch-design: planned design of local socket interface
Mychaela Falconia <falcon@freecalypso.org>
parents: 2
diff changeset
530 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
531
b084a9542471 doc/Arch-design: planned design of local socket interface
Mychaela Falconia <falcon@freecalypso.org>
parents: 2
diff changeset
532 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
533 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
534 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
535 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
536 internal interface:
b084a9542471 doc/Arch-design: planned design of local socket interface
Mychaela Falconia <falcon@freecalypso.org>
parents: 2
diff changeset
537
b084a9542471 doc/Arch-design: planned design of local socket interface
Mychaela Falconia <falcon@freecalypso.org>
parents: 2
diff changeset
538 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
539 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
540 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
541
b084a9542471 doc/Arch-design: planned design of local socket interface
Mychaela Falconia <falcon@freecalypso.org>
parents: 2
diff changeset
542 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
543 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
544 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
545 these specific roles.
b084a9542471 doc/Arch-design: planned design of local socket interface
Mychaela Falconia <falcon@freecalypso.org>
parents: 2
diff changeset
546
b084a9542471 doc/Arch-design: planned design of local socket interface
Mychaela Falconia <falcon@freecalypso.org>
parents: 2
diff changeset
547 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
548 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
549 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
550
b084a9542471 doc/Arch-design: planned design of local socket interface
Mychaela Falconia <falcon@freecalypso.org>
parents: 2
diff changeset
551 * 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
552 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
553
b084a9542471 doc/Arch-design: planned design of local socket interface
Mychaela Falconia <falcon@freecalypso.org>
parents: 2
diff changeset
554 * 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
555 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
556 as detailed in this section.
b084a9542471 doc/Arch-design: planned design of local socket interface
Mychaela Falconia <falcon@freecalypso.org>
parents: 2
diff changeset
557
b084a9542471 doc/Arch-design: planned design of local socket interface
Mychaela Falconia <falcon@freecalypso.org>
parents: 2
diff changeset
558 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
559
b084a9542471 doc/Arch-design: planned design of local socket interface
Mychaela Falconia <falcon@freecalypso.org>
parents: 2
diff changeset
560 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
561 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
562 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
563 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
564 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
565 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
566 that peer, etc.
b084a9542471 doc/Arch-design: planned design of local socket interface
Mychaela Falconia <falcon@freecalypso.org>
parents: 2
diff changeset
567
b084a9542471 doc/Arch-design: planned design of local socket interface
Mychaela Falconia <falcon@freecalypso.org>
parents: 2
diff changeset
568 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
569
b084a9542471 doc/Arch-design: planned design of local socket interface
Mychaela Falconia <falcon@freecalypso.org>
parents: 2
diff changeset
570 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
571 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
572 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
573 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
574 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
575 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
576
b084a9542471 doc/Arch-design: planned design of local socket interface
Mychaela Falconia <falcon@freecalypso.org>
parents: 2
diff changeset
577 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
578
b084a9542471 doc/Arch-design: planned design of local socket interface
Mychaela Falconia <falcon@freecalypso.org>
parents: 2
diff changeset
579 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
580 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
581 (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
582 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
583 GSM MO side.
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 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
586
b084a9542471 doc/Arch-design: planned design of local socket interface
Mychaela Falconia <falcon@freecalypso.org>
parents: 2
diff changeset
587 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
588 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
589 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
590
b084a9542471 doc/Arch-design: planned design of local socket interface
Mychaela Falconia <falcon@freecalypso.org>
parents: 2
diff changeset
591 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
592
b084a9542471 doc/Arch-design: planned design of local socket interface
Mychaela Falconia <falcon@freecalypso.org>
parents: 2
diff changeset
593 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
594 (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
595 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
596
b084a9542471 doc/Arch-design: planned design of local socket interface
Mychaela Falconia <falcon@freecalypso.org>
parents: 2
diff changeset
597 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
598
b084a9542471 doc/Arch-design: planned design of local socket interface
Mychaela Falconia <falcon@freecalypso.org>
parents: 2
diff changeset
599 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
600 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
601
b084a9542471 doc/Arch-design: planned design of local socket interface
Mychaela Falconia <falcon@freecalypso.org>
parents: 2
diff changeset
602 * ROLE_IMSI_LOOKUP
b084a9542471 doc/Arch-design: planned design of local socket interface
Mychaela Falconia <falcon@freecalypso.org>
parents: 2
diff changeset
603 * ROLE_GSM_MT_DELIVERY
b084a9542471 doc/Arch-design: planned design of local socket interface
Mychaela Falconia <falcon@freecalypso.org>
parents: 2
diff changeset
604 * ROLE_PEER_DELIVERY
b084a9542471 doc/Arch-design: planned design of local socket interface
Mychaela Falconia <falcon@freecalypso.org>
parents: 2
diff changeset
605
b084a9542471 doc/Arch-design: planned design of local socket interface
Mychaela Falconia <falcon@freecalypso.org>
parents: 2
diff changeset
606 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
607 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
608 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
609 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
610 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
611
b084a9542471 doc/Arch-design: planned design of local socket interface
Mychaela Falconia <falcon@freecalypso.org>
parents: 2
diff changeset
612 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
613 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
614 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
615
b084a9542471 doc/Arch-design: planned design of local socket interface
Mychaela Falconia <falcon@freecalypso.org>
parents: 2
diff changeset
616 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
617
b084a9542471 doc/Arch-design: planned design of local socket interface
Mychaela Falconia <falcon@freecalypso.org>
parents: 2
diff changeset
618 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
619 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
620 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
621 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
622 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
623 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
624
b084a9542471 doc/Arch-design: planned design of local socket interface
Mychaela Falconia <falcon@freecalypso.org>
parents: 2
diff changeset
625 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
626
b084a9542471 doc/Arch-design: planned design of local socket interface
Mychaela Falconia <falcon@freecalypso.org>
parents: 2
diff changeset
627 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
628 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
629 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
630
b084a9542471 doc/Arch-design: planned design of local socket interface
Mychaela Falconia <falcon@freecalypso.org>
parents: 2
diff changeset
631 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
632
b084a9542471 doc/Arch-design: planned design of local socket interface
Mychaela Falconia <falcon@freecalypso.org>
parents: 2
diff changeset
633 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
634
b084a9542471 doc/Arch-design: planned design of local socket interface
Mychaela Falconia <falcon@freecalypso.org>
parents: 2
diff changeset
635 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
636 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
637 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
638 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
639 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
640 outcomes:
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 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
643 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
644
b084a9542471 doc/Arch-design: planned design of local socket interface
Mychaela Falconia <falcon@freecalypso.org>
parents: 2
diff changeset
645 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
646 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
647 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
648 via SMSC_MT_TRANSFER.
b084a9542471 doc/Arch-design: planned design of local socket interface
Mychaela Falconia <falcon@freecalypso.org>
parents: 2
diff changeset
649
b084a9542471 doc/Arch-design: planned design of local socket interface
Mychaela Falconia <falcon@freecalypso.org>
parents: 2
diff changeset
650 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
651
b084a9542471 doc/Arch-design: planned design of local socket interface
Mychaela Falconia <falcon@freecalypso.org>
parents: 2
diff changeset
652 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
653 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
654 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
655 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
656
b084a9542471 doc/Arch-design: planned design of local socket interface
Mychaela Falconia <falcon@freecalypso.org>
parents: 2
diff changeset
657 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
658
b084a9542471 doc/Arch-design: planned design of local socket interface
Mychaela Falconia <falcon@freecalypso.org>
parents: 2
diff changeset
659 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
660 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
661 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
662
b084a9542471 doc/Arch-design: planned design of local socket interface
Mychaela Falconia <falcon@freecalypso.org>
parents: 2
diff changeset
663 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
664
b084a9542471 doc/Arch-design: planned design of local socket interface
Mychaela Falconia <falcon@freecalypso.org>
parents: 2
diff changeset
665 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
666 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
667 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
668
4
da97e78a5586 doc/Arch-design: document queueing architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 3
diff changeset
669 2.6. Queueing architecture of ThemWi-SMSC
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 2.6.1. Queueing in themwi-smsc-core
da97e78a5586 doc/Arch-design: document queueing architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 3
diff changeset
672
da97e78a5586 doc/Arch-design: document queueing architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 3
diff changeset
673 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
674 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
675 organized by SM destination:
da97e78a5586 doc/Arch-design: document queueing architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 3
diff changeset
676
da97e78a5586 doc/Arch-design: document queueing architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 3
diff changeset
677 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
678
da97e78a5586 doc/Arch-design: document queueing architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 3
diff changeset
679 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
680 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
681 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
682 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
683
da97e78a5586 doc/Arch-design: document queueing architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 3
diff changeset
684 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
685 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
686 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
687 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
688 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
689 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
690 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
691 exchange on it, and so forth.
da97e78a5586 doc/Arch-design: document queueing architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 3
diff changeset
692
da97e78a5586 doc/Arch-design: document queueing architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 3
diff changeset
693 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
694
da97e78a5586 doc/Arch-design: document queueing architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 3
diff changeset
695 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
696
da97e78a5586 doc/Arch-design: document queueing architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 3
diff changeset
697 * 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
698 _different_ target MSISDN in need of resolution;
da97e78a5586 doc/Arch-design: document queueing architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 3
diff changeset
699
da97e78a5586 doc/Arch-design: document queueing architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 3
diff changeset
700 * 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
701 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
702
da97e78a5586 doc/Arch-design: document queueing architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 3
diff changeset
703 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
704 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
705 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
706 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
707 described in section 2.6.1.4.
da97e78a5586 doc/Arch-design: document queueing architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 3
diff changeset
708
da97e78a5586 doc/Arch-design: document queueing architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 3
diff changeset
709 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
710
da97e78a5586 doc/Arch-design: document queueing architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 3
diff changeset
711 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
712 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
713 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
714 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
715 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
716 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
717 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
718 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
719 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
720 quickly.
da97e78a5586 doc/Arch-design: document queueing architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 3
diff changeset
721
da97e78a5586 doc/Arch-design: document queueing architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 3
diff changeset
722 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
723
da97e78a5586 doc/Arch-design: document queueing architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 3
diff changeset
724 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
725
da97e78a5586 doc/Arch-design: document queueing architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 3
diff changeset
726 * 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
727 custody of themwi-smsc-core;
da97e78a5586 doc/Arch-design: document queueing architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 3
diff changeset
728
da97e78a5586 doc/Arch-design: document queueing architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 3
diff changeset
729 * 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
730 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
731
da97e78a5586 doc/Arch-design: document queueing architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 3
diff changeset
732 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
733 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
734 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
735 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
736 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
737 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
738 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
739
da97e78a5586 doc/Arch-design: document queueing architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 3
diff changeset
740 2.6.2. Queueing in themwi-smsc-gsmif
da97e78a5586 doc/Arch-design: document queueing architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 3
diff changeset
741
da97e78a5586 doc/Arch-design: document queueing architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 3
diff changeset
742 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
743 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
744 (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
745 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
746 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
747 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
748 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
749 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
750 of GSM MT delivery attempts.
da97e78a5586 doc/Arch-design: document queueing architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 3
diff changeset
751
da97e78a5586 doc/Arch-design: document queueing architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 3
diff changeset
752 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
753 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
754 other parts of ThemWi-SMSC first.
da97e78a5586 doc/Arch-design: document queueing architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 3
diff changeset
755
1
c4f8a32af088 doc/Arch-design: continuing
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
756 3. SMS communication via direct shell access
c4f8a32af088 doc/Arch-design: continuing
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
757
c4f8a32af088 doc/Arch-design: continuing
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
758 To be filled.
c4f8a32af088 doc/Arch-design: continuing
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
759
c4f8a32af088 doc/Arch-design: continuing
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
760 4. Interface to local Osmocom GSM network
c4f8a32af088 doc/Arch-design: continuing
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
761
c4f8a32af088 doc/Arch-design: continuing
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
762 GSUP and separate MSISDN-to-IMSI lookup, to be described.
c4f8a32af088 doc/Arch-design: continuing
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
763
c4f8a32af088 doc/Arch-design: continuing
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
764 5. SMPP connection handlers and outside-world SM exchange
c4f8a32af088 doc/Arch-design: continuing
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
765
c4f8a32af088 doc/Arch-design: continuing
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
766 To be filled.