System Functions

Reserved namespaces and built-in functions

Overview

Function names beginning with mesh. are reserved for system functions. Applications MUST NOT define functions in this namespace.

System functions provide protocol-level capabilities like health checks, introspection, and operation management.

Reserved Namespace

Rules

Function names starting with mesh. are reserved
Applications MUST NOT define custom functions with this prefix
Servers SHOULD implement core system functions
Clients MAY call system functions like any other function

Format

mesh.<category>.<action>

Categories:

mesh.ping — Simple connectivity check
mesh.health — Comprehensive health check
mesh.describe — Introspection
mesh.capabilities — Feature discovery
mesh.operation.* — Async operation management

Core System Functions

mesh.ping

Health check function. MUST return immediately if service is healthy.

Request:

{
  "protocol": { "name": "mesh", "version": "0.1.0" },
  "id": "req_health",
  "call": {
    "function": "mesh.ping",
    "version": "1",
    "arguments": {}
  }
}

Response:

{
  "protocol": { "name": "mesh", "version": "0.1.0" },
  "id": "req_health",
  "result": {
    "status": "healthy",
    "timestamp": "2024-01-15T10:30:00Z"
  },
  "meta": {
    "node": "orders-api-2",
    "duration": { "value": 1, "unit": "millisecond" }
  }
}

Arguments: None required

Returns:

Field	Type	Description
`status`	string	Health status: MUST be one of `healthy`, `degraded`, `unhealthy`
`timestamp`	string	MUST be ISO 8601 timestamp
`details`	object	OPTIONAL additional health info

mesh.health

Comprehensive health check with component-level status. Use for load balancer health checks, dependency monitoring, and operational visibility.

Request:

{
  "protocol": { "name": "mesh", "version": "0.1.0" },
  "id": "req_health",
  "call": {
    "function": "mesh.health",
    "version": "1",
    "arguments": {}
  }
}

Response:

{
  "protocol": { "name": "mesh", "version": "0.1.0" },
  "id": "req_health",
  "result": {
    "status": "healthy",
    "components": {
      "database": {
        "status": "healthy",
        "latency": { "value": 2, "unit": "millisecond" }
      },
      "cache": {
        "status": "healthy",
        "latency": { "value": 1, "unit": "millisecond" }
      },
      "queue": {
        "status": "healthy"
      }
    },
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Arguments:

Field	Type	Required	Description
`component`	string	No	Check specific component only
`include_details`	boolean	No	Include detailed check info (default: `true`)

Returns:

Field	Type	Description
`status`	string	Aggregate status (see below)
`components`	object	Component health status
`functions`	object	Function-level health (optional)
`timestamp`	string	ISO 8601 timestamp
`version`	string	Optional service version

Health Status Values

Status	Description	HTTP Equivalent
`healthy`	All systems operational	200
`degraded`	Functional but impaired	200
`unhealthy`	Not able to serve requests	503

Component Check Object

Each component in components contains:

Field	Type	Description
`status`	string	Component status
`latency`	object	Optional response time
`message`	string	Optional status message
`last_check`	string	Optional last successful check time

Aggregate Status Rules

The top-level status MUST reflect the worst component status:

If ANY component is unhealthy → aggregate is unhealthy
If ANY component is degraded (and none unhealthy) → aggregate is degraded
If ALL components are healthy → aggregate is healthy

Check Specific Component

// Request
{
  "call": {
    "function": "mesh.health",
    "version": "1",
    "arguments": {
      "component": "database"
    }
  }
}

// Response
{
  "result": {
    "status": "healthy",
    "components": {
      "database": {
        "status": "healthy",
        "latency": { "value": 2, "unit": "millisecond" },
        "message": "Primary connection active"
      }
    },
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Degraded Example

{
  "result": {
    "status": "degraded",
    "components": {
      "database": {
        "status": "healthy",
        "latency": { "value": 3, "unit": "millisecond" }
      },
      "cache": {
        "status": "degraded",
        "message": "Failover to secondary, elevated latency",
        "latency": { "value": 45, "unit": "millisecond" }
      },
      "external_api": {
        "status": "healthy"
      }
    },
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Unhealthy Example

{
  "result": {
    "status": "unhealthy",
    "components": {
      "database": {
        "status": "unhealthy",
        "message": "Connection refused",
        "last_check": "2024-01-15T10:29:55Z"
      },
      "cache": {
        "status": "healthy"
      }
    },
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Liveness vs Readiness

For Kubernetes-style probes, use the component argument:

Probe	Component	Purpose
Liveness	`"self"`	Is the process alive?
Readiness	(omit)	Can it serve traffic?

// Liveness probe - just checks if service is running
{
  "arguments": {
    "component": "self",
    "include_details": false
  }
}

// Response
{
  "result": {
    "status": "healthy",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Standard Component Names

Services SHOULD use these component names when applicable:

Component	Description
`self`	The service process itself
`database`	Primary database
`cache`	Caching layer (Redis, Memcached)
`queue`	Message queue
`storage`	Object/file storage
`search`	Search engine (Elasticsearch)
`<service>_api`	External service dependency

Function-Level Health

Functions can report their own health status independently of component health. This enables graceful degradation where some functions remain available while others are temporarily disabled.

Function Health Object

Field	Type	Description
`status`	string	Function status (see below)
`message`	string	Optional explanation
`until`	string	Optional ISO 8601 timestamp
`retry_after`	object	Optional duration before retry

Function Status Values

Status	Description
`healthy`	Function is fully operational
`degraded`	Function works but with limitations
`disabled`	Function temporarily unavailable

Example: Function Disabled

{
  "result": {
    "status": "degraded",
    "components": {
      "database": { "status": "healthy" },
      "cache": { "status": "healthy" }
    },
    "functions": {
      "reports.generate": {
        "status": "disabled",
        "message": "Disabled during maintenance window",
        "until": "2024-01-15T12:00:00Z"
      },
      "orders.create": {
        "status": "healthy"
      },
      "orders.list": {
        "status": "healthy"
      }
    },
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Example: Function Degraded

{
  "result": {
    "status": "degraded",
    "components": {
      "database": { "status": "healthy" },
      "external_api": { "status": "degraded" }
    },
    "functions": {
      "orders.create": {
        "status": "degraded",
        "message": "Payment validation disabled, orders require manual review"
      },
      "exports.create": {
        "status": "degraded",
        "message": "Rate limited due to high load",
        "retry_after": { "value": 30, "unit": "second" }
      }
    },
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Aggregate Status with Functions

Function health contributes to aggregate status:

If ANY function is disabled → aggregate is at least degraded
Function degraded → aggregate is at least degraded
Component unhealthy always takes precedence → aggregate is unhealthy

Calling Disabled Functions

When a function is marked disabled, calls to that function SHOULD return:

{
  "errors": [{
    "code": "FUNCTION_DISABLED",
    "message": "Disabled for scheduled maintenance",
    "retryable": true,
    "details": {
      "function": "reports.generate",
      "until": "2024-01-15T12:00:00Z"
    }
  }]
}

mesh.capabilities

Discover what the service supports.

Request:

{
  "protocol": { "name": "mesh", "version": "0.1.0" },
  "id": "req_caps",
  "call": {
    "function": "mesh.capabilities",
    "version": "1",
    "arguments": {}
  }
}

Response:

{
  "protocol": { "name": "mesh", "version": "0.1.0" },
  "id": "req_caps",
  "result": {
    "service": "orders-api",
    "protocol_versions": ["0.1.0"],
    "extensions": [
      {
        "urn": "urn:mesh:ext:async",
        "documentation": "urn:mesh:ext:async"
      }
    ],
    "functions": [
      "orders.create",
      "orders.get",
      "orders.list",
      "orders.cancel"
    ],
    "limits": {
      "max_request_bytes": 1048576,
      "default_deadline": { "value": 30, "unit": "second" }
    }
  }
}

Arguments: None required

Returns:

Field	Type	Description
`service`	string	Service identifier
`protocol_versions`	array	Supported Mesh protocol versions
`extensions`	array	Supported extensions
`functions`	array	Available function names (without versions)
`limits`	object	Service limits

mesh.describe

Get detailed information about a specific function, including schema, operation type, and capabilities.

Request:

{
  "protocol": { "name": "mesh", "version": "0.1.0" },
  "id": "req_describe",
  "call": {
    "function": "mesh.describe",
    "version": "1",
    "arguments": {
      "function": "orders.create"
    }
  }
}

Response:

{
  "protocol": { "name": "mesh", "version": "0.1.0" },
  "id": "req_describe",
  "result": {
    "function": "orders.create",
    "description": "Create a new order",
    "operation": "write",
    "versions": [
      {
        "version": "1",
        "status": "stable",
        "description": "Original version",
        "deprecated": {
          "reason": "Use version 2 for improved validation",
          "sunset": "2025-06-01"
        }
      },
      {
        "version": "2",
        "status": "stable",
        "description": "Current version with improved validation",
        "schema": {
          "arguments": {
            "type": "object",
            "properties": {
              "customer_id": { "type": "string" },
              "items": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "product_id": { "type": "string" },
                    "quantity": { "type": "integer", "minimum": 1 }
                  },
                  "required": ["product_id", "quantity"]
                }
              },
              "shipping_address": { "$ref": "#/definitions/address" }
            },
            "required": ["customer_id", "items"]
          },
          "returns": {
            "type": "object",
            "properties": {
              "id": { "type": "string" },
              "status": { "type": "string", "enum": ["pending", "confirmed"] },
              "total": { "type": "number" }
            }
          },
          "definitions": {
            "address": {
              "type": "object",
              "properties": {
                "street": { "type": "string" },
                "city": { "type": "string" },
                "country_code": { "type": "string", "pattern": "^[A-Z]{2}$" }
              }
            }
          }
        }
      },
      {
        "version": "3",
        "status": "beta",
        "description": "Beta with async support"
      }
    ],
    "recommended_version": "2"
  }
}

Arguments:

Field	Type	Required	Description
`function`	string	Yes	Function name to describe
`version`	string	No	Specific version (returns all if omitted)
`include_schema`	boolean	No	Include JSON Schema (default: `true`)

Returns:

Field	Type	Description
`function`	string	Function name
`description`	string	Human-readable description
`operation`	string	Operation type (see below)
`versions`	array	Available versions with status
`recommended_version`	string	Suggested version to use

Operation Types

The operation field indicates the function’s effect:

Type	Description	Idempotent	Safe
`read`	Retrieves data without modification	Yes	Yes
`write`	Creates or updates data	Depends	No
`delete`	Removes data	Yes	No

Safe means the operation has no side effects. Idempotent means repeated calls produce the same result.

Schema Object

Each version MAY include a schema object with JSON Schema definitions:

Field	Type	Description
`arguments`	object	JSON Schema for function arguments
`returns`	object	JSON Schema for successful result
`definitions`	object	Shared schema definitions

Schemas use JSON Schema Draft 2020-12 with these extensions:

$ref for referencing definitions
Standard formats: date-time, email, uri, etc.

Version Status Values

Status	Description
`stable`	Production-ready, fully supported
`beta`	Testing, MAY change
`removed`	No longer available (MAY be omitted from list)

Deprecation is indicated by the presence of a deprecated object, not a status value. See Deprecated Object.

Pagination Discovery

For list functions, mesh.describe returns pagination capabilities:

{
  "result": {
    "function": "orders.list",
    "description": "List orders with filtering and pagination",
    "operation": "read",
    "versions": [
      {
        "version": "1",
        "status": "stable",
        "pagination": {
          "styles": ["cursor", "offset"],
          "default_style": "cursor",
          "default_limit": 50,
          "max_limit": 100
        }
      }
    ],
    "recommended_version": "1"
  }
}

Pagination Object

Field	Type	Description
`styles`	array	Supported pagination styles
`default_style`	string	Style used when not specified
`default_limit`	integer	Items per page when not specified
`max_limit`	integer	Maximum allowed limit

Pagination Styles

Style	Description
`cursor`	Opaque cursor-based pagination
`offset`	Numeric offset pagination
`keyset`	Key-based pagination (e.g., `after_id`)

Query Capabilities

For functions supporting filtering, sorting, and sparse fieldsets:

{
  "result": {
    "function": "orders.list",
    "operation": "read",
    "versions": [
      {
        "version": "1",
        "status": "stable",
        "capabilities": {
          "filters": {
            "self": ["id", "status", "created_at", "total_amount"],
            "customer": ["id", "type", "country_code"]
          },
          "sorts": ["created_at", "total_amount", "status"],
          "fields": {
            "self": ["id", "status", "total_amount", "created_at", "updated_at"],
            "customer": ["id", "name", "email"]
          },
          "relationships": ["customer", "items", "shipments"]
        },
        "pagination": {
          "styles": ["cursor"],
          "default_limit": 50,
          "max_limit": 100
        }
      }
    ]
  }
}

Capabilities Object

Field	Type	Description
`filters`	object	Filterable attributes by resource
`sorts`	array	Sortable attributes
`fields`	object	Selectable fields by resource
`relationships`	array	Includable relationships

mesh.operation.status

Check status of an async operation. See Async.

Request:

{
  "protocol": { "name": "mesh", "version": "0.1.0" },
  "id": "req_op_status",
  "call": {
    "function": "mesh.operation.status",
    "version": "1",
    "arguments": {
      "operation_id": "op_xyz789"
    }
  }
}

Arguments:

Field	Type	Required	Description
`operation_id`	string	Yes	Operation ID to check

Returns: See Async for response format.

mesh.operation.cancel

Cancel a pending async operation.

Request:

{
  "protocol": { "name": "mesh", "version": "0.1.0" },
  "id": "req_op_cancel",
  "call": {
    "function": "mesh.operation.cancel",
    "version": "1",
    "arguments": {
      "operation_id": "op_xyz789"
    }
  }
}

Arguments:

Field	Type	Required	Description
`operation_id`	string	Yes	Operation ID to cancel

Returns:

Field	Type	Description
`operation_id`	string	Operation ID
`status`	string	New status (MUST be `cancelled`)
`cancelled_at`	string	MUST be ISO 8601 timestamp

mesh.operation.list

List operations for the current caller.

Request:

{
  "protocol": { "name": "mesh", "version": "0.1.0" },
  "id": "req_op_list",
  "call": {
    "function": "mesh.operation.list",
    "version": "1",
    "arguments": {
      "status": "processing",
      "limit": 10
    }
  }
}

Arguments:

Field	Type	Required	Description
`status`	string	No	Filter by status
`function`	string	No	Filter by function name
`limit`	integer	No	Max results (default 50)
`cursor`	string	No	Pagination cursor

Returns:

{
  "operations": [
    {
      "id": "op_abc123",
      "function": "reports.generate",
      "version": "1",
      "status": "processing",
      "progress": 0.45,
      "started_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "op_def456",
      "function": "exports.create",
      "version": "1",
      "status": "processing",
      "progress": 0.12,
      "started_at": "2024-01-15T10:31:00Z"
    }
  ],
  "next_cursor": "eyJpZCI6Im9wX2RlZjQ1NiJ9"
}

Future Reserved Namespaces

These namespaces are reserved for potential future use:

Namespace	Intended Purpose
`mesh.auth.*`	Authentication functions
`mesh.schema.*`	Schema introspection
`mesh.metrics.*`	Metrics and observability
`mesh.config.*`	Configuration discovery

Implementation Requirements

Required Functions

Servers SHOULD implement:

mesh.ping — Simple connectivity check
mesh.health — Comprehensive health check

Recommended Functions

Servers SHOULD implement if applicable:

mesh.capabilities — For service discovery
mesh.describe — For API exploration
mesh.operation.* — If supporting async operations

Ping vs Health

Function	Purpose	Use Case
`mesh.ping`	Fast connectivity check	Heartbeats, basic liveness
`mesh.health`	Dependency-aware health	Load balancers, readiness probes

Use mesh.ping when you just need to know if the service is reachable. Use mesh.health when you need to know if the service can actually serve requests (dependencies are healthy).

Custom System Functions

Organizations MAY define additional system functions within their own namespace:

myorg.system.audit
myorg.system.config

These MUST NOT use the mesh. prefix.

Examples

Health Check

// Request
{
  "protocol": { "name": "mesh", "version": "0.1.0" },
  "id": "health_001",
  "call": {
    "function": "mesh.ping",
    "version": "1"
  }
}

// Response
{
  "protocol": { "name": "mesh", "version": "0.1.0" },
  "id": "health_001",
  "result": {
    "status": "healthy",
    "timestamp": "2024-01-15T10:30:00Z",
    "details": {
      "database": "connected",
      "cache": "connected",
      "queue": "connected"
    }
  }
}

Function Discovery

// Request
{
  "protocol": { "name": "mesh", "version": "0.1.0" },
  "id": "discover_001",
  "call": {
    "function": "mesh.capabilities",
    "version": "1"
  }
}

// Response
{
  "protocol": { "name": "mesh", "version": "0.1.0" },
  "id": "discover_001",
  "result": {
    "service": "user-service",
    "protocol_versions": ["0.1.0"],
    "extensions": [
      { "urn": "urn:mesh:ext:async" }
    ],
    "functions": [
      "users.create",
      "users.get",
      "users.update",
      "users.delete",
      "users.list"
    ],
    "limits": {
      "default_deadline": { "value": 10, "unit": "second" }
    }
  }
}

Degraded Health

{
  "protocol": { "name": "mesh", "version": "0.1.0" },
  "id": "health_002",
  "result": {
    "status": "degraded",
    "timestamp": "2024-01-15T10:30:00Z",
    "details": {
      "database": "connected",
      "cache": "disconnected",
      "queue": "connected"
    },
    "message": "Cache unavailable, operating with degraded performance"
  }
}