Categorygithub.com/hathora/ciinternalsdk
package
0.0.0-20241217165659-7265ebecce3b
Repository: https://github.com/hathora/ci.git
Documentation: pkg.go.dev
Overview
Versions
1
Dependencies
15
Dependents
3
Files
22.4k SLOC

# README

github.com/hathora/ci/internal/sdk

šŸ— Welcome to your new SDK! šŸ—

It has been generated successfully based on your OpenAPI spec. However, it is not yet ready for production use. Here are some next steps:

SDK Installation

go get github.com/hathora/ci/internal/sdk

SDK Example Usage

Example

package main

import (
	"context"
	"github.com/hathora/ci/internal/sdk"
	"github.com/hathora/ci/internal/sdk/models/shared"
	"log"
	"os"
)

func main() {
	s := sdk.New(
		sdk.WithSecurity(shared.Security{
			HathoraDevToken: sdk.String(os.Getenv("HATHORA_DEV_TOKEN")),
		}),
		sdk.WithAppID("app-af469a92-5b45-4565-b3c4-b79878de67d2"),
	)
	var orgID string = "org-6f706e83-0ec1-437a-9a46-7d4281eb2f39"
	ctx := context.Background()
	res, err := s.TokensV1.GetOrgTokens(ctx, orgID)
	if err != nil {
		log.Fatal(err)
	}
	if res.ListOrgTokens != nil {
		// handle response
	}
}

Available Resources and Operations

TokensV1

RoomsV1

RoomsV2

ProcessesV1

ProcessesV2

ProcessesV3

OrganizationsV1

MetricsV1

ManagementV1

LogsV1

LobbiesV1

LobbiesV2

  • CreatePrivateLobby - :warning: Deprecated
  • CreatePublicLobby - :warning: Deprecated
  • CreateLocalLobby - :warning: Deprecated
  • CreateLobbyDeprecated - Create a new lobby for an application. A lobby object is a wrapper around a room object. With a lobby, you get additional functionality like configuring the visibility of the room, managing the state of a match, and retrieving a list of public lobbies to display to players. :warning: Deprecated
  • ListActivePublicLobbiesDeprecatedV2 - Get all active lobbies for a an application. Filter by optionally passing in a region. Use this endpoint to display all public lobbies that a player can join in the game client. :warning: Deprecated
  • GetLobbyInfo - Get details for a lobby. :warning: Deprecated
  • SetLobbyState - Set the state of a lobby. State is intended to be set by the server and must be smaller than 1MB. Use this endpoint to store match data like live player count to enforce max number of clients or persist end-game data (i.e. winner or final scores). :warning: Deprecated

LobbiesV3

  • CreateLobby - Create a new lobby for an application. A lobby object is a wrapper around a room object. With a lobby, you get additional functionality like configuring the visibility of the room, managing the state of a match, and retrieving a list of public lobbies to display to players.
  • ListActivePublicLobbies - Get all active lobbies for a given application. Filter the array by optionally passing in a region. Use this endpoint to display all public lobbies that a player can join in the game client.
  • GetLobbyInfoByRoomID - Get details for a lobby.
  • GetLobbyInfoByShortCode - Get details for a lobby. If 2 or more lobbies have the same shortCode, then the most recently created lobby will be returned.

DiscoveryV1

  • GetPingServiceEndpointsDeprecated - Returns an array of V1 regions with a host and port that a client can directly ping. Open a websocket connection to wss://<host>:<port>/ws and send a packet. To calculate ping, measure the time it takes to get an echo packet back. :warning: Deprecated

DiscoveryV2

  • GetPingServiceEndpoints - Returns an array of all regions with a host and port that a client can directly ping. Open a websocket connection to wss://<host>:<port>/ws and send a packet. To calculate ping, measure the time it takes to get an echo packet back.

DeploymentsV1

DeploymentsV2

DeploymentsV3

BuildsV1

BuildsV2

BuildsV3

  • GetBuilds - Returns an array of builds for an application.
  • CreateBuild - Creates a new build with optional multipartUploadUrls that can be used to upload larger builds in parts before calling runBuild. Responds with a buildId that you must pass to RunBuild() to build the game server artifact. You can optionally pass in a buildTag to associate an external version with a build.
  • GetBuild - Get details for a build.
  • DeleteBuild - Delete a build. All associated metadata is deleted. Be careful which builds you delete. This endpoint does not prevent you from deleting actively used builds. Deleting a build that is actively build used by an app's deployment will cause failures when creating rooms.
  • RunBuild - Builds a game server artifact from a tarball you provide. Pass in the buildId generated from CreateBuild().

BillingV1

AuthV1

  • LoginAnonymous - Returns a unique player token for an anonymous user.
  • LoginNickname - Returns a unique player token with a specified nickname for a user.
  • LoginGoogle - Returns a unique player token using a Google-signed OIDC idToken.

AppsV1

AppsV2

Global Parameters

A parameter is configured globally. This parameter may be set on the SDK client instance itself during initialization. When configured as an option during SDK initialization, This global value will be used as the default on the operations that use it. When such operations are called, there is a place in each to override the global value, if needed.

For example, you can set appId to "app-af469a92-5b45-4565-b3c4-b79878de67d2" at SDK initialization and then you do not have to pass the same value on calls to operations like CreateRoomDeprecated. But if you want to do so you may, which will locally override the global setting. See the example code below for a demonstration.

Available Globals

The following global parameter is available.

NameTypeRequiredDescription
AppIDstringThe AppID parameter.

Example

package main

import (
	"context"
	"github.com/hathora/ci/internal/sdk"
	"github.com/hathora/ci/internal/sdk/models/shared"
	"log"
	"os"
)

func main() {
	s := sdk.New(
		sdk.WithSecurity(shared.Security{
			HathoraDevToken: sdk.String(os.Getenv("HATHORA_DEV_TOKEN")),
		}),
		sdk.WithAppID("app-af469a92-5b45-4565-b3c4-b79878de67d2"),
	)
	createRoomParams := shared.CreateRoomParams{
		RoomConfig: sdk.String("{\"name\":\"my-room\"}"),
		Region:     shared.RegionChicago,
	}

	var appID *string = sdk.String("app-af469a92-5b45-4565-b3c4-b79878de67d2")

	var roomID *string = sdk.String("2swovpy1fnunu")
	ctx := context.Background()
	res, err := s.RoomsV1.CreateRoomDeprecated(ctx, createRoomParams, appID, roomID)
	if err != nil {
		log.Fatal(err)
	}
	if res.RoomID != nil {
		// handle response
	}
}

Error Handling

Handling errors in this SDK should largely match your expectations. All operations return a response object or an error, they will never return both. When specified by the OpenAPI spec document, the SDK will return the appropriate subclass.

Error ObjectStatus CodeContent Type
sdkerrors.APIError401,404,429application/json
sdkerrors.SDKError4xx-5xx/

Example

package main

import (
	"context"
	"errors"
	"github.com/hathora/ci/internal/sdk"
	"github.com/hathora/ci/internal/sdk/models/sdkerrors"
	"github.com/hathora/ci/internal/sdk/models/shared"
	"log"
	"os"
)

func main() {
	s := sdk.New(
		sdk.WithSecurity(shared.Security{
			HathoraDevToken: sdk.String(os.Getenv("HATHORA_DEV_TOKEN")),
		}),
		sdk.WithAppID("app-af469a92-5b45-4565-b3c4-b79878de67d2"),
	)
	var orgID string = "org-6f706e83-0ec1-437a-9a46-7d4281eb2f39"
	ctx := context.Background()
	res, err := s.TokensV1.GetOrgTokens(ctx, orgID)
	if err != nil {

		var e *sdkerrors.APIError
		if errors.As(err, &e) {
			// handle error
			log.Fatal(e.Error())
		}

		var e *sdkerrors.SDKError
		if errors.As(err, &e) {
			// handle error
			log.Fatal(e.Error())
		}
	}
}

Server Selection

Select Server by Index

You can override the default server globally using the WithServerIndex option when initializing the SDK client instance. The selected server will then be used as the default on the operations that use it. This table lists the indexes associated with the available servers:

#ServerVariables
0https://api.hathora.devNone
1https:///None

Example

package main

import (
	"context"
	"github.com/hathora/ci/internal/sdk"
	"github.com/hathora/ci/internal/sdk/models/shared"
	"log"
	"os"
)

func main() {
	s := sdk.New(
		sdk.WithServerIndex(1),
		sdk.WithSecurity(shared.Security{
			HathoraDevToken: sdk.String(os.Getenv("HATHORA_DEV_TOKEN")),
		}),
		sdk.WithAppID("app-af469a92-5b45-4565-b3c4-b79878de67d2"),
	)
	var orgID string = "org-6f706e83-0ec1-437a-9a46-7d4281eb2f39"
	ctx := context.Background()
	res, err := s.TokensV1.GetOrgTokens(ctx, orgID)
	if err != nil {
		log.Fatal(err)
	}
	if res.ListOrgTokens != nil {
		// handle response
	}
}

Override Server URL Per-Client

The default server can also be overridden globally using the WithServerURL option when initializing the SDK client instance. For example:

package main

import (
	"context"
	"github.com/hathora/ci/internal/sdk"
	"github.com/hathora/ci/internal/sdk/models/shared"
	"log"
	"os"
)

func main() {
	s := sdk.New(
		sdk.WithServerURL("https://api.hathora.dev"),
		sdk.WithSecurity(shared.Security{
			HathoraDevToken: sdk.String(os.Getenv("HATHORA_DEV_TOKEN")),
		}),
		sdk.WithAppID("app-af469a92-5b45-4565-b3c4-b79878de67d2"),
	)
	var orgID string = "org-6f706e83-0ec1-437a-9a46-7d4281eb2f39"
	ctx := context.Background()
	res, err := s.TokensV1.GetOrgTokens(ctx, orgID)
	if err != nil {
		log.Fatal(err)
	}
	if res.ListOrgTokens != nil {
		// handle response
	}
}

Custom HTTP Client

The Go SDK makes API calls that wrap an internal HTTP client. The requirements for the HTTP client are very simple. It must match this interface:

type HTTPClient interface {
	Do(req *http.Request) (*http.Response, error)
}

The built-in net/http client satisfies this interface and a default client based on the built-in is provided by default. To replace this default with a client of your own, you can implement this interface yourself or provide your own client configured as desired. Here's a simple example, which adds a client with a 30 second timeout.

import (
	"net/http"
	"time"
	"github.com/myorg/your-go-sdk"
)

var (
	httpClient = &http.Client{Timeout: 30 * time.Second}
	sdkClient  = sdk.New(sdk.WithClient(httpClient))
)

This can be a convenient way to configure timeouts, cookies, proxies, custom headers, and other low-level configuration.

Authentication

Per-Client Security Schemes

This SDK supports the following security scheme globally:

NameTypeScheme
HathoraDevTokenhttpHTTP Bearer

You can configure it using the WithSecurity option when initializing the SDK client instance. For example:

package main

import (
	"context"
	"github.com/hathora/ci/internal/sdk"
	"github.com/hathora/ci/internal/sdk/models/shared"
	"log"
	"os"
)

func main() {
	s := sdk.New(
		sdk.WithSecurity(shared.Security{
			HathoraDevToken: sdk.String(os.Getenv("HATHORA_DEV_TOKEN")),
		}),
		sdk.WithAppID("app-af469a92-5b45-4565-b3c4-b79878de67d2"),
	)
	var orgID string = "org-6f706e83-0ec1-437a-9a46-7d4281eb2f39"
	ctx := context.Background()
	res, err := s.TokensV1.GetOrgTokens(ctx, orgID)
	if err != nil {
		log.Fatal(err)
	}
	if res.ListOrgTokens != nil {
		// handle response
	}
}

Per-Operation Security Schemes

Some operations in this SDK require the security scheme to be specified at the request level. For example:

package main

import (
	"context"
	"github.com/hathora/ci/internal/sdk"
	"github.com/hathora/ci/internal/sdk/models/operations"
	"github.com/hathora/ci/internal/sdk/models/shared"
	"log"
	"os"
)

func main() {
	s := sdk.New(
		sdk.WithAppID("app-af469a92-5b45-4565-b3c4-b79878de67d2"),
	)
	security := operations.CreatePrivateLobbyDeprecatedSecurity{
		PlayerAuth: os.Getenv("PLAYER_AUTH"),
	}

	var appID *string = sdk.String("app-af469a92-5b45-4565-b3c4-b79878de67d2")

	var region *shared.Region = shared.RegionLondon.ToPointer()

	var local *bool = sdk.Bool(false)
	ctx := context.Background()
	res, err := s.LobbiesV1.CreatePrivateLobbyDeprecated(ctx, security, appID, region, local)
	if err != nil {
		log.Fatal(err)
	}
	if res.RoomID != nil {
		// handle response
	}
}

Special Types

Retries

Some of the endpoints in this SDK support retries. If you use the SDK without any configuration, it will fall back to the default retry strategy provided by the API. However, the default retry strategy can be overridden on a per-operation basis, or across the entire SDK.

To change the default retry strategy for a single API call, simply provide a retry.Config object to the call by using the WithRetries option:

package main

import (
	"context"
	"github.com/hathora/ci/internal/sdk"
	"github.com/hathora/ci/internal/sdk/models/shared"
	"github.com/hathora/ci/internal/sdk/retry"
	"log"
	"models/operations"
	"os"
)

func main() {
	s := sdk.New(
		sdk.WithSecurity(shared.Security{
			HathoraDevToken: sdk.String(os.Getenv("HATHORA_DEV_TOKEN")),
		}),
		sdk.WithAppID("app-af469a92-5b45-4565-b3c4-b79878de67d2"),
	)
	var orgID string = "org-6f706e83-0ec1-437a-9a46-7d4281eb2f39"
	ctx := context.Background()
	res, err := s.TokensV1.GetOrgTokens(ctx, orgID, operations.WithRetries(
		retry.Config{
			Strategy: "backoff",
			Backoff: &retry.BackoffStrategy{
				InitialInterval: 1,
				MaxInterval:     50,
				Exponent:        1.1,
				MaxElapsedTime:  100,
			},
			RetryConnectionErrors: false,
		}))
	if err != nil {
		log.Fatal(err)
	}
	if res.ListOrgTokens != nil {
		// handle response
	}
}

If you'd like to override the default retry strategy for all operations that support retries, you can use the WithRetryConfig option at SDK initialization:

package main

import (
	"context"
	"github.com/hathora/ci/internal/sdk"
	"github.com/hathora/ci/internal/sdk/models/shared"
	"github.com/hathora/ci/internal/sdk/retry"
	"log"
	"os"
)

func main() {
	s := sdk.New(
		sdk.WithRetryConfig(
			retry.Config{
				Strategy: "backoff",
				Backoff: &retry.BackoffStrategy{
					InitialInterval: 1,
					MaxInterval:     50,
					Exponent:        1.1,
					MaxElapsedTime:  100,
				},
				RetryConnectionErrors: false,
			}),
		sdk.WithSecurity(shared.Security{
			HathoraDevToken: sdk.String(os.Getenv("HATHORA_DEV_TOKEN")),
		}),
		sdk.WithAppID("app-af469a92-5b45-4565-b3c4-b79878de67d2"),
	)
	var orgID string = "org-6f706e83-0ec1-437a-9a46-7d4281eb2f39"
	ctx := context.Background()
	res, err := s.TokensV1.GetOrgTokens(ctx, orgID)
	if err != nil {
		log.Fatal(err)
	}
	if res.ListOrgTokens != nil {
		// handle response
	}
}

Development

Maturity

This SDK is in beta, and there may be breaking changes between versions without a major version update. Therefore, we recommend pinning usage to a specific package version. This way, you can install the same version each time without breaking changes unless you are intentionally looking for the latest version.

Contributions

While we value open-source contributions to this SDK, this library is generated programmatically. Feel free to open a PR or a Github issue as a proof of concept and we'll do our best to include it in a future release!

SDK Created by Speakeasy

# Packages

No description provided by the author
No description provided by the author
No description provided by the author

# Functions

Bool provides a helper function to return a pointer to a bool.
Float32 provides a helper function to return a pointer to a float32.
Float64 provides a helper function to return a pointer to a float64.
Int provides a helper function to return a pointer to an int.
Int64 provides a helper function to return a pointer to an int64.
New creates a new instance of the SDK with the provided options.
String provides a helper function to return a pointer to a string.
WithAppID allows setting the AppID parameter for all supported operations.
WithClient allows the overriding of the default HTTP client used by the SDK.
No description provided by the author
WithSecurity configures the SDK to use the provided security details.
WithSecuritySource configures the SDK to invoke the Security Source function on each method call to determine authentication.
WithServerIndex allows the overriding of the default server by index.
WithServerURL allows the overriding of the default server URL.
WithTemplatedServerURL allows the overriding of the default server URL with a templated URL populated with the provided parameters.
WithTimeout Optional request timeout applied to each operation.

# Variables

ServerList contains the list of servers available to the SDK.

# Structs

No description provided by the author
No description provided by the author
AuthV1 - Operations that allow you to generate a Hathora-signed [JSON web token (JWT)](https://jwt.io/) for [player authentication](https://hathora.dev/docs/lobbies-and-matchmaking/auth-service).
BillingV1 -.
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
DiscoveryV1 - Deprecated.
DiscoveryV2 - Service that allows clients to directly ping all Hathora regions to get latency information.
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
ManagementV1 -.
MetricsV1 - Operations to get metrics by [process](https://hathora.dev/docs/concepts/hathora-entities#process).
No description provided by the author
ProcessesV1 - Deprecated.
ProcessesV2 - Operations to get data on active and stopped [processes](https://hathora.dev/docs/concepts/hathora-entities#process).
No description provided by the author
No description provided by the author
No description provided by the author
SDK - Hathora Cloud API: Welcome to the Hathora Cloud API documentation! Learn how to use the Hathora Cloud APIs to build and scale your game servers globally.
TokensV1 -.

# Interfaces

HTTPClient provides an interface for suplying the SDK with a custom HTTP client.

# Type aliases

No description provided by the author