Skip to main content

​
gRPC API

TaskDaemon provides a gRPC API for high-performance clients.

​
Connection

localhost:50051

​
Proto Definition

syntax = "proto3";

package taskdaemon;

service TaskDaemon {
  rpc QueueTask(QueueTaskRequest) returns (QueueTaskResponse);
  rpc GetTask(GetTaskRequest) returns (Task);
  rpc ListTasks(ListTasksRequest) returns (ListTasksResponse);
  rpc DeleteTask(DeleteTaskRequest) returns (DeleteTaskResponse);
  rpc RedriveTask(RedriveTaskRequest) returns (Task);
  rpc HealthCheck(HealthCheckRequest) returns (HealthCheckResponse);
}

message QueueTaskRequest {
  string task_type = 1;
  string task_data_json = 2;
}

message QueueTaskResponse {
  string task_id = 1;
}

message GetTaskRequest {
  string task_id = 1;
}

message Task {
  string id = 1;
  string task_type = 2;
  string status = 3;
  string task_data_json = 4;
  string result_json = 5;
  string error = 6;
  int32 retry_count = 7;
  string created_at = 8;
  string updated_at = 9;
}

message ListTasksRequest {
  int32 limit = 1;
  string status = 2;
}

message ListTasksResponse {
  repeated Task tasks = 1;
}

message DeleteTaskRequest {
  string task_id = 1;
}

message DeleteTaskResponse {
  bool deleted = 1;
}

message RedriveTaskRequest {
  string task_id = 1;
}

message HealthCheckRequest {}

message HealthCheckResponse {
  string status = 1;
  int32 queue_size = 2;
  int32 workers = 3;
}

​
Client Examples

​
Python

import grpc
import taskdaemon_pb2
import taskdaemon_pb2_grpc
import json

channel = grpc.insecure_channel('localhost:50051')
stub = taskdaemon_pb2_grpc.TaskDaemonStub(channel)

# Queue task
response = stub.QueueTask(taskdaemon_pb2.QueueTaskRequest(
    task_type="resize",
    task_data_json=json.dumps({"url": "https://example.com/image.jpg"})
))
print(f"Task ID: {response.task_id}")

# Get task
task = stub.GetTask(taskdaemon_pb2.GetTaskRequest(task_id=response.task_id))
print(f"Status: {task.status}")

​
Go

package main

import (
    "context"
    "encoding/json"
    "log"

    pb "github.com/your/taskdaemon/proto"
    "google.golang.org/grpc"
)

func main() {
    conn, _ := grpc.Dial("localhost:50051", grpc.WithInsecure())
    defer conn.Close()
    
    client := pb.NewTaskDaemonClient(conn)
    
    // Queue task
    data, _ := json.Marshal(map[string]any{"url": "https://example.com/image.jpg"})
    resp, _ := client.QueueTask(context.Background(), &pb.QueueTaskRequest{
        TaskType:     "resize",
        TaskDataJson: string(data),
    })
    log.Printf("Task ID: %s", resp.TaskId)
    
    // Get task
    task, _ := client.GetTask(context.Background(), &pb.GetTaskRequest{
        TaskId: resp.TaskId,
    })
    log.Printf("Status: %s", task.Status)
}

​
Node.js

const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');

const packageDefinition = protoLoader.loadSync('taskdaemon.proto');
const proto = grpc.loadPackageDefinition(packageDefinition).taskdaemon;

const client = new proto.TaskDaemon('localhost:50051', grpc.credentials.createInsecure());

// Queue task
client.QueueTask({
  task_type: 'resize',
  task_data_json: JSON.stringify({ url: 'https://example.com/image.jpg' })
}, (err, response) => {
  console.log('Task ID:', response.task_id);
});

​
Reflection

gRPC reflection is enabled for tools like grpcurl: 
# List services
grpcurl -plaintext localhost:50051 list

# Describe service
grpcurl -plaintext localhost:50051 describe taskdaemon.TaskDaemon

# Queue task
grpcurl -plaintext -d '{"task_type": "echo", "task_data_json": "{\"msg\": \"hello\"}"}' \
  localhost:50051 taskdaemon.TaskDaemon/QueueTask

​
When to Use gRPC

Use gRPC over HTTP when:
  • Building high-throughput internal services
  • Need streaming (future feature)
  • Using strongly-typed clients
  • Performance is critical
Use HTTP when:
  • Quick testing with curl
  • Browser-based clients
  • Simpler integration needs