Coverage for mcpgateway / plugins / framework / constants.py: 100%

1# -*- coding: utf-8 -*- 

2"""Location: ./mcpgateway/plugins/framework/constants.py 

3Copyright 2025 

4SPDX-License-Identifier: Apache-2.0 

5Authors: Teryl Taylor 

6 

7Plugins constants file. 

8This module stores a collection of plugin constants used throughout the framework. 

9""" 

10 

11# Standard 

12 

13# Standard 

14from dataclasses import dataclass 

15from types import MappingProxyType 

16from typing import Mapping 

17 

18# Model constants. 

19# Specialized plugin types. 

20EXTERNAL_PLUGIN_TYPE = "external" 

21 

22# MCP related constants. 

23PYTHON_SUFFIX = ".py" 

24URL = "url" 

25SCRIPT = "script" 

26CMD = "cmd" 

27ENV = "env" 

28CWD = "cwd" 

29UDS = "uds" 

30 

31NAME = "name" 

32PLUGIN_NAME = "plugin_name" 

33PAYLOAD = "payload" 

34CONTEXT = "context" 

35RESULT = "result" 

36ERROR = "error" 

37IGNORE_CONFIG_EXTERNAL = "ignore_config_external" 

38 

39# Global Context Metadata fields 

40 

41TOOL_METADATA = "tool" 

42GATEWAY_METADATA = "gateway" 

43 

44# MCP Plugin Server Runtime constants 

45MCP_SERVER_NAME = "MCP Plugin Server" 

46MCP_SERVER_INSTRUCTIONS = "External plugin server for ContextForge" 

47GET_PLUGIN_CONFIGS = "get_plugin_configs" 

48GET_PLUGIN_CONFIG = "get_plugin_config" 

49HOOK_TYPE = "hook_type" 

50INVOKE_HOOK = "invoke_hook" 

51 

52 

53@dataclass(frozen=True) 

54class PluginViolationCode: 

55 """ 

56 Plugin violation codes as an immutable dataclass object. 

57 

58 Provide Mapping for violation codes to their corresponding HTTP status codes for proper error responses. 

59 """ 

60 

61 code: int 

62 name: str 

63 message: str 

64 

65 

66PLUGIN_VIOLATION_CODE_MAPPING: Mapping[str, PluginViolationCode] = MappingProxyType( 

67 # MappingProxyType will make sure the resulting object is immutable and hence this will act as a constant. 

68 { 

69 # Rate Limiting 

70 "RATE_LIMIT": PluginViolationCode(429, "RATE_LIMIT", "Used when rate limit is exceeded (rate_limiter plugin)"), 

71 # Resource & URI Validation 

72 "INVALID_URI": PluginViolationCode(400, "INVALID_URI", "Used when URI cannot be parsed or has invalid format (resource_filter, cedar, opa)"), 

73 "PROTOCOL_BLOCKED": PluginViolationCode(403, "PROTOCOL_BLOCKED", "Used when protocol/scheme is not allowed (resource_filter)"), 

74 "DOMAIN_BLOCKED": PluginViolationCode(403, "DOMAIN_BLOCKED", "Used when domain is in blocklist (resource_filter)"), 

75 "CONTENT_TOO_LARGE": PluginViolationCode(413, "CONTENT_TOO_LARGE", "Used when resource content exceeds size limit (resource_filter)"), 

76 # Content Moderation & Safety 

77 "CONTENT_MODERATION": PluginViolationCode(422, "CONTENT_MODERATION", "Used when harmful content is detected (content_moderation plugin)"), 

78 "MODERATION_ERROR": PluginViolationCode(503, "MODERATION_ERROR", "Used when moderation service fails (content_moderation plugin)"), 

79 "PII_DETECTED": PluginViolationCode(422, "PII_DETECTED", "Used when PII is detected in content (pii_filter plugin)"), 

80 "SENSITIVE_CONTENT": PluginViolationCode(422, "SENSITIVE_CONTENT", "Used when sensitive information is detected"), 

81 # Authentication & Authorization 

82 "INVALID_TOKEN": PluginViolationCode(401, "INVALID_TOKEN", "Used for invalid/expired tokens (simple_token_auth example)"), # nosec B105 - Not a password; INVALID_TOKEN is a HTTP Status Code 

83 "API_KEY_REVOKED": PluginViolationCode(401, "API_KEY_REVOKED", "Used when API key has been revoked (custom_auth_example)"), 

84 "AUTH_REQUIRED": PluginViolationCode(401, "AUTH_REQUIRED", "Used when authentication is missing"), 

85 # Generic Violation Codes 

86 "PROHIBITED_CONTENT": PluginViolationCode(422, "PROHIBITED_CONTENT", "Used when content violates policy rules"), 

87 "BLOCKED_CONTENT": PluginViolationCode(403, "BLOCKED_CONTENT", "Used when content is explicitly blocked by policy"), 

88 "BLOCKED": PluginViolationCode(403, "BLOCKED", "Generic blocking violation"), 

89 "EXECUTION_ERROR": PluginViolationCode(500, "EXECUTION_ERROR", "Used when plugin execution fails"), 

90 "PROCESSING_ERROR": PluginViolationCode(500, "PROCESSING_ERROR", "Used when processing encounters an error"), 

91 } 

92) 

93 

94VALID_HTTP_STATUS_CODES: dict[int, str] = { # RFC 9110 

95 # 4xx — Client Error 

96 400: "Bad Request", 

97 401: "Unauthorized", 

98 402: "Payment Required", 

99 403: "Forbidden", 

100 404: "Not Found", 

101 405: "Method Not Allowed", 

102 406: "Not Acceptable", 

103 407: "Proxy Authentication Required", 

104 408: "Request Timeout", 

105 409: "Conflict", 

106 410: "Gone", 

107 411: "Length Required", 

108 412: "Precondition Failed", 

109 413: "Content Too Large", # (was "Payload Too Large" before RFC 9110) 

110 414: "URI Too Long", 

111 415: "Unsupported Media Type", 

112 416: "Range Not Satisfiable", 

113 417: "Expectation Failed", 

114 418: "(Unused)", 

115 421: "Misdirected Request", 

116 422: "Unprocessable Content", # (was "Unprocessable Entity") 

117 423: "Locked", 

118 424: "Failed Dependency", 

119 425: "Too Early", 

120 426: "Upgrade Required", 

121 428: "Precondition Required", 

122 429: "Too Many Requests", 

123 431: "Request Header Fields Too Large", 

124 451: "Unavailable For Legal Reasons", 

125 # 5xx — Server Error 

126 500: "Internal Server Error", 

127 501: "Not Implemented", 

128 502: "Bad Gateway", 

129 503: "Service Unavailable", 

130 504: "Gateway Timeout", 

131 505: "HTTP Version Not Supported", 

132 506: "Variant Also Negotiates", 

133 507: "Insufficient Storage", 

134 508: "Loop Detected", 

135 510: "Not Extended", 

136 511: "Network Authentication Required", 

137}