Add skeleton of the client APIs

src/client.zig

@@ -1,17 +1,18 @@
 // Copyright (c) 2024 g41797
 // SPDX-License-Identifier: MIT
 
-//! [Beanstalk](https://beanstalkd.github.io/) _is a simple, fast work queue._ 
+//! [Beanstalk](https://beanstalkd.github.io/) _is a simple, fast work queue._
 //! - [repository](https://github.com/beanstalkd/beanstalkd)
 //! - [protocol](https://github.com/beanstalkd/beanstalkd/blob/master/doc/protocol.txt)
-//! 
+//!
 //! Zig beanstalk client supports **subset** of commands:
 //! - _use_: set current tube(queue)
-//! - _put_: submit job 
-//! - _reserve-with-timeout_: consume job
-//! - _delete_: remove job from the system
+//! - _put_: submit job
+//! - _state_: jet job state
 //! - _watch_: subscribe to jobs submitted to the tube
+//! - _reserve-with-timeout_: consume job
 //! - _ignore_: un-subscribe
+//! - _delete_: remove job from the system
 
 const std = @import("std");
 const Mutex = std.Thread.Mutex;
@@ -25,12 +26,19 @@ pub const DefaultAddr = "127.0.0.1";
 pub const DafaultPort = 11300;
 pub const DafaultTube = "default";
 
+pub const JobState = enum {
+    DELAYED,
+    READY,
+    RESERVED,
+    BURIED,
+};
+
 pub const Client = struct {
     ready: bool = false,
     mutex: Mutex = .{},
-    allocator: Allocator,
+    allocator: ?Allocator = null,
 
-    /// Connects to beanstalkd
+    /// Returns connected to beanstalkd client.
     /// Arguments:
     ///     allocator:
     ///     addr: IPv4 address or host name, for null - DefaultAddr is used
@@ -39,8 +47,10 @@ pub const Client = struct {
     /// Returns errors for:
     ///     - failed connection
     ///     - already existing connection
-    pub fn connect(cl: *Client, allocator: Allocator, _: ?[]const u8, _: ?u16) !void {
-        cl.allocator = allocator;
+    pub fn connect(allocator: ?Allocator, addr: ?[]const u8, port: ?u16) !*Client {
+        _ = allocator;
+        _ = addr;
+        _ = port;
     }
 
     pub fn disconnect(cl: *Client) void {
@@ -69,7 +79,7 @@ pub const Client = struct {
         return false;
     }
 
-    /// Inserts a job into the client's currently used tube.
+    /// Inserts a job into the client's currently used tube(queue).
     /// Arguments:
     ///     pri: is an integer < 2**32. Jobs with smaller priority values will be
     ///     scheduled before jobs with larger priorities. The most urgent priority is 0;
@@ -101,4 +111,56 @@ pub const Client = struct {
         _ = ttr;
         _ = job;
     }
+
+    /// Returns state of the job.
+    ///
+    /// Arguments:
+    ///     id: job id
+    /// If job does not exists - returns NotFound.
+    pub fn state(cl: *Client, id: u32) ReturnedError!JobState {
+        _ = cl;
+        _ = id;
+    }
+
+    /// Adds tube to the watch list for the current connection.
+    /// A reserve-with-timeout command will take a job from any of the tubes in the watch list.
+    /// For each new connection, the watch list initially consists of one tube, named "default".
+    ///
+    /// Arguments:
+    ///     tname: tube name
+    ///
+    pub fn watch(cl: *Client, tname: []const u8) ReturnedError!void {
+        _ = cl;
+        _ = tname;
+    }
+
+    /// Returns job for processing from the watched tubes.
+    /// Client will block no more then 'timeout' seconds if job for processing does not exist.
+    pub fn reserve(cl: *Client, timeout: u32) ReturnedError!struct { id: u32, job: []const u8 } {
+        _ = cl;
+        _ = timeout;
+    }
+
+    /// Removes a job from the server entirely.
+    /// A client can delete jobs that it has reserved,
+    /// ready jobs, delayed jobs, and jobs that are buried.
+    ///
+    /// Arguments:
+    ///     id: job id
+    ///
+    pub fn delete(cl: *Client, id: u32) ReturnedError!void {
+        _ = cl;
+        _ = id;
+    }
+
+    /// Removes the tube from the watch list for the current connection.
+    ///
+    /// Arguments:
+    ///     tname: tube name
+    ///
+    /// Returns NotIgnored if watch list contains only one tube.
+    pub fn ignore(cl: *Client, tname: []const u8) ReturnedError!void {
+        _ = cl;
+        _ = tname;
+    }
 };