Kronk

DESCRIPTION:

Kronk is a command line swiss-army-knife for HTTP services.

With Kronk, you easily parse and segregate data, run diffs between the parsed data from different queries, and easily replay logs and loadtest your HTTP applications.

Kronk was made possible by the sponsoring of YP.com.

FEATURES:

  • Parse and display or diff data from http response body and/or headers.

  • Include, exclude or map specific data points with file-glob-like paths.

  • Query and logfile playback with custom output.

  • Supports json, rails-ish xml, and plist.

  • URI-specific configuration.

  • Support for custom data parsers and diff formatters.

  • Launch IRB console with the retrieved response data.

  • Support for proxies, ssl, and basic auth.

  • Cookie/session handling.

  • Easy-to-read output (color or ascii, line numbers, etc).

  • Helper methods for test suites.

  • Yes, it works on Windows.

SYNOPSIS:

Check if your json response returns the same data as your xml variety:

$ kronk host.com/path.json host.com/path.xml

Compare body structure only (uses datatypes instead of values):

$ kronk host.com/path.json host.com/path.xml --struct

Call comparison with similar uri suffixes:

$ kronk host.com/path.json host.com/path.xml --suff '?page=1'

Compare response over ssl with the previous call:

$ kronk https://host.com/path --prev

Compare response with a local file:

$ kronk host.com/path.json ./saved_response.json

Do a simple text diff on the http response, including headers:

$ kronk host.com/A/path.json host.com/B/path.json --raw -i

Run it to display formatted data:

$ kronk host.com/path.json

Run it to display raw data with headers from the default host (localhost:3000). Default host is assumed when the path starts with “/” and no local files match the given path:

$ kronk /path.json --raw -i

Parse the data and run an IRB console with the response:

$ kronk http://host.com/path.json --irb

CONFIGURATION:

Although Kronk supports Ruby-1.8.7, it’s been fine-tuned for Ruby-1.9.2 and runs about 5x faster when benchmarking between 1.8.7p249 and 1.9.2p180.

Kronk pulls it’s config from $HOME/.kronk/rc and supports the following:

Set the file to save the last http response retrieved in:

cache_file: ~/.kronk_cache

Content types to match to a parser. Keys are used as a part of a regexp and values are evaluated by const_get.

content_types:
  xml:   XMLParser
  plist: PlistParser
  json:  JSON

Number of lines of context to use for diff. Full diff is returned when set to false:

context: 5     # show 5 lines before and after diff
context: false # show the full file

How to format the diff output. Supports the special values ‘ascii’ and ‘color’ or any string that will correctly resolve to a constant:

diff_format: ascii

Output parsed data with color-coded values:

color_data: true

Adding User-Agent aliases is useful and simple!

user_agents:
  win_ie9: Mozilla/4.0 (compatible; MSIE 9.0; Windows NT 6.0)

Disabling cookies altogether may be done as so:

use_cookies: false

Setting URI-specific config options - useful if you always need to send headers or use one-off configs. Each URI option key is dropped in a regexp to match against the given URIs so this also works for local files. See Kronk::Request.new, Kronk::Response.new and Kronk::Response#data for all options supported:

uri_options:
  example.com:
    parser:         XMLParser
    allow_encoding: gzip;q=1.0
    force_gzip:     true
    http_method:    POST

    follow_redirects: true

    ignore_data:
      - path/to/data/point

    headers:
      X-Something: custom header value

    query:
      offset: 1
      limit:  10

Require specific files or gems in the ruby runtime:

requires:
  - kronk-my_custom_parser
  - kronk-my_custom_diff_formatter

Show line numbers in the output:

show_lines: true

Assign a default host to use when none is specified:

default_host: http://localhost:3000

Set the number of spaces for indentation:

indentation: 2

Bash Completion:

Bash completion is available by sourcing the file returned by:

$ kronk --completion
[gem path]/script/kronk_completion

DATA MANIPULATION:

One of Kronk’s most powerful features is its ability to segregate data. From the command line, this is done by passing data paths after ‘–’.

All data manipulation is handled by the ruby-path gem.

Selecting and Deleting:

The first kind of data transformation is the ability to select and delete data by path:

$ kronk http://host.com -- data/path1 data/path2/1/child

The previous example will narrow down the parsed data returned to something like:

{
  "data": {
    "path1": "value1",
    "path2": [
      {
        "child": "child value"
      }
    ]
  }
}

If excluding data points is preferred, prepending a ‘-’ to the path will flag it to remove data:

$ kronk http://host.com -- -data/path2

{
  "data": {
    "path1": "value1",
    "path3": "value3",
    "path4": "value4"
  }
}

If you would like to exclude or include only items with a specific child attribute, you can do so by appending “/..” to the path.

$ kronk http://host.com -- data/path2/1/child/..

{
  "data": {
    "path2": [
      {
        "first_child": "first value",
        "child": "child value",
        "last_child": "last value"
      },
    ]
  }
}

Path matcher parsing may also be affected by appending Regexp options to the end of the path in the following fashion:

# Make path case insensitive
$ kronk host.com -- data/path2/1//i

{
  "data": {
    "PATH2": [
      "item at index 1"
    ],

    "path2": [
      {
        "first_child": "first value",
        "child": "child value",
        "last_child": "last value"
      }
    ]
  }
}

# Make path case insensitive and multiline
$ kronk host.com -- data/**=*foobar*//im

{
  "data": {
    "subdata": "test for\nFOOBAR\nmultiline"
  }
}

Mapping and Moving:

In Kronk, mapping equates to selecting and renaming a given path in an empty data structure. Moving refers to deleting the path value and placing it back in the original data structure at the new path.

# Mapping is done with the > operator:
$ kronk host.com -- data/path3 "data/path(1|2)>moved%1"

{
  "data": {
    "path3": "value3"
  }
  "moved1": "value1",
  "moved2": "value2"
}

# Moving is done with the >> operator:
$ kronk host.com -- "data/path(1|2)>moved%1"

{
  "data": {
    "path3": "value3",
    "path4": "value4"
  }
  "moved1": "value1",
  "moved2": "value2"
}

Special Characters:

There are additionally a variety of wildcard and special characters that are supported:

  • * matches /.*/, meaning zero or more characters

  • **/ matches any key recursively down the data structure

  • ../ matches the parent of the previously matched item

  • 2..5, 2…6 and 2,3 match any Integer or String from 2 to 5

  • ? matches zero or one character

  • | effectively works as an “OR” character, matches /^val1|val2$/

  • = is used to match values and may be used in conjuction with a key or not

  • Parentheses may be used in conjunction with other special characters for a given path item, such as: /path(1|2)

  • \ escapes any special path character

  • > is used to exclusively map one path to another

  • >> moves a path to another within the original data structure

  • %NUM is used in the target path to reference a given match

  • %% is used to reference splats from the original path and assign it in the target path

Check out Kronk::Path and Kronk::Path::Transaction for more details on data manipulation.

Note: Bash may try to parse your data paths, especially if they start with wildcards or if they contain the pipe “|” character, so you may need to put single quotes around some of your paths.

REQUIREMENTS:

  • json gem

  • cookiejar gem

  • ruby-path gem

INSTALL:

$ gem install kronk

DEVELOPERS:

After checking out the source, run:

$ rake newb

This task will install any missing dependencies, run the tests/specs, and generate the RDoc.

LICENSE:

(The MIT License)

Copyright © 2010, 2011 Jeremie Castagna

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the ‘Software’), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED ‘AS IS’, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.