feat: add restriction mode (#370)

Author: tobiasehlert

README.md

@@ -24,6 +24,7 @@ Documentation of API endpoints can be found on [docs.tibiadata.com](https://docs
 - [API documentation](#api-documentation)
   - [Available endpoints](#available-endpoints)
   - [Deprecated endpoints](#deprecated-endpoints)
+  - [Restricted endpoints](#restricted-endpoints)
 - [General information](#general-information)
 - [Credits](#credits)
 
@@ -156,27 +157,15 @@ Those are the current existing endpoints.
 
 ### Deprecated Endpoints
 
-- GET `/health`
-- GET `/v3/boostablebosses`
-- GET `/v3/character/:name`
-- GET `/v3/creature/:race`
-- GET `/v3/creatures`
-- GET `/v3/fansites`
-- GET `/v3/guild/:name`
-- GET `/v3/guilds/:world`
-- GET `/v3/highscores/:world/:category/:vocation/:page`
-- GET `/v3/house/:world/:house_id`
-- GET `/v3/houses/:world/:town`
-- GET `/v3/killstatistics/:world`
-- GET `/v3/news/archive`
-- GET `/v3/news/archive/:days`
-- GET `/v3/news/id/:news_id`
-- GET `/v3/news/latest`
-- GET `/v3/news/newsticker`
-- GET `/v3/spell/:spell_id`
-- GET `/v3/spells`
-- GET `/v3/world/:name`
-- GET `/v3/worlds`
+In addition to the deprecated API versions like v1, v2 and v3, there are also some endpoints that are deprecated. As of now, those are:
+
+- GET `/healthz`
+
+### Restricted endpoints
+
+There are some endpoints that can be deviant between the container documentation and the hosted version. This is due to restricted mode that restrict certain API actions due to high load on the tibia.com servers.
+
+- `/v4/highscores`-filtering on vocation is removed, only the `all` category is valid.
 
 ## General information
 

src/main.go

@@ -15,8 +15,9 @@ var (
 	TibiaDataDefaultVoc string = "all"
 
 	// TibiaData app flags for running
-	TibiaDataAPIversion int = 4
-	TibiaDataDebug      bool
+	TibiaDataAPIversion      int = 4
+	TibiaDataDebug           bool
+	TibiaDataRestrictionMode bool
 
 	// TibiaData app settings
 	TibiaDataHost       string     // set through env TIBIADATA_HOST

src/validation/errors.go

@@ -30,6 +30,10 @@ var (
 	// Code: 9001
 	ErrorStringCanNotBeConvertedToInt = Error{errors.New("the provided string can not be converted to an integer")}
 
+	// ErrorRestrictionMode will be sent if the request contains a page that is not available due to restriction mode
+	// Code: 9002
+	ErrorRestrictionMode = Error{errors.New("the provided page is not available due to restriction mode")}
+
 	// ErrorCharacterNameEmpty will be sent if the request contains an empty character name
 	// Code: 10001
 	ErrorCharacterNameEmpty = Error{errors.New("the provided character name is an empty string")}
@@ -223,6 +227,8 @@ func (e Error) Code() int {
 		return 11
 	case ErrorStringCanNotBeConvertedToInt:
 		return 9001
+	case ErrorRestrictionMode:
+		return 9002
 	case ErrorCharacterNameEmpty:
 		return 10001
 	case ErrorCharacterNameTooSmall:

src/validation/tibia.go

@@ -27,6 +27,16 @@ var (
 	validVocations = []string{"none", "knight", "knights", "paladin", "paladins", "sorcerer", "sorcerers", "druid", "druids", "all"}
 )
 
+// IsRestrictionMode reports whether the restriction mode is enabled
+// Check if error == nil to see whether the restriction mode is enabled or not
+func IsRestrictionMode(mode bool) error {
+	if mode {
+		return ErrorRestrictionMode
+	}
+
+	return nil
+}
+
 // IsNewsIDValid reports wheter the provided int represents a valid news ID
 // Check if error == nil to see whether the ID is valid or not
 func IsNewsIDValid(ID int) error {

src/validation/validation_test.go

@@ -484,6 +484,9 @@ func TestErrors(t *testing.T) {
 		ErrorStringCanNotBeConvertedToInt: {
 			Code: 9001,
 		},
+		ErrorRestrictionMode: {
+			Code: 9002,
+		},
 		ErrorCharacterNameEmpty: {
 			Code: 10001,
 		},
@@ -856,6 +859,18 @@ func TestFake(t *testing.T) {
 	setSpellsVars()
 }
 
+func TestRestrictionMode(t *testing.T) {
+	err := IsRestrictionMode(true)
+	if err == nil {
+		t.Fatal("Restriction mode is enabled but IsRestrictionMode is returning an error")
+	}
+
+	err = IsRestrictionMode(false)
+	if err != nil {
+		t.Fatalf("Restriction mode is disabled but IsRestrictionMode is returning an error: %s", err)
+	}
+}
+
 func TestNewsIDValidator(t *testing.T) {
 	err := IsNewsIDValid(1)
 	if err != nil {

src/webserver.go

@@ -112,6 +112,10 @@ func runWebServer() {
 		_ = router.SetTrustedProxies(nil)
 	}
 
+	// Set the TibiaData restriction mode
+	TibiaDataRestrictionMode = getEnvAsBool("TIBIADATA_RESTRICTION_MODE", false)
+	log.Printf("[info] TibiaData API restriction-mode: %t", TibiaDataRestrictionMode)
+
 	// Set the ping endpoint
 	router.GET("/ping", func(c *gin.Context) {
 		data := Information{
@@ -487,12 +491,13 @@ func tibiaGuildsOverview(c *gin.Context) {
 // Highscores godoc
 // @Summary      Highscores of tibia
 // @Description  Show all highscores of tibia
+// @Description  In restriction mode, the valid vocation option is all.
 // @Tags         highscores
 // @Accept       json
 // @Produce      json
 // @Param        world    path string true "The world" default(all) extensions(x-example=Antica)
 // @Param        category path string true "The category" default(experience) Enums(achievements, axefighting, charmpoints, clubfighting, distancefighting, experience, fishing, fistfighting, goshnarstaint, loyaltypoints, magiclevel, shielding, swordfighting, dromescore, bosspoints) extensions(x-example=fishing)
-// @Param        vocation path string true "The vocation" default(all) Enums(all, knights, paladins, sorcerers, druids) extensions(x-example=knights)
+// @Param        vocation path string true "The vocation" default(all) Enums(all, knights, paladins, sorcerers, druids) extensions(x-example=all)
 // @Param        page     path int    true "The current page" default(1) minimum(1) extensions(x-example=1)
 // @Success      200  {object}  HighscoresResponse
 // @Failure      400  {object}  Information
@@ -547,6 +552,12 @@ func tibiaHighscores(c *gin.Context) {
 	// Sanitize of vocation input
 	vocationName, vocationid := TibiaDataVocationValidator(vocation)
 
+	// Check if restriction mode is enabled
+	if TibiaDataRestrictionMode && vocationName != "all" {
+		TibiaDataErrorHandler(c, validation.ErrorRestrictionMode, http.StatusBadRequest)
+		return
+	}
+
 	// checking the page provided
 	if page == "" {
 		page = "1"