Skip to content

release 1.0.0 #19

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 12, 2024
Merged

release 1.0.0 #19

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .luacov
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
modules = {
["uuid.*"] = "src"
include = {
"src%/.+$",
}

runreport = true
7 changes: 4 additions & 3 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ The scope of what is covered by the version number excludes:

## Version history

### Version 1.0.0, unreleased
### Version 1.0.0, released 13-Oct-2024

- BREAKING: no default rng will be picked anymore, one must be set explicitly, see `set_rng`
- BREAKING: calling on the module table `uuid()` will now call `v4()` instead of `new()`
Expand All @@ -44,10 +44,11 @@ The scope of what is covered by the version number excludes:
additional input for seeding the Lua rng (eg. pass in a mac address).
- Feat: new `rng.luasystem` rng that uses LuaSystem for random number generation (Posix + Windows)
- Feat: new `rng.urandom` rng that uses /dev/urandom for random number generation (Posix, no Windows)
- Feat: new `rng.win_ffi` rng that uses the ffi for random number generation (Windows, no Posix)
- Feat: new `rng.math_random` rng that replaces the old rng used, based on Lua's `math.random` function.
- Feat: improved seeding, using LuaSystem, or /dev/urandom if available. If not, the fallback now uses
- Feat: improved seeding, using LuaSystem, win-ffi, or /dev/urandom if available. If not, the fallback now uses
more inputs (including a user provided one, eg. a mac address) and calculates a SHA1 used as seed.
Also support for the Lua 5.4
Also support for the Lua 5.4 `randomseed()` implementation

### Version 0.3, released 11-Jul-2021

Expand Down
2 changes: 1 addition & 1 deletion LICENSE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -188,7 +188,7 @@
same "printed page" as the copyright notice for easier
identification within third-party archives.

Copyright 2012 Rackspace, 2013-2021 Thijs Schreijer
Copyright 2012 Rackspace, 2013-2024 Thijs Schreijer

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
Expand Down
207 changes: 28 additions & 179 deletions docs/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,211 +27,60 @@
<h1>uuid</h1>


<h2>Contents</h2>
<ul>
<li><a href="#Functions">Functions</a></li>
</ul>



<h2>Modules</h2>
<ul class="nowrap">
<li><strong>uuid</strong></li>
<li><a href="modules/uuid.html">uuid</a></li>
<li><a href="modules/uuid.rng.html">uuid.rng</a></li>
</ul>
<h2>Topics</h2>
<ul class="">
<li><a href="topics/readme.md.html">readme</a></li>
<li><a href="topics/01-introduction.md.html">1. Introduction</a></li>
<li><a href="topics/CHANGELOG.md.html">CHANGELOG</a></li>
<li><a href="topics/LICENSE.md.html">Apache 2.0 License</a></li>
</ul>

</div>

<div id="content">

<h1>Module <code>uuid</code></h1>
<p>Copyright 2012 Rackspace (original), 2013-2021 Thijs Schreijer (modifications)</p>

<p> Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.</p>
<p> You may obtain a copy of the License at</p>


<pre>
http://www.apache.org/licenses/LICENSE-<span class="number">2.0</span>
</pre>

<p> Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS-IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.</p>

<p> see http://www.ietf.org/rfc/rfc4122.txt</p>

<p> Note that this is not a true version 4 (random) UUID. Since <code>os.time()</code> precision is only 1 second, it would be hard
to guarantee spacial uniqueness when two hosts generate a uuid after being seeded during the same second. This
is solved by using the node field from a version 1 UUID. It represents the mac address.</p>
<h2>Module to generate uuids in pure Lua</h2>

<p> 28-apr-2013 modified by Thijs Schreijer from the original <a href="https://github.com/kans/zirgo/blob/807250b1af6725bad4776c931c89a784c1e34db2/util/uuid.lua">Rackspace code</a> as a generic Lua module.
Regarding the above mention on <code>os.time()</code>; the modifications use the <code>socket.gettime()</code> function from LuaSocket
if available and hence reduce that problem (provided LuaSocket has been loaded before uuid).</p>

<p> <strong>Important:</strong> the random seed is a global piece of data. Hence setting it is
an application level responsibility, libraries should never set it!</p>

<p> See this issue; <a href="https://github.com/Kong/kong/issues/478">https://github.com/Kong/kong/issues/478</a>
It demonstrates the problem of using time as a random seed. Specifically when used from multiple processes.
So make sure to seed only once, application wide. And to not have multiple processes do that
simultaneously.</p>


<h2><a href="#Functions">Functions</a></h2>
<table class="function_list">
<h2>Modules</h2>
<table class="module_list">
<tr>
<td class="name" nowrap><a href="#new">new (hwaddr)</a></td>
<td class="summary">Creates a new uuid.</td>
<td class="name" nowrap><a href="modules/uuid.html">uuid</a></td>
<td class="summary">Copyright 2012 Rackspace (original), 2013-2024 Thijs Schreijer (modifications)</td>
</tr>
<tr>
<td class="name" nowrap><a href="#randomseed">randomseed (seed)</a></td>
<td class="summary">Improved randomseed function.</td>
<td class="name" nowrap><a href="modules/uuid.rng.html">uuid.rng</a></td>
<td class="summary">Random number generator utilities with different properties and uses.</td>
</tr>
</table>
<h2>Topics</h2>
<table class="module_list">
<tr>
<td class="name" nowrap><a href="#seed">seed ()</a></td>
<td class="summary">Seeds the random generator.</td>
<td class="name" nowrap><a href="topics/01-introduction.md.html">01-introduction.md</a></td>
<td class="summary"></td>
</tr>
<tr>
<td class="name" nowrap><a href="topics/CHANGELOG.md.html">CHANGELOG.md</a></td>
<td class="summary"></td>
</tr>
<tr>
<td class="name" nowrap><a href="topics/LICENSE.md.html">LICENSE.md</a></td>
<td class="summary"></td>
</tr>
</table>

<br/>
<br/>


<h2 class="section-header "><a name="Functions"></a>Functions</h2>

<dl class="function">
<dt>
<a name = "new"></a>
<strong>new (hwaddr)</strong>
</dt>
<dd>

<p>Creates a new uuid. Either provide a unique hex string, or make sure the
random seed is properly set. The module table itself is a shortcut to this
function, so <code>my_uuid = uuid.new()</code> equals <code>my_uuid = uuid()</code>.</p>

<p> For proper use there are 3 options;</p>

<ol>
<li>first require <code>luasocket</code>, then call <code>uuid.seed()</code>, and request a uuid using no
parameter, eg. <code>my_uuid = uuid()</code></li>
<li>use <a href="index.html#">uuid</a> without <code>luasocket</code>, set a random seed using <code>uuid.randomseed(some_good_seed)</code>,
and request a uuid using no parameter, eg. <code>my_uuid = uuid()</code></li>
<li>use <a href="index.html#">uuid</a> without <code>luasocket</code>, and request a uuid using an unique hex string,
eg. <code>my_uuid = uuid(my_networkcard_macaddress)</code></li>
</ol>




<h3>Parameters:</h3>
<ul>
<li><span class="parameter">hwaddr</span>
(optional) string containing a unique hex value (e.g.: <code>00:0c:29:69:41:c6</code>), to be used to compensate for the lesser <code>math_random()</code> function. Use a mac address for solid results. If omitted, a fully randomized uuid will be generated, but then you must ensure that the random seed is set properly!
</li>
</ul>

<h3>Returns:</h3>
<ol>

a properly formatted uuid string
</ol>



<h3>Usage:</h3>
<ul>
<pre class="example"><span class="keyword">local</span> uuid = <span class="global">require</span>(<span class="string">"uuid"</span>)
<span class="global">print</span>(<span class="string">"here's a new uuid: "</span>,uuid())</pre>
</ul>

</dd>
<dt>
<a name = "randomseed"></a>
<strong>randomseed (seed)</strong>
</dt>
<dd>
Improved randomseed function.
Lua 5.1 and 5.2 both truncate the seed given if it exceeds the integer
range. If this happens, the seed will be 0 or 1 and all randomness will
be gone (each application run will generate the same sequence of random
numbers in that case). This improved version drops the most significant
bits in those cases to get the seed within the proper range again.


<h3>Parameters:</h3>
<ul>
<li><span class="parameter">seed</span>
the random seed to set (integer from 0 - 2^32, negative values will be made positive)
</li>
</ul>

<h3>Returns:</h3>
<ol>

the (potentially modified) seed used
</ol>



<h3>Usage:</h3>
<ul>
<pre class="example"><span class="keyword">local</span> socket = <span class="global">require</span>(<span class="string">"socket"</span>) <span class="comment">-- gettime() has higher precision than os.time()
</span><span class="keyword">local</span> uuid = <span class="global">require</span>(<span class="string">"uuid"</span>)
<span class="comment">-- see also example at uuid.seed()
</span>uuid.randomseed(socket.gettime()*<span class="number">10000</span>)
<span class="global">print</span>(<span class="string">"here's a new uuid: "</span>,uuid())</pre>
</ul>

</dd>
<dt>
<a name = "seed"></a>
<strong>seed ()</strong>
</dt>
<dd>
Seeds the random generator.
It does so in 3 possible ways;</p>

<ol>
<li>if in ngx_lua, use <code>ngx.time() + ngx.worker.pid()</code> to ensure a unique seed
for each worker. It should ideally be called from the <code>init_worker</code> context.</li>
<li>use luasocket <code>gettime()</code> function, but it only does so when LuaSocket
has been required already.</li>
<li>use <code>os.time()</code>: this only offers resolution to one second (used when
LuaSocket hasn't been loaded)</li>
</ol>

<p> <strong>Important:</strong> the random seed is a global piece of data. Hence setting it is
an application level responsibility, libraries should never set it!






<h3>Usage:</h3>
<ul>
<pre class="example"><span class="keyword">local</span> socket = <span class="global">require</span>(<span class="string">"socket"</span>) <span class="comment">-- gettime() has higher precision than os.time()
</span><span class="comment">-- LuaSocket loaded, so below line does the same as the example from randomseed()
</span>uuid.seed()
<span class="global">print</span>(<span class="string">"here's a new uuid: "</span>,uuid())</pre>
</ul>

</dd>
</dl>


</div> <!-- id="content" -->
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
<i style="float:right;">Last updated 2021-07-11 08:59:24 </i>
<i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i>
<i style="float:right;">Last updated 2024-10-13 00:59:03 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>
Expand Down
2 changes: 1 addition & 1 deletion docs/ldoc.css
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
body {
body {
color: #47555c;
font-size: 16px;
font-family: "Open Sans", sans-serif;
Expand Down
Loading
Loading