artifacts.go

Overview

The artifacts.go file defines the ArtifactsAPIController, which implements HTTP handlers to provide a RESTful API for managing artifacts associated with user-agent interaction sessions. Artifacts represent files or blobs stored and versioned within a session context, enabling persistence and retrieval of data generated or consumed by agents.

This controller exposes endpoints to:

• List artifact filenames in a session.

• Load artifact content, optionally by specific version.

• Delete artifacts from a session.

It acts as an intermediary between HTTP clients and the underlying artifact storage service, handling request validation, parameter parsing, error handling, and encoding JSON responses.

The file is part of the controllers package and integrates with:

• The artifact.Service interface (from Artifact Management) to perform artifact operations.

• The models.SessionIDFromHTTPParameters helper to parse session identifiers from HTTP request path variables.

• The Gorilla Mux router (mux.Vars) for extracting route parameters.

• A JSON response encoder utility (EncodeJSONResponse) for consistent API responses.

Types and Functions

ArtifactsAPIController

type ArtifactsAPIController struct {
	artifactService artifact.Service
}

Description:
This struct is the main controller type for artifact-related REST API endpoints. It holds a reference to an artifact.Service implementation, which provides the core artifact management functions such as listing, loading, and deleting artifacts.

Usage:
Instantiate with NewArtifactsAPIController by injecting an artifact.Service to enable API handlers to delegate artifact operations.

NewArtifactsAPIController

func NewArtifactsAPIController(artifactService artifact.Service) *ArtifactsAPIController

Description:
Creates a new ArtifactsAPIController instance with the provided artifact service.

Parameters:

• artifactService (artifact.Service): The artifact service backend implementation.

Returns:

• Pointer to a newly initialized ArtifactsAPIController.

Example:

svc := artifact.NewInMemoryService()
controller := NewArtifactsAPIController(svc)

ListArtifactsHandler

func (c *ArtifactsAPIController) ListArtifactsHandler(rw http.ResponseWriter, req *http.Request)

Description:
HTTP handler that lists artifact filenames within a specified session.

Request Parameters:

• Extracts session_id, app_name, and user_id from URL path variables.

Behavior:

• Validates presence and correctness of session parameters.

• Calls artifactService.List() with a ListRequest containing session identifiers.

• On success, returns JSON array of artifact filenames (empty array if none).

• On failure, returns HTTP 400 or 500 with error message.

Response:

• HTTP 200 with JSON body: []string (artifact filenames).

Example:
GET /api/sessions/{app_name}/{user_id}/{session_id}/artifacts

LoadArtifactHandler

func (c *ArtifactsAPIController) LoadArtifactHandler(rw http.ResponseWriter, req *http.Request)

Description:
HTTP handler to load the content of a specific artifact by name for a session. Supports optional version parameter via query string.

Request Parameters:

• Extracts session_id, app_name, user_id, and artifact_name from path variables.

• Optional query param: version (string integer).

Behavior:

• Validates session and artifact name presence.

• Parses version query param if present, converting to integer.

• Constructs an artifact.LoadRequest with session info, filename, and optional version.

• Calls artifactService.Load() to retrieve artifact part.

• On success, returns JSON encoded artifact part.

• On error, returns HTTP 400 or 500 as appropriate.

Response:

• HTTP 200 with JSON body: artifact content part (artifact.Part).

Example:
GET /api/sessions/{app_name}/{user_id}/{session_id}/artifacts/{artifact_name}?version=2

LoadArtifactVersionHandler

func (c *ArtifactsAPIController) LoadArtifactVersionHandler(rw http.ResponseWriter, req *http.Request)

Description:
HTTP handler that loads a specific version of an artifact by name from a session. The version is specified as a path variable.

Request Parameters:

• Extracts session_id, app_name, user_id, artifact_name, and version from URL path variables.

Behavior:

• Validates all parameters are present and that version is an integer.

• Makes an artifact.LoadRequest with the specified version.

• Calls artifactService.Load() to retrieve the artifact.

• Returns JSON encoded artifact part on success.

• Returns HTTP 400 or 500 on error.

Response:

• HTTP 200 with JSON body: artifact content part (artifact.Part).

Example:
GET /api/sessions/{app_name}/{user_id}/{session_id}/artifacts/{artifact_name}/versions/{version}

DeleteArtifactHandler

func (c *ArtifactsAPIController) DeleteArtifactHandler(rw http.ResponseWriter, req *http.Request)

Description:
HTTP handler that deletes an artifact from a session.

Request Parameters:

• Extracts session_id, app_name, user_id, and artifact_name from path variables.

Behavior:

• Validates session and artifact name presence.

• Calls artifactService.Delete() with a DeleteRequest.

• On success, returns HTTP 200 with empty JSON.

• On failure, returns HTTP 400 or 500 with error message.

Response:

• HTTP 200 with empty JSON body (null).

Example:
DELETE /api/sessions/{app_name}/{user_id}/{session_id}/artifacts/{artifact_name}

Implementation Details and Algorithms

• Session Identification:
  Session parameters (app_name, user_id, session_id) are parsed using models.SessionIDFromHTTPParameters. This method ensures consistent extraction and validation of session context across controllers (refer to Session Management).

• Artifact Service Delegation:
  All artifact operations delegate requests to artifactService methods. This abstraction supports pluggable backends like in-memory or Google Cloud Storage (Artifact Management).

• Version Handling:
  The version parameter is optionally accepted either as a query parameter (LoadArtifactHandler) or as a path parameter (LoadArtifactVersionHandler). It must be a valid integer, ensuring explicit version control over artifact retrieval.

• Error Handling:
  Invalid parameters or service errors result in appropriate HTTP error responses:

  • 400 Bad Request for missing or invalid inputs.

  • 500 Internal Server Error for backend failures.

• Response Encoding:
  All successful responses are JSON encoded using EncodeJSONResponse, which sets the appropriate status code and marshals the response body.

Interaction with Other System Components

• Artifact Service (artifact.Service):
  The controller relies on this interface for core artifact operations such as listing, loading, and deleting artifacts. The service may be backed by different storage implementations described in Artifact Management.

• Session Model (models.SessionIDFromHTTPParameters):
  Ensures session context is consistently parsed and validated from HTTP parameters, linking artifact operations to specific user sessions (Session Management).

• Routing and HTTP Framework:
  Uses Gorilla Mux to extract URL variables and route requests to corresponding handlers (REST API and Web Launchers).

• JSON Encoding Utility (EncodeJSONResponse):
  Standardizes JSON response writing with proper status codes and error propagation.

• Other Controllers/Services:
  Complementary to SessionsAPIController and RuntimeAPIController, this controller manages the artifact lifecycle within the broader context of session and agent management.

Usage Examples

List Artifacts in a Session

GET /api/sessions/myapp/user123/session456/artifacts

Response:

[
  "output.json",
  "log.txt",
  "result.csv"
]

Load Artifact Content (Latest Version)

GET /api/sessions/myapp/user123/session456/artifacts/output.json

Response:

{
  "data": "base64-encoded-content",
  "size": 1024,
  "version": 5
}

Load Specific Artifact Version

GET /api/sessions/myapp/user123/session456/artifacts/output.json/versions/3

Response:

{
  "data": "base64-encoded-content",
  "size": 900,
  "version": 3
}

Delete an Artifact

DELETE /api/sessions/myapp/user123/session456/artifacts/log.txt

Response:

null

Diagram: ArtifactsAPIController Structure and Handler Relationships

classDiagram
class ArtifactsAPIController {
-artifactService: artifact.Service
+ListArtifactsHandler()
+LoadArtifactHandler()
+LoadArtifactVersionHandler()
+DeleteArtifactHandler()
}

References

• Artifact Management — Defines the artifact service interfaces and implementations used by this controller.

• Session Management — Provides session identification and validation functions.

• REST API and Web Launchers — Covers the routing and overall REST API architecture where this controller is integrated.

• REST API Controllers — Describes the general role and structure of controllers like this one in the system.