Skip to main content

TeleportFailedReportUtils

What the engine said about a client teleport, and what that means for what to do next.

TeleportInitFailed reports outcomes rather than only failures -- Success and IsTeleporting arrive through the same event as the refusals do -- so a report is classified rather than assumed to be one. Two questions are worth asking of one: whether the hop is still running (TeleportFailedReportUtils.isInFlight), and whether a refusal is worth another request (TeleportFailedReportUtils.shouldRetry).

All logic here is pure, so it is unit tested without a Player or a teleport.

Types​

TeleportReport​

</>
interface TeleportReport {
result: Enum.TeleportResult
message: string
placeId: number--

the destination the report is about

}

The whole of TeleportInitFailed, kept together so a caller decides on result instead of parsing message. Every rejection from TeleportServiceUtils.promiseTeleportClientOnce carries one, and it renders itself when a consumer only wants text.

Functions​

new​

</>
TeleportFailedReportUtils.new(
placeId: number,
result: Enum.TeleportResult,
message: string
) → TeleportReport

A report that renders itself, so text-only consumers need not reach into it -- including PromiseRetryUtils, which tostrings whatever an attempt rejected with.

isReport​

</>
TeleportFailedReportUtils.isReport(value: any) → boolean

Whether a value is a report at all. A promise cancelled mid-teleport rejects with nothing rather than a refusal, so a consumer reading rejections has to tell the two apart before classifying.

isInFlight​

</>
TeleportFailedReportUtils.isInFlight(report: TeleportReport) → boolean

Whether a report means the hop is still happening rather than refused. Success is the engine confirming the request; IsTeleporting is it refusing a DUPLICATE while the original still runs, which is to say the one result that proves a request is alive. Neither is a failure, and answering either with another request is what stacks the concurrent teleports Roblox cannot hold.

shouldRetry​

</>
TeleportFailedReportUtils.shouldRetry(report: TeleportReport) → boolean

Whether a refusal is worth another request: the request is gone and the reason may not recur. False for the terminal refusals (GameNotFound, Unauthorized), which will refuse again however long we wait, and for Flooded, where another request is precisely what the engine is objecting to -- retrying either spends the player's time to reach the same refusal.

Show raw api
{
    "functions": [
        {
            "name": "new",
            "desc": "A report that renders itself, so text-only consumers need not reach into it -- including\nPromiseRetryUtils, which tostrings whatever an attempt rejected with.",
            "params": [
                {
                    "name": "placeId",
                    "desc": "",
                    "lua_type": "number"
                },
                {
                    "name": "result",
                    "desc": "",
                    "lua_type": "Enum.TeleportResult"
                },
                {
                    "name": "message",
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "TeleportReport"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 44,
                "path": "src/teleportserviceutils/src/Shared/TeleportFailedReportUtils.lua"
            }
        },
        {
            "name": "isReport",
            "desc": "Whether a value is a report at all. A promise cancelled mid-teleport rejects with nothing rather\nthan a refusal, so a consumer reading rejections has to tell the two apart before classifying.",
            "params": [
                {
                    "name": "value",
                    "desc": "",
                    "lua_type": "any"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 67,
                "path": "src/teleportserviceutils/src/Shared/TeleportFailedReportUtils.lua"
            }
        },
        {
            "name": "isInFlight",
            "desc": "Whether a report means the hop is still happening rather than refused. `Success` is the engine\nconfirming the request; `IsTeleporting` is it refusing a DUPLICATE while the original still runs,\nwhich is to say the one result that proves a request is alive. Neither is a failure, and answering\neither with another request is what stacks the concurrent teleports Roblox cannot hold.",
            "params": [
                {
                    "name": "report",
                    "desc": "",
                    "lua_type": "TeleportReport"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 80,
                "path": "src/teleportserviceutils/src/Shared/TeleportFailedReportUtils.lua"
            }
        },
        {
            "name": "shouldRetry",
            "desc": "Whether a refusal is worth another request: the request is gone and the reason may not recur.\nFalse for the terminal refusals (`GameNotFound`, `Unauthorized`), which will refuse again however\nlong we wait, and for `Flooded`, where another request is precisely what the engine is objecting\nto -- retrying either spends the player's time to reach the same refusal.",
            "params": [
                {
                    "name": "report",
                    "desc": "",
                    "lua_type": "TeleportReport"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 95,
                "path": "src/teleportserviceutils/src/Shared/TeleportFailedReportUtils.lua"
            }
        }
    ],
    "properties": [],
    "types": [
        {
            "name": "TeleportReport",
            "desc": "The whole of `TeleportInitFailed`, kept together so a caller decides on `result` instead of parsing\n`message`. Every rejection from [TeleportServiceUtils.promiseTeleportClientOnce] carries one, and it\nrenders itself when a consumer only wants text.",
            "fields": [
                {
                    "name": "result",
                    "lua_type": "Enum.TeleportResult",
                    "desc": ""
                },
                {
                    "name": "message",
                    "lua_type": "string",
                    "desc": ""
                },
                {
                    "name": "placeId",
                    "lua_type": "number",
                    "desc": "the destination the report is about"
                }
            ],
            "source": {
                "line": 29,
                "path": "src/teleportserviceutils/src/Shared/TeleportFailedReportUtils.lua"
            }
        }
    ],
    "name": "TeleportFailedReportUtils",
    "desc": "What the engine said about a client teleport, and what that means for what to do next.\n\n`TeleportInitFailed` reports outcomes rather than only failures -- `Success` and `IsTeleporting`\narrive through the same event as the refusals do -- so a report is classified rather than assumed\nto be one. Two questions are worth asking of one: whether the hop is still running\n([TeleportFailedReportUtils.isInFlight]), and whether a refusal is worth another request\n([TeleportFailedReportUtils.shouldRetry]).\n\nAll logic here is pure, so it is unit tested without a [Player] or a teleport.",
    "source": {
        "line": 15,
        "path": "src/teleportserviceutils/src/Shared/TeleportFailedReportUtils.lua"
    }
}