2024-06-20T12:36:27Z

SRE tools

2024-05-28T17:09:30Z

Thexa4:

* [https://www.asterisk.org/community/documentation/ Asterisk]
* [https://www.gnu.org/software/bash/manual/bash.html Bash]
* [https://docs.ceph.com/en/latest/ Ceph]
* [https://www.debian.org/doc/manuals/debian-handbook/ Debian]
* [https://www.debian.org/doc/manuals/maint-guide/ Debian packaging]
* [https://www.freeipa.org/page/Documentation FreeIPA]
* [https://howhttps.works/ HTTPS/TLS]
* [https://web.mit.edu/kerberos/www/krb5-latest/doc/ Kerberos]
* [https://www.keycloak.org/documentation Keycloak]
* [https://manpages.debian.org/unstable/ldap-utils/ldapsearch.1.en.html LDAP]
* [https://www.gnu.org/software/make/manual/make.html Make]
* [https://netboxlabs.com/docs/netbox/en/stable/ Netbox]
* [https://nginx.org/en/docs/ Nginx]
* [https://pve.proxmox.com/pve-docs/ Proxmox]
* [https://pbs.proxmox.com/docs/ Proxmox Backup Server]
* [https://www.zabbix.com/manuals Zabbix]
* [https://zulip.com/help/ Zulip]

== References you want to know exist ==

* [https://refspecs.linuxfoundation.org/FHS_3.0/fhs/index.html Filesystem Hierarchy Standard]

SRE tools

2024-05-28T17:09:23Z

Thexa4:

Thexa4: Thexa4 moved page Media-Types Validatoin (Ruby) to Media-Types Validation (Ruby)

#REDIRECT [[Media-Types Validation (Ruby)]]

Media-Types Validation (Ruby)

2021-01-19T14:05:19Z

Thexa4: Thexa4 moved page Media-Types Validatoin (Ruby) to Media-Types Validation (Ruby)

The repository for the <code>media_types</code> [https://rubygems.org/gems/media_types gem] currently lives at GitHub: <code>[https://github.com/SleeplessByte/media-types-ruby sleeplessbyte/media-types-ruby]</code>.

= MediaTypes =

Media Types based on scheme, with versioning, views, suffixes and validations.

This library makes it easy to define schemas that can be used to validate JSON objects based on their Content-Type.

== Installation ==

Add this line to your application’s Gemfile:

<syntaxhighlight lang="ruby">gem 'media_types'</syntaxhighlight>
And then execute:

<pre>$ bundle</pre>
Or install it yourself as:

<pre>$ gem install media_types</pre>
== Usage ==

Define a validation:

<syntaxhighlight lang="ruby">require 'media_types'

module Acme
MediaTypes::set_organisation Acme, 'acme'

class FooValidator
include MediaTypes::Dsl

use_name 'foo'

validations do
attribute :foo, String
end
end
end</syntaxhighlight>

Validate an object:

<syntaxhighlight lang="ruby">Acme::FooValidator.validate!({ foo: 'bar' })</syntaxhighlight>

== Full example ==

<syntaxhighlight lang="ruby">require 'media_types'

class Venue
include MediaTypes::Dsl

def self.organisation
'mydomain'
end

use_name 'venue'

validations do
version 2 do
attribute :name, String
collection :location do
attribute :latitude, Numeric
attribute :longitude, Numeric
attribute :altitude, AllowNil(Numeric)
end

link :self
link :route, allow_nil: true
end

version 1 do
attribute :name, String
attribute :coords, String
attribute :updated_at, String

link :self
end

view 'create' do
collection :location do
attribute :latitude, Numeric
attribute :longitude, Numeric
attribute :altitude, AllowNil(Numeric)
end

version 1 do
collection :location do
attribute :latitude, Numeric
attribute :longitude, Numeric
attribute :altitude, AllowNil(Numeric)
end
end
end
end
end</syntaxhighlight>

== Schema Definitions ==

If you include ‘MediaTypes::Dsl’ in your class you can use the following functions within a <code>validation do</code> block to define your schema:

=== <code>attribute</code> ===

Adds an attribute to the schema, if a +block+ is given, uses that to test against instead of +type+

{| class="wikitable"
!width="26%"| param
!width="23%"| type
!width="50%"| description
|-
| key
| <code>Symbol</code>
| the attribute name
|-
| opts
| <code>Hash</code>
| options to pass to <code>Scheme</code> or <code>Attribute</code>
|-
| type
| <code>Class</code>, <code>===</code>, Scheme
| The type of the value, can be anything that responds to <code>===</code>, or scheme to use if no <code>&block</code> is given. Defaults to <code>Object</code> without a <code>&block</code> and to Hash with a <code>&block</code>.
|-
| optional:
| <code>TrueClass</code>, <code>FalseClass</code>
| if true, key may be absent, defaults to <code>false</code>
|-
| &block
| <code>Block</code>
| defines the scheme of the value of this attribute
|}

==== Add an attribute named foo, expecting a string ====

<syntaxhighlight lang="ruby">require 'media_types'

class MyMedia
include MediaTypes::Dsl

validations do
attribute :foo, String
end
end

MyMedia.valid?({ foo: 'my-string' })
# => true</syntaxhighlight>

==== Add an attribute named foo, expecting nested scheme ====

<syntaxhighlight lang="ruby">class MyMedia
include MediaTypes::Dsl

validations do
attribute :foo do
attribute :bar, String
end
end
end

MyMedia.valid?({ foo: { bar: 'my-string' }})
# => true</syntaxhighlight>

=== <code>any</code> ===

Allow for any key. The <code>&block</code> defines the Schema for each value.

{| class="wikitable"
!width="26%"| param
!width="23%"| type
!width="50%"| description
|-
| scheme
| <code>Scheme</code>, <code>NilClass</code>
| scheme to use if no <code>&block</code> is given
|-
| allow_empty:
| <code>TrueClass</code>, <code>FalsClass</code>
| if true, empty (no key/value present) is allowed
|-
| expected_type:
| <code>Class</code>,
| forces the validated value to have this type, defaults to <code>Hash</code>. Use <code>Object</code> if either <code>Hash</code> or <code>Array</code> is fine
|-
| &block
| <code>Block</code>
| defines the scheme of the value of this attribute
|}

==== Add a collection named foo, expecting any key with a defined value ====

<syntaxhighlight lang="ruby">class MyMedia
include MediaTypes::Dsl

validations do
collection :foo do
any do
attribute :bar, String
end
end
end
end

MyMedia.valid?({ foo: [{ anything: { bar: 'my-string' }, other_thing: { bar: 'other-string' } }] })
# => true</syntaxhighlight>

=== <code>not_strict</code> ===

Allow for extra keys in the schema/collection even when passing <code>strict: true</code> to <code>#validate!</code>

==== Allow for extra keys in collection ====

<syntaxhighlight lang="ruby">class MyMedia
include MediaTypes::Dsl

validations do
collection :foo do
attribute :required, String
not_strict
end
end
end

MyMedia.valid?({ foo: [{ required: 'test', bar: 42 }] })
# => true</syntaxhighlight>

=== <code>collection</code> ===

Expect a collection such as an array or hash. The <code>&block</code> defines the Schema for each item in that collection.

{| class="wikitable"
!width="26%"| param
!width="23%"| type
!width="50%"| description
|-
| key
| <code>Symbol</code>
| key of the collection (same as <code>#attribute</code>)
|-
| scheme
| <code>Scheme</code>, <code>NilClass</code>, <code>Class</code>
| scheme to use if no <code>&block</code> is given or <code>Class</code> of each item in the
|-
| allow_empty:
| <code>TrueClass</code>, <code>FalseClass</code>
| if true, empty (no key/value present) is allowed
|-
| expected_type:
| <code>Class</code>,
| forces the validated value to have this type, defaults to <code>Array</code>. Use <code>Object</code> if either <code>Array</code> or <code>Hash</code> is fine.
|-
| optional:
| <code>TrueClass</code>, <code>FalseClass</code>
| if true, key may be absent, defaults to <code>false</code>
|-
| &block
| <code>Block</code>
| defines the scheme of the value of this attribute
|}

==== Collection with an array of string ====

<syntaxhighlight lang="ruby">class MyMedia
include MediaTypes::Dsl

validations do
collection :foo, String
end
end

MyMedia.valid?({ collection: ['foo', 'bar'] })
# => true</syntaxhighlight>

==== Collection with defined scheme ====

<syntaxhighlight lang="ruby">class MyMedia
include MediaTypes::Dsl

validations do
collection :foo do
attribute :required, String
attribute :number, Numeric
end
end
end

MyMedia.valid?({ foo: [{ required: 'test', number: 42 }, { required: 'other', number: 0 }] })
# => true</syntaxhighlight>

=== <code>link</code> ===

Expect a link with a required <code>href: String</code> attribute

{| class="wikitable"
!width="26%"| param
!width="23%"| type
!width="50%"| description
|-
| key
| <code>Symbol</code>
| key of the link (same as <code>#attribute</code>)
|-
| allow_nil:
| <code>TrueClass</code>, <code>FalseClass</code>
| if true, value may be nil
|-
| optional:
| <code>TrueClass</code>, <code>FalseClass</code>
| if true, key may be absent, defaults to <code>false</code>
|-
| &block
| <code>Block</code>
| defines the scheme of the value of this attribute, in addition to the <code>href</code> attribute
|}

==== Links as defined in HAL, JSON-Links and other specs ====

<syntaxhighlight lang="ruby">class MyMedia
include MediaTypes::Dsl

validations do
link :_self
link :image
end
end

MyMedia.valid?({ _links: { self: { href: 'https://example.org/s' }, image: { href: 'https://image.org/i' }} })
# => true</syntaxhighlight>

==== Link with extra attributes ====

<syntaxhighlight lang="ruby">class MyMedia
include MediaTypes::Dsl

validations do
link :image do
attribute :templated, TrueClass
end
end
end

MyMedia.valid?({ _links: { image: { href: 'https://image.org/{md5}', templated: true }} })
# => true</syntaxhighlight>

== Validation ==

If your type has a validations, you can now use this media type for validation:

<syntaxhighlight lang="ruby">Venue.valid?({
#...
})
# => true if valid, false otherwise

Venue.validate!({
# /*...*/
})
# => raises if it's not valid</syntaxhighlight>

If an array is passed, check the scheme for each value, unless the scheme is defined as expecting a hash:

<syntaxhighlight lang="ruby">expected_hash = Scheme.new(expected_type: Hash) { attribute(:foo) } expected_object = Scheme.new { attribute(:foo) }

expected_hash.valid?({ foo: ‘string’ }) # => true

expected_hash.valid?([{ foo: ‘string’ }]) # => false

expected_object.valid?({ foo: ‘string’ }) # => true

expected_object.valid?([{ foo: ‘string’ }]</syntaxhighlight>

== API ==

A defined schema has the following functions available:

=== <code>valid?</code> ===

Example: <code>Venue.valid?({ foo: 'bar' })</code>

Allows passing in validation options as a second parameter.

=== <code>validate!</code> ===

Example: <code>Venue.validate!({ foo: 'bar' })</code>

Allows passing in validation options as a second parameter.

=== <code>validatable?</code> ===

Example: <code>Venue.version(42).validatable?</code>

Tests wether the current configuration of the schema has a validation defined.

=== <code>register</code> ===

Example: <code>Venue.register</code>

Registers the media type to the registry.

=== <code>view</code> ===

Example: <code>Venue.view('create')</code>

Returns a schema validator configured with the specified view.

=== <code>version</code> ===

Example: <code>Venue.version(42)</code>

Returns a schema validator configured with the specified version.

=== <code>suffix</code> ===

Example: <code>Venue.suffix(:json)</code>

Returns a schema validator configured with the specified suffix.

=== <code>identifier</code> ===

Example: <code>Venue.version(2).identifier</code> (returns <code>'application/vnd.application.venue.v2'</code>)

Returns the IANA compatible [https://en.wikipedia.org/wiki/Media_type Media Type Identifier] for the configured schema.

=== <code>available_validations</code> ===

Example: <code>Venue.available_validations</code>

Returns a list of all the schemas that are defined.

== Related ==

* [https://github.com/XPBytes/media_types-serialization <code>MediaTypes::Serialization</code>]: :cyclone: Add media types supported serialization to Rails.

== Development ==

After checking out the repo, run <code>bin/setup</code> to install dependencies. Then, run <code>rake test</code> to run the tests. You can also run <code>bin/console</code> for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run <code>bundle exec rake install</code>. To release a new version, update the version number in <code>version.rb</code>, call <code>bundle exec rake release</code> to create a new git tag, push git commits and tags, and push the <code>.gem</code> file to rubygems.org.

== Contributing ==

Bug reports and pull requests are welcome on GitHub at [https://github.com/SleeplessByte/media-types-ruby SleeplessByte/media-types-ruby]