REST API: Code Inspection (Function Spans)
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Function Spans inspection is a specialized feature of the rust-code-analysis-web server, a high-performance web service built using the Actix Web framework. This feature allows users to programmatically identify the location of every function within a provided source file by extracting its start and end line numbers along with the function name.
This service is part of the broader rust-code-analysis suite, which leverages the Tree-sitter parsing library to analyze source code across multiple programming languages. By exposing these capabilities through a RESTful API, the project enables integration with external tools, IDEs, and CI/CD pipelines that require structural information about code without local library dependencies.
Sources: README.md:16-24, rust-code-analysis-book/src/commands/rest.md:3-12, rust-code-analysis-web/README.md:1-12
API Architecture and Data Flow
The Function Spans inspection is implemented through the rust-code-analysis-web tool, which acts as a bridge between HTTP requests and the core rust-code-analysis library. When a request is sent to the /function endpoint, the server identifies the programming language based on the file extension and processes the code to locate functional blocks.
Request Processing Flow
The server supports two primary modes for retrieving function spans: a JSON-based payload and a plain text/octet-stream payload.
- Language Detection: The system uses
guess_languageto determine the parser needed for the input code. - Configuration: A
WebFunctionCfgobject is initialized, typically containing a unique request ID. - Analysis: The
action::<WebFunctionCallback>function is invoked, utilizing the core library's AST traversal to find function nodes. - Response: The server returns a list of spans containing the function name and coordinates.
The diagram above illustrates the internal routing and execution path for function span requests within the Actix Web server.
Sources: rust-code-analysis-web/src/web/server.rs:188-232, rust-code-analysis-web/src/web/server.rs:271-282
Endpoint Specification
1. Function Spans (JSON)
The JSON endpoint is designed for structured interaction, requiring a specific payload that identifies the file and provides the content.
- URL:
/function - Method:
POST - Header:
Content-Type: application/json
Request Payload Fields:
| Field | Type | Description |
|---|---|---|
id | String | A unique identifier for the request, returned in the response. |
file_name | String | The name of the file, used to determine the language grammar. |
code | String | The raw source code to be analyzed. |
Sources: rust-code-analysis-book/src/commands/rest.md:65-75, rust-code-analysis-web/src/web/server.rs:188-195
2. Function Spans (Plain/Octet-Stream)
For large files or direct binary streaming, the server provides an octet-stream alternative where the metadata is passed via query parameters.
- URL:
/function?file_name=<filename> - Method:
POST - Header:
Content-Type: application/octet-stream
Sources: rust-code-analysis-web/src/web/server.rs:210-232
Data Structures and Response Format
The inspection results are serialized into a standard JSON format. Each identified function is represented as a "span" object.
Span Object Definition
| Field | Type | Description |
|---|---|---|
name | String | The identifier of the function as found in the source. |
start_line | Integer | The line number where the function definition begins. |
end_line | Integer | The line number where the function definition ends. |
error | Boolean | Indicates if a parsing error occurred specifically for this span. |
Example Response:
{
"id": "unique-id",
"spans": [
{
"name": "calculate_total",
"start_line": 10,
"end_line": 25,
"error": false
}
]
}
Sources: rust-code-analysis-book/src/commands/rest.md:79-90, rust-code-analysis-web/src/web/server.rs:569-585
Server Configuration and Execution
The web server can be configured for performance and accessibility using command-line arguments during startup.
| Option | Default | Description |
|---|---|---|
--host | 127.0.0.1 | The IP address the server binds to. |
--port | 8080 | The port on which the service listens. |
-j, --num-jobs | (System dependent) | Number of parallel threads for analysis tasks. |
Startup Command Example:
rust-code-analysis-web --host 0.0.0.0 --port 9090 --num-jobs 4
Sources: rust-code-analysis-book/src/commands/rest.md:15-22, rust-code-analysis-web/README.md:18-28
Conclusion
The REST API's Function Spans feature provides a critical capability for tools that need to understand the physical structure of source code. By utilizing the robust parsing engine of rust-code-analysis, the service delivers precise line-number coordinates across a wide range of supported languages, facilitating automated code navigation and refined metrics calculation at the functional level.