New documentation for README + contribution

CONTRIBUTING.md

@@ -0,0 +1,19 @@
+# How to Contribute
+
+We'd love to accept your contributions to this project - there are just a few small guidelines you need to follow.
+
+## Submitting code via pull requests
+* All code must be submitted via pull requests.
+* We follow the [GitHub Pull Request Model](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) for all contrubitions.
+* For large bodies of work, please open an issue first to discuss the work with the team describing the feature you
+would like to build and how you plan to implement it.
+* All submissions will require review before being merged.
+* Please follow our style guides for [**Java**](todo), [**Golang**](todo) and [**Protobuf**](docs/PROTO_STYLE.md).
+
+## Additional instructions for protobuf changes
+Make sure to run the `gen/generate.sh` script before committing any changes. This will ensure changes to protobuf
+files are reflected in the generated code. Java code is auto-generated on gradle build.
+
+## Project Layout
+
+Protobuf files are located in the `src/proto` directory.

docs/PROTO_STYLE.md

@@ -0,0 +1,78 @@
+# Protobuf Style Guide
+
+This guide extends from the official style guide, in that everything outlined in the official style guide is also
+recommended to be used here. As such, anything included in the official style guide has been omitted here for the
+sake of brevity.
+
+The official style guide can be found [here](https://protobuf.dev/programming-guides/style/).
+
+Every file in this repository should use the proto version 3 syntax.
+
+## Service naming
+
+* Every service should be named in PascalCase.
+* The use of generic terms such as 'Service' or 'Manager' in the service name should be avoided (e.g. call it `McPlayer` not `McPlayerService`)
+
+## Directory structure
+
+* Every service should have its own directory where only its declarations live.
+* This directory should be named the same as the service but in snake_cast (e.g. `mc_player`)
+
+## File naming
+
+Each service is generally made up of three components:
+* service RPC declarations, requests/responses and error responses (`grpc.proto`)
+* models that are used by the service to model data (`models.proto`), e.g. a user, player, or game type
+* the messages (events) that can be sent by the service over Kafka (`messages.proto`), e.g. a user being created, or a game being started
+
+## Package naming
+
+### Protobuf
+* The full name should be `emortal.<component>.<service>` where the component is either `grpc`, `model`, or `message`
+* The service part of the package name should be in lower snake_case
+
+An example of this would be for a service called McPlayer the package will be `emortal.grpc.mc_player`
+
+### Java
+* The full name should be `dev.emortal.api.<component>.<service>` where the component is either `grpc`, `model`, or `message`
+* The service part of the package name should be in lower case with no spaces
+
+An example of this would be for a service called McPlayer the package will be `dev.emortal.api.grpc.mcplayer`
+
+### Go
+* The full name should be `github.com/emortalmc/proto-specs/gen/go/<component>/<service>`
+* The service part of the package name should be in lower case with no spaces (same as Java)
+
+An example of this would be for a service called McPlayer the package will be `github.com/emortalmc/proto-specs/gen/go/grpc/mcplayer`
+
+## Documentation
+
+All elements should be well documented, as advised in the [API Best Practices](https://protobuf.dev/programming-guides/api/).
+
+The general rule of thumb is try to document things like they are going to be read by someone who has no idea how
+any of the system works, and is trying to figure it out.
+
+## Generated Code Options
+
+### Java
+
+TODO - Apply this convention everywhere
+
+For gRPC declarations (`grpc.proto` file), the option `java_outer_classname` should be set to the name of the service (in pascal case),
+with the suffix "Proto" appended to it. For example, the name for a service called "McPlayer" would be "McPlayerProto".
+
+For other declarations (`messages.proto` and `models.proto`), the option `java_multiple_files` should be used instead
+which will generate a separate Java file for each message declaration.
+
+## Errors
+
+Always prefer using existing status codes over a custom error response, however, don't stretch it to a point of
+ambiguity and don't use a combination of both status codes and custom error responses. Use custom error codes when:
+* There are multiple errors that fit into the same status code
+* There isn't a clear status code that fits the error
+* You want to provide additional information or context to the error to the client
+
+If existing status codes aren't sufficient you should define your own error response named `<RequestName>ErrorResponse`
+(e.g. `CreateUserErrorResponse`) and include it in the service's `grpc.proto` file.
+It should be after the `<RequestName>Response` message. This message should contain an enum called `Reason` and be
+specified in a field called `reason` at index 1.

src/proto/README.md

@@ -0,0 +1,15 @@
+# EmortalMC proto-specs
+
+This repository contains the protobuf specifications for all EmortalMC APIs.
+
+## How to Contribute
+
+Please read out [contributing guidelines](CONTRIBUTING.md) for more information.
+
+## Project Layout
+
+* **Protobuf** files are located at `src/proto`.
+* **Autogenerated Java code** is created by `gradlew generateProto` and run during `gradlew build`.
+* **Additional Java code** is located at `src/java`.
+* **Autogenerated Go code** is located at `gen/go`.
+* **Additional Go code** is located at `gen/go/nongenerated`.

src/proto/account_conn_manager/grpc.proto → src/proto/account_connection/grpc.proto

@@ -1,13 +1,13 @@
 syntax = "proto3";
-package emortal.grpc.account_conn_manager;
+package emortal.grpc.account_connection;
 
-option java_package = "dev.emortal.api.grpc.accountconnmanager";
-option java_outer_classname = "AccountConnManagerProto";
-option go_package = "github.com/emortalmc/proto-specs/gen/go/grpc/accountconnmanager";
+option java_package = "dev.emortal.api.grpc.accountconnection";
+option java_outer_classname = "AccountConnectionProto";
+option go_package = "github.com/emortalmc/proto-specs/gen/go/grpc/accountconnection";
 
-import "account_conn_manager/models.proto";
+import "account_connection/models.proto";
 
-service AccountConnectionManager {
+service AccountConnection {
   rpc GetUser(GetUserRequest) returns (GetUserResponse);
   rpc CreateOAuthLink(CreateOAuthLinkRequest) returns (CreateOAuthLinkResponse);
 }
@@ -21,7 +21,7 @@ message GetUserRequest {
 }
 
 message GetUserResponse {
-  model.account_conn_manager.ConnectionUser user = 1;
+  model.account_connection.ConnectionUser user = 1;
 }
 
 // CreateOAuthLinkRequest requests an OAuth URL to link an account to another.
@@ -32,7 +32,7 @@ message CreateOAuthLinkRequest {
     int64 source_github_id = 3;
   }
 
-  model.account_conn_manager.ConnectionType target_connection = 4;
+  model.account_connection.ConnectionType target_connection = 4;
 }
 
 message CreateOAuthLinkResponse {
@@ -45,5 +45,6 @@ message CreateOAuthLinkErrorResponse {
     // CONNECTION_ALREADY_EXISTS note this is only that this user already has this connection, we don't know the target conn ID yet.
     CONNECTION_ALREADY_EXISTS = 1;
   }
-}
 
+  Reason reason = 1;
+}

src/proto/account_connection/messages.proto

@@ -0,0 +1,20 @@
+syntax = "proto3";
+package emortal.message.account_connection;
+
+option java_package = "dev.emortal.api.message.accountconnection";
+option java_multiple_files = true;
+option go_package = "github.com/emortalmc/proto-specs/gen/go/message/accountconnection";
+
+import "account_connection/models.proto";
+
+// AccountConnectedMessage is sent when a connection is successful, not when the OAuth URL is created.
+// NOTE: multiple connection types my be present (e.g. if it's the first link there might be MINECRAFT and DISCORD)
+message AccountConnectedMessage {
+  model.account_connection.ConnectionUser user = 1;
+  repeated model.account_connection.ConnectionType connection_types = 2;
+}
+
+message AccountConnectionRemovedMessage {
+  model.account_connection.ConnectionUser user = 1;
+  model.account_connection.ConnectionType removed_connection = 2;
+}

src/proto/account_conn_manager/models.proto → src/proto/account_connection/models.proto

@@ -1,9 +1,9 @@
 syntax = "proto3";
-package emortal.model.account_conn_manager;
+package emortal.model.account_connection;
 
-option java_package = "dev.emortal.api.model.accountconnmanager";
+option java_package = "dev.emortal.api.model.accountconnection";
 option java_multiple_files = true;
-option go_package = "github.com/emortalmc/proto-specs/gen/go/model/accountconnmanager";
+option go_package = "github.com/emortalmc/proto-specs/gen/go/model/accountconnection";
 
 message ConnectionUser {
   // minecraft_id of type UUID

src/proto/badges/grpc.proto

@@ -2,22 +2,28 @@ syntax = "proto3";
 package emortal.grpc.badge;
 
 option java_package = "dev.emortal.api.grpc.badge";
-option java_outer_classname = "BadgeManagerProto";
+option java_outer_classname = "BadgeManagerProto"; // TODO: Update this to "BadgeProto"
 option go_package = "github.com/emortalmc/proto-specs/gen/go/grpc/badge";
 
 import "badges/models.proto";
 
+// TODO: Rename this to just "Badge" and update corresponding code
 service BadgeManager {
+  // GetBadges gets all the registered badges
+  rpc GetBadges(GetBadgesRequest) returns (GetBadgesResponse) {}
   rpc GetPlayerBadges(GetPlayerBadgesRequest) returns (GetPlayerBadgesResponse) {}
 
   rpc GetActivePlayerBadge(GetActivePlayerBadgeRequest) returns (GetActivePlayerBadgeResponse) {}
   rpc SetActivePlayerBadge(SetActivePlayerBadgeRequest) returns (SetActivePlayerBadgeResponse) {}
 
   rpc AddBadgeToPlayer(AddBadgeToPlayerRequest) returns (AddBadgeToPlayerResponse) {}
   rpc RemoveBadgeFromPlayer(RemoveBadgeFromPlayerRequest) returns (RemoveBadgeFromPlayerResponse) {}
+}
 
-  // GetBadges gets all the registered badges
-  rpc GetBadges(GetBadgesRequest) returns (GetBadgesResponse) {}
+message GetBadgesRequest {}
+
+message GetBadgesResponse {
+  repeated model.badge.Badge badges = 1;
 }
 
 message GetPlayerBadgesRequest {
@@ -32,6 +38,15 @@ message GetPlayerBadgesResponse {
   optional string active_badge_id = 2;
 }
 
+message GetActivePlayerBadgeRequest {
+  // player_id of type UUID
+  string player_id = 1;
+}
+
+message GetActivePlayerBadgeResponse {
+  model.badge.Badge badge = 1;
+}
+
 message SetActivePlayerBadgeRequest {
   // player_id of type UUID
   string player_id = 1;
@@ -48,15 +63,6 @@ message SetActivePlayerBadgeErrorResponse {
   Reason reason = 1;
 }
 
-message GetActivePlayerBadgeRequest {
-  // player_id of type UUID
-  string player_id = 1;
-}
-
-message GetActivePlayerBadgeResponse {
-  model.badge.Badge badge = 1;
-}
-
 message AddBadgeToPlayerRequest {
   // player_id of type UUID
   string player_id = 1;
@@ -88,9 +94,3 @@ message RemoveBadgeFromPlayerErrorResponse {
 
   Reason reason = 1;
 }
-
-message GetBadgesRequest {}
-
-message GetBadgesResponse {
-  repeated model.badge.Badge badges = 1;
-}

src/proto/badges/models.proto

@@ -25,4 +25,3 @@ message Badge {
 
   GuiItem gui_item = 7;
 }
-