NAME

Etcd::Keys - etcd key space API

VERSION

version 0.004

SYNOPSIS

    use Etcd;
    my $etcd = Etcd->new;
    
    # set value for key
    $etcd->set("/message", "hello world");
    
    # get key
    my $response = $etcd->get("/message");
    
    # delete key
    $etcd->delete("/message");
    
    # atomic compare-and-swap value for key
    $etcd->compare_and_swap("/message", "new", "old");
    
    # atomic compare-and-delete key
    $etcd->compare_and_delete("/message", "old");
    
    # create key. like set, but fails if the key exists
    $etcd->create("/message", "value");
    
    # update key. like set, but fails if the key doesn't exist
    $etcd->update("/message", "value");
    
    # check if key exists
    my $exists = $etcd->exists("/message");
    
    # create dir, a "valueless" key to hold subkeys
    $etcd->create_dir("/dir");
    
    # delete key and everything under it
    $etcd->delete_dir("/dir");
    
    # atomically create in-order key
    $etcd->create_in_order("/dir", "value");
    
    # block until key changes
    $etcd->watch("/message");

DESCRIPTION

This module provides access to etcd's key space API. The methods here map almost exactly to operations described in the etcd API documentation. See "SEE ALSO" in Etcd for further reading.

All methods except exists returns a Etcd::Response object on success and die on error. On error, $@ will contain either a reference to a Etcd::Error object (for API-level errors) or a regular string (for network, transport or other errors).

All methods can take any number of additional arguments in key => value form. These are added to the query parameters in the URL that gets submitted to etcd. This is how you would pass options for ttl or recursive, for example.

Any arguments of this kind that clash with the internal operation of a method will silently be ignored; for example, passing a value key to set will be ignored because that's how the value is passed internally.

METHODS

• set

      $etcd->set("/message", "hello world");

  Set a value for a key. The key will be created if it doesn't exist.

  This invokes the PUT method for the given key.

• get

      my $node = $etcd->get("/message");

  Get a key.

  This invokes the GET method for the given key.

• delete

      $etcd->delete("/message");

  Delete a key.

  This invokes the DELETE method for the given key.

• compare_and_swap

      $etcd->compare_and_swap("/message", "new", "old");

  Atomic compare-and-swap the value of a key.

  This invokes the PUT method for the given key with the prevValue query parameter.

• compare_and_delete

      $etcd->compare_and_delete("/message", "old");

  Atomic compare-and-delete the value of a key.

  This invokes the DELETE method for the given key with the prevValue query parameter.

• create

      $etcd->create("/message", "value");

  Create a key. Like set, but fails if the key exists.

  This invokes the PUT method for the given key with the prevExist query parameter set to false.

• update

      $etcd->update("/message", "value");

  Update the value of a key. Like set, but fails if the key doesn't exist.

  This invokes the PUT method for the given key with the prevExist query parameter set to true.

• exists

      my $exists = $etcd->exists("/message");

  Check if key exists. Unlike the other methods, it does not return a reference to a Etcd::Response object but insteads returns a true or false value. It may still throw an error.

  This invokes the GET method for the given key.

• create_dir

      $etcd->create_dir("/dir");

  Creates a directory, a "valueless" key to hold sub-keys.

  This invokes the PUT method for the given key with the dir query parameter set to true.

• delete_dir

      $etcd->delete_dir("/dir");

  Deletes a key and all its sub-keys.

  This invokes the DELETE method for the given key with the dir query parameter set to true.

• create_dir

      $etcd->create_in_order("/dir", "value");

  Atomically creates an in-order key.

  This invokes the POST method for the given key.

• watch

      $etcd->watch("/message");

  Block until the given key changes, then return the change.

  This invokes the GET method for the given key with the wait query parameter set to true.

KNOWN ISSUES

• There is no convenient way to specify the prevIndex test to compare_and_swap or compare_and_delete. These can be implemented directly with set.

• watch has no asynchronous mode.

See "SUPPORT" in Etcd for information on how to report bugs or feature requests.

AUTHORS

• Robert Norris <rob@eatenbyagrue.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2014 by Robert Norris.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.