Parse messy JIRA URLs into a canonicalised format

README.md

@@ -145,6 +145,45 @@ curl -X POST localhost:4050/admin/configureService --data-binary '{
 
 This request will make `BotUserID` join the `Rooms` specified and create webhooks for the `owner/repo` projects given.
 
+
+## Starting a JIRA Service
+
+### Register a JIRA realm
+
+Generate an RSA private key: (JIRA does not support key sizes >2048 bits)
+
+```bash
+openssl genrsa -out privkey.pem 2048
+```
+
+
+
+```
+curl -X POST localhost:4050/admin/configureAuthRealm --data-binary '{
+    "ID": "jirarealm",
+    "Type": "jira",
+    "Config": {
+        "ConsumerName": "goneb",
+        "ConsumerKey": "goneb",
+        "ConsumerSecret": "random_long_string",
+        "PrivateKeyPEM": "-----BEGIN RSA PRIVATE KEY-----\r\nMIIEowIBAAKCAQEA39UhbOvQHEkBP9fGnhU+eSObTWBDGWygVYzbcONOlqEOTJUN\r\n8gmnellWqJO45S4jB1vLLnuXiHqEWnmaShIvbUem3QnDDqghu0gfqXHMlQr5R8ZP\r\norTt1F2idWy1wk5rVXeLKSG7uriYhDVOVS69WuefoW5v55b5YZV283v2jROjxHuj\r\ngAsJA7k6tvpYiSXApUl6YHmECfBoiwG9bwItkHwhZ\/fG9i4H8\/aOyr3WlaWbVeKX\r\n+m38lmYZvzQFRAk5ab1vzCGz4cyc\r\nTk2qmZpcjHRd1ijcOkgC23KF8lHWF5Zx0tySR+DWL1JeGm8NJxKMRJZuE8MIkJYF\r\nryE7kjspNItk6npkA3\/A4PWwElhddI4JpiuK+29mMNipRcYYy9e0vH\/igejv7ayd\r\nPLCRMQKBgBDSNWlZT0nNd2DXVqTW9p+MG72VKhDgmEwFB1acOw0lpu1XE8R1wmwG\r\nZRl\/xzri3LOW2Gpc77xu6fs3NIkzQw3v1ifYhX3OrVsCIRBbDjPQI3yYjkhGx24s\r\nVhhZ5S\/TkGk3Kw59bDC6KGqAuQAwX9req2l1NiuNaPU9rE7tf6Bk\r\n-----END RSA PRIVATE KEY-----"
+    }
+}'
+```
+
+Returns:
+
+
+
+### Make a request for JIRA Auth
+
+TODO
+
+### Create a JIRA bot
+
+TODO
+
+
 # Developing on go-neb.
 
 There's a bunch more tools this project uses when developing in order to do

src/github.com/matrix-org/go-neb/realms/jira/jira.go

@@ -6,7 +6,7 @@ import (
 	"encoding/json"
 	"encoding/pem"
 	"errors"
-	log "github.com/Sirupsen/logrus"
+	"github.com/matrix-org/go-neb/realms/jira/urls"
 	"github.com/matrix-org/go-neb/types"
 	"net/http"
 )
@@ -34,14 +34,27 @@ func (r *jiraRealm) Register() error {
 	if r.ConsumerName == "" || r.ConsumerKey == "" || r.ConsumerSecret == "" || r.PrivateKeyPEM == "" {
 		return errors.New("ConsumerName, ConsumerKey, ConsumerSecret, PrivateKeyPEM must be specified.")
 	}
-	log.Print("Registering..")
+	if r.JIRAEndpoint == "" {
+		return errors.New("JIRAEndpoint must be specified")
+	}
+
 	// Make sure the private key PEM is actually a private key.
 	err := r.parsePrivateKey()
 	if err != nil {
 		return err
 	}
 
-	// TODO: Check to see if JIRA endpoint is valid and known
+	// Parse the messy input URL into a canonicalised form.
+	ju, err := urls.ParseJIRAURL(r.JIRAEndpoint)
+	if err != nil {
+		return err
+	}
+
+	// Check to see if JIRA endpoint is valid by pinging an endpoint
+	err = jiraClient(ju, "")
+	if err != nil {
+		return err
+	}
 
 	return nil
 }
@@ -100,6 +113,10 @@ func publicKeyAsPEM(pkey *rsa.PrivateKey) (string, error) {
 	return string(pem.EncodeToMemory(&block)), nil
 }
 
+func jiraClient(u urls.JIRAURL, userID string) error {
+	return nil
+}
+
 func init() {
 	types.RegisterAuthRealm(func(realmID string) types.AuthRealm {
 		return &jiraRealm{id: realmID}

src/github.com/matrix-org/go-neb/realms/jira/urls/urls.go

@@ -0,0 +1,107 @@
+// Package urls handles converting between various JIRA URL representations in a consistent way. There exists three main
+// types of JIRA URL which Scalar cares about:
+//    - URL Keys => matrix.org/jira
+//    - Base URLs => https://matrix.org/jira/
+//    - REST URLs => https://matrix.org/jira/rest/api/2/issue/12680
+// When making outbound requests to JIRA, Scalar needs to use the Base URL representation. Likewise, when Scalar
+// sends Matrix messages with JIRA URLs in them, the Base URL needs to be used to form the URL. The URL Key is
+// used to determine equivalence of various JIRA installations and is mainly required when searching the database.
+// The REST URLs are present on incoming webhook events and are the only way to map the event to a JIRA installation.
+package urls
+
+import (
+	"errors"
+	"net/url"
+	"strings"
+)
+
+// JIRAURL contains the parsed representation of a JIRA URL
+type JIRAURL struct {
+	Base string // The base URL of the JIRA installation. Always has a trailing / and a protocol.
+	Key  string // The URL key of the JIRA installation. Never has a trailing / or a protocol.
+	Raw  string // The raw input URL, if given. Freeform.
+}
+
+// ParseJIRAURL parses a raw input URL and returns a struct which has various JIRA URL representations. The input
+// URL can be a JIRA REST URL, a speculative base JIRA URL from a client, or a URL key. The input string will be
+// stored as under JIRAURL.Raw. If a URL key is given, this struct will default to https as the protocol.
+func ParseJIRAURL(u string) (j JIRAURL, err error) {
+	if u == "" {
+		err = errors.New("No input JIRA URL")
+		return
+	}
+	j.Raw = u
+	// URL keys don't have a protocol, everything else does
+	if !strings.HasPrefix(u, "https://") && !strings.HasPrefix(u, "http://") {
+		// assume input is a URL key
+		k, e := makeURLKey(u)
+		if e != nil {
+			err = e
+			return
+		}
+		j.Key = k
+		j.Base = makeBaseURL(u)
+		return
+	}
+	// Attempt to parse out REST API paths. This is a horrible heuristic which mostly works.
+	if strings.Contains(u, "/rest/api/") {
+		j.Base = makeBaseURL(strings.Split(u, "/rest/api/")[0])
+	} else {
+		// Assume it already is a base URL
+		j.Base = makeBaseURL(u)
+	}
+
+	k, e := makeURLKey(j.Base)
+	if e != nil {
+		err = e
+		return
+	}
+	j.Key = k
+	return
+}
+
+// SameJIRAURL returns true if the two given JIRA URLs are pointing to the same JIRA installation.
+// Equivalence is determined solely by the provided URLs, by sanitising them then comparing.
+func SameJIRAURL(a, b string) bool {
+	ja, err := ParseJIRAURL(a)
+	if err != nil {
+		return false
+	}
+	jb, err := ParseJIRAURL(b)
+	if err != nil {
+		return false
+	}
+	return ja.Key == jb.Key
+}
+
+// makeBaseURL assumes the input is a base URL and makes sure that the string conforms to JIRA Base URL rules:
+//  - Must have a protocol
+//  - Must have a trailing slash
+// Defaults to HTTPS if there is no protocol specified.
+func makeBaseURL(s string) string {
+	if !strings.HasPrefix(s, "https://") && !strings.HasPrefix(s, "http://") {
+		s = "https://" + s
+	}
+	return withTrailingSlash(s)
+}
+
+// makeURLKey assumes the input is a URL key and makes sure that the string conforms to JIRA URL Key rules:
+//  - Must not have a protocol
+//  - Must not have a trailing slash
+// For example:
+//   https://matrix.org/jira/  =>  matrix.org/jira
+func makeURLKey(s string) (string, error) {
+	u, err := url.Parse(s)
+	if err != nil {
+		return "", err
+	}
+	return u.Host + strings.TrimSuffix(u.Path, "/"), nil
+}
+
+// withTrailingSlash makes sure the input string has a trailing slash. Will not add one if one already exists.
+func withTrailingSlash(s string) string {
+	if strings.HasSuffix(s, "/") {
+		return s
+	}
+	return s + "/"
+}

src/github.com/matrix-org/go-neb/realms/jira/urls/urls_test.go

@@ -0,0 +1,45 @@
+package urls
+
+import (
+	"testing"
+)
+
+var urltests = []struct {
+	in      string
+	outKey  string
+	outBase string
+	outRaw  string
+}{
+	// valid url key as input
+	{"matrix.org/jira", "matrix.org/jira", "https://matrix.org/jira/", "matrix.org/jira"},
+	// valid url base as input
+	{"https://matrix.org/jira/", "matrix.org/jira", "https://matrix.org/jira/", "https://matrix.org/jira/"},
+	// valid rest url as input
+	{"https://matrix.org/jira/rest/api/2/issue/12680", "matrix.org/jira", "https://matrix.org/jira/", "https://matrix.org/jira/rest/api/2/issue/12680"},
+	// missing trailing slash as input
+	{"https://matrix.org/jira", "matrix.org/jira", "https://matrix.org/jira/", "https://matrix.org/jira"},
+	// missing protocol but with trailing slash
+	{"matrix.org/jira/", "matrix.org/jira", "https://matrix.org/jira/", "matrix.org/jira/"},
+	// no jira path as base url (subdomain)
+	{"https://jira.matrix.org", "jira.matrix.org", "https://jira.matrix.org/", "https://jira.matrix.org"},
+	// explicit http as input
+	{"http://matrix.org/jira", "matrix.org/jira", "http://matrix.org/jira/", "http://matrix.org/jira"},
+}
+
+func TestParseJIRAURL(t *testing.T) {
+	for _, urltest := range urltests {
+		jURL, err := ParseJIRAURL(urltest.in)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if jURL.Key != urltest.outKey {
+			t.Fatalf("ParseJIRAURL(%s) => Key: Want %s got %s", urltest.in, urltest.outKey, jURL.Key)
+		}
+		if jURL.Base != urltest.outBase {
+			t.Fatalf("ParseJIRAURL(%s) => Base: Want %s got %s", urltest.in, urltest.outBase, jURL.Key)
+		}
+		if jURL.Raw != urltest.outRaw {
+			t.Fatalf("ParseJIRAURL(%s) => Raw: Want %s got %s", urltest.in, urltest.outRaw, jURL.Raw)
+		}
+	}
+}