Documentation
¶
Overview ¶
Package ss7client is the NATS client for ss7-3eai-gateway: the subjects, the message schema and a typed request/response client for the MAP interfaces the gateway implements.
This module is licensed under the Apache License 2.0, separately from the gateway server (AGPL-3.0-only), so an SMSC or any other application can link it without taking on the server's licence. The dependency runs one way: the server imports this module for the wire contract, this module never imports the server.
Interface covered ¶
Only the interface the gateway implements end to end is exposed:
- SRI-for-SM (MAP op 45): Client.SendRoutingInfoForSM, subjects SubjectSRIRequest → SubjectSRIResponse.
- MT-Forward-SM (MAP op 44): Client.MTForwardSM, subjects SubjectMTSMSRequest → SubjectMTSMSResponse.
- MO-Forward-SM (MAP op 46), gateway → application: Client.SubscribeMO, subject SubjectMOSMS.
- AnyTimeInterrogation (MAP op 71) towards the HLR: Client.AnyTimeInterrogation, subjects SubjectATIRequest → SubjectATIResponse.
- ProvideSubscriberInfo (MAP op 70) towards the VLR: Client.ProvideSubscriberInfo, subjects SubjectPSIRequest → SubjectPSIResponse.
Wire model ¶
Every message is a JSON-encoded Message. Requests are published on a request subject; the gateway queue-subscribes, runs the MAP dialogue and publishes the outcome — result or failure — on the matching response subject with the request's correlation_id. Response subjects are broadcast: every client instance receives every response and keeps only its own, by correlation_id.
A request the gateway refuses before starting a dialogue — a missing or invalid field, no capacity for a new dialogue — is answered with StatusRejected from gateway 0.7.4 on; earlier gateways send nothing, and nothing can be sent for a request that is not valid JSON. Client therefore validates the fields the gateway requires before publishing, and applies a default deadline when the context has none.
Index ¶
- Constants
- Variables
- type ATIRequest
- type AddressString
- type CellGlobalID
- type Client
- func (c *Client) AnyTimeInterrogation(ctx context.Context, req ATIRequest) (*SubscriberInfoResult, error)
- func (c *Client) Close() error
- func (c *Client) MTForwardSM(ctx context.Context, req MTRequest) (*MTResult, error)
- func (c *Client) ProvideSubscriberInfo(ctx context.Context, req PSIRequest) (*SubscriberInfoResult, error)
- func (c *Client) SendRoutingInfoForSM(ctx context.Context, req SRIRequest) (*SRIResult, error)
- func (c *Client) SubscribeMO(queue string, handle func(*Message)) (*nats.Subscription, error)
- type Direction
- type GatewayError
- type Location
- type LocationArea
- type LocationEPS
- type MNPInfo
- type MTRequest
- type MTResult
- type Message
- type MessageType
- type Option
- type PSIRequest
- type RequestedInfo
- type SRIRequest
- type SRIResult
- type ServiceAreaID
- type SubscriberInfo
- type SubscriberInfoResult
- type SubscriberState
Constants ¶
const ( // SubjectATIRequest carries AnyTimeInterrogation requests, application → gateway. SubjectATIRequest = "map.ati.request" // SubjectATIResponse carries AnyTimeInterrogation results and failures, gateway → application. SubjectATIResponse = "map.ati.response" // SubjectPSIRequest carries ProvideSubscriberInfo requests, application → gateway. SubjectPSIRequest = "map.psi.request" // SubjectPSIResponse carries ProvideSubscriberInfo results and failures, gateway → application. SubjectPSIResponse = "map.psi.response" )
NATS subjects of the MAP location interface (3GPP TS 29.002 §8.11).
const ( DomainCS = "cs" DomainPS = "ps" )
Domains of RequestedInfo.Domain (TS 29.002 DomainType).
const ( // SubjectSRIRequest carries SRI-for-SM requests, application → gateway. SubjectSRIRequest = "map.sri.request" // SubjectSRIResponse carries SRI-for-SM results and failures, gateway → application. SubjectSRIResponse = "map.sri.response" // SubjectMTSMSRequest carries MT-Forward-SM requests, application → gateway. SubjectMTSMSRequest = "map.mt.sms.request" // SubjectMTSMSResponse carries MT-Forward-SM results and failures, gateway → application. SubjectMTSMSResponse = "map.mt.sms.response" // SubjectMOSMS carries MO-Forward-SM received from a foreign MSC, gateway → application. SubjectMOSMS = "map.mo.sms" )
NATS subjects of the MAP SMS interface. The gateway queue-subscribes to the request subjects (queue group = its cluster name) and publishes on the response subjects.
const ( // ParamServiceCentreAddress (request, SRI and MT): the SMSC address, as // a digit string or an [AddressString] object. ParamServiceCentreAddress = "service_centre_address" // ParamNetworkNodeNumber (request, MT): the serving MSC/VLR address // returned by SRI-for-SM, as a digit string or an [AddressString] object. ParamNetworkNodeNumber = "network_node_number" // ParamTPDUBase64 (request, MT): the TPDU as standard base64, an // alternative to Message.PayloadData. ParamTPDUBase64 = "tpdu_base64" // ParamVMSCAddress (response, SRI): digits of the network node number // returned by the HLR. ParamVMSCAddress = "vmsc_address" )
Keys of Message.Parameters understood or produced by the gateway.
const ( // StatusDelivered: MT-Forward-SM ended with a ReturnResult. A successful // SRI-for-SM, AnyTimeInterrogation or ProvideSubscriberInfo response // carries an empty status. StatusDelivered = "DELIVERED" // StatusTimeout: the gateway's TCAP dialogue timer expired. StatusTimeout = "TIMEOUT" // StatusAborted: the peer aborted the dialogue (TC-P-ABORT / TC-U-ABORT). StatusAborted = "ABORTED" // StatusRejected: the gateway refused the request before starting a // dialogue — a missing or invalid field, or no capacity for a new // dialogue. ErrorCode is ErrCodeRejected and ErrorMessage the reason. StatusRejected = "REJECTED" // StatusRemoteError: the peer answered with a MAP ReturnError — ErrorCode // is the MAP error code (positive, see MAPErr*) and ErrorMessage its name — // or with a TCAP Reject / a ReturnError without a code — ErrorCode is // ErrCodeRemoteError. StatusRemoteError = "REMOTE_ERROR" )
Values of Message.Status on response subjects.
const ( ErrCodeTimeout int32 = -1 ErrCodeAborted int32 = -2 ErrCodeRemoteError int32 = -3 ErrCodeRejected int32 = -4 ErrCodeUnclassified int32 = -99 )
Gateway-private failure codes in Message.ErrorCode. They are negative so they never collide with MAP error codes (3GPP TS 29.002 MAP-ErrorCodes, positive).
const ( MAPErrUnknownSubscriber int32 = 1 MAPErrUnidentifiedSubscriber int32 = 5 MAPErrAbsentSubscriberSM int32 = 6 MAPErrIllegalSubscriber int32 = 9 MAPErrTeleserviceNotProvisioned int32 = 11 MAPErrIllegalEquipment int32 = 12 MAPErrCallBarred int32 = 13 MAPErrFacilityNotSupported int32 = 21 MAPErrSubscriberBusyForMTSMS int32 = 31 MAPErrSMDeliveryFailure int32 = 32 MAPErrSystemFailure int32 = 34 MAPErrDataMissing int32 = 35 MAPErrUnexpectedDataValue int32 = 36 )
MAP error codes (3GPP TS 29.002, MAP-ErrorCodes) that SendRoutingInfoForSM and MT-ForwardSM can return, carried in Message.ErrorCode with StatusRemoteError. The gateway passes any code through; these are the ones an SMSC's retry logic normally distinguishes.
const DefaultTimeout = 40 * time.Second
DefaultTimeout bounds a request whose context has no deadline. It is longer than the gateway's default TCAP dialogue timeout (tcap.dialogue_timeout, 30s), so the gateway's own TIMEOUT response normally arrives first.
const MAPErrATINotAllowed int32 = 49
MAPErrATINotAllowed is ati-NotAllowed (TS 29.002 MAP-ErrorCodes): the HLR does not accept AnyTimeInterrogation from this gsmSCF-Address. The other errors of ATI and PSI — systemFailure, dataMissing, unexpectedDataValue, unknownSubscriber — have MAPErr* constants already.
const ( // ParamVLRNumber (request, PSI): the address of the VLR serving the // subscriber, as a digit string or an [AddressString] object. ParamVLRNumber = "vlr_number" )
Keys of Message.Parameters for the location interface.
Variables ¶
var ( // ErrInvalidRequest wraps a request rejected before publishing because // a field the gateway requires is missing. ErrInvalidRequest = errors.New("ss7 client: invalid request") // ErrClosed is returned for requests made after, or pending at, Close. ErrClosed = errors.New("ss7 client: closed") )
Functions ¶
This section is empty.
Types ¶
type ATIRequest ¶ added in v0.2.0
type ATIRequest struct {
// Exactly one of MSISDN and IMSI (digits) identifies the subscriber.
MSISDN string
IMSI string
// Requested selects what to ask for.
Requested RequestedInfo
// HLRGlobalTitle and HLRPointCode address the HLR directly. Without
// them the gateway routes on the MSISDN as global title (or uses
// map.hlr_gt / map.hlr_pc when map.sri_routing is "hlr"); a request by
// IMSI therefore needs one of them or map.sri_routing "hlr".
HLRGlobalTitle string
HLRPointCode uint32
}
ATIRequest is a MAP AnyTimeInterrogation towards the subscriber's HLR (3GPP TS 29.002 §8.11.1).
type AddressString ¶
type AddressString struct {
Digits string `json:"digits"`
Nature uint8 `json:"nature"`
NumberingPlan uint8 `json:"numbering_plan"`
}
AddressString is the object form of an address parameter. Nature and NumberingPlan are the TS 29.002 AddressString nature-of-address and numbering-plan indicators, coded as there: Nature 1 = international, 2 = national significant, 4 = subscriber number (not the SCCP global title coding, where international is 4); NumberingPlan 1 = ISDN/E.164. A bare digit string in Parameters means international / ISDN-E.164.
func E164 ¶
func E164(digits string) AddressString
E164 returns an international ISDN/E.164 AddressString.
type CellGlobalID ¶ added in v0.2.0
type CellGlobalID struct {
MCC string `json:"mcc"`
MNC string `json:"mnc"`
LAC uint16 `json:"lac"`
CI uint16 `json:"ci"`
}
CellGlobalID is a cell global identity or service area identity (TS 23.003).
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client sends MAP requests to the gateway and matches the responses by correlation ID. It is safe for concurrent use. It does not own the NATS connection: Close releases the client's subscriptions only.
func (*Client) AnyTimeInterrogation ¶ added in v0.2.0
func (c *Client) AnyTimeInterrogation(ctx context.Context, req ATIRequest) (*SubscriberInfoResult, error)
AnyTimeInterrogation asks the subscriber's HLR for the information in req.Requested. The gsmSCF-Address the HLR screens the request on is the gateway's own (map.gsmscf_address, else its cluster GT, else its GT); a request cannot choose it, so a NATS publisher cannot present itself as another gsmSCF. On a gateway-reported failure it returns *GatewayError — with MAPErrATINotAllowed when the HLR refuses this gsmSCF.
func (*Client) MTForwardSM ¶
MTForwardSM delivers a short message to the serving MSC. On a gateway-reported failure it returns *GatewayError.
func (*Client) ProvideSubscriberInfo ¶ added in v0.2.0
func (c *Client) ProvideSubscriberInfo(ctx context.Context, req PSIRequest) (*SubscriberInfoResult, error)
ProvideSubscriberInfo asks the VLR serving the subscriber for the information in req.Requested. On a gateway-reported failure it returns *GatewayError.
func (*Client) SendRoutingInfoForSM ¶
SendRoutingInfoForSM asks the subscriber's HLR where to deliver a short message. On a gateway-reported failure it returns *GatewayError.
func (*Client) SubscribeMO ¶
SubscribeMO delivers MO-Forward-SM messages the gateway received from foreign MSCs: Sender is the originating MSC address, Recipient the SMSC address, IMSI the originator when the network supplied it, PayloadData the SMS-SUBMIT TPDU. With a non-empty queue, instances sharing the queue name split the stream; with an empty queue every instance receives every message. The returned subscription is the caller's to unsubscribe.
MO is a plain NATS publish: a message published while no subscriber is connected is lost.
type Direction ¶
type Direction string
Direction is relative to the SS7 network: Inbound goes into it (application → gateway), Outbound comes out of it (gateway → application).
type GatewayError ¶
type GatewayError struct {
CorrelationID string
Status string // StatusTimeout, StatusAborted, ...
Code int32 // ErrCode* (negative) or a MAP error code (positive, MAPErr*)
Message string
NodeID string
}
GatewayError is a failure the gateway reported on a response subject.
func (*GatewayError) Error ¶
func (e *GatewayError) Error() string
type Location ¶ added in v0.2.0
type Location struct {
// AgeMinutes is the time since the last contact with the subscriber:
// 0 = in contact now, 32767 = at least that old.
AgeMinutes *int `json:"age_minutes,omitempty"`
// VLRNumber and MSCNumber (CS) or SGSNNumber (PS): E.164 digits.
VLRNumber string `json:"vlr_number,omitempty"`
MSCNumber string `json:"msc_number,omitempty"`
SGSNNumber string `json:"sgsn_number,omitempty"`
// At most one of CellGlobalID, ServiceAreaID and LocationArea is set.
CellGlobalID *CellGlobalID `json:"cell_global_id,omitempty"`
ServiceAreaID *ServiceAreaID `json:"service_area_id,omitempty"`
LocationArea *LocationArea `json:"location_area,omitempty"`
// RoutingAreaID is the RAI value part (TS 29.060), hex. PS only.
RoutingAreaID string `json:"routing_area_id,omitempty"`
// LocationNumber (ITU-T Q.763), hex. CS only.
LocationNumber string `json:"location_number,omitempty"`
// GeographicalInformation (TS 23.032 ellipsoid point with uncertainty
// circle, 8 octets) and GeodeticInformation (Q.763, 10 octets), hex.
GeographicalInformation string `json:"geographical_information,omitempty"`
GeodeticInformation string `json:"geodetic_information,omitempty"`
// CurrentLocationRetrieved: the location was obtained by paging just now.
CurrentLocationRetrieved bool `json:"current_location_retrieved,omitempty"`
// EPS is the E-UTRAN location, when the HLR returned it within the CS
// location. CS only.
EPS *LocationEPS `json:"eps,omitempty"`
}
Location is TS 29.002 LocationInformation (CS) or LocationInformationGPRS (PS).
type LocationArea ¶ added in v0.2.0
type LocationArea struct {
MCC string `json:"mcc"`
MNC string `json:"mnc"`
LAC uint16 `json:"lac"`
}
LocationArea is a location area identity (TS 23.003).
type LocationEPS ¶ added in v0.2.0
type LocationEPS struct {
// ECGI and TAI as coded in TS 29.118, hex.
ECGI string `json:"ecgi,omitempty"`
TAI string `json:"tai,omitempty"`
// MMEName is the serving MME's Diameter identity.
MMEName string `json:"mme_name,omitempty"`
AgeMinutes *int `json:"age_minutes,omitempty"`
GeographicalInformation string `json:"geographical_information,omitempty"`
GeodeticInformation string `json:"geodetic_information,omitempty"`
CurrentLocationRetrieved bool `json:"current_location_retrieved,omitempty"`
}
LocationEPS is TS 29.002 LocationInformationEPS.
type MNPInfo ¶ added in v0.2.0
type MNPInfo struct {
RouteingNumber string `json:"routeing_number,omitempty"`
IMSI string `json:"imsi,omitempty"`
MSISDN string `json:"msisdn,omitempty"`
// Status is the NumberPortabilityStatus name: notKnownToBePorted,
// ownNumberPortedOut, foreignNumberPortedToForeignNetwork,
// ownNumberNotPortedOut, foreignNumberPortedIn.
Status string `json:"status,omitempty"`
}
MNPInfo is TS 29.002 MNPInfoRes.
type MTRequest ¶
type MTRequest struct {
IMSI string // required, from SRIResult.IMSI
NetworkNodeNumber AddressString // required, from SRIResult.NetworkNodeNumber
ServiceCentreAddress AddressString // required
TPDU []byte // required, SMS-DELIVER TPDU (3GPP TS 23.040), opaque to the gateway
// MSCPointCode overrides the destination point code. Zero routes on the
// network node number GT alone.
MSCPointCode uint32
}
MTRequest is a MAP MT-ForwardSM request (3GPP TS 29.002 §12.9).
type Message ¶
type Message struct {
MessageID string `json:"message_id"`
CorrelationID string `json:"correlation_id,omitempty"`
MessageType MessageType `json:"message_type"`
Direction Direction `json:"direction"`
Timestamp time.Time `json:"timestamp"`
// Addressing (E.164 digits).
Sender string `json:"sender,omitempty"`
Recipient string `json:"recipient,omitempty"`
IMSI string `json:"imsi,omitempty"`
MSISDN string `json:"msisdn,omitempty"`
// SS7 routing overrides. Zero/empty means "use the gateway's configuration".
OPC uint32 `json:"opc,omitempty"`
DPC uint32 `json:"dpc,omitempty"`
SSN uint8 `json:"ssn,omitempty"`
GlobalTitle string `json:"global_title,omitempty"`
Content string `json:"content,omitempty"`
PayloadData []byte `json:"payload_data,omitempty"` // base64 in JSON
Parameters map[string]interface{} `json:"parameters,omitempty"`
ServiceKey uint32 `json:"service_key,omitempty"`
EventType string `json:"event_type,omitempty"`
// Location interface (map.ati.*, map.psi.*): what a request asks for
// and what the answer carries.
RequestedInfo *RequestedInfo `json:"requested_info,omitempty"`
SubscriberInfo *SubscriberInfo `json:"subscriber_info,omitempty"`
Status string `json:"status,omitempty"`
ErrorCode int32 `json:"error_code,omitempty"`
ErrorMessage string `json:"error_message,omitempty"`
TraceID string `json:"trace_id,omitempty"`
NodeID string `json:"node_id,omitempty"` // gateway node that handled the dialogue
}
Message is the JSON document carried on every subject. Field names and JSON tags are the wire contract shared with non-Go consumers; changing one breaks them.
type MessageType ¶
type MessageType string
MessageType identifies the operation a Message belongs to.
const ( MsgTypeMAPATI MessageType = "MAP_ATI" MsgTypeMAPPSI MessageType = "MAP_PSI" )
const ( MsgTypeMAPSRI MessageType = "MAP_SRI" MsgTypeMAPMTSMS MessageType = "MAP_MT_SMS" MsgTypeMAPMOSMS MessageType = "MAP_MO_SMS" )
type Option ¶
type Option func(*Client)
Option configures a Client.
func WithDecodeErrorHandler ¶
WithDecodeErrorHandler receives messages on the client's subscriptions that are not valid JSON Messages. Without it they are dropped.
func WithDefaultTimeout ¶
WithDefaultTimeout replaces DefaultTimeout for requests without a deadline.
type PSIRequest ¶ added in v0.2.0
type PSIRequest struct {
IMSI string // required
// VLRNumber is the serving VLR's address (required). For a combined
// MSC/VLR it is normally the network node number SendRoutingInfoForSM
// returned.
VLRNumber AddressString
// Requested selects what to ask for. MNP is not available here.
Requested RequestedInfo
// VLRPointCode routes on point code instead of the VLR number GT.
VLRPointCode uint32
}
PSIRequest is a MAP ProvideSubscriberInfo towards the VLR serving the subscriber (3GPP TS 29.002 §8.11.2).
type RequestedInfo ¶ added in v0.2.0
type RequestedInfo struct {
// Location asks for the location information of Domain.
Location bool `json:"location,omitempty"`
// CurrentLocation asks the serving node to page the subscriber for an
// up-to-date location instead of the last known one. Requires Location.
CurrentLocation bool `json:"current_location,omitempty"`
// EPSLocation tells the HLR that the E-UTRAN location may be returned,
// in Location.EPS or in SubscriberInfo.LocationEPS. Requires Location.
EPSLocation bool `json:"eps_location,omitempty"`
// State asks for the subscriber state of Domain.
State bool `json:"state,omitempty"`
// Domain is DomainCS (the default when empty) or DomainPS.
Domain string `json:"domain,omitempty"`
// IMEI asks for the equipment identity.
IMEI bool `json:"imei,omitempty"`
// MSClassmark asks for MS Classmark 2, returned for the CS domain.
MSClassmark bool `json:"ms_classmark,omitempty"`
// MNP asks for number portability information. AnyTimeInterrogation only.
MNP bool `json:"mnp,omitempty"`
}
RequestedInfo selects what an AnyTimeInterrogation or ProvideSubscriberInfo asks for (TS 29.002 RequestedInfo). At least one item must be set.
type SRIRequest ¶
type SRIRequest struct {
MSISDN string // required, E.164 digits
ServiceCentreAddress AddressString // required
// HLRGlobalTitle and HLRPointCode override the gateway's map.hlr_gt and
// map.hlr_pc for this request. Leave empty to use the configuration.
HLRGlobalTitle string
HLRPointCode uint32
}
SRIRequest is a MAP SendRoutingInfoForSM request (3GPP TS 29.002 §12.1).
type SRIResult ¶
type SRIResult struct {
IMSI string
// NetworkNodeNumber is the serving MSC/VLR address digits; pass it to
// MTRequest.NetworkNodeNumber.
NetworkNodeNumber string
NodeID string // gateway node that ran the dialogue
Raw *Message
}
SRIResult is a successful SendRoutingInfoForSM answer.
type ServiceAreaID ¶ added in v0.2.0
type ServiceAreaID struct {
MCC string `json:"mcc"`
MNC string `json:"mnc"`
LAC uint16 `json:"lac"`
SAC uint16 `json:"sac"`
}
ServiceAreaID is a service area identity (TS 23.003): SAC is the service area code.
type SubscriberInfo ¶ added in v0.2.0
type SubscriberInfo struct {
// Location is the circuit-switched location (MSC/VLR).
Location *Location `json:"location,omitempty"`
// State is the circuit-switched subscriber state.
State *SubscriberState `json:"state,omitempty"`
// LocationGPRS is the packet-switched location (SGSN).
LocationGPRS *Location `json:"location_gprs,omitempty"`
// PSState is the packet-switched subscriber state.
PSState *SubscriberState `json:"ps_state,omitempty"`
// EPSState is the EPS subscriber state.
EPSState *SubscriberState `json:"eps_state,omitempty"`
// LocationEPS is the EPS location returned outside Location.
LocationEPS *LocationEPS `json:"location_eps,omitempty"`
// IMEI digits (TS 23.003), 15 or 16 of them.
IMEI string `json:"imei,omitempty"`
// MSClassmark2 is the value part of the MS Classmark 2 IE (TS 24.008), hex.
MSClassmark2 string `json:"ms_classmark2,omitempty"`
// MNP is the number portability information.
MNP *MNPInfo `json:"mnp,omitempty"`
}
SubscriberInfo is the answer to an AnyTimeInterrogation or a ProvideSubscriberInfo (TS 29.002 SubscriberInfo): only what was requested and what the network knows is present. Octet strings whose layout another specification defines are passed through as lowercase hex.
type SubscriberInfoResult ¶ added in v0.2.0
type SubscriberInfoResult struct {
Info *SubscriberInfo // never nil
NodeID string // gateway node that ran the dialogue
Raw *Message
}
SubscriberInfoResult is a successful AnyTimeInterrogation or ProvideSubscriberInfo answer.
type SubscriberState ¶ added in v0.2.0
type SubscriberState struct {
State string `json:"state"`
NotReachableReason string `json:"not_reachable_reason,omitempty"`
}
SubscriberState is TS 29.002 SubscriberState (CS) or PS-SubscriberState (PS, EPS). State is the ASN.1 name of the alternative:
- CS: assumedIdle, camelBusy, netDetNotReachable, notProvidedFromVLR;
- PS/EPS: notProvidedFromSGSNorMME, ps-Detached, ps-AttachedNotReachableForPaging, ps-AttachedReachableForPaging, ps-PDP-ActiveNotReachableForPaging, ps-PDP-ActiveReachableForPaging, netDetNotReachable.
NotReachableReason accompanies netDetNotReachable: msPurged, imsiDetached, restrictedArea or notRegistered.