From bcc2f21ec75fcb10a8185857f3bc323bb19619da Mon Sep 17 00:00:00 2001 From: Maxim Sharabayko Date: Wed, 7 Aug 2024 13:15:15 +0200 Subject: [PATCH] [docs] Added Rejection Reasons document (#2762). Co-authored-by: stevomatthews --- docs/API/API-functions.md | 2 + docs/API/rejection-codes.md | 473 ++++++++++++++++++++++++++++++++ docs/README.md | 1 + docs/features/access-control.md | 193 +------------ 4 files changed, 477 insertions(+), 192 deletions(-) create mode 100644 docs/API/rejection-codes.md diff --git a/docs/API/API-functions.md b/docs/API/API-functions.md index 54895fe15..74fbc506f 100644 --- a/docs/API/API-functions.md +++ b/docs/API/API-functions.md @@ -174,6 +174,8 @@ Since SRT v1.5.0. | [SRT_REJ_CRYPTO](#SRT_REJ_CRYPTO) | 1.5.2 | The connection was rejected due to an unsupported or mismatching encryption mode | | | | | +See the full list in [Rejection Reason Codes](./rejection-codes.md). +

Error Codes

| *Error Code* | *Description* | diff --git a/docs/API/rejection-codes.md b/docs/API/rejection-codes.md new file mode 100644 index 000000000..0b8418b5f --- /dev/null +++ b/docs/API/rejection-codes.md @@ -0,0 +1,473 @@ +# SRT Rejection Codes + +This document provides an overview of the rejection (error) codes used by and supported within SRT and SRT-based applications. For information on other types of error codes refer to the [API Socket Options](./docs/API/API-socket-options.md) document. + +[:arrow_down:   Jump to list of rejection codes](#api-function-rejection-codes) + + +## Summary of Rejection Codes + +Rejection codes are used in the SRT API, and are transferred on the wire as a part of a Handshake packet (refer to the `Handshake Type` field of the [Handshake](./docs/features/handshake.md) packet). +The rejection codes are divided into several ranges: + + - SRT internal + - Predefined application level codes + - User defined (custom) codes + +In the SRT API these ranges are marked with the following constants (preprocessor definitions): + + - `SRT_REJC_INTERNAL` = 0 + - `SRT_REJC_PREDEFINED` = 1000 + - `SRT_REJC_USERDEFINED` = 2000 + +When transferred on the wire, the API value is incremented by 1000 to become the `Handshake Type` field value. In the following sections the values of rejection reason codes are given in accordance with the API values. + + +### SRT Internal Rejection Codes + +Defined in [**srt.h**](srtcore/srt.h), these codes provide the reason why a connection is rejected by SRT. They cover the reserved range 0 - 999 (below `SRT_REJC_PREDEFINED`). These codes cannot be used by applications to report a rejection reason. + +Naming: `SRT_REJ_*` + + - `SRT_REJ_UNKNOWN` = 0 + - `SRT_REJ_SYSTEM` = 1 + - ... + - `SRT_REJ_CRYPTO` = 17 +See [the list below](#api-function-rejection-codes) for details. + +### Extended Rejection Codes + +As defined in [**access_control.h**](srtcore/access_control.h), these are standard server error codes including those adopted from HTTP. They provide the reason why an application rejects a connection. The value is expected to be set by an application via the listener callback if it wants to reject an incoming connection request. These codes cover the reserved range 1000 - 1999 (`SRT_REJC_PREDEFINED` - `SRT_REJC_USERDEFINED`). + + +Subranges (1000 + value): + + - **0 - 99**: Reserved for unique SRT-specific codes (unused by HTTP) + - **100 - 399**: Info, Success, and Redirection in HTTP (unused by SRT) + - **400 - 599**: Client and server errors in HTTP (adopted by SRT) + +Naming: `SRT_REJX_*` + +Example: + + - `SRT_REJX_KEY_NOTSUP` (1001): The key used in the StreamID keyed string is not supported by the service. + - `SRT_REJX_BAD_REQUEST` (1400) + - ... + +### User Defined Rejection Codes + +These codes can be freely defined by an application. They can be custom codes, not adopted by other vendors. For example, `2005: “Makito license expired”`. They cover the reserved range 2000 - 2999 (higher than `SRT_REJC_USERDEFINED`). + + +## API Function Rejection Codes + +SRT's API function rejection codes refer to system-level error conditions caused by SRT-specific settings or operating conditions. They are uninfluenced by application-related events, and applications are not permitted to use or simulate these codes. + +The table below lists the rejection codes as defined in [**srt.h**](srtcore/srt.h) (click the *Rejection Reason* link to view a complete description). + +| *Code* | *Rejection Reason* | *Since* | *Description* | +|:------:|:-------------------------------------------------- |:-------:|:-------------------------------------------------------------------------------------------------------------- | +| 0 | [SRT_REJ_UNKNOWN](#SRT_REJ_UNKNOWN) | 1.3.4 | Fallback value for cases where connection is not rejected. | +| 1 | [SRT_REJ_SYSTEM](#SRT_REJ_SYSTEM) | 1.3.4 | System function reported a failure. | +| 2 | [SRT_REJ_PEER](#SRT_REJ_PEER) | 1.3.4 | Connection rejected by peer, with no additional details. | +| 3 | [SRT_REJ_RESOURCE](#SRT_REJ_RESOURCE) | 1.3.4 | Problem with resource allocation (usually memory). | +| 4 | [SRT_REJ_ROGUE](#SRT_REJ_ROGUE) | 1.3.4 | Data sent by one party cannot be interpreted. | +| 5 | [SRT_REJ_BACKLOG](#SRT_REJ_BACKLOG) | 1.3.4 | Listener's backlog has been exceeded. | +| 6 | [SRT_REJ_IPE](#SRT_REJ_IPE) | 1.3.4 | Internal Program Error. | +| 7 | [SRT_REJ_CLOSE](#SRT_REJ_CLOSE) | 1.3.4 | Listener socket received a request as it is being closed. | +| 8 | [SRT_REJ_VERSION](#SRT_REJ_VERSION) | 1.3.4 | Minimum version requirement for a connection not satisfied by one party. | +| 9 | [SRT_REJ_RDVCOOKIE](#SRT_REJ_RDVCOOKIE) | 1.3.4 | Rendezvous cookie collision. | +| 10 | [SRT_REJ_BADSECRET](#SRT_REJ_BADSECRET) | 1.3.4 | Both parties have defined connection passphrases that differ. | +| 11 | [SRT_REJ_UNSECURE](#SRT_REJ_UNSECURE) | 1.3.4 | Only one party has set up a connection password. | +| 12 | [SRT_REJ_MESSAGEAPI](#SRT_REJ_MESSAGEAPI) | 1.3.4 | [`SRTO_MESSAGEAPI`](API-socket-options.md#SRTO_MESSAGEAPI) flag is different on both connection parties. | +| 13 | [SRT_REJ_CONGESTION](#SRT_REJ_CONGESTION) | 1.3.4 | Incompatible congestion-controller type. | +| 14 | [SRT_REJ_FILTER](#SRT_REJ_FILTER) | 1.3.4 | [`SRTO_PACKETFILTER`](API-socket-options.md#SRTO_PACKETFILTER) option is different on both connection parties. | +| 15 | [SRT_REJ_GROUP](#SRT_REJ_GROUP) | 1.4.2 | Group type or group settings are incompatible between connection parties. | +| 16 | [SRT_REJ_TIMEOUT](#SRT_REJ_TIMEOUT) | 1.4.2 | Connection not rejected, but timed out. | +| 17 | [SRT_REJ_CRYPTO](#SRT_REJ_CRYPTO) | 1.5.2 | Connection rejected due to unsupported or mismatching encryption mode. | +| | | | | + + +## Access Control Rejection Codes + +SRT's access control rejection codes are intended for use by applications to forcefully reject connections in SRT listener callbacks. They are intended only as a guide to promote standardization. If they are used in an application, a description of their specific implementation should be published (the descriptions in this documentation are not definitive). + +The table below lists the rejection codes as defined in [**access_control.h**](srtcore/access_control.h) (click the *Rejection Reason* link to view a complete description). + +| *Code* | *Rejection Reason* | *Since* | *Description* | +|:------:|:------------------------------------------------- |:-------:|:-------------------------------------------------------------------------------------------------------------- | +| 1000 | [SRT_REJX_FALLBACK](#SRT_REJX_FALLBACK) | 1.4.2 | Callback handler has interrupted an incoming connection. | +| 1001 | [SRT_REJX_KEY_NOTSUP](#SRT_REJX_KEY_NOTSUP) | 1.4.2 | Key specified in StreamID string not supported by application. | +| 1002 | [SRT_REJX_FILEPATH](#SRT_REJX_FILEPATH) | 1.4.2 | Resource type designates file where path has wrong syntax or is not found. | +| 1003 | [SRT_REJX_HOSTNOTFOUND](#SRT_REJX_HOSTNOTFOUND) | 1.4.2 | The host specified in the `h` key cannot be identified. | +| 1400 | [SRT_REJX_BAD_REQUEST](#SRT_REJX_BAD_REQUEST) | 1.4.2 | General syntax error. | +| 1401 | [SRT_REJX_UNAUTHORIZED](#SRT_REJX_UNAUTHORIZED) | 1.4.2 | Authentication failed; client unauthorized to access the resource. | +| 1402 | [SRT_REJX_OVERLOAD](#SRT_REJX_OVERLOAD) | 1.4.2 | Server load too heavy to process request, or credit limit exceeded. | +| 1403 | [SRT_REJX_FORBIDDEN](#SRT_REJX_FORBIDDEN) | 1.4.2 | Access denied to the resource for any reason. | +| 1404 | [SRT_REJX_NOTFOUND](#SRT_REJX_NOTFOUND) | 1.4.2 | Resource specified by `r` and `h` keys cannot be found. | +| 1405 | [SRT_REJX_BAD_MODE](#SRT_REJX_BAD_MODE) | 1.4.2 | Mode specified in the `m` key in StreamID is not supported for this request. | +| 1406 | [SRT_REJX_UNACCEPTABLE](#SRT_REJX_UNACCEPTABLE) | 1.4.2 | Unavailable parameters in `StreamID`, or `m=publish` data format not supported. | +| 1409 | [SRT_REJX_CONFLICT](#SRT_REJX_CONFLICT) | 1.4.2 | Resource specified by `r` and `h` keys is locked for modification. | +| 1415 | [SRT_REJX_NOTSUP_MEDIA](#SRT_REJX_NOTSUP_MEDIA) | 1.4.2 | Media type not supported by the application. | +| 1423 | [SRT_REJX_LOCKED](#SRT_REJX_LOCKED) | 1.4.2 | Resource is locked against any access. | +| 1424 | [SRT_REJX_FAILED_DEPEND](#SRT_REJX_FAILED_DEPEND) | 1.4.2 | Dependent entity for the request is not present. | +| 1500 | [SRT_REJX_ISE](#SRT_REJX_ISE) | 1.4.2 | Internal server error. | +| 1501 | [SRT_REJX_UNIMPLEMENTED](#SRT_REJX_UNIMPLEMENTED) | 1.4.2 | Request not supported by current version of the service. | +| 1502 | [SRT_REJX_GW](#SRT_REJX_GW) | 1.4.2 | Target endpoint rejected connection from gateway server | +| 1503 | [SRT_REJX_DOWN](#SRT_REJX_DOWN) | 1.4.2 | Service is down for maintenance. | +| 1505 | [SRT_REJX_VERSION](#SRT_REJX_VERSION) | 1.4.2 | SRT application version not supported. | +| 1507 | [SRT_REJX_NOROOM](#SRT_REJX_NOROOM) | 1.4.2 | Data stream cannot be archived due to lack of storage space. | +| | | | | + + +**NOTE**: SRT rejection codes follow this prefix convention: + + - `SRT_REJ`: standard rejection codes from SRT API functions (0 - 99) + - `SRT_REJC`: mark the border values between ranges. + - `SRT_REJX`: extended rejection codes (code values above 1000).above)?* + + +## API Function Rejection Reasons + + +#### SRT_REJ_UNKNOWN + +A fallback value for cases when there was no connection rejected. + + +#### SRT_REJ_SYSTEM + +One system function reported a failure. Usually this means some system +error or lack of system resources to complete the task. + + +#### SRT_REJ_PEER + +The connection has been rejected by the peer, but no further details are available. +This usually means that the peer doesn't support rejection reason reporting. + + +#### SRT_REJ_RESOURCE + +A problem with resource allocation (usually memory). + + +#### SRT_REJ_ROGUE + +The data sent by one party to another cannot be properly interpreted. This +should not happen during normal usage, unless it's a bug, or some weird +events are happening on the network. + + +#### SRT_REJ_BACKLOG + +The listener's backlog has exceeded its queue limit (there are many other callers +waiting for the opportunity to be connected and the "wait queue" has +reached its limit). + + +#### SRT_REJ_IPE + +Internal Program Error. This should not happen during normal usage. It +usually indicates a bug in the software (although this can be reported by both +local and foreign hosts). + + +#### SRT_REJ_CLOSE + +The listener socket was able to receive the request, but is currently +being closed. It's likely that the next request will result in a timeout. + + +#### SRT_REJ_VERSION + +One party in the connection has set up a minimum version that is required for +that connection, but the other party doesn't satisfy this requirement. + + +#### SRT_REJ_RDVCOOKIE + +Rendezvous cookie collision. Normally, the probability that this will happen is +negligible. However, it *can* result from a misconfiguration when, in attempting +to make a rendezvous connection, both parties try to bind to the same IP address, +or both are local addresses of the same host. In such a case the sent handshake +packets are returned to the same host as if they were sent by the peer (i.e. a +party is sending to itself). In such situations, this reject reason will be +reported for every attempt. + + +#### SRT_REJ_BADSECRET + +Both parties have defined a passphrase for a connection, but they differ. + + +#### SRT_REJ_UNSECURE + +Only one connection party has set up a password. See also the +[`SRTO_ENFORCEDENCRYPTION`](API-socket-options.md#SRTO_ENFORCEDENCRYPTION) flag. + + +#### SRT_REJ_MESSAGEAPI + +The value of the [`SRTO_MESSAGEAPI`](API-socket-options.md#SRTO_MESSAGEAPI) +flag is different on both parties in a connection. + + +#### SRT_REJ_CONGESTION + +The [`SRTO_CONGESTION`](API-socket-options.md#SRTO_CONGESTION)option has +been set up differently on both parties in a connection. + + +#### SRT_REJ_FILTER + +The [`SRTO_PACKETFILTER`](API-socket-options.md#SRTO_PACKETFILTER) option +has been set differently on both parties in a connection. + + +#### SRT_REJ_GROUP + +The group type or some group settings are incompatible between connection parties. +While every connection within a bonding group may have different target addresses, +they should all designate the same endpoint and the same SRT application. If this +condition isn't satisfied, then the peer will respond with a different peer group +ID for the connection that is trying to contact a machine/application that is +completely different from the existing connections in the bonding group. + + +#### SRT_REJ_TIMEOUT + +The connection wasn't rejected, but it timed out. This code is always sent on +a connection timeout, but this is the only way to get this state in non-blocking +mode (see [`SRTO_RCVSYN`](API-socket-options.md#SRTO_RCVSYN)). + +There may also be server and user rejection codes, as defined by the +`SRT_REJC_INTERNAL`, `SRT_REJC_PREDEFINED`, and `SRT_REJC_USERDEFINED` +constants. Note that the number space from the value of `SRT_REJC_PREDEFINED` +and above is reserved for "predefined codes" (`SRT_REJC_PREDEFINED` value plus +adopted HTTP codes). Values above `SRT_REJC_USERDEFINED` are freely defined by +the application. + +#### SRT_REJ_CRYPTO + +The connection was rejected due to a mismatch in crypto modes. See `SRTO_CRYPTOMODE`. + +[:arrow_up:   Back to top](#srt-rejection-codes) + + +## Access Control Rejection Reasons + +An SRT listener callback handler can decide to reject an incoming connection. +Under normal circumstances, the rejection code is predefined as `SRT_REJ_RESOURCE`. +The handler can, however, set its own rejection code. There are two numbered spaces +intended for this purpose (as the range below `SRT_REJC_PREDEFINED` is reserved +for internal codes): + +- `SRT_REJC_PREDEFINED` and above: These are predefined errors. Errors from this +range (that is, below `SRT_REJC_USERDEFINED`) have their definitions provided in +the `access_control.h` public header file. The intention is that applications +using these codes understand the situations they describe in a standard way. + +- `SRT_REJC_USERDEFINED` and above: These are errors that are freely defined by +the application. Codes from this range can be only understood if each application +knows the code definitions of the other. These codes should be used only after +making sure that the applications at either end of a connection understand them. + +The intention here is for the predefined codes to be consistent with the HTTP +standard codes. Such code can be set by using the [`srt_setrejectreason`](docs/api/api-functions.md#srt-setrejectreason) function. + +The SRT-specific codes are: + +#### SRT_REJX_FALLBACK + +This code should be set by the callback handler in the beginning in case +the application needs to be informed that the callback handler +actually has interpreted the incoming connection, but hasn't set a +more appropriate code describing the situation. + +#### SRT_REJX_KEY_NOTSUP + +Indicates there was a key specified in the StreamID string that this application +doesn't support. Note that it's not obligatory for the application to +react this way - it may chose to ignore unknown keys completely, or +to have some keys in the ignore list (which it won't interpret, but tolerate) +while rejecting any others. It is also up to the application +to decide to return this specific error, or more generally report +the syntax error with `SRT_REJX_BAD_REQUEST`. + +#### SRT_REJX_FILEPATH + +The resource type designates a file, and the path either has the wrong syntax +or is not found. In the case where `t=file`, the path should be specified under +the `r` key, and the file specified there must be able to be saved this way. +It's up to the application to decide how to treat this path, how to parse it, +and what this path specifically means. For the `r` key, the application should +at least handle the single filename, and have storage space available to save +it (provided a file of the same name does not already exist there). The +application should decide whether and how to handle all other situations (like +directory path, special markers in the path to be interpreted by the +application, etc.), or to report this error. + +#### SRT_REJX_HOSTNOTFOUND + +The host specified in the `h` key cannot be identified. The `h` key is +generally for a situation when you have multiple DNS names for a host, +so an application may want to extract the name from the URI and set it +to the `h` key so that the application can distinguish the request also by +the target host name. The application may, however, limit the number of +recognized services by host name to some predefined names and not +handle the others, even if this is properly resolved by DNS. In this +case it should report this error. + +The other error codes are HTTP codes adapted for SRT: + +#### SRT_REJX_BAD_REQUEST + +General syntax error. This can be reported in any case when parsing +the StreamID contents failed, or it cannot be properly interpreted. + +#### SRT_REJX_UNAUTHORIZED + +Authentication failed, which makes the client unauthorized to access the +resource. This error, however, confirms that the syntax is correct and +the resource has been properly identified. Note that this cannot be +reported when you use a simple user-password authentication +method because in this case the password is verified only after the +listener callback handler accepts the connection. This error is rather +intended to be reported in the case of `t=auth` when the authentication +process has generated some valid session ID, but then the session +connection has specified a resource that is not within the frames +of that authentication. + +#### SRT_REJX_OVERLOAD + +The server is too heavily loaded to process the request, or the credit limit +for accessing the service and the resource has been exceeded. +In HTTP the description mentions payment for a service, but +it is also used by some services for general "credit" management +for a client. In SRT it should be used when the service is doing +any kind of credit management to limit access to selected clients +that "have" enough credit, even if the credit is something the client +can recharge itself, or that can be granted depending on available +service resources. + +#### SRT_REJX_FORBIDDEN + +Access denied to the resource for any reason. This error is +independent of an authorization or authentication error (as reported +by `SRT_REJX_UNAUTHORIZED`). The application can decide which +is more appropriate. This error is usually intended for +a resource that should only be accessed after a successful +authorization over a separate auth-only connection, where the query +in StreamID has correctly specified the resource identity and mode, +but the session ID (in the `s` key) is either (a) not specified, or +(b) specifies a valid session, but the authorization region for this +session does not include the specified resource. + +#### SRT_REJX_NOTFOUND + +The resource specified in the `r` key (in combination with the `h` key) +is not found at this time. This error should be only reported if the +information about resource accessibility is allowed to be publicly +visible. Otherwise, the application might report authorization +errors. + +#### SRT_REJX_BAD_MODE + +The mode specified in the `m` key in StreamID is not supported for this request. +This may apply to read-only or write-only resources, as well when interactive +(bidirectional) access is not valid for a resource. + +#### SRT_REJX_UNACCEPTABLE + +Applies when the parameters specified in StreamID cannot be satisfied for the +requested resource, or when `m=publish` but the data format is not acceptable. +This is a general error reporting an unsupported format for data that appears to +be wrong when sending, or a restriction on the data format (as specified in the +details of the resource specification) such that it cannot be provided +when receiving. + +#### SRT_REJX_CONFLICT + +The resource being accessed (as specified by `r` and `h` keys) is locked for +modification. This error should only be reported for `m=publish` when the +resource being accessed is read-only because another client (not necessarily +connected through SRT): + +- is currently publishing into this resource +- has reserved this resource ID for publishing + +Note that this error should be reported when there is no other reason for +having a problem accessing the resource. + +#### SRT_REJX_NOTSUP_MEDIA + +The media type is not supported by the application. The media type is +specified in the `t` key. The currently standard types are +`stream`, `file` and `auth`. An application may extend this list, and +is not obliged to support all of the standard types. + +#### SRT_REJX_LOCKED + +The resource being accessed is locked against any access. This is similar to +`SRT_REJX_CONFLICT`, but in this case the resource is locked for reading +and writing. This is for when the resource should be shown as existing and +available to the client, but access is temporarily blocked. + +#### SRT_REJX_FAILED_DEPEND + +The dependent entity for the request is not present. In this case the +dependent entity is the session, which should be specified in the `s` +key. This means that the specified session ID is nonexistent, or it +has already expired. + +#### SRT_REJX_ISE + +Internal server error. This is for a general case when a request has +been correctly verified, with no related problems found, but an +unexpected error occurs after the processing of the request has started. + +#### SRT_REJX_UNIMPLEMENTED + +The request was correctly recognized, but the current software version +of the service (be it SRT or any other software component) doesn't +support it. This should be reported for a case where some features to +be specified in the StreamID request are supposed to be supported in a +predictable future, but the current version of the server does not +support it, or the support for this feature in this version has been +temporarily blocked. This shouldn't be reported for existing features that are +being deprecated, or older features that are no longer supported +(for this case the general `SRT_REJX_BAD_REQUEST` is more appropriate). + +#### SRT_REJX_GW + +The server acts as a gateway and the target endpoint rejected the +connection. The reason the connection was rejected is unspecified. +The gateway cannot forward the original rejection code from the +target endpoint because this would suggest the error was on the +gateway itself. Use this error with some other mechanism to report +the original target error, if possible. + +#### SRT_REJX_DOWN + +The service is down for maintenance. This can only be reported +when the service has been temporarily replaced by a stub that is only +reporting this error, while the real service is down for maintenance. + +#### SRT_REJX_VERSION + +Application version not supported. This can refer to an application feature +that is unsupported (possibly from an older SRT version), or to a feature +that is no longer supported because of backward compatibility requirements. + +#### SRT_REJX_NOROOM + +The data stream cannot be archived due to a lack of storage space. This is +reported when a request to send a file or a live stream to be archived is +unsuccessful. Note that the length of a file transmission is usually +pre-declared, so this error can be reported early. It can also be reported when +the stream is of undefined length, and there is no more storage space +available. + + +[:arrow_up:   Back to top](#srt-rejection-codes) diff --git a/docs/README.md b/docs/README.md index 9e3bdb198..8c07ee515 100644 --- a/docs/README.md +++ b/docs/README.md @@ -7,6 +7,7 @@ | [SRT API](API/API.md) | [API](API/) | [API.md](API/API.md) | Detailed description of the SRT C API. | | [SRT API Functions](API/API-functions.md) | [API](API/) | [API-functions.md](API/API-functions.md) | Reference document for SRT API functions. | | [SRT API Socket Options](API/API-socket-options.md) | [API](API/) | [API-socket-options.md](API/API-socket-options.md) | Instructions and list of socket options for SRT API. | +| [SRT Rejection Codes](API/rejections-codes.md) | [API](API/) | [rejection-codes.md](API/rejection-codes.md) | The list of SRT rejections codes. | | [SRT Statistics](API/statistics.md) | [API](API/) | [statistics.md](API/statistics.md) | How to use SRT socket and socket group statistics. | | [Configuration Guidelines](API/configuration-guidelines.md) | [API](API/) | [configuration-guidelines.md](API/configuration-guidelines.md) | How to configure SRT buffers. | | | | | | diff --git a/docs/features/access-control.md b/docs/features/access-control.md index 99fe891fa..6375802b2 100644 --- a/docs/features/access-control.md +++ b/docs/features/access-control.md @@ -154,198 +154,7 @@ standard codes. Therefore the following sub-ranges are used: Such a code can be set by using the `srt_setrejectreason` function. -The SRT-specific codes are: - -#### SRT_REJX_FALLBACK - -This code should be set by the callback handler in the beginning in case -the application needs to be informed that the callback handler -actually has interpreted the incoming connection, but hasn't set a -more appropriate code describing the situation. - -#### SRT_REJX_KEY_NOTSUP - -Indicates there was a key specified in the StreamID string that this application -doesn't support. Note that it's not obligatory for the application to -react this way - it may chose to ignore unknown keys completely, or -to have some keys in the ignore list (which it won't interpret, but tolerate) -while rejecting any others. It is also up to the application -to decide to return this specific error, or more generally report -the syntax error with `SRT_REJX_BAD_REQUEST`. - -#### SRT_REJX_FILEPATH - -The resource type designates a file, and the path either has the wrong syntax -or is not found. In the case where `t=file`, the path should be specified under -the `r` key, and the file specified there must be able to be saved this way. -It's up to the application to decide how to treat this path, how to parse it, -and what this path specifically means. For the `r` key, the application should -at least handle the single filename, and have storage space available to save -it (provided a file of the same name does not already exist there). The -application should decide whether and how to handle all other situations (like -directory path, special markers in the path to be interpreted by the -application, etc.), or to report this error. - -#### SRT_REJX_HOSTNOTFOUND - -The host specified in the `h` key cannot be identified. The `h` key is -generally for a situation when you have multiple DNS names for a host, -so an application may want to extract the name from the URI and set it -to `h` key so that the application can distinguish the request also by -the target host name. The application may however limit the number of -recognized services by host name to some predefined names and not -handle the others, even if this is properly resolved by DNS. In this -case it should report this error. - -The other error codes are HTTP codes adopted for SRT: - -#### SRT_REJX_BAD_REQUEST - -General syntax error. This can be reported in any case when parsing -the StreamID contents failed, or it cannot be properly interpreted. - -#### SRT_REJX_UNAUTHORIZED - -Authentication failed, which makes the client unauthorized to access the -resource. This error, however, confirms that the syntax is correct and -the resource has been properly identified. Note that this cannot be -reported when you use a simple user-password authentication -method because in this case the password is verified only after the -listener callback handler accepts the connection. This error is rather -intended to be reported in case of `t=auth` when the authentication -process has generated some valid session ID, but then the session -connection has specified a resource that is not within the frames -of that authentication. - -#### SRT_REJX_OVERLOAD - -The server is too heavily loaded to process your request, or you -have exceeded credits for accessing the service and the resource. -In HTTP the description mentions payment for a service, but -it is also used by some services for general "credit" management -for a client. In SRT it should be used when your service is doing -any kind of credit management to limit access to selected clients -that "have" enough credit, even if the credit is something the client -can recharge itself, or that can be granted depending on available -service resources. - -#### SRT_REJX_FORBIDDEN - -Access denied to the resource for any reason. This error is -independent of an authorization or authentication error (as reported -by `SRT_REJX_UNAUTHORIZED`). The application can decide which -is more appropriate. This error is usually intended for -a resource that should only be accessed after a successful -authorization over a separate auth-only connection, where the query -in StreamID has correctly specified the resource identity and mode, -but the session ID (in the `s` key) is either (a) not specified, or (b) does -specify a valid session, but the authorization region for this -session does not embrace the specified resource. - -#### SRT_REJX_NOTFOUND - -The resource specified in the `r` key (in combination with the `h` key) -is not found at this time. This error should be only reported if the -information about resource accessibility is allowed to be publicly -visible. Otherwise the application might report authorization -errors. - -#### SRT_REJX_BAD_MODE - -The mode specified in the `m` key in StreamID is not supported for this request. -This may apply to read-only or write-only resources, as well for when interactive -(bidirectional) access is not valid for a resource. - -#### SRT_REJX_UNACCEPTABLE - -Applies when the parameters specified in StreamID cannot be satisfied for the -requested resource, or when `m=publish` but the data format is not acceptable. -This is a general error reporting an unsupported format for data that appears to -be wrong when sending, or a restriction on the data format (as specified in the -details of the resource specification) such that it cannot be provided -when receiving. - -#### SRT_REJX_CONFLICT - -The resource being accessed (as specified by `r` and `h` keys) is locked for -modification. This error should only be reported for `m=publish` when the -resource being accessed is read-only because another client (not necessarily -connected through SRT): - -- is currently publishing into this resource -- has reserved this resource ID for publishing - -Note that this error should be reported when there is no other reason for -having a problem accessing the resource. - -#### SRT_REJX_NOTSUP_MEDIA - -The media type is not supported by the application. The media type is -specified in the `t` key. The currently standard types are -`stream`, `file` and `auth`. An application may extend this list, and -is not obliged to support all of the standard types. - -#### SRT_REJX_LOCKED - -The resource being accessed is locked against any access. This is similar to -`SRT_REJX_CONFLICT`, but in this case the resource is locked for reading -and writing. This is for when the resource should be shown as existing and -available to the client, but access is temporarily blocked. - -#### SRT_REJX_FAILED_DEPEND - -The dependent entity for the request is not present. In this case the -dependent entity is the session, which should be specified in the `s` -key. This means that the specified session ID is nonexistent or it -has already expired. - -#### SRT_REJX_ISE - -Internal server error. This is for a general case when a request has -been correctly verified, with no related problems found, but an -unexpected error occurs after the processing of the request has started. - -#### SRT_REJX_UNIMPLEMENTED - -The request was correctly recognized, but the current software version -of the service (be it SRT or any other software component) doesn't -support it. This should be reported for a case, when some features to -be specified in the StreamID request are supposed to be supported in a -predictable future, but the current version of the server does not -support it, or the support for this feature in this version has been -temporarily blocked. This shouldn't be reported for existing features that are -being deprecated, or older features that are no longer supported -(for this case the general `SRT_REJX_BAD_REQUEST` is more appropriate). - -#### SRT_REJX_GW - -The server acts as a gateway and the target endpoint rejected the -connection. The reason the connection was rejected is unspecified. -The gateway cannot forward the original rejection code from the -target endpoint because this would suggest the error was on the -gateway itself. Use this error with some other mechanism to report -the original target error, if possible. - -#### SRT_REJX_DOWN - -The service is down for maintenance. This can only be reported -when the service has been temporarily replaced by a stub that is only -reporting this error, while the real service is down for maintenance. - -#### SRT_REJX_VERSION - -Application version not supported. This can refer to an application feature -that is unsupported (possibly from an older SRT version), or to a feature -that is no longer supported because of backward compatibility requirements. - -#### SRT_REJX_NOROOM - -The data stream cannot be archived due to a lack of storage space. This is -reported when a request to send a file or a live stream to be archived is -unsuccessful. Note that the length of a file transmission is usually -pre-declared, so this error can be reported early. It can also be reported when -the stream is of undefined length, and there is no more storage space -available. +See the list of rejection codes in the [Rejection Codes](../API/rejection-codes.md) document. ## Example