Projekti

Yleinen

Profile

SipOHttp(s) proxy

Lisää sipmessages-endpointin REST APIin, sen kautta voi keskustella SIP-serverin kanssa. Viestiin tulee SIP-käyttäjätunnus ja salasana mukaan, joten käyttö vain HTTPS:n kanssa.

KD-4439: https://tiketti.koha-suomi.fi/issues/4439

Viestintä

REST-rajapinnan kutsuma SipOHttp.pm -moduli keskustelee sip-palvelimen kanssa Socketeilla, joiden välinen yhteys luodaan SipOHttp.pm-modulissa aina uuden viestin saapuessa endpointiin (käynnistää SipOHttp.pm-modulin process-metodin). Kun viesti on käsitelty, socket-yhteys katkeaa.

Laitteet, jotka käyttävät sipohttp:tä tarvitsevat SIPConfig.xml:ssä määritettyjen tietojen (sama, kuin xml:n login-parametri, jolla laite tunnistautuu sip-palvelimelle) mukaisen määrityksen määritystiedostoon <Sipdevices></Sipdevices> sisään. Määritykseen lisätään ip ja portti, mitkä kertovat, missä osoitteessa sijaitsevaan sip-palvelimeen viestit on lähetettävä.

Esimerkki määritystiedostosta sip2ohttp-config.xml:

<?xml version='1.0' encoding='UTF-8' standalone="yes" ?>

<Config>

    <!-- Configuration -->

    <!-- log levels: info, error -->

        <logfile>/home/koha/koha-dev/var/log/SIPoHTTP.log</logfile>
        <loglevel>info</loglevel>

    <!-- Device logins and sip server host:port to use -->

    <Sipdevices>

        <SIPDEVICE>
            <host>10.0.3.217</host>
            <port>6009</port>
        </SIPDEVICE>
        <sipdevice2>
            <host>10.0.3.217</host>
            <port>6010</port>
        </sipdevice2>

    </Sipdevices>

</Config>

SipOHttp.pm

Kun rajapinnan sipmessages-polku vastaanottaa POST-viestin, SIPoHTTP.pm tarkistaa, että pyynnön bodyssa kulkee XML-muotoinen viesti sisältäen SIP-viestin.
XML-muotoisen viestin on noudatettava seuraavaa xml-skeemaa: /koha/Koha/koha-tmpl/sipschema.xsd

<?xml version="1.0" encoding="UTF-8"?>

<!-- sipschema.xsd  $Revision: 1.0 $ support@koha-suomi.fi -->

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:ns1="https://koha-suomi.fi/sipschema.xsd" targetNamespace="https://koha-suomi.fi/sipschema.xsd" elementFormDefault="unqualified" attributeFormDefault="unqualified">

  <xs:element name="sip">

    <xs:complexType>

      <xs:choice>

        <xs:element name="request" type="xs:string"/>

        <xs:element name="response" type="xs:string"/>

        <xs:element name="error" type="xs:string"/>

      </xs:choice>

      <xs:attribute name="login" type="xs:string"/>

      <xs:attribute name="password" type="xs:string"/>

    </xs:complexType>

  </xs:element>

</xs:schema>

XML-viestiä verrataan tähän skeematiedostoon ja jos xml-rakenteessa on virheitä, skripti palauttaa rajapintaan virhekoodin.
Jos viesti on oikean muotoinen, siitä puretaan SIP-viesti. Laite, minkä tunnistautuminen vaaditaan, puretaan "login:" ja "password" tiedosta XML:n sisällä. Näillä tiedoilla rakennetaan sip-palvelimelle viesti autentikointia varten. Jos autentikointi onnistuu ja sip-palvelin vastaa "941", lähetetään itse xml:n <request></request> sisällä oleva sip-viesti. Palautuneesta SIP-viestistä muodostetaan xml-muotoinen paluuviesti.

Viesti välitetään rajapintaan vastauksena POST-pyyntöön response bodyssa.

Mikäli sip-laitteen tunnistautuminen ei onnistu, palautetaan rajapintaan sip-palvelimen palauttama "940" ja viestin käsittely keskeytyy.

Virhetilanteet ja loki

SipOHttp-skripti palauttaa rajapinnan kautta seuraavat virheilmoitukset response bodyssa POST-kyselyihin:

- XML validointi epäonnistui skeematiedostoa vastaan: HTTP-virhe 400 viestillä "Invalid Request. Validation failed." 
- Jos sip-serveriin ei saada yhteyttä: HTTP 500 "Something went wrong, check the logs."
- Jos XML-viestin "login:" tai "password:" parametria vastaavia asetuksia ei löydy sip2ohttp-config.xml:stä tai ne ovat puutteelliset: HTTP 400 "Invalid request. No config found for login device."

Käyttöönotto

SipOHttp on production-haarassa, commit f90a020b3c01e17302652cf1cd08dba5c504535b

- kopioi Koha/koha-tmpl/sipschema.xsd koha-dev/koha-tmpl/ - vaatii myös että tämä tiedosto on saatavilla osoitteesta https://koha-suomi.fi/sipschema.xsd
- kopioi Koha/etc/sip2ohttp-config.xml koha-dev/etc/
- muokkaa tuota sip2ohttp-config.xml -tiedostoa, lisää sinne jokaista SIP-käyttäjätunnusta varten jonka pitää pystyä käyttämään tätä sipmessages-endpointtia seuraavaa:

  <LOGINNIMI>
     <host>127.0.0.1</host>
     <port>6009</host>
  </LOGINNIMI>

Korvaa LOGINNIMI sillä SIP-käyttäjätunnuksella. host ja port -arvot vastaavat SIP-palvelimen iipparia ja porttia, jonka kanssa tuolla tunnuksella jutellaan.

Testaus

Endpointtia voi testata komentoriviltä esim. curlilla:

curl -X POST -H 'Content-Type: application/xml' -H 'Accept: text/html' 'https://127.0.0.1:8086/api/v1/sipmessages?query=XXX'

Korvaa IP ja portti tarvittaviksi. XXX korvataan seuraavanlaisella XML:llä (joka pitää URL-enkoodata):

 <?xml version="1.0" encoding="UTF-8"?>
 <ns1:sip login="LOGINNIMI" password="SALASANA" xsi:schemaLocation="https://koha-suomi.fi/sipschema.xsd"  xmlns:ns1="https://koha-suomi.fi/sipschema.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <request>9900302.00</request>
 </ns1:sip>

Vaihda LOGINNIMI ja SALASANA siihen SIP-käyttäjätunnukseen ja sen salasanaan. query-parametri sisältää halutun SIP-komennon.

curl -X POST \
     --insecure \
     --header 'Content-Type: application/xml' \
     --header 'Accept: text/html' \
     'https://127.0.0.1:8086/api/v1/sipmessages?query=%3C%3Fxml+version%3D%221.0%22+encoding%3D%22UTF-8%22%3F%3E%3Cns1%3Asip+login%3D%22LOGINNIMI%22+password%3D%22SALASANA%22+xsi%3AschemaLocation%3D%22https%3A%2F%2Fkoha-suomi.fi%2Fsipschema.xsd%22+xmlns%3Ans1%3D%22https%3A%2F%2Fkoha-suomi.fi%2Fsipschema.xsd%22+xmlns%3Axsi%3D%22http%3A%2F%2Fwww.w3.org%2F2001%2FXMLSchema-instance%22%3E%3Crequest%3E9900302.00%3C%2Frequest%3E%3C%2Fns1%3Asip%3E'

tai, parempi tapa on lähettää XML-data bodyssä, jolloin salasana ja käyttäjätunnus eivät jää http-serverin logiin:

curl -X POST \
     --header 'Content-Type: application/xml' \
     --header 'Accept: text/html' \
     -d '<?xml version="1.0" encoding="UTF-8"?><ns1:sip login="LOGINNIMI" password="SALASANA" xsi:schemaLocation="https://koha-suomi.fi/sipschema.xsd"  xmlns:ns1="https://koha-suomi.fi/sipschema.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><request>9900302.00</request></ns1:sip>' \
     'https://127.0.0.1/api/v1/sipmessages'

Koodin parannusta (TODO)

- Tällä hetkellä vastaus-XML on kovakoodattu (kts. buildXml() SIPoHTTP.pm:ssä), tämän voisi parametroida joko template-tiedostoksi, tai esim. Kohan systempreferenceksi.
- Vaatiiko SIP-merkkijono enkoodausta/dekoodausta? Jos siinä käytetään &lt; merkkiä, niin osaako xml-parseri automaattisesti muuttaa sen < merkiksi?
- Sip2oHttp-config.xml on vähän turhan oloinen, sen voisi ehkä tehdä pelkkänä sipin asetuksena, systempreffinä, tai jtn muuta?