podium

README

Podium

A leaderboard system written in Go using Redis database. For more info, read the docs.

Features

• Multi-tenant - Just vary the name of the leaderboard and you can have any number of tenants using leaderboards;
• Seasonal Leaderboards - Including suffixes like year2016week01 or year2016month06 is all you need to create seasonal leaders. I'm serious! That's all there is to it;
• No leaderboard configuration - Just start notifying scores for members of a leaderboard. There's no need to create, configure or maintain leaderboards. Let Podium do that for you;
• Top Members - Get the top members of a leaderboard whether you need by absolute value (top 200 members) or percentage (top 3% members);
• Members around me - Podium easily returns members around a specific member in the leaderboard. It will even compensate if you ask for the top member or last member to make sure you get a consistent amount of members;
• Batch score update - In a single operation, send a member score to many different leaderboards or many members score to the same leaderboard. This allows easy tracking of member rankings in several leaderboards at once (global, regional, clan, etc.);
• Easy to deploy - Podium comes with containers already exported to docker hub for every single of our successful builds. Just pick your choice!
• Leaderboards with expiration - If a player last update is older than (timeNow - X seconds), delete it from the leaderboard;
• Use as library - You can use podium as a library as well, adding leaderboard functionality directly to your application;

Installation

Install Leaderboard using the "go get" command:

go get github.com/topfreegames/podium

And then run

make setup

Quickstart (for using as library)

import (
	"context"
	"fmt"
	"log"

	"github.com/topfreegames/podium/leaderboard"
)

func main() {
	leaderboards, err := leaderboard.NewClient("localhost", 1234, "", 0, 200)
	if err != nil {
		log.Fatalf("leaderboard.NewClient failed: %v", err)
	}

	const leaderboardID = "myleaderboardID"

	//setting player scores
	players := leaderboard.Members{
		&leaderboard.Member{Score: 10, PublicID: "player1"},
		&leaderboard.Member{Score: 20, PublicID: "player2"},
	}

	err = leaderboards.SetMembersScore(context.Background(), leaderboardID, players, false, "")
	if err != nil {
		log.Fatalf("leaderboards.SetMembersScore failed: %v", err)
	}

	//getting the leaders of the leaderboard
	leaders, err := leaderboards.GetLeaders(context.Background(), leaderboardID, 10, 1, "desc")
	if err != nil {
		log.Fatalf("leaderboards.GetLeaders failed: %v", err)
	}

	for _, player := range leaders {
		fmt.Printf("Player(id: %s, score: %d rank: %d)\n", player.PublicID, player.Score, player.Rank)
	}
}

Testing

make test

Coverage

make test-coverage test-coverage-html

Benchmarks

Podium benchmarks prove it's blazing fast:

BenchmarkSetMemberScore-8                           30000        284307 ns/op       0.32 MB/s        5635 B/op         81 allocs/op
BenchmarkSetMembersScore-8                           5000       1288746 ns/op       3.01 MB/s       51452 B/op        583 allocs/op
BenchmarkIncrementMemberScore-8                     30000        288306 ns/op       0.32 MB/s        5651 B/op         81 allocs/op
BenchmarkRemoveMember-8                             50000        202398 ns/op       0.08 MB/s        4648 B/op         68 allocs/op
BenchmarkGetMember-8                                30000        215802 ns/op       0.33 MB/s        4728 B/op         68 allocs/op
BenchmarkGetMemberRank-8                            50000        201367 ns/op       0.28 MB/s        4712 B/op         68 allocs/op
BenchmarkGetAroundMember-8                          20000        397849 ns/op       3.14 MB/s        8703 B/op         69 allocs/op
BenchmarkGetTotalMembers-8                          50000        192860 ns/op       0.16 MB/s        4536 B/op         64 allocs/op
BenchmarkGetTopMembers-8                            20000        306186 ns/op       3.85 MB/s        8585 B/op         66 allocs/op
BenchmarkGetTopPercentage-8                          1000      10011287 ns/op      11.88 MB/s      510300 B/op         77 allocs/op
BenchmarkSetMemberScoreForSeveralLeaderboards-8      1000     106129629 ns/op       1.03 MB/s      516103 B/op         98 allocs/op
BenchmarkGetMembers-8                                2000       3931289 ns/op       9.13 MB/s      243755 B/op         76 allocs/op

To run the benchmarks: make bench-redis bench-podium-app bench-run.

Our builds also show the difference to the previous build.

License

© 2016, Top Free Games. Released under the MIT License.

Forked from: © 2013, Maxwell Dayvson da Silva.