design

Documentation

Overview

Package design contains the API design used for generating goa models and controllers.

Index

• Variables

Variables

var BackupDestination = Type("BackupDestination", func() {
	Param("type", String, func() {
		Description("Specifies the destination type of the backup. Can be 'file' 'download', 's3' or 'server'")
		Example("file")
	})
	Param("path", String, func() {
		Description("Specifies the destination path.\n" +
			"If type is server, this should be ip+port of the other server, eg. 10.0.0.1:8080.\n" +
			"If the type is s3, the source should be specified as s3://bucket/path/file.bin. Replace bucket and path+file",
		)
		Example("./backup.bin")
	})
	Param("server_list_id_suffix", String, func() {
		Description("Optional alternative list id suffix for server-to-server transfers.\n" +
			"If not provided the original list id/segment ids will be used and any existing list will be overwritten.")
	})
	Param("server_list_id_prefix", String, func() {
		Description("Optional alternative list id prefix for server-to-server transfers.\n" +
			"If not provided the original list id/segment ids will be used and any existing list will be overwritten.")
	})
	Required("type")
})

var BackupInfo = MediaType("application/vnd.rankdb.backup_status+json", func() {
	Description("Backup Information")
	Attributes(func() {
		Attribute("cancelled", Boolean, "Will be true if backup was cancelled")
		Attribute("done", Boolean, "Will be true when the backup has finished processing")
		Attribute("uri", String, "URI of backed up content. Used for restore.")
		Attribute("lists", Integer, "Number of lists to be backed up")
		Attribute("lists_done", Integer, "Number of lists backed up now")
		Attribute("storage", String, "Storage used for backup")
		Attribute("size", Integer, "Size of stored data", func() {
			Metadata("struct:field:type", "int64")
		})
		Attribute("custom", HashOf(String, String), "Custom information provided by backup")
		Attribute("started", DateTime, "Time backup was started")
		Attribute("finished", DateTime, "Time backup was finished")
		Attribute("success", ArrayOf(String), func() {
			Description("Successful operations, list IDs")
			Example([]string{"highscore-uk-all"})
		})
		Attribute("errors", HashOf(String, String), func() {
			Description("Failed operations, indexed by list IDs")
			Example(msi{"highscore-dk-all": rankdb.ErrNotFound.Error()})
		})

	})
	Required("done", "cancelled", "lists", "storage", "size", "uri", "started", "lists_done")
	tiny := func() {
		Attribute("cancelled")
		Attribute("done")
		Attribute("lists")
		Attribute("lists_done")
		Attribute("uri")
		Attribute("size")
		Attribute("started")
		Attribute("finished")
	}
	def := func() {
		tiny()
		Attribute("storage")
		Attribute("errors")
		Attribute("custom")
	}
	View("tiny", tiny)
	View("default", def)
	View("full", func() {
		def()
		Attribute("success")
	})
})

BackupInfo backup information.

var Callback = MediaType("application/vnd.rankdb.callback+json", func() {
	Description("Backup Information")
	Attributes(func() {
		Attribute("id", String)
		Attribute("callback_url", String)
	})
	Required("id", "callback_url")
	View("default", func() {
		Attribute("id")
		Attribute("callback_url")
	})
})

var ElementPayload = Type("Element", func() {
	Attribute("id", Integer, func() {
		Description("ID of element")
		Example(100)
		Minimum(0)
		Metadata("struct:field:type", "uint64")

	})
	Attribute("score", Integer, func() {
		Description("Score of the element. Higher score gives higher placement.")
		Example(100)
		Minimum(0)

		Metadata("struct:field:type", "uint64")
	})
	Attribute("tie_breaker", Integer, func() {
		Description("Tie breaker, used if score matches for consistent sorting. Higher value = higher placement if score is equal.")
		Minimum(0)
		Maximum(math.MaxUint32)
		Example(2000)
		Metadata("struct:field:type", "uint32")
	})
	Attribute("payload", HashOf(String, Any), func() {
		Metadata("struct:field:type", "json.RawMessage", "encoding/json")
		Description("Custom payload. Stored untouched. On updates null means do not update. `{}` is the empty value.")
		Example(msi{"name": "Mark Anthony", "country": "dk"})
	})
	Required("id", "score")
})

ElementPayload defines the data structure used in the create element request body.

var ElementRank = MediaType("application/vnd.rankdb.element+json", func() {
	Description("List Element")
	Reference(ElementPayload)
	Attributes(func() {
		Attribute("id")
		Attribute("from_top", Integer, func() {
			Description("Element rank in list from top.\n Top element has value 0.")
			Example(50)
		})
		Attribute("from_bottom", Integer, func() {
			Description("Element rank in list from bottom.\n Bottom element has value 0.")
			Example(4000)
		})
		ListID("list_id")
		Attribute("score")
		Attribute("tie_breaker")
		Attribute("payload")
		Attribute("updated_at", DateTime, "Date of last update")
		Attribute("neighbors", func() {
			Description("Neighbors to current element")
			Attribute("above", CollectionOf("application/vnd.rankdb.element+json"), func() {
				View("default")
				Description("Elements above the current element.\nEnds with element just above current.")
			})
			Attribute("below", CollectionOf("application/vnd.rankdb.element+json"), func() {
				View("default")
				Description("Elements below the current element.\nStarts with element just below current.")
			})
		})
		Attribute("local_from_top", Integer, func() {
			Description("Local element rank in list from top when requesting sub-list.\n Top element has value 0.")
			Example(50)
		})
		Attribute("local_from_bottom", Integer, func() {
			Description("Local element rank in list from bottom when requesting sub-list.\n Bottom element has value 0.")
			Example(4000)
		})

		Attribute("previous_rank", "application/vnd.rankdb.element+json", "Rank of element before update")

		Required("id", "from_top", "from_bottom", "score")
		Required("list_id", "payload", "updated_at", "tie_breaker")
	})

	tiny := func() {
		Attribute("id")
		Attribute("from_top")
		Attribute("from_bottom")
		Attribute("score")
		Attribute("payload")
	}
	def := func() {
		tiny()
		Attribute("list_id")
		Attribute("updated_at")
		Attribute("tie_breaker")
	}
	full := func() {
		def()
		Attribute("neighbors")
		Attribute("local_from_top")
		Attribute("local_from_bottom")
	}

	View("tiny", tiny)
	View("default", def)
	View("full", full)
	View("full-update", func() {
		full()
		Attribute("previous_rank")
	})
})

Element is an element on a rank list.

var ElementRanks = MediaType("application/vnd.rankdb.multielement+json", func() {
	Attributes(func() {
		Attribute("found", CollectionOf("application/vnd.rankdb.element+json"), func() {
			Description("Elements that was found in the list, ordered by score.")
		})
		Attribute("not_found", ArrayOf(Integer), func() {
			Description("Elements that wasn't found in the list. Unordered.")
			Metadata("struct:field:type", "[]uint64")
		})
	})
	View("default", func() {
		Attribute("found")
		Attribute("not_found")
	})
	Required("found")
})

var IncludeTopBottom = func() {
	Param("top_bottom", Boolean, func() {
		Description("Include top_element and bottom_element in result.")
		Default(false)
	})
}

var JWT = JWTSecurity("jwt", func() {
	Header("Authorization")
	Scope("api:read", "API Read Access")
	Scope("api:update", "API Update Access.")
	Scope("api:delete", "API Delete Access.")
	Scope("api:manage", "API Manager Access.")
})

JWT defines a security scheme using JWT. The scheme uses the "Authorization" header to lookup the token. It also defines then scope "api".

var JWTAPIDelete = func() {
	Security(JWT, func() {
		Scope("api:delete")
	})
	Response(Unauthorized, ErrorMedia)
}

var JWTAPIManage = func() {
	Security(JWT, func() {
		Scope("api:manage")
	})
	Response(Unauthorized, ErrorMedia)
}

var JWTAPIRead = func() {
	Security(JWT, func() {
		Scope("api:read")
	})
	Response(Unauthorized, ErrorMedia)
}

var JWTAPIUpdate = func() {
	Security(JWT, func() {
		Scope("api:update")
	})
	Response(Unauthorized, ErrorMedia)
}

var ListID = func(name string) {
	Param(name, String, func() {
		Description("The ID of the list to apply the operation on.\nCan be `a` to `z` (both upper/lower case), `0` to `9` or one of these characters `_-.`")
		MinLength(2)
		MaxLength(100)
		Example("highscore-list")
		Pattern(`^[a-zA-Z0-9-_.]+$`)
	})
}

var ListOpResult = MediaType("application/vnd.rankdb.listopresult+json", func() {
	Description("Result of a list operation. Will contain either an error or a list.")
	Attributes(func() {
		Attribute("error", String, func() {
			Description("Error, if any encountered")
			Example(rankdb.ErrNotFound.Error())
		})
		Attribute("list", RankList, func() {
			View("default")
		})

	})

	View("default", func() {
		Attribute("error")
		Attribute("list")
	})
})

var ListPayloadQL = Type("ListPayloadQL", func() {
	listQL()
	Attribute("payload", ArrayOf(ElementPayload), func() {
		Description("Payloads for create/update functions.\n" + "" +
			"Will be ignored on deletes.")
	})
})

ListPayloadQL defines the data structure used in the create element request body.

var ListQL = Type("ListQL", func() {
	listQL()
})

ListQL defines the query types to access multiple lists

var ListsResult = MediaType("application/vnd.rankdb.listsresult+json", func() {
	Attribute("lists_before", Integer, func() {
		Description("The number of lists before the first element")
	})
	Attribute("lists_after", Integer, func() {
		Description("The number of lists after the last element")
	})
	Attribute("lists", CollectionOf(RankList, func() {
		View("default")
		View("tiny")
	}))
	Required("lists_before", "lists_after", "lists")
	View("default", func() {
		Attribute("lists_before")
		Attribute("lists_after")
		Attribute("lists")
	})
})

var MultiElementPayload = Type("MultiElement", func() {
	Attribute("element_ids", ArrayOf(Integer, func() {
		Description("Element ID")
		Example(100)
		Minimum(0)
		Metadata("struct:field:type", "uint64")
	}), func() {
		Description("IDs of elements")
		Example([]uint64{120, 340, 550})
		Metadata("struct:field:type", "[]uint64")
	})
	Required("element_ids")
})

MultiElementPayload defines the data structure for requesting multiple elements.

var MultiListBackup = Type("MultiListBackup", func() {
	Param("destination", BackupDestination)
	Param("lists", ListQL)
	Required("destination", "lists")
})

MultiListBackup defines the query types to access multiple lists

var OperationSuccess = MediaType("application/vnd.rankdb.operation_success+json", func() {
	Attribute("results", CollectionOf(ElementRank), func() {
		Description("If `results` parameter was true, the resulting element is returned here.")
		View("tiny")
	})
	View("default", func() {
		Attribute("results")
	})
})

var RankList = MediaType("application/vnd.rankdb.ranklist+json", func() {
	Description("Rank List")
	Reference(RankListPayload)
	Attributes(func() {
		Attribute("id")
		Attribute("set")
		Attribute("split_size")
		Attribute("merge_size")
		Attribute("load_index")
		Attribute("metadata")
		Attribute("elements", Integer, func() {
			Description("Number of elements in list")
			Example(15000)
		})
		Attribute("top_element", ElementRank, func() {
			Description("This element is only returned if 'top_bottom' parameter is set to true.")
		})
		Attribute("bottom_element", ElementRank)
		Attribute("segments", Integer, func() {
			Description("Number of segment in list")
			Example(15)
		})
		Attribute("avg_segment_elements", Number, func() {
			Description("Average number of elements per segment")
			Example(1005.5)
		})
		Attribute("cache_hits", Integer, func() {
			Description("Cache hits while segments have been loaded.")
			Example(643)
		})
		Attribute("cache_misses", Integer, func() {
			Description("Cache misses while segments have been loaded.")
			Example(123)
		})
		Attribute("cache_percent", Number, func() {
			Description("Cache hit percentage while segments have been loaded.")
			Example(64.56)
		})
	})
	Required("id")
	Required("set", "metadata")
	Required("segments", "elements", "avg_segment_elements")
	Required("split_size", "merge_size", "load_index")
	Required("cache_hits", "cache_misses", "cache_percent")

	tiny := func() {
		Attribute("id")
	}
	View("tiny", func() {
		tiny()
	})

	def := func() {
		tiny()
		Attribute("set")
		Attribute("metadata")
		Attribute("split_size")
		Attribute("merge_size")
		Attribute("load_index")
	}
	View("default", func() {
		def()
	})

	View("full", func() {
		def()
		Attribute("segments")
		Attribute("avg_segment_elements")
		Attribute("elements")
		Attribute("top_element")
		Attribute("bottom_element")
		Attribute("cache_hits")
		Attribute("cache_misses")
		Attribute("cache_percent")
	})
})

RankList is the rank list resource media type.

var RankListPayload = Type("RankList", func() {
	ListID("id")
	Attribute("set", String, func() {
		Description("Set used for storage")
		MinLength(2)
		MaxLength(100)
		Example("storage-set")
	})
	Attribute("metadata", HashOf(String, String), func() {
		Description("Custom metadata. String to String hash.")
		Example(mss{"game": "2", "country": "dk"})
	})
	Attribute("split_size", Integer, func() {
		Description("Split Segments larger than this number of entries")
		Minimum(10)
		Maximum(1e5)
		Default(2000)
		Example(2000)
	})
	Attribute("merge_size", Integer, func() {
		Description("Merge adjacent Segments with less than this number of entries")
		Minimum(10)
		Maximum(1e5)
		Default(500)
		Example(500)
	})
	Attribute("load_index", Boolean, func() {
		Description("Load Index on server startup")
		Default(false)
	})
	Attribute("populate", ArrayOf(ElementPayload), func() {
		Description("Populate list with specified elements")
	})
	Required("id", "set")
})

RankListPayload defines the data structure used in the create bottle request body. It is also the base type for the bottle media type used to render bottles.

var RestoreResultList = MediaType("application/vnd.rankdb.restoreresult+json", func() {
	Attributes(func() {
		Attribute("restored", Integer, func() {
			Description("Successful restore operations, indexed by list IDs")
			Example(20)
		})
		Attribute("skipped", Integer, func() {
			Description("Skipped lists, indexed by list IDs")
			Example(1)
		})
		Attribute("errors", HashOf(String, String), func() {
			Description("Failed operations, indexed by list IDs")
			Example(msi{"highscore-dk-all": rankdb.ErrNotFound.Error()})
		})
	})
	Required("restored", "skipped", "errors")
	View("default", func() {
		Attribute("restored")
		Attribute("skipped")
		Attribute("errors")
	})
})

var ResultList = MediaType("application/vnd.rankdb.resultlist+json", func() {
	Attributes(func() {
		Attribute("success", HashOf(String, OperationSuccess), func() {
			Description("Successful operations, indexed by list IDs")
			Example(msi{"highscore-uk-all": msi{}})
		})
		Attribute("errors", HashOf(String, String), func() {
			Description("Failed operations, indexed by list IDs")
			Example(msi{"highscore-dk-all": rankdb.ErrNotFound.Error()})
		})
	})
	View("default", func() {
		Attribute("success")
		Attribute("errors")
		Required("success", "errors")
	})
})

var SysInfo = MediaType("application/vnd.rankdb.sysinfo+json", func() {
	Description("System Info. The model is sparse and may contain other information.")
	Attributes(func() {
		Attribute("memory", HashOf(String, Any), "Memory Information", func() {
			Example(msi{"Alloc": 621480, "TotalAlloc": 621480, "Sys": 4262136, "Lookups": 5, "Mallocs": 5940})
		})
		Attribute("element_cache", HashOf(String, Any), "Element Cache Information", func() {
			Example(msi{"current_entries": 5000, "max_size": 10000})
		})
		Attribute("lazy_saver", HashOf(String, Any), func() {
			Description("Lazy saver cache information.")
			Metadata("struct:field:type", "json.RawMessage", "encoding/json")
			Example(msi{"current_entries": 5000, "max_size": 10000})
		})
	})

	View("default", func() {
		Attribute("memory")
		Attribute("element_cache")
		Attribute("lazy_saver")
	})
})

SysInfo is the account resource media type.