From 2c0d9cd3656ce3289e4e73d96f7c354373a7e759 Mon Sep 17 00:00:00 2001
From: "Gerasimos (Makis) Maropoulos" <kataras2006@hotmail.com>
Date: Sat, 20 Jul 2019 19:14:28 +0300
Subject: [PATCH] add HTTP Referer section

---
 HTTP-referer.md | 83 +++++++++++++++++++++++++++++++++++++++++++++++++
 Home.md         |  1 +
 _Sidebar.md     |  1 +
 3 files changed, 85 insertions(+)
 create mode 100644 HTTP-referer.md

diff --git a/HTTP-referer.md b/HTTP-referer.md
new file mode 100644
index 0000000..0b0a042
--- /dev/null
+++ b/HTTP-referer.md
@@ -0,0 +1,83 @@
+The HTTP referer is an optional HTTP header field that identifies the address of the webpage (i.e. the URI or IRI) which is linked to the resource being requested. By checking the referrer, the new webpage can see where the request originated.
+
+Read more at [wikipedia](https://en.wikipedia.org/wiki/HTTP_referer)
+
+--------
+
+Iris uses the [Shopify's goreferrer](https://github.com/Shopify/goreferrer/pull/27) package to expose the `Context.GetReferrer()` method.
+
+The `GetReferrer` Context's method extracts and returns the information from the `"Referer"` header as specified in https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referrer-Policy or by the URL `query parameter "referer"`.
+
+```go
+GetReferrer() Referrer
+```
+
+Which `Referrer` looks like that:
+
+```go
+type (
+    Referrer struct {
+        Type       ReferrerType
+        Label      string
+        URL        string
+        Subdomain  string
+        Domain     string
+        Tld        string         
+        Path       string              
+        Query      string                 
+        GoogleType ReferrerGoogleSearchType
+    }
+```
+
+The `ReferrerType` is the enum for a Referrer.Type value (indirect, direct, email, search, social). The available types are:
+
+```go
+ReferrerInvalid
+ReferrerIndirect
+ReferrerDirect
+ReferrerEmail
+ReferrerSearch
+ReferrerSocial
+```
+
+The `GoogleType` can be one of those:
+
+```go
+ReferrerNotGoogleSearch
+ReferrerGoogleOrganicSearch
+ReferrerGoogleAdwords
+```
+
+## Example
+
+```go
+package main
+
+import "github.com/kataras/iris"
+
+func main() {
+    app := iris.New()
+
+    app.Get("/", func(ctx iris.Context) {
+        r := ctx.GetReferrer()
+        switch r.Type {
+        case iris.ReferrerSearch:
+            ctx.Writef("Search %s: %s\n", r.Label, r.Query)
+            ctx.Writef("Google: %s\n", r.GoogleType)
+        case iris.ReferrerSocial:
+            ctx.Writef("Social %s\n", r.Label)
+        case iris.ReferrerIndirect:
+            ctx.Writef("Indirect: %s\n", r.URL)
+        }
+    })
+
+    app.Run(iris.Addr(":8080"))
+}
+```
+
+How to `curl`:
+
+```sh
+curl http://localhost:8080?referer=https://twitter.com/Xinterio/status/1023566830974251008
+curl http://localhost:8080?referer=https://www.google.com/search?q=Top+6+golang+web+frameworks&oq=Top+6+golang+web+frameworks
+```
diff --git a/Home.md b/Home.md
index dcf630d..1479392 100644
--- a/Home.md
+++ b/Home.md
@@ -19,6 +19,7 @@ This wiki is the main source of documentation for **developers** working with (o
     * [[Wrap the Router|Routing-wrap-the-router]]
     * [[Override Context|Routing-override-context]]
 * [[API Versioning]]
+* [[HTTP Referer]]
 * [[Request Authentication]]
 * [[URL Query Parameters]]
 * [[Forms]]
diff --git a/_Sidebar.md b/_Sidebar.md
index b8651be..6057489 100644
--- a/_Sidebar.md
+++ b/_Sidebar.md
@@ -14,6 +14,7 @@
     * [[Wrap the Router|Routing-wrap-the-router]]
     * [[Override Context|Routing-override-context]]
 * [[API Versioning]]
+* [[HTTP Referer]]
 * [[Request Authentication]]
 * [[URL Query Parameters]]
 * [[Forms]]