gRPC API

TaskDaemon grpc api guide

gRPC API

The default endpoint is localhost:50051, using plaintext gRPC with reflection. The API has unary requests; it currently has no task streaming RPC.

Proto Definition

Generate clients from crates/task-daemon-grpc/proto/task_daemon.proto in the TaskDaemon repository. Source access currently requires GitHub authorization for the private repository. You can also copy the complete schema below to task_daemon.proto to generate clients. The current schema is:

syntax = "proto3";

package taskdaemon;

// TaskDaemon gRPC service
service TaskDaemon {
  // Queue a new task
  rpc QueueTask(TaskRequest) returns (TaskResponse);

  // Get task status and result
  rpc GetTask(TaskIdRequest) returns (TaskInfo);

  // Get health status
  rpc GetHealth(Empty) returns (HealthStatus);

  // Get metrics
  rpc GetMetrics(Empty) returns (MetricsSummary);

  // List recent tasks
  rpc ListTasks(ListTasksRequest) returns (TaskList);

  // Delete a task
  rpc DeleteTask(TaskIdRequest) returns (DeleteResponse);

  // Redrive a failed task
  rpc RedriveTask(TaskIdRequest) returns (RedriveResponse);
}

// Empty message for requests with no parameters
message Empty {}

// Task request - using JSON string for flexibility
message TaskRequest {
  string task_type = 1;
  string task_data_json = 2;  // JSON string - simple and universal
}

// Task response
message TaskResponse {
  string task_id = 1;
}

// Task ID request
message TaskIdRequest {
  string task_id = 1;
}

// Task information
message TaskInfo {
  string id = 1;
  string task_type = 2;
  string task_data = 3;
  string status = 4;
  string created_at = 5;
  string completed_at = 6;
  int32 attempts = 7;
  string last_error = 8;
  string result = 9;
}

// Health status
message HealthStatus {
  string status = 1;
  int32 queue_size = 2;
  string timestamp = 3;
  int32 workers = 4;
}

// Metrics summary
message MetricsSummary {
  double tasks_received = 1;
  double tasks_processed_success = 2;
  double tasks_processed_failed = 3;
  double queue_size = 4;
  bool daemon_healthy = 5;
}

// List tasks request
message ListTasksRequest {
  int32 limit = 1;
}

// Task list
message TaskList {
  repeated TaskInfo tasks = 1;
}

// Delete response
message DeleteResponse {
  bool success = 1;
  string message = 2;
}

// Redrive response
message RedriveResponse {
  bool success = 1;
  string message = 2;
}

QueueTask accepts JSON encoded in task_data_json and uses default priority 50. There is no gRPC priority field. TaskInfo.task_data and result are JSON strings; absent results, errors, and completion timestamps are empty strings. attempts starts at zero and increments on retry scheduling or a Failed marking; successful completion does not increment it. The handler’s request uses attempt = stored attempts + 1 before execution. An initial success therefore has request attempt: 1 and API attempts: 0; an initial terminal failure stores attempts: 1. Recovery can repeat the same request attempt, so these fields do not count all handler executions.

ListTasks clamps its requested limit to 1–100; an omitted or zero limit returns at most one task. It has no status filter. DeleteTask and RedriveTask report their outcome in success and message. Redrive preserves attempts and retry budget. GetHealth reads a fresh Pending count, while GetMetrics.queue_size uses the one-second sample. All counters are process-local and reset on restart.

Python Client

Install grpcio and grpcio-tools, then generate the two modules from the schema in your working directory:

python -m grpc_tools.protoc -I. --python_out=. --grpc_python_out=. task_daemon.proto

import json
import grpc
import task_daemon_pb2 as pb
import task_daemon_pb2_grpc as rpc

with grpc.insecure_channel("localhost:50051") as channel:
    client = rpc.TaskDaemonStub(channel)
    queued = client.QueueTask(pb.TaskRequest(
        task_type="echo",
        task_data_json=json.dumps({"message": "hello"}),
    ), timeout=10)
    task = client.GetTask(pb.TaskIdRequest(task_id=queued.task_id), timeout=10)
    print(task.id, task.status)
    health = client.GetHealth(pb.Empty(), timeout=10)
    print(health.status, health.queue_size)

Poll GetTask until completed or failed before reading the result.

Go Client

Generate Go bindings using protoc-gen-go and protoc-gen-go-grpc. The schema has no go_package option, so provide your own module mapping, for example in a module named example.com/taskclient:

protoc -I. \
  --go_out=. --go_opt=module=example.com/taskclient \
  --go_opt=Mtask_daemon.proto=example.com/taskclient/proto \
  --go-grpc_out=. --go-grpc_opt=module=example.com/taskclient \
  --go-grpc_opt=Mtask_daemon.proto=example.com/taskclient/proto \
  task_daemon.proto

package main

import (
    "context"
    "log"
    "time"

    pb "example.com/taskclient/proto"
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/insecure"
)

func main() {
    conn, err := grpc.NewClient("localhost:50051", grpc.WithTransportCredentials(insecure.NewCredentials()))
    if err != nil { log.Fatal(err) }
    defer conn.Close()
    client := pb.NewTaskDaemonClient(conn)
    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
    defer cancel()
    queued, err := client.QueueTask(ctx, &pb.TaskRequest{
        TaskType: "echo", TaskDataJson: `{"message":"hello"}`,
    })
    if err != nil { log.Fatal(err) }
    task, err := client.GetTask(ctx, &pb.TaskIdRequest{TaskId: queued.TaskId})
    if err != nil { log.Fatal(err) }
    log.Printf("Task %s: %s", task.Id, task.Status)
}

Node.js Client

Install @grpc/grpc-js and @grpc/proto-loader. keepCase: true preserves the schema’s snake_case field names:

const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const definition = protoLoader.loadSync('task_daemon.proto', { keepCase: true });
const proto = grpc.loadPackageDefinition(definition).taskdaemon;
const client = new proto.TaskDaemon('localhost:50051', grpc.credentials.createInsecure());

client.queueTask({
  task_type: 'echo',
  task_data_json: JSON.stringify({ message: 'hello' }),
}, (err, response) => {
  if (err) throw err;
  console.log('Task ID:', response.task_id);
  client.close();
});

Reflection and grpcurl

grpcurl -plaintext localhost:50051 list
grpcurl -plaintext localhost:50051 describe taskdaemon.TaskDaemon
grpcurl -plaintext -d '{"task_type":"echo","task_data_json":"{\"message\":\"hello\"}"}' \
  localhost:50051 taskdaemon.TaskDaemon/QueueTask
grpcurl -plaintext -d '{}' localhost:50051 taskdaemon.TaskDaemon/GetHealth

Use gRPC for generated typed clients or existing gRPC services. Use HTTP for curl, browser integration, or priority submission.