Skip to content

Commit 1d788a2

Browse files
ErinCompaanErinCompaan
committed
feat: add protobuf jobs files
1 parent 4e1ae14 commit 1d788a2

File tree

2 files changed

+197
-0
lines changed

2 files changed

+197
-0
lines changed

‎proto/tamr/api/v1beta1/errors.proto‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
syntax = "proto3";
2+
3+
package tamr.api.v1beta1;
4+
5+
option go_package = "tamr.api.v1beta1";
6+
option java_package = "com.tamr.api.v1beta1.errors.protos";
7+
option java_multiple_files = true;
8+
9+
message Error {
10+
// A short error code that summarizes the error. This is a constant value that identifies the cause of the error.
11+
// This should be at most 63 characters and match a regular expression of `[A-Z][A-Z0-9_]+[A-Z0-9]`, which represents
12+
// UPPER_SNAKE_CASE.
13+
string reason = 1;
14+
15+
// A human-readable description of the error. Error messages should be concise and helpful, providing specifics about
16+
// the problem when appropriate and suggesting next steps to resolve. Error messages should not expose sensitive
17+
// information about system internals.
18+
string message = 2;
19+
}

‎proto/tamr/api/v1beta1/jobs.proto‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
syntax = "proto3";
2+
3+
package tamr.api.v1beta1;
4+
5+
option go_package = "tamr.api.v1beta1";
6+
option java_package = "com.tamr.api.v1beta1.jobs.protos";
7+
option java_multiple_files = true;
8+
9+
import "google/api/annotations.proto";
10+
import "google/api/field_behavior.proto";
11+
import "google/protobuf/timestamp.proto";
12+
import "tamr/api/v1beta1/errors.proto";
13+
14+
service Jobs {
15+
// Gets details of a job.
16+
rpc GetJob (GetJobRequest) returns (Job) {
17+
option (google.api.http) = {
18+
get: "/api/v1beta1/jobs/{job_id}"
19+
};
20+
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
21+
summary: "get"
22+
description: "Fetch details of a job, including its configuration and status."
23+
};
24+
}
25+
26+
// Lists a page of jobs.
27+
rpc ListJobs (ListJobsRequest) returns (ListJobsResponse) {
28+
option (google.api.http) = {
29+
get: "/api/v1beta1/jobs"
30+
};
31+
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
32+
summary: "list"
33+
description: "Fetch a page of jobs."
34+
};
35+
}
36+
37+
// Signals a job to stop executing. `PENDING` jobs are cancelled immediately. `RUNNING` jobs are interrupts and will
38+
// begin to terminate. This is an asynchronous operation and it may take some time for a `RUNNING` job to transition
39+
// to `DONE`. In fact, a job may still succeed or fail after `StopJob` has been called. Users should monitor job
40+
// status with `GetJob` until the job is `DONE`."
41+
rpc StopJob (StopJobRequest) returns (StopJobResponse) {
42+
option (google.api.http) = {
43+
post: "/api/v1beta1/jobs/{job_id}:stop"
44+
body: "*"
45+
};
46+
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
47+
summary: "stop"
48+
description:
49+
"Signal a job to stop.\n\n"
50+
"* If the job is `PENDING`, it will immediately transition to `DONE`.\n"
51+
"* If the job is `RUNNING`, then the job will interrupt its work and terminate.\n"
52+
"* If the job is `DONE`, `stop` has no effect.\n\n"
53+
"*Note*: this is an asynchronous operation and it may take some time before a `RUNNING` job transitions to "
54+
"`DONE`. In fact, a job may still succeed or fail after `stop` has been signalled. Users should monitor job "
55+
"status with `get` until the job is `DONE`."
56+
};
57+
}
58+
59+
// Creates a new job and starts planning and execution.
60+
rpc CreateJob (CreateJobRequest) returns (Job) {
61+
option (google.api.http) = {
62+
post: "/api/v1beta1/jobs"
63+
body: "job"
64+
};
65+
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
66+
summary: "create"
67+
description: "Create a job for immediate execution."
68+
};
69+
}
70+
}
71+
72+
message CreateJobRequest {
73+
// Required. Definition of the job to create.
74+
Job job = 1 [(google.api.field_behavior) = REQUIRED];;
75+
}
76+
77+
message GetJobRequest {
78+
// Required. ID of the job to fetch.
79+
string job_id = 1 [(google.api.field_behavior) = REQUIRED];
80+
}
81+
82+
// Describes configuration and status of a job.
83+
message Job {
84+
// Output only. ID of the job.
85+
string job_id = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
86+
87+
// Required. What the job does.
88+
JobConfiguration configuration = 2 [(google.api.field_behavior) = REQUIRED];
89+
90+
// Output only. Current status of the job
91+
JobStatus status = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
92+
93+
// Output only. Past statuses of the job.
94+
repeated JobStatus status_history = 4 [(google.api.field_behavior) = OUTPUT_ONLY];
95+
}
96+
97+
// Required. Set only one type. What the job does.
98+
message JobConfiguration {
99+
// [Pick one] Load source data.
100+
message LoadJob {
101+
// Required. Source to load.
102+
string source_id = 1 [(google.api.field_behavior) = REQUIRED];
103+
}
104+
105+
// [Pick one] Publish data to a destination.
106+
message PublishJob {
107+
// Required. Destination to refresh.
108+
string destination_id = 1 [(google.api.field_behavior) = REQUIRED];
109+
}
110+
111+
// [Pick one] Run a data product flow to update results.
112+
message UpdateJob {
113+
// Required. Data product to update.
114+
string data_product_id = 1 [(google.api.field_behavior) = REQUIRED];
115+
}
116+
117+
oneof job_type {
118+
LoadJob load = 1;
119+
120+
UpdateJob update = 2;
121+
122+
PublishJob publish = 3;
123+
}
124+
}
125+
126+
// Represents the lifecycle of a job.
127+
enum JobState {
128+
// The job state value is unset.
129+
STATE_UNSPECIFIED = 0;
130+
131+
// The job has been received but has not begun to execute.
132+
PENDING = 1;
133+
134+
// The job is actively executing.
135+
RUNNING = 2;
136+
137+
// A signal to stop has been received, but the job is still running.
138+
STOPPING = 3;
139+
140+
// The job is done.
141+
DONE = 4;
142+
}
143+
144+
// Output only. Describes execution status and errors.
145+
message JobStatus {
146+
// Output only. State of job execution.
147+
JobState state = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
148+
149+
// Output only. Time when the job entered this state.
150+
google.protobuf.Timestamp state_start_time = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
151+
152+
// Optional. Output only. If present, indicates that the job is done and was unsuccessful.
153+
Error error = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
154+
}
155+
156+
message ListJobsRequest {
157+
// Optional. The maximum number of jobs to return. Default is 10, and the maximum allowed is 30.
158+
uint32 page_size = 1;
159+
160+
// Optional. The next_page_token value returned from a previous response. Set this value to continue paging.
161+
string page_token = 2;
162+
}
163+
164+
message ListJobsResponse {
165+
// A page of results. Jobs are ordered by start time, most recent first.
166+
repeated Job jobs = 1;
167+
168+
// Token to retrieve the next page of results, or empty if there are no more results in the list.
169+
string next_page_token = 2;
170+
}
171+
172+
message StopJobRequest {
173+
// Required. ID of the job to stop.
174+
string job_id = 1 [(google.api.field_behavior) = REQUIRED];
175+
}
176+
177+
message StopJobResponse {
178+
}

0 commit comments

Comments
 (0)