openapi: 3.1.0
info:
  title: Vineyard Python Client API
  description: >-
    The Vineyard Python client API provides programmatic access to the Vineyard
    in-memory immutable data manager (v6d), a CNCF project. Clients connect via
    IPC (UNIX domain socket) for zero-copy local access or via RPC (TCP) for
    remote access. The API supports storing, retrieving, naming, persisting, and
    deleting distributed in-memory objects.
  version: 0.19.0
  contact:
    name: Vineyard Community
    url: https://v6d.io/
  license:
    name: Apache 2.0
    url: https://github.com/v6d-io/v6d/blob/main/LICENSE
externalDocs:
  description: Vineyard Python API Reference
  url: https://v6d.io/notes/references/python-api.html
servers:
  - url: ipc://{socket}
    description: IPC socket connection (local zero-copy access)
    variables:
      socket:
        default: /var/run/vineyard.sock
  - url: tcp://{host}:{port}
    description: RPC TCP connection (remote access)
    variables:
      host:
        default: localhost
      port:
        default: '9600'
tags:
  - name: Connection
    description: Connect to and disconnect from a vineyard server
  - name: Objects
    description: Store and retrieve in-memory objects
  - name: Metadata
    description: Inspect and manage object metadata
  - name: Names
    description: Associate human-readable names with object IDs
  - name: Blobs
    description: Low-level blob storage operations
  - name: Persistence
    description: Persist objects for cross-instance visibility
paths:
  /connect:
    post:
      operationId: connectToServer
      summary: Connect to Server
      description: >-
        Establish a connection to a vineyard server via IPC socket or TCP endpoint.
        Returns a client object (IPCClient or RPCClient) for subsequent operations.
      tags:
        - Connection
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                socket:
                  type: string
                  description: UNIX domain socket path for IPC connection
                  example: /var/run/vineyard.sock
                host:
                  type: string
                  description: Hostname for RPC TCP connection
                port:
                  type: integer
                  description: Port number for RPC TCP connection
                  example: 9600
      responses:
        '200':
          description: Successfully connected to vineyard server
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientInfo'
        '503':
          description: Server unavailable or connection failed
  /objects:
    post:
      operationId: putObject
      summary: Put Object
      description: >-
        Store a Python object in vineyard. Returns the ObjectID for later retrieval.
        Optionally persist the object for cross-instance visibility or associate a name.
      tags:
        - Objects
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PutObjectRequest'
      responses:
        '201':
          description: Object stored successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectIDResponse'
        '400':
          description: Invalid object or unsupported type
  /objects/{objectId}:
    get:
      operationId: getObject
      summary: Get Object
      description: >-
        Retrieve a vineyard object by its ObjectID, deserializing it back to a Python value.
      tags:
        - Objects
      parameters:
        - name: objectId
          in: path
          required: true
          description: The 64-bit unsigned integer ObjectID
          schema:
            type: string
        - name: fetch
          in: query
          required: false
          description: Whether to fetch remote objects via RPC if not local
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Object retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectResponse'
        '404':
          description: Object not found
    delete:
      operationId: deleteObject
      summary: Delete Object
      description: Remove a vineyard object from memory by its ObjectID.
      tags:
        - Objects
      parameters:
        - name: objectId
          in: path
          required: true
          description: The ObjectID to delete
          schema:
            type: string
        - name: force
          in: query
          required: false
          description: Force deletion even if the object is referenced
          schema:
            type: boolean
            default: true
        - name: deep
          in: query
          required: false
          description: Recursively delete member objects
          schema:
            type: boolean
            default: true
      responses:
        '204':
          description: Object deleted successfully
        '404':
          description: Object not found
  /objects/{objectId}/metadata:
    get:
      operationId: getObjectMetadata
      summary: Get Object Metadata
      description: >-
        Fetch the metadata of a vineyard object, including typename, nbytes,
        isglobal, islocal, and all custom key-value metadata properties.
      tags:
        - Metadata
      parameters:
        - name: objectId
          in: path
          required: true
          description: The ObjectID to inspect
          schema:
            type: string
      responses:
        '200':
          description: Metadata retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectMetadata'
        '404':
          description: Object not found
  /objects/{objectId}/persist:
    post:
      operationId: persistObject
      summary: Persist Object
      description: >-
        Make a vineyard object persistent, making it visible across all vineyard
        server instances in the cluster.
      tags:
        - Persistence
      parameters:
        - name: objectId
          in: path
          required: true
          description: The ObjectID to persist
          schema:
            type: string
      responses:
        '200':
          description: Object persisted successfully
        '404':
          description: Object not found
  /names:
    post:
      operationId: putName
      summary: Associate Name with Object
      description: Associate a human-readable name string with a vineyard ObjectID.
      tags:
        - Names
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - object_id
                - name
              properties:
                object_id:
                  type: string
                  description: The ObjectID to associate with the name
                name:
                  type: string
                  description: Human-readable name string
      responses:
        '200':
          description: Name associated successfully
        '409':
          description: Name already in use
  /names/{name}:
    get:
      operationId: getByName
      summary: Get Object by Name
      description: Retrieve the ObjectID associated with a human-readable name.
      tags:
        - Names
      parameters:
        - name: name
          in: path
          required: true
          description: The human-readable name
          schema:
            type: string
        - name: wait
          in: query
          required: false
          description: Block until the name becomes available
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: ObjectID retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectIDResponse'
        '404':
          description: Name not found
  /blobs:
    post:
      operationId: createBlob
      summary: Create Blob
      description: Allocate a raw memory blob of the specified size in vineyard.
      tags:
        - Blobs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - size
              properties:
                size:
                  type: integer
                  description: Number of bytes to allocate
      responses:
        '201':
          description: Blob created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlobInfo'
  /blobs/{objectId}:
    get:
      operationId: getBlob
      summary: Get Blob
      description: Retrieve a raw memory blob by its ObjectID.
      tags:
        - Blobs
      parameters:
        - name: objectId
          in: path
          required: true
          schema:
            type: string
        - name: remote
          in: query
          required: false
          description: Retrieve blob from a remote vineyard instance
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Blob retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlobInfo'
        '404':
          description: Blob not found
components:
  schemas:
    ClientInfo:
      type: object
      description: Information about the established vineyard client connection
      properties:
        instance_id:
          type: integer
          description: The vineyard instance ID this client is connected to
        version:
          type: string
          description: Vineyard server version
        ipc_socket:
          type: string
          description: IPC socket path (for IPCClient)
        rpc_endpoint:
          type: string
          description: RPC endpoint (for RPCClient)
    PutObjectRequest:
      type: object
      description: Request to store an object in vineyard
      properties:
        value:
          description: The Python object to store (serialized representation)
        persist:
          type: boolean
          description: Whether to immediately persist the object globally
          default: false
        name:
          type: string
          description: Optional human-readable name to associate
    ObjectIDResponse:
      type: object
      description: Response containing a vineyard ObjectID
      properties:
        object_id:
          type: string
          description: The 64-bit unsigned integer ObjectID as a string
    ObjectResponse:
      type: object
      description: Response containing a retrieved vineyard object
      properties:
        object_id:
          type: string
          description: The ObjectID of the retrieved object
        value:
          description: The deserialized Python object value
        typename:
          type: string
          description: The vineyard type name of the object
    ObjectMetadata:
      type: object
      description: Metadata for a vineyard object
      properties:
        id:
          type: string
          description: The ObjectID
        typename:
          type: string
          description: >-
            Type name of the object (e.g., vineyard::Tensor<float64>,
            vineyard::DataFrame, vineyard::RecordBatch)
        nbytes:
          type: integer
          description: Memory size in bytes
        isglobal:
          type: boolean
          description: Whether the object is globally persistent across instances
        islocal:
          type: boolean
          description: Whether the object is local to this vineyard instance
        instance_id:
          type: integer
          description: The vineyard instance ID where the object resides
        hostname:
          type: string
          description: Hostname of the vineyard instance
        extra:
          type: object
          description: Additional custom key-value metadata properties
          additionalProperties:
            type: string
    BlobInfo:
      type: object
      description: Information about a raw vineyard blob
      properties:
        object_id:
          type: string
          description: The ObjectID of the blob
        size:
          type: integer
          description: Size of the blob in bytes
        buffer:
          type: string
          description: Base64-encoded blob data (for remote blobs)